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

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

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

button

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

لماذا تبديل النماذج في نظام وكيل على الإطلاق؟

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

التكلفة. تستهلك جلسات الوكيل الرموز بسرعة لأن كل نتيجة أداة يتم إرجاعها إلى السياق. توجيه الجلسات الروتينية إلى نموذج أرخص، أو إلى DeepSeek V4-Flash بدلاً من V4-Pro، يغير فاتورتك دون تغيير سير عملك. يمكنك الاحتفاظ بنموذج رائد باهظ الثمن مُكوَّن للجلسات التي تحتاجه.

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

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

يتبع التصميم من بنية dsh: كل شيء في النظام هو مكون إضافي، ومحول النموذج هو إحدى القطع القابلة للاستبدال. تعود ملكية مسارات المزود إلى المكون الإضافي dsh-llm-pi-ai، والذي تم توثيقه في كتالوج تكوين المكونات الإضافية للمستودع على أنه يحتوي على "مسارات المزود التي يمتلكها هذا المثيل". هذه هي الآلية. الواجهة الموجهة للمستخدم هي كتلة YAML واحدة.

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

توجد المزودات المخصصة في $DSH_HOME/settings.yaml، ويمكنك أيضًا إنشاؤها من واجهة المستخدم الويب ضمن الإعدادات ← النماذج. إليك المثال مباشرة من الوثائق الرسمية:

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]

ما يفعله كل مفتاح:

my-gateway هو معرّف المزود. إنه معرّف دائم، لذا اختر اسمًا يمكنك التعايش معه؛ يتم تعيين اسم العرض الظاهر في واجهة المستخدم بشكل منفصل.
apiKeyEnv يسمي متغير البيئة الذي يحمل مفتاح API الخاص بك. ملف الإعدادات لا يحتوي أبدًا على السر نفسه، فقط هذا المرجع. المزيد حول مكان وجود المفتاح الفعلي أدناه.
api يعلن عن بروتوكول الاتصال. openai-completions هي القيمة الموثقة لنقاط النهاية المتوافقة مع OpenAI، وهذا ما يجعل وعد "أي نموذج" يعمل: تتحدث معظم البوابات، وأوقات التشغيل المحلية، والمزودات المستضافة بهذا البروتوكول.
baseURL هو الجذر الأساسي لنقطة النهاية الذي يرسل النظام الطلبات إليه.
models يسرد معرفات النموذج المتاحة من خلال هذا المزود. يحتاج كل إدخال إلى id واحد على الأقل، والذي يجب أن يتطابق مع ما تتوقعه نقطة النهاية في نص الطلب.
input يعلن عن الأنماط لكل نموذج. النماذج المخصصة افتراضياً هي نصية فقط، لذلك يجب أن يعلن نموذج الرؤية صراحة input: [text, image] وإلا فلن تصل إليه مرفقات الصور. يوجد أيضًا defaultInput على مستوى المسار يحدد قيمة احتياطية لكل نموذج في المزود؛ يتجاوزه input على مستوى النموذج.
compat يحمل مفاتيح التوافق لنقاط النهاية التي تنحرف عن سلوك OpenAI القياسي. تشير الوثائق إلى اثنين: supportsDeveloperRole: false للواجهات الخلفية التي ترفض دور developer، و maxTokensField: max_tokens للواجهات الخلفية التي تريد اسم حقل تحديد الإخراج الأقدم. يمكن تعيين Compat على مستوى المسار أو لكل نموذج.

إحدى الميزات المفيدة التي تستحق المعرفة: عند إضافة مزود مخصص من خلال واجهة المستخدم الويب، يستعلم خيار "جلب النماذج المتاحة" عن مسار GET /models المتوافق مع OpenAI لنقطة النهاية ويملأ قائمة النماذج لك. إذا كانت نقطة النهاية الخاصة بك تنفذ هذا المسار، فإنك تتجنب الكتابة اليدوية.

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

يتم تخزين الأسرار في وضع الكتابة فقط في $DSH_HOME/.credentials.yaml. بعد حفظ مفتاح عبر واجهة المستخدم، يعيد dsh فقط وصفًا محجوبًا؛ لا يتم عرض القيمة الحرفية مرة أخرى أبدًا. يحتوي settings.yaml على مراجع (أسماء apiKeyEnv، واصفات بيانات الاعتماد)، وليس المفاتيح نفسها أبدًا. هذا الفصل يعني أنه يمكنك الالتزام أو مشاركة ملف الإعدادات دون تسريب أي شيء، وتدوير المفتاح دون لمس تكوين المزود.

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

يكشف Ollama عن واجهة برمجة تطبيقات متوافقة مع OpenAI على http://localhost:11434/v1، وهو ما توثقه Ollama في دليل التوافق مع OpenAI الخاص بها. نظرًا لأن dsh يتحدث openai-completions إلى أي عنوان URL أساسي، فإن الاقتران مباشر.

[تحقق: لا تعرض وثائق dsh مثالاً خاصًا بـ Ollama؛ تطبق هذه الوصفة مخطط المزود المخصص الموثق على نقطة نهاية Ollama المتوافقة مع OpenAI والموثقة. اختبر على تثبيتك قبل النشر داخليًا.]

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

ملاحظات حول هذا:

لا يتطلب Ollama مفتاح API محليًا، لكن المخطط يتوقع مرجع بيانات اعتماد، لذا قم بتعيين قيمة وهمية: export OLLAMA_API_KEY=ollama. يتجاهل Ollama أي شيء ترسله.
يجب أن يتطابق id النموذج مع العلامة التي يقدمها Ollama. قم بتشغيل ollama list وانسخ الأسماء بدقة، بما في ذلك العلامة.
اسحب النموذج أولاً (ollama pull gpt-oss:20b) وتأكد من أن الخادم يستجيب قبل توصيله بـ dsh. لقد غطينا الإعداد المحلي الكامل في كيفية تشغيل GPT-OSS باستخدام Ollama، ويعمل نفس النمط للنماذج مفتوحة الوزن الأخرى مثل Kimi K3 إذا كانت أجهزتك تسمح بذلك.

فحص سريع للمنطق يوفر عليك جلسة وكيل مربكة: قم بزيارة http://localhost:11434/v1/models في Apidog قبل لمس تكوين dsh. إذا أعاد هذا الطلب قائمة النماذج الخاصة بك، فإن عنوان URL الأساسي صحيح، والخادم يعمل، و"جلب النماذج المتاحة" في واجهة مستخدم dsh سيعمل أيضًا. إذا لم يعمل، فلن يحل أي قدر من تكوين النظام المشكلة.

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

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

للحصول على مثال مستضاف، اختر بائعًا يوثق توافقه مع OpenAI بدلاً من افتراض وجوده. يقوم Alibaba Cloud Model Studio (DashScope) بذلك: توثق صفحة توافقه مع OpenAI نقطة نهاية /compatible-mode/v1 لنماذج Qwen، مع نطاقات إقليمية خاصة بمساحة العمل (لسنغافورة: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) والمصادقة عبر متغير البيئة DASHSCOPE_API_KEY.

مُطابقة مع مخطط dsh:

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

استبدل {WorkspaceId} بمعرف مساحة العمل الفعلي الخاص بك من وحدة تحكم Model Studio، وتحقق من قائمة نماذج البائع للحصول على المعرفات الحالية؛ نحتفظ بملخص للنماذج الرائدة في دليل API الخاص بـ Qwen 3.8. يمتد نفس النمط إلى أي بائع لديه توافق موثق مع OpenAI: واجهة Kimi API من Moonshot، أو OpenRouter، أو نشر vLLM، أو بوابة شركتك الداخلية. الأجزاء الوحيدة التي تتغير هي baseURL، واسم متغير البيئة، ومعرفات النموذج. إذا قمت بتكوين نماذج مفتوحة المصدر في Codex، فسيبدو هذا مألوفًا؛ تلعب كتلة YAML في dsh نفس الدور الذي يلعبه تكوين model_providers في Codex.

نقطتان خاصتان بنقطة النهاية المستضافة:

إذا رفضت نقطة نهاية البائع الطلبات بأخطاء غريبة حول الأدوار أو حقول الرموز، فهذا هو الغرض من مفاتيح compat. جرب supportsDeveloperRole: false أولاً؛ تسبق تطبيقات OpenAI المتوافقة الأقدم دور developer.
يجب أن تعلن نماذج الرؤية صراحة input: [text, image]، حتى لو كان النموذج المستضاف يدعم الصور. يفترض dsh أنها نصية فقط للنماذج المخصصة ما لم يُذكر خلاف ذلك.

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

لا تحتاج إلى كتلة مخصصة للسحابات الرئيسية. يشحن dsh مزودي كتالوج لـ DeepSeek و Anthropic و OpenAI، حيث يكون الإعداد في الغالب "لصق مفتاح API". تحمل إدخالات الكتالوج المتخصصة تدفقات المصادقة الأصلية الخاصة بها: يستخدم Bedrock بيانات اعتماد AWS، ويريد Vertex مشروع ADC، ويحتاج Azure إلى إصدار API الخاص به، ويصادق Codex عبر OAuth.

مزودو الكتالوج هم المسار ذو الاحتكاك المنخفض عندما تريد فقط Claude أو GPT خلف النظام، وهم كيف سيقوم معظم الناس بتشغيل DeepSeek V4-Pro، الذي وصل إطلاق واجهة برمجة التطبيقات الخاصة به في أغسطس 2026 جنبًا إلى جنب مع النظام نفسه (التفاصيل في api-docs.deepseek.com). المزودون المخصصون مخصصون لكل ما لا يغطيه الكتالوج: أوقات التشغيل المحلية، والبوابات، والبائعين الإقليميين، والمجمعين المتوافقين مع OpenAI.

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

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

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

يعد تثبيت الجلسة هذا مهمًا للتكرارية: عندما تقارن dsh بأنظمة أخرى (فعلنا ذلك بالضبط في DeepSeek Harness vs Claude Code)، يمكنك الوثوق بأن سجل الجلسة يعكس نموذجًا واحدًا، وليس تبادلاً في منتصف التشغيل.

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

baseURL خاطئ أو لا يمكن الوصول إليه. الفشل الأكثر شيوعًا هو الأقل غرابة. تأكد من أن عنوان URL ينتهي حيث يتوقع البروتوكول (عادةً /v1 لنقاط النهاية المتوافقة مع OpenAI، و /compatible-mode/v1 لـ DashScope) وأن طلب GET {baseURL}/models العادي ينجح خارج النظام. هذه هي نقطة الفحص التي تجعل تنزيل Apidog يؤتي ثماره في خمس دقائق: أرسل الطلب بنفس الترويسة (Authorization: Bearer $KEY) التي سيرسلها النظام، واقرأ رمز الحالة الفعلي والجسم بدلاً من خطأ النظام المغلف. إذا كنت تقوم بالتطوير دون اتصال بالإنترنت أو كان البائع غير موثوق به، فقم بمحاكاة استجابات /models و /chat/completions للمزود في Apidog ووجه baseURL إلى المحاكاة أثناء البناء.

متغير بيئة مفقود أو فارغ. apiKeyEnv يسمي متغيرًا؛ لا ينشئ واحدًا. إذا لم يتم تعيين المتغير في البيئة التي يعمل فيها dsh بالفعل، فسيتم إرسال الطلبات دون مصادقة وتعود برمز 401. تذكر أن العملية التي يتم تشغيلها من واجهة المستخدم الرسومية أو مدير الخدمة قد لا ترث ملف تعريف Shell الخاص بك. قم بتشغيل echo $GATEWAY_API_KEY في نفس السياق الذي يطلق dsh web، وليس فقط في طرفية عشوائية.

عدم تطابق نمط الإدخال. تقوم بإرفاق صورة، ولا يراها النموذج أبدًا، أو يحدث خطأ في الطلب. النماذج المخصصة هي نصية فقط بشكل افتراضي. أضف input: [text, image] على إدخال النموذج، أو عيّن defaultInput على مستوى المسار إذا كانت كل النماذج في المزود تتعامل مع الصور.

غرائب البروتوكول. الأخطاء التي تذكر دورًا غير مدعوم أو معلمة رمز مرفوضة تشير إلى مفاتيح التوافق: supportsDeveloperRole: false و maxTokensField: max_tokens هما الموثقان. يمكن أن تُعيّن compat على مستوى المسار أو لكل نموذج.

كل شيء كان يعمل بالأمس. إصدار مطور مبدئي. ثبّت الإصدار الذي تنشره، واقرأ ملاحظات الإصدار قبل الترقية، وتوقع أن يتغير مخطط الإعدادات. مستودع deepseek-harness هو مصدر الحقيقة، وليس أي منشور مدونة، بما في ذلك هذا المنشور.

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

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

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

لا تذكر وثيقة المزودين الرسمية Ollama بالاسم. ما تدعمه هو أي نقطة نهاية تتحدث بروتوكول openai-completions، ويوثق Ollama واجهة برمجة تطبيقات متوافقة مع OpenAI على http://localhost:11434/v1. تجمع الوصفة أعلاه بين النصفين الموثقين؛ اختبرها على تثبيتك، حيث أن dsh هو إصدار مطور مبدئي وقد تتغير المخططات بين الإصدارات.

أين يخزن dsh مفاتيح API الخاصة بي؟

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

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

نعم. اختيار نموذج يحدد الإعداد الافتراضي للجلسات الجديدة فقط؛ تحتفظ كل جلسة موجودة بالنموذج الذي بدأت به. لذا يمكنك تشغيل نموذج رخيص مثل DeepSeek V4-Flash للجلسات الروتينية، ثم تبديل الافتراضي إلى نموذج أثقل لمشكلة صعبة، وتبقى جلساتك السابقة دون مساس.

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

قارن الحمولة الدقيقة. قد يرسل النظام دور developer أو حقل تحديد رمز جديد لا تقبله الواجهة الخلفية الخاصة بك؛ الإصلاحات الموثقة هي supportsDeveloperRole: false و maxTokensField: max_tokens تحت compat. إعادة تشغيل الطلب بشكل النظام في عميل API يوضح لك الحقل الذي يسبب مشكلة في الواجهة الخلفية.