دليل عملي لتشغيل DeerFlow عبر Docker وإدارة بيئات العمل

ما هو DeerFlow وكيف يعمل في الواقع العملي؟

مشروع DeerFlow إطار عمل مفتوح المصدر لتنسيق الوكلاء الأذكياء. لا يعمل النظام كأداة محادثة عادية، بل يوفر بيئة لتنظيم مسارات عمل يتعاون فيها وكيل رئيسي مع وكلاء فرعيين، معتمداً على الذاكرة لحفظ السياق، وصناديق الحماية لتأمين التنفيذ، والأدوات القابلة للتوسيع.

عند بدء مهمة، يضع الوكيل الرئيسي خطة العمل ويوزع المهام على مساعديه؛ فيتولى وكيل فرعي قراءة ملف معين، بينما يستخرج آخر بيانات فنية محددة، ثم يجمع الوكيل الرئيسي النتائج في مخرج موحد. يمنع هذا التوزيع تكدس البيانات ويساعد على إنجاز المهام بسلاسة.

متطلبات مزودات النماذج وإعدادات الاتصال

لا يشتمل DeerFlow على نماذج ذكاء اصطناعي مدمجة، بل يعمل كمحرك تنسيق يتصل بمزود خارجي متوافق. يمكنك ربط النظام بخدمات سحابية، أو بخوادم استدلال محلية على حاسوبك تدعم معيار OpenAI Chat Completions.

لا يتطلب استخدام الإطار بالضرورة اشتراكاً في واجهات برمجة التطبيقات (API) عند تشغيل مزود محلي متوافق، بينما تعتمد تكاليف الحوسبة والاستضافة والمزود على طبيعة الإعداد المعتمد. تُحفظ مفاتيح الاتصال وعناوين الوصول في ملف .env، وتُسجل خيارات النماذج وقواعد السلوك في config.yaml.

معالج الإعداد التفاعلي خطوة بخطوة

يوفر المشروع معالجاً تفاعلياً لتسهيل التهيئة دون صياغة ملفات الإعداد يدوياً. وفقاً لما يوضحه دليل البدء السريع لـ DeerFlow، تبدأ الخطوات بنسخ المستودع وتشغيل المعالج:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup

يرشدك أمر make setup عبر خطوات واضحة:

• اختيار مزود النماذج وحفظ مفاتيح الاتصال في .env.
• تفعيل البحث عبر الإنترنت أو تخطيه مؤقتاً.
• ضبط تفضيلات الأمان، كنمط صندوق الحماية وصلاحيات أوامر الصدفة البرمجية (Bash) وكتابة الملفات.
• إنشاء ملف الإعداد الأساسي config.yaml.

ولنسخ القالب الكامل وضبط القيم يدوياً، يمكن تشغيل:

make config

متطلبات Docker وأوامر make التوثيقية الدقيقة

يتطلب تشغيل DeerFlow عبر الحاويات تثبيت Docker Desktop أو Docker Engine مع Docker Compose v2.24+ (يتم التحقق منه عبر docker compose version). تعجز الإصدارات الأقدم عن قراءة وسائط env_file الاختيارية في إعدادات التطوير.

تحدد الوثائق الرسمية أوامر make التالية لإدارة الحاويات:

make docker-init
make docker-start
make docker-logs

تؤدي هذه الأوامر وظائف تشغيلية محددة:

• make docker-init: يسحب الصور الأساسية لصندوق الحماية من السجل، ويُنفذ عند التثبيت الأولي أو تحديث الصور.
• make docker-start: يشغل الحاويات ويكتشف نمط صندوق الحماية تلقائياً من config.yaml، ويبدأ خدمة provisioner فقط إذا كان وضع التوفير مفعلاً.
• make docker-logs: يعرض السجلات الحية لجميع الخدمات لمتابعة التشغيل ورصد أي أخطاء.

مسار التشغيل والتحقق من العنوان المحلي

عند تشغيل الحاويات، يُنصح بفحص مخرجات بدء التشغيل الفعلية وإعدادات التكوين للتحقق من عناوين الاتصال، إذ لا يُضمن أن تطبع كافة السجلات عناوين الاستماع تلقائياً. ولمتابعة مجريات التشغيل وتشخيص الحالة، يمكن فحص سجلات الحاويات:

make docker-logs

تساعد مراجعة مخرجات التشغيل والسجلات في التحقق من استقرار تهيئة الخدمات ورصد أي تعارض محتمل في المنافذ. وتعد مراجعة السجلات إجراءً تشخيصياً، ولا تمنع تلقائياً تعارض المنافذ إذا كان هناك برنامج آخر يشغل المنفذ نفسه.

فحص جاهزية النظام باستخدام make doctor

يحتوي المشروع على أداة فحص مدمجة للتأكد من جاهزية البيئة قبل بدء المهام. يمكنك تشغيل الفحص في أي وقت عبر:

make doctor

يفحص هذا الأمر ملفات التكوين، وتوافر التبعيات البرمجية، واتصال الحاويات، ويطبع إرشادات عملية لتصحيح أي خلل يتم اكتشافه.

حدود صندوق الحماية والاعتبارات الأمنية

صندوق الحماية (Sandbox) هو بيئة معزولة لتشغيل الأوامر والتعامل مع الملفات بأمان، للحد من وصول عمليات الوكيل إلى نظام حاسوبك المضيف وفقاً للإعدادات المحددة.

لكن صندوق الحماية حاجز تشغيلي قابل للضبط وليس حماية مطلقة. كما أنه يتطلب التفعيل؛ فليست كل مهمة معزولة ما لم يُفعل نمط الحماية في config.yaml. ويعتمد الأمان على الصلاحيات الممنوحة؛ فمنح الوكيل صلاحيات كتابة واسعة أو تشغيل أوامر صدفة دون قيود قد يعرض البيئة لمخاطر، لذا ينبغي حصر الصلاحيات في حدود الحاجة.

جدول مقارنة مسارات وبيئات التشغيل الموثقة

الأرقام الواردة أدناه تمثل نقاط بداية تشغيلية استرشادية وثقها المشروع وليست حدوداً دنيا صارمة:

مهمة عملية مقترحة: تقرير مقارنة بين مستندين

لاختبار النظام عملياً، نقترح تنفيذ مقارنة فنية بين وثيقتين، كمسودتي سياسة أمنية أو مواصفات مشروعين.

خطوات تنفيذ المهمة

1. وضع الملفين المستهدفين في مسار العمل المتاح للوكيل داخل البيئة.
2. توجيه الوكيل الرئيسي لوضع خطة مقارنة، وتكليف وكيلين فرعيين بقراءة كل وثيقة واستخراج بنودها مستقلاً.
3. دمج المخرجات في تقرير شامل يوضح نقاط الاتفاق والاختلاف.

معايير القبول والتحقق للمهمة

• الارتباط الدقيق بالأدلة: الاعتماد الحصري على نصوص الوثيقتين دون افتراضات خارجية.
• مصفوفة مقارنة جدولية: تنظيم البنود المتناظرة في جدول Markdown واضح.
• تحديد التباينات بدقة: حصر أي تعارض مباشر في الشروط بقسم مستقل.
• تقرير منظم وموجز: تقديم مخرجات Markdown واضحة مزودة بقوائم نقطية وعناوين محددة.