DEV Community

Cover image for كيفية تشغيل أي نموذج في ديب سيك هارنس؟
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

كيفية تشغيل أي نموذج في ديب سيك هارنس؟

يأتي DeepSeek Harness (dsh) مزودًا بنماذج DeepSeek، لكنك لست مقيدًا بها. يتعامل النظام مع مزودي النماذج كتكوين: وجّه كتلة مزود إلى أي نقطة نهاية متوافقة مع OpenAI، واربطها ببيانات اعتماد، ثم شغّل جلسات الوكيل باستخدام أي نموذج خلف تلك النقطة. يمكنك توصيل Ollama محليًا، أو بوابة داخلية، أو Qwen عبر وضع DashScope المتوافق، أو مزودي الكتالوج مثل Anthropic وOpenAI ضمن نفس الإعداد.

جرّب Apidog اليوم

يوضح هذا الدليل إعداد المزود مفتاحًا بمفتاح، ثم يقدم ثلاث وصفات عملية: نموذج محلي، ونقطة نهاية مستضافة متوافقة مع OpenAI، ومزودو الكتالوج المدمجون. تعتمد التفاصيل على دليل المزودين الرسمي في الفرع الرئيسي، الذي جُلب في 20 أغسطس 2026.

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

إذا كنت جديدًا على النظام، ابدأ بـ ما هو DeepSeek Harness وكيف يعمل، ثم عد لإعداد المزود.

لماذا تبدّل النماذج في نظام وكيل؟

نظام الوكيل عبارة عن حلقة: يخطط النموذج، يستدعي الأدوات، يقرأ النتائج، ثم يكرر العملية. النظام يدير الحلقة، بينما النموذج مكوّن قابل للاستبدال.

تبديل النموذج مفيد في ثلاث حالات عملية:

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

يتوافق ذلك مع بنية dsh: كل شيء مكوّن إضافي، بما في ذلك محول النموذج. مسارات المزود يمتلكها المكون الإضافي dsh-llm-pi-ai، كما هو موثق في كتالوج تكوين المكونات الإضافية. عمليًا، ستتعامل مع كتلة YAML واحدة.

كتلة المزود، مفتاحًا بمفتاح

أضف المزودات المخصصة في:

$DSH_HOME/settings.yaml
Enter fullscreen mode Exit fullscreen mode

ويمكنك إنشاؤها أيضًا من واجهة الويب عبر الإعدادات ← النماذج.

مثال أساسي:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]
Enter fullscreen mode Exit fullscreen mode

شرح المفاتيح

المفتاح الاستخدام
my-gateway معرّف المزود. استخدم اسمًا ثابتًا لأن الإعدادات قد تعتمد عليه.
apiKeyEnv اسم متغير البيئة الذي يحتوي مفتاح API، وليس المفتاح نفسه.
api بروتوكول الاتصال. استخدم openai-completions لنقاط النهاية المتوافقة مع OpenAI.
baseURL الجذر الأساسي لنقطة النهاية التي تستقبل الطلبات.
models قائمة النماذج المتاحة من هذا المزود.
id معرف النموذج كما تتوقعه نقطة النهاية في الطلب.
input أنواع الإدخال التي يقبلها النموذج، مثل text وimage.
defaultInput قيمة إدخال افتراضية لكل نماذج المزود، ويمكن تجاوزها داخل كل نموذج.
compat إعدادات توافق لنقاط النهاية التي لا تطابق سلوك OpenAI بالكامل.

تكون النماذج المخصصة نصية فقط افتراضيًا. إذا كان النموذج يدعم الصور، أضف:

input: [text, image]
Enter fullscreen mode Exit fullscreen mode

للتعامل مع اختلافات بعض الواجهات الخلفية، استخدم compat:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode
  • استخدم supportsDeveloperRole: false إذا كانت الواجهة الخلفية ترفض دور developer.
  • استخدم maxTokensField: max_tokens إذا كانت الواجهة تتوقع اسم الحقل الأقدم لتحديد حد الإخراج.

يمكن تعيين compat على مستوى المزود أو على مستوى نموذج محدد.

جلب قائمة النماذج تلقائيًا

عند إضافة مزود مخصص من واجهة dsh، يمكن لخيار جلب النماذج المتاحة استدعاء المسار المتوافق مع OpenAI:

GET /models
Enter fullscreen mode Exit fullscreen mode

إذا كانت نقطة النهاية تنفذ هذا المسار، ستتمكن من ملء قائمة النماذج تلقائيًا بدل إدخالها يدويًا.

أين يوجد مفتاح API الفعلي؟

يخزن dsh الأسرار بوضع كتابة فقط داخل:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

بعد حفظ مفتاح من واجهة المستخدم، يعرض النظام وصفًا محجوبًا فقط ولا يعرض القيمة الحرفية مجددًا. يجب أن يحتوي settings.yaml على مراجع مثل apiKeyEnv، وليس مفاتيح فعلية.

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

الوصفة 1: تشغيل نموذج محلي عبر Ollama

يكشف Ollama واجهة متوافقة مع OpenAI على:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

وهذا موثق في دليل توافق Ollama مع OpenAI. لذلك يمكن لـ dsh الاتصال به باستخدام openai-completions.

أضف المزود التالي إلى settings.yaml:

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3
Enter fullscreen mode Exit fullscreen mode

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

  1. شغّل Ollama.
  2. اسحب النموذج الذي تريد استخدامه: 
   ollama pull gpt-oss:20b
Enter fullscreen mode Exit fullscreen mode
  1. اعرض أسماء النماذج المتاحة: 
   ollama list
Enter fullscreen mode Exit fullscreen mode
  1. انسخ اسم النموذج كما يظهر، بما في ذلك العلامة مثل gpt-oss:20b.
  2. عيّن قيمة وهمية لمتغير البيئة، لأن مخطط المزود يتوقع مرجع بيانات اعتماد: 
   export OLLAMA_API_KEY=ollama
Enter fullscreen mode Exit fullscreen mode

لا يحتاج Ollama المحلي إلى مفتاح فعلي، ويتجاهل هذه القيمة.

  1. تحقق من نقطة النهاية قبل فتح جلسة وكيل: 
   curl http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا اختبار الطلب من Apidog عبر:

GET http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

إذا أعاد الطلب قائمة النماذج، فهذا يؤكد أن الخادم يعمل وأن baseURL صحيح. إذا فشل، أصلح مشكلة Ollama أو الشبكة أولًا؛ لن يعالجها تعديل إعدادات dsh.

لإعداد محلي كامل، راجع كيفية تشغيل GPT-OSS باستخدام Ollama.

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

الوصفة 2: نقطة نهاية مستضافة متوافقة مع OpenAI — Qwen عبر DashScope

لا تفترض أن كل بائع متوافق مع OpenAI؛ استخدم التوافق الموثق. توثق Alibaba Cloud Model Studio (DashScope) مسارًا متوافقًا مع OpenAI لنماذج Qwen:

/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

راجع صفحة توافق OpenAI مع DashScope للتفاصيل.

مثال لنطاق سنغافورة:

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max
Enter fullscreen mode Exit fullscreen mode

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

  1. استبدل {WorkspaceId} بمعرف مساحة العمل من وحدة تحكم Model Studio.
  2. عيّن مفتاح API: 
   export DASHSCOPE_API_KEY="your-api-key"
Enter fullscreen mode Exit fullscreen mode
  1. تحقق من معرفات النماذج الحالية لدى البائع قبل إضافتها.
  2. اختبر المسار: 
   curl \
     -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
     "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/models"
Enter fullscreen mode Exit fullscreen mode

للاطلاع على تفاصيل إضافية حول نماذج Qwen، راجع دليل API الخاص بـ Qwen 3.8.

ينطبق النمط نفسه على أي خدمة توثق توافق OpenAI، مثل بوابة داخلية، أو نشر vLLM، أو OpenRouter، أو Moonshot/Kimi. عادةً ستغير فقط:

  • baseURL
  • اسم متغير البيئة
  • معرفات النماذج

إذا سبق لك إعداد نماذج مفتوحة المصدر في Codex، فالفكرة مشابهة: كتلة YAML في dsh تؤدي دور إعداد model_providers في Codex.

مشاكل شائعة مع النقاط المستضافة

إذا ظهرت أخطاء تتعلق بالأدوار أو حقول الرموز، جرّب:

compat:
  supportsDeveloperRole: false
Enter fullscreen mode Exit fullscreen mode

وإذا كانت الواجهة الخلفية ترفض حقل حد الإخراج، جرّب:

compat:
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

ولنماذج الرؤية، أعلن دعم الصور صراحة:

models:
  - id: qwen-vision-model
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

الوصفة 3: مزودو الكتالوج المدمجون

لا تحتاج إلى كتلة مزود مخصصة لكل خدمة. يوفّر dsh مزودي كتالوج لـ DeepSeek وAnthropic وOpenAI، حيث يقتصر الإعداد غالبًا على إضافة مفتاح API.

تحمل بعض إدخالات الكتالوج تدفقات مصادقة أصلية خاصة بها:

  • Bedrock: بيانات اعتماد AWS.
  • Vertex: مشروع ADC.
  • Azure: إصدار API خاص بالخدمة.
  • Codex: مصادقة OAuth.

استخدم مزودي الكتالوج عندما تريد أقل قدر من الإعداد لتشغيل Claude أو GPT أو نماذج DeepSeek. استخدم المزودات المخصصة للحالات غير الموجودة في الكتالوج، مثل:

  • Ollama المحلي
  • بوابات الشركات
  • البائعين الإقليميين
  • المجمعات المتوافقة مع OpenAI

للتفاصيل المتعلقة بواجهة DeepSeek API، راجع api-docs.deepseek.com.

اختيار النموذج وما تتذكره الجلسات

إضافة مزود تجعل نماذجه متاحة. اختيار نموذج من الإعدادات ← النماذج يجعله النموذج الافتراضي للجلسات الجديدة.

انتبه إلى السلوكين التاليين:

  1. الجلسات الحالية تبقى على نموذجها الأصلي.

    تغيير النموذج الافتراضي لا يغيّر النموذج الذي تعمل به جلسة قائمة.

  2. حذف مزود النموذج الافتراضي يتطلب اختيار بديل.

    يمنع dsh المتابعة حتى تحدد نموذجًا افتراضيًا جديدًا، بدل التخمين أو التبديل الصامت.

هذا مهم للتكرارية: سجل الجلسة يعكس نموذجًا واحدًا، وليس مزيجًا من نماذج تغيرت أثناء التنفيذ. راجع أيضًا مقارنة DeepSeek Harness vs Claude Code.

استكشاف الأخطاء الشائعة

baseURL غير صحيح أو لا يمكن الوصول إليه

تأكد من أن المسار ينتهي بالقيمة التي يتوقعها البروتوكول:

  • غالبًا /v1 للنقاط المتوافقة مع OpenAI.
  • استخدم /compatible-mode/v1 لـ DashScope.

اختبر خارج dsh أولًا:

curl \
  -H "Authorization: Bearer $KEY" \
  "{baseURL}/models"
Enter fullscreen mode Exit fullscreen mode

استخدم تنزيل Apidog لإرسال الطلب نفسه ومراجعة رمز الحالة وجسم الاستجابة الفعلي بدل الاعتماد على رسالة الخطأ المغلفة من النظام.

إذا كنت تعمل دون اتصال أو مع بائع غير موثوق، يمكنك محاكاة المسارين التاليين في Apidog:

GET /models
POST /chat/completions
Enter fullscreen mode Exit fullscreen mode

ثم وجّه baseURL إلى المحاكاة أثناء التطوير.

متغير بيئة مفقود أو فارغ

apiKeyEnv يشير إلى متغير موجود؛ لا ينشئه.

إذا كان المتغير غير متاح ضمن البيئة التي يشغّل منها dsh، سترسل الطلبات دون مصادقة وقد تحصل على 401.

تحقق من المتغير ضمن سياق التشغيل الفعلي:

echo $GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

لا تكتفِ بالتحقق في طرفية عشوائية إذا كنت تشغل dsh web من واجهة رسومية أو مدير خدمات؛ قد لا يرث هذا السياق إعدادات Shell.

عدم تطابق نوع الإدخال

إذا أرفقت صورة ولم تصل إلى النموذج، أضف دعم الصور:

models:
  - id: vision-preview
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

أو عيّن القيمة الافتراضية لكل نماذج المزود:

defaultInput: [text, image]
Enter fullscreen mode Exit fullscreen mode

غرائب البروتوكول

إذا ذكر الخطأ دورًا غير مدعوم أو معلمة رمز مرفوضة، أضف:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

يمكنك وضع compat على مستوى المزود أو النموذج.

كل شيء كان يعمل بالأمس

بما أن dsh إصدار مطور مبدئي:

  1. ثبّت الإصدار الذي تنشره.
  2. اقرأ ملاحظات الإصدار قبل الترقية.
  3. راجع مخطط الإعدادات بعد كل تحديث.
  4. اعتبر مستودع deepseek-harness مصدر الحقيقة، وليس أي منشور مدونة.

مزودو النماذج نصف التخصيص فقط؛ النصف الآخر هو الأدوات التي يستطيع الوكيل استدعاءها. يمكنك توصيل تدفقات عمل API مباشرة، كما في استخدام Apidog CLI داخل DeepSeek Harness.

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

هل يدعم DeepSeek Harness Ollama رسميًا؟

لا تذكر وثيقة المزودين الرسمية Ollama بالاسم. لكنها تدعم أي نقطة نهاية تستخدم بروتوكول openai-completions، بينما يوثق Ollama واجهة متوافقة مع OpenAI على:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

الوصفة السابقة تجمع بين هذين الجزأين الموثقين. اختبرها على إصدارك المثبت لأن مخططات dsh قد تتغير بين الإصدارات.

أين يخزن dsh مفاتيح API؟

داخل:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

وبوضع كتابة فقط. تعرض واجهة المستخدم وصفًا محجوبًا بعد الحفظ، بينما يحتوي settings.yaml على مراجع مثل apiKeyEnv فقط.

هل يمكن تشغيل نماذج مختلفة لجلسات مختلفة؟

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

يمكنك مثلًا استخدام DeepSeek V4-Flash للجلسات الروتينية، ثم تغيير النموذج الافتراضي لمهمة أصعب، دون التأثير في الجلسات السابقة.

نقطة النهاية المخصصة تُرجع أخطاء لا تظهر عند تنفيذ الطلب نفسه عبر curl. ماذا أفعل؟

قارن الحمولة الفعلية، وليس النتيجة فقط. قد يرسل dsh دور developer أو حقلًا حديثًا لحد الرموز لا تقبله الواجهة الخلفية.

ابدأ بإعدادات التوافق الموثقة:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

ثم أعد تنفيذ الطلب في عميل API بالحمولة نفسها لتحديد الحقل الذي ترفضه الواجهة الخلفية.

Top comments (0)