إعداد Agentic Data Stack باستخدام Docker Compose

شغّل حزمة Agentic Data Stack الكاملة (ClickHouse وLibreChat وخادم MCP وLangfuse) باستخدام Docker Compose

شغّل Agentic Data Stack بالكامل محليًا باستخدام Docker Compose لطرح أسئلة على بياناتك منذ أول تسجيل دخول. يتيح لك أمر واحد فقط، وهو docker compose up، تشغيل LibreChat وخادم MCP من ClickHouse وClickHouse وLangfuse لأغراض المراقبة.

​

المتطلبات الأساسية

• Docker مع إضافة Compose (الإصدار 2 أو أحدث).
• Git، لاستنساخ المستودع.
• مفتاح API لمزوّد نماذج (مثل OpenAI أو Anthropic أو Google). يحتاج الوكيل إلى نموذج للإجابة عن الأسئلة، لذا وفّر مفتاحًا أثناء الإعداد أو أضِف واحدًا في واجهة LibreChat قبل بدء أول محادثة.

​

شغِّل المكدس

1. استنسخ المستودع

   git clone https://github.com/ClickHouse/agentic-data-stack
   cd agentic-data-stack
   

   يتضمّن المستودع ملف docker-compose.yml في المستوى الأعلى، لذا يمكنك تشغيل المكدس بالكامل بأمر واحد. راجع البنية للاطلاع على القائمة الكاملة للخدمات.

2. شغّل سكربت إعداد العرض التوضيحي

   ./scripts/prepare-demo.sh
   

   يؤدي ذلك إلى إنشاء ملف .env يحتوي على بيانات الاعتماد لكل خدمة، ثم يعرض قائمة تفاعلية لإعداد مفاتيح API لمزوّد تختاره. ويمكنك أيضًا ضبط هذه المفاتيح مباشرةً في ملف .env. وأي مزوّد تتخطّاه سيظل مضبوطًا على user_provided، بحيث يمكنك إضافة مفتاحك الخاص في واجهة LibreChat بدلًا من ذلك.

   عند التشغيل لأول مرة، ينشئ المكدس مستخدم Admin من ملف .env. وبيانات تسجيل الدخول الافتراضية هي [e-mail] / password.

   عيّن بيانات تسجيل الدخول الخاصة بك

   شغّل generate-env.sh بهذه المتغيرات قبل prepare-demo.sh:

   USER_EMAIL="[e-mail]" USER_PASSWORD="supersecret" USER_NAME="YourName" ./scripts/generate-env.sh
   

   بعد ذلك سيتعرّف prepare-demo.sh على ملف .env الحالي وينتقل مباشرةً إلى إعداد مفاتيح API.

3. ابدأ الخدمات في الخلفية

   docker compose up -d
   

   يُرتَّب تسلسل بدء التشغيل تلقائيًا. ولا يبدأ LibreChat إلا بعد أن تصبح حالة خادم MCP سليمة، لذا يكون اتصاله بـ ClickHouse جاهزًا عند أول تحميل.

4. افتح LibreChat وسجّل الدخول

   بمجرد تشغيل المكدس، ستصبح الخدمات متاحة في متصفحك:

   • LibreChat (واجهة الدردشة) — http://localhost:3080
   • Langfuse (المراقبة) — http://localhost:3000
   • لوحة إدارة (إعداد LibreChat عبر المتصفح) — http://localhost:3081
   • وحدة تحكم MinIO (تخزين الكائنات؛ بيانات الاعتماد في .env) — http://localhost:9091

   سجّل الدخول إلى LibreChat باستخدام بيانات اعتماد المسؤول من ملف .env.

5. اختر نموذجًا

   يكون هناك نموذج محدد افتراضيًا. وإذا أردت تغييره، فافتح محدِّد النماذج واختر النموذج الذي تريد استخدامه.

   إذا لم تُعيّن مفتاح مزوّد أثناء الإعداد، فأضف واحدًا في واجهة المستخدم.

   عيّن مفتاح مزوّد في واجهة المستخدم

   افتح محدِّد النماذج وانقر على Set API Key بجانب المزوّد.

   ألصق مفتاحك في مربع الحوار وانقر على Submit. يمكنك تعيين تاريخ انتهاء، أو الإبقاء على المفتاح بدون انتهاء.

6. اختر خادم MCP

   يضبط المكدس مسبقًا خوادم MCP الخاصة به في ملف librechat.yaml الخاص بـ LibreChat. وفي منطقة كتابة الرسائل، انقر على MCP Servers واختر ClickHouse-Local.

   واختر ClickHouse-Cloud بدلًا من ذلك لاستخدام خدمة ClickHouse Cloud.

7. اطرح سؤالك الأول

   على سبيل المثال:

   ما قواعد البيانات والجداول المتاحة، وكم عدد الصفوف في أكبر جدول؟

   يستخدم الوكيل أدوات خادم MCP لسرد قواعد البيانات والجداول، وتشغيل استعلامات read-only على ClickHouse، وبناء إجابة من النتائج. ولا تحتاج إلى كتابة SQL.

​

إيقاف المكدس أو إعادة ضبطه

أوقف الخدمات من دون حذف أي شيء:

docker compose down

لإزالة جميع الحاويات ومسح كل وحدات التخزين والبدء من جديد بشكل نظيف، استخدم البرنامج النصي لإعادة تعيين المكدس:

./scripts/reset-all.sh

​

البنية المعمارية

يُعدّ docker-compose.yml نقطة دخول بسيطة تتضمن أربعة ملفات Compose:

ملف Compose	يعرّف
langfuse-compose.yml	Langfuse وخدماته الداعمة (ClickHouse وPostgreSQL وRedis وMinIO)
clickhouse-mcp-compose.yml	خادم ClickHouse MCP
librechat-compose.yml	LibreChat وخدماته الداعمة (MongoDB وMeilisearch وpgvector وRAG API)
admin-panel-compose.yml	لوحة إدارة LibreChat

هناك عاملان يجعلان التشغيل بأمر واحد ممكنًا:

• فحوصات الحالة وترتيب البدء. يستخدم Compose فحوصات الحالة لتنظيم تسلسل بدء التشغيل. ينتظر خادم MCP حتى يصبح ClickHouse جاهزًا، وينتظر LibreChat خادم MCP.
• ملف بيئة مشترك. يحتوي .env على بيانات الاعتماد وقيم الاتصال الخاصة بكل خدمة، وتُضبط هذه القيم بشكل متسق بحيث تتمكن الخدمات من الوصول إلى بعضها بعضًا. على سبيل المثال، يتصل خادم MCP بـ ClickHouse باستخدام بيانات اعتماد ClickHouse من .env. كما يُزوَّد LibreChat بكل من LANGFUSE_PUBLIC_KEY وLANGFUSE_SECRET_KEY وLANGFUSE_BASE_URL، بحيث يُرسَل تتبّع كل تشغيل إلى Langfuse مباشرةً من البداية.

يلعب ClickHouse دورين في هذه المنظومة: فهو الواجهة الخلفية للتخزين لدى Langfuse، وهو أيضًا قاعدة البيانات التي يستعلم عنها الوكيل عبر خادم MCP.

​

الخطوات التالية

• تعرّف على دور كل مكوّن في المكدس: خادم MCP من ClickHouse، وLibreChat، وLangfuse.
• اطّلع على نظرة عامة لمعرفة كيف تتكامل مكوّنات المكدس.
• لتجربة المكدس على مجموعات بيانات عامة من دون تثبيت أي شيء، استخدم AgentHouse، النسخة التجريبية المستضافة.