🧠 تثبيت Chroma — قاعدة بيانات متجهات سهلة للمطورين لتطبيقات RAG

انشر Chroma على Ubuntu بـ Docker — قاعدة بيانات embeddings مفتوحة المصدر تخزّن متجهات المستندات، تبحث بالتشابه الدلالي، وتتكامل مباشرة مع LangChain وLlamaIndex لتطبيقات RAG.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — واجهة Chroma REST API جاهزة بأمر واحد.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/ai/chroma/chroma-ubuntu.sh
chmod +x chroma-ubuntu.sh
sudo bash chroma-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/ai/chroma/chroma-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x chroma-ubuntu.sh

3 تشغيل المُثبّت

يثبّت السكريبت Docker إن لزم، ويُشغّل صورة chromadb/chroma على المنفذ 8000، مع تخزين مجموعاتك (collections) والمتجهات في حجم محلي دائم.

sudo bash chroma-ubuntu.sh

4 الدخول إلى واجهة الويب

لا تملك Chroma لوحة ويب مدمجة — تأكد من عمل السيرفر بطلب نقطة heartbeat، ثم اتصل من كود تطبيقك باستخدام مكتبة عميل Chroma:

curl http://:8000/api/v2/heartbeat

المنافذ المستخدمة

المنفذالغرض
8000Chroma REST API

نظرة عامة

Chroma (المعروفة أيضاً باسم ChromaDB) هي قاعدة بيانات embeddings مفتوحة المصدر مصمَّمة خصيصاً لتطبيقات الذكاء الاصطناعي. تخزّن المتجهات (vector embeddings) إلى جانب المستندات المصدرية وبياناتها الوصفية، ثم تتيح لك البحث بالتشابه الدلالي بدلاً من المطابقة الحرفية للكلمات المفتاحية. تُقدَّم كسيرفر خفيف بواجهة REST API بسيطة ومكتبات عميل رسمية لـ Python وJavaScript، وهي من أكثر قواعد بيانات المتجهات استخداماً في أنظمة RAG (التوليد المعزّز بالاسترجاع).

لماذا تستخدمه

صُممت Chroma خصيصاً للمطورين الذين يحتاجون إضافة بحث دلالي أو RAG إلى تطبيقهم دون إعداد عنقود بحث ثقيل وعام الغرض. تتولى تخزين المتجهات والفهرسة والبحث بالتشابه في خدمة واحدة صغيرة، وتقدّم تكاملات جاهزة مع LangChain وLlamaIndex، ويمكن تشغيلها في الذاكرة للنماذج الأولية أو كسيرفر دائم للإنتاج. مقارنة بإضافة بحث المتجهات فوق قاعدة بيانات علائقية، فإن Chroma مبنية خصيصاً لهذا النوع من الأحمال وتنقلك من الصفر إلى نموذج RAG عامل خلال دقائق.

متى تحتاجه

  • تبني تطبيق RAG (توليد معزّز بالاسترجاع) وتحتاج تخزين والبحث في متجهات المستندات
  • تريد بحثاً دلالياً في مستنداتك أو تذاكر الدعم أو قاعدة المعرفة بدلاً من المطابقة الحرفية للكلمات
  • تُجرّب تطبيق ذكاء اصطناعي باستخدام LangChain أو LlamaIndex وتحتاج قاعدة متجهات تتكامل بأقل إعداد
  • تحتاج الاحتفاظ بالمتجهات ومستنداتها المصدرية على بنيتك التحتية الخاصة بدلاً من قاعدة متجهات سحابية مُدارة
  • يحتاج تطبيقك بحث أقرب-جار تقريبي سريع عبر عشرات الآلاف إلى بضعة ملايين من المتجهات

من يحتاجه

  • مهندسو الذكاء الاصطناعي والتعلم الآلي الذين يبنون أنظمة RAG ويحتاجون قاعدة متجهات تتكامل مباشرة مع LangChain أو LlamaIndex أو كود Python/JS مخصص
  • المطورون الذين يُجرّبون روبوتات محادثة أو أنظمة أسئلة وأجوبة فوق مستندات خاصة ويريدون تفادي اشتراك قاعدة متجهات مُدارة
  • الشركات الناشئة التي تبني منتجات ذكاء اصطناعي وتحتاج إبقاء المتجهات والمستندات الحساسة على بنية تحتية تتحكم بها
  • فرق البيانات التي تُجرّب البحث الدلالي أو إزالة التكرار أو التجميع فوق نماذج embedding
  • الفرق التي تُشغّل بالفعل Ollama أو نموذج لغوي محلي وتريد قاعدة متجهات ذاتية الاستضافة تُكمل المنظومة
  • الباحثون والطلاب الذين يتعلمون كيفية عمل الاسترجاع القائم على embeddings دون دفع تكلفة قاعدة متجهات مُستضافة
  • الشركات ذات متطلبات إقامة البيانات أو الامتثال التي تستبعد إرسال متجهات المستندات لخدمة سحابية طرف ثالث

حالات الاستخدام الشائعة

  • تشغيل روبوت محادثة RAG يجيب على الأسئلة من توثيقك الداخلي أو الويكي أو تذاكر الدعم
  • بناء بحث دلالي لكتالوج منتجات يتيح للعملاء البحث بالمعنى بدلاً من الكلمات الحرفية
  • إزالة التكرار من مجموعات بيانات نصية كبيرة عبر إيجاد المستندات شبه المتطابقة بتشابه المتجهات
  • اقتراح مقالات أو منتجات أو إجابات دعم ذات صلة بناءً على مسافة المتجهات
  • تخزين متجهات سجل المحادثات لمنح نموذج اللغة ذاكرة طويلة المدى عبر الجلسات
  • تجميع وتصنيف بيانات نصية غير مهيكلة لأغراض التحليلات أو إشراف المحتوى

الميزات الرئيسية

  • واجهة REST API بسيطة ومكتبات عميل رسمية لـ Python وJavaScript بأقل كود تحضيري
  • تكاملات أصلية مع LangChain وLlamaIndex وأطر عمل RAG الشائعة الأخرى
  • تدعم دوال مسافة التشابه الجيبي (cosine) وL2 (إقليدي) وحاصل الضرب الداخلي لكل مجموعة
  • تصفية بالبيانات الوصفية — دمج بحث التشابه بالمتجهات مع مرشحات مهيكلة على البيانات الوصفية للمستند
  • مجموعات (collections) لتنظيم المتجهات في مجموعات منطقية (مثلاً واحدة لكل مصدر بيانات أو مستأجر)
  • تعمل في الذاكرة للنماذج الأولية السريعة، أو كسيرفر دائم مدعوم بـ SQLite/Parquet للإنتاج
  • دعم متعدد الوسائط — تخزين والبحث في متجهات النصوص والصور وأنواع أخرى في نفس القاعدة
  • مفتوحة المصدر برخصة Apache 2.0 مع مجتمع نشط وإصدارات متكررة

كيفية الاستخدام بعد التثبيت

  • تحقق من وصول السيرفر بطلب curl لنقطة heartbeat على http://your-server-ip:8000/api/v2/heartbeat
  • ثبّت مكتبة عميل Chroma في مشروعك (pip install chromadb لـ Python، أو حزمة chromadb لـ JS) ووجّهها لعنوان ومنفذ سيرفرك
  • أنشئ مجموعة (collection) لحفظ متجهاتك، واختر دالة مسافة (cosine هي الافتراضية وتعمل جيداً لمعظم embeddings النصية)
  • أضف مستندات بتمرير النص والمتجهات (أو دع Chroma يحسبها بدالة embedding مُعدّة) والبيانات الوصفية
  • استعلم المجموعة بنص أو متجه استعلام لاسترجاع أقرب المستندات تشابهاً
  • اربط Chroma بـ LangChain أو LlamaIndex كخلفية قاعدة متجهات إن كنت تبني خط أنابيب RAG
  • فعّل مصادقة الرمز (token) قبل كشف السيرفر خارج localhost — Chroma لا تفعّل أي مصادقة افتراضياً
  • أعدّ نسخاً احتياطية دورية لدليل البيانات الدائم قبل الاعتماد على Chroma لبيانات إنتاجية

أفضل ممارسات الأمان

  • تأتي Chroma دون أي مصادقة مفعّلة افتراضياً — فعّل مصادقة الرمز أو الأساسية عبر CHROMA_SERVER_AUTHN_PROVIDER قبل كشفها خارج localhost
  • لا تكشف المنفذ 8000 مباشرة للإنترنت العام — ضع Chroma خلف وكيل عكسي مع TLS وقيّد الوصول بعنوان IP أو VPN
  • استخدم رمز مصادقة عشوائي محدود النطاق وخزّنه في متغيرات بيئة أو مدير أسرار، لا في كود التطبيق المصدري
  • عطّل القياس عن بُعد المجهول الهوية إذا كنت تتعامل مع بيانات حساسة بضبط ANONYMIZED_TELEMETRY=FALSE
  • شغّل Chroma في شبكة Docker معزولة مع خدمات التطبيق التي تحتاج الوصول إليها فقط
  • حدّث صورة chromadb/chroma بانتظام — اسحب الإصدارات الجديدة دورياً لتلقّي إصلاحات الأمان والاستقرار
  • قيّد صلاحيات نظام الملفات على دليل البيانات الدائم لأنه يحتوي نص المستندات الخام والمتجهات
  • إذا كانت البيئة متعددة المستأجرين، استخدم مجموعات منفصلة أو نسخ Chroma منفصلة لكل مستأجر بدلاً من الاعتماد فقط على تصفية على مستوى التطبيق

المنافذ وإعدادات جدار الحماية

تستمع Chroma على المنفذ 8000 لواجهة REST API الخاصة بها افتراضياً، دون TLS أو مصادقة مدمجة جاهزة. لا تكشف المنفذ 8000 مباشرة للإنترنت أبداً دون إضافة وكيل عكسي — يجب أن يمر كود التطبيق وأي أدوات تعمل من المتصفح تتواصل مع Chroma عبر Nginx Proxy Manager أو Caddy بشهادة TLS صالحة. إذا كانت Chroma تُستخدم فقط من حاويات أخرى على نفس المضيف، تجنّب نشر المنفذ للمضيف أصلاً ودع الخدمات تصل إليها عبر شبكة Docker الداخلية. لأي كشف خارج localhost، فعّل مصادقة الرمز أولاً.

النسخ الاحتياطي والصيانة

  • انسخ احتياطياً دليل البيانات الدائم (الحجم المُركَّب على /data أو /chroma/chroma داخل الحاوية) الذي يحمل مجموعاتك ومتجهاتك وبياناتها الوصفية
  • أوقف حركة الكتابة أو خذ لقطة متسقة قبل نسخ دليل البيانات لتفادي التقاط حالة مكتوبة جزئياً
  • صدّر المجموعات المهمة دورياً باستخدام عميل Chroma لتحتفظ بنسخة احتياطية محمولة ومستقلة عن الصيغة خارج ملفات القاعدة الخام
  • خزّن النسخ الاحتياطية على قرص مختلف عن دليل البيانات الحي، ويُفضّل على سيرفر بعيد أو تخزين كائنات
  • وثّق نموذج embedding وأبعاده المستخدمة لكل مجموعة — استعادة البيانات دون مطابقة بيانات دالة embedding تجعل الاستعلامات الجديدة غير متسقة مع المتجهات القديمة
  • اختبر استعادة دليل البيانات إلى حاوية جديدة دورياً للتأكد أن عملية النسخ الاحتياطي تعمل فعلاً

الأخطاء الشائعة

  • كشف المنفذ 8000 للإنترنت دون تفعيل المصادقة — لا تملك Chroma مصادقة افتراضياً وأي شخص يصل إليها يمكنه قراءة أو حذف كل مجموعة
  • تشغيل Chroma في وضع مؤقت/بالذاكرة في الإنتاج وفقدان كل المتجهات عند إعادة تشغيل الحاوية
  • خلط متجهات مُولَّدة من نماذج embedding مختلفة في نفس المجموعة — تصبح درجات التشابه بلا معنى عندما لا تتطابق فضاءات المتجهات
  • عدم ضبط دالة مسافة مناسبة لنموذج embedding — استخدام L2 مع متجهات مُطبَّعة للتشابه الجيبي يعطي نتائج ضعيفة
  • نسيان إعادة embedding وإعادة فهرسة المستندات بعد التبديل لنموذج embedding مختلف أو مُحدَّث
  • تخزين مستندات خام كبيرة جداً كبيانات وصفية بدلاً من مجرد معرّفات وإشارات لتخزين خارجي، مما يُضخّم القاعدة بلا داعٍ
  • عدم التصفية بالبيانات الوصفية عندما تُضيّق مساحة البحث، والاعتماد فقط على تشابه المتجهات لاستعلامات لها مرشح مهيكل واضح
  • تخطي النسخ الاحتياطي لأن Chroma 'تعمل ببساطة' — دليل بيانات تالف أو محذوف يعني إعادة embedding مجموعة مستنداتك بأكملها من الصفر

استكشاف الأخطاء وإصلاحها

  • نقطة heartbeat لا تستجيب — تحقق من تشغيل الحاوية بـ docker ps، راجع docker logs chroma لأخطاء البدء، وتأكد أن المنفذ 8000 غير مستخدم مسبقاً
  • العميل لا يتصل من حاوية أخرى — تحقق أن الحاويتين على نفس شبكة Docker واستخدم اسم الحاوية، لا localhost، كعنوان المضيف
  • الاستعلامات تُرجع نتائج غير ذات صلة — تحقق من استخدام نفس نموذج embedding ودالة المسافة المستخدمة عند إنشاء المجموعة في الاستعلامات
  • أخطاء مصادقة بعد تفعيل مصادقة الرمز — تأكد أن CHROMA_SERVER_AUTHN_CREDENTIALS يطابق الرمز الذي يرسله عميلك وأن اسم فئة المزوّد مكتوب بدقة
  • استخدام ذاكرة مرتفع على مجموعات كبيرة — تُحمّل Chroma الفهارس في الذاكرة؛ فكّر بتقسيم مجموعات البيانات الكبيرة جداً عبر عدة مجموعات أو نسخ
  • بيانات مفقودة بعد إعادة تشغيل الحاوية — تأكد أن حجم البيانات مُركَّب بشكل صحيح ولم يُنشأ بالخطأ كحجم مجهول تمت إزالته
  • استعلامات بطيئة على مجموعات كبيرة — تحقق من استخدام دالة مسافة مناسبة وفكّر بتقليل أبعاد embedding إذا كان نموذجك يدعم ذلك
  • أخطاء عدم تطابق إصدار بين العميل والسيرفر — حافظ على توافق إصدار عميل chromadb لـ Python/JS مع إصدار صورة السيرفر، خاصة بعد تغييرات API من v1 إلى v2

البدائل

Qdrant منافس قريب مكتوب بلغة Rust بأداء قوي وواجهة برمجية سهلة للمطورين مشابهة — خيار جيد إذا احتجت معدل نقل أعلى عند التوسّع. Weaviate يضيف بحثاً هجيناً مدمجاً وواجهة GraphQL لكن ببصمة تشغيلية أثقل. Milvus مبنية للانتشارات كبيرة الحجم جداً (مليارات المتجهات) لكنها تتطلب بنية تحتية أكبر لتعمل بكفاءة. pgvector يحوّل قاعدة PostgreSQL موجودة لديك إلى قاعدة متجهات، وهو خيار جذاب إذا كنت تُشغّل Postgres بالفعل وتريد تفادي خدمة منفصلة. Pinecone وقواعد المتجهات السحابية المُدارة الأخرى تُزيل العبء التشغيلي تماماً لكن بمعنى أن متجهاتك ومستنداتك تعيش على بنية تحتية طرف آخر. لمعظم مشاريع RAG الصغيرة والمتوسطة التي تريد الاستضافة الذاتية بأقل إعداد، تبقى Chroma أبسط نقطة انطلاق.

متى لا تستخدمه

Chroma ليست الخيار الصحيح إذا احتجت فهرسة مليارات المتجهات باتفاقيات زمن استجابة منخفض صارمة على نطاق واسع — Milvus أو خدمة مُدارة مثل Pinecone مبنيتان لهذا النطاق من التشغيل. إذا كان فريقك يُشغّل PostgreSQL بالفعل ويريد تفادي تشغيل خدمة قاعدة بيانات إضافية، قد يكون pgvector خياراً أفضل لأنه يعيد استخدام بنية تحتية تديرها بالفعل. كما لا تملك Chroma تحكم وصول متعدد المستأجرين أو مصادقة مدمجة جاهزة من الصندوق، فإذا احتجت إدارة وصول على مستوى المؤسسات دون بنائها بنفسك، قد تكون Weaviate أو قاعدة متجهات مُدارة نقطة انطلاق أفضل. للبحث البسيط بالكلمات المفتاحية دون حاجة لتشابه دلالي، محرك بحث تقليدي مثل Meilisearch أو Elasticsearch خيار أفضل وأرخص.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

هل Chroma هي نفسها ChromaDB؟

نعم. "Chroma" و"ChromaDB" يشيران لنفس المشروع مفتوح المصدر — الحزمة منشورة باسم chromadb على PyPI وnpm، بينما المشروع نفسه يُعرف غالباً باسم Chroma فقط.

هل أحتاج GPU لتشغيل Chroma؟

لا. Chroma نفسها تخزّن وتبحث في المتجهات فقط — لا تُولّد embeddings. الـ GPU يهم فقط لنموذج embedding المنفصل الذي تستخدمه لتحويل النص إلى متجهات (مثلاً نموذج محلي عبر Ollama أو Sentence Transformers). تخزين وبحث Chroma يعملان بارتياح على المعالج.

هل تملك Chroma لوحة تحكم ويب؟

النسخة مفتوحة المصدر لا تأتي بواجهة إدارة كاملة — تتفاعل معها عبر REST API ومكتبات العميل الرسمية. Chroma Cloud، النسخة السحابية التجارية، تضيف لوحة تحكم ويب، لكن هذا النشر ذاتي الاستضافة عبر Docker يعمل بواجهة API فقط.

كيف تختلف Chroma عن قاعدة بيانات تقليدية؟

قاعدة البيانات التقليدية تطابق قيماً حرفية (مساواة، نطاقات، كلمات مفتاحية). Chroma تخزّن متجهات embedding عالية الأبعاد وتجد العناصر بالتشابه الدلالي — تجيب عن "ما الأقرب لهذا" بدلاً من "ما الذي يطابق هذا المرشح بالضبط". تستخدم تطبيقات كثيرة كليهما: قاعدة بيانات علائقية للبيانات المهيكلة وChroma للبحث الدلالي فوقها.

هل يمكن لتطبيقات متعددة مشاركة نسخة Chroma واحدة؟

نعم، باستخدام مجموعات منفصلة لكل تطبيق أو مستأجر. لكن Chroma لا تفرض تفويضاً لكل مجموعة من الصندوق، فإذا كان يجب ألا ترى التطبيقات المختلفة بيانات بعضها، إما شغّل نسخاً منفصلة أو أضف طبقة تفويض أمام السيرفر المشترك.