كيفية ربط DeepSeek Harness بواجهات API متعددة النماذج؟ منطق إعداد أربعة بروتوكولات واستخدامها في بوابات مثل APIYI

كيفية ربط DeepSeek Harness بواجهات API متعددة النماذج؟ منطق إعداد أربعة بروتوكولات واستخدامها في بوابات مثل APIYI

ملخص: يستطيع DeepSeek Harness الاتصال ببوابات مثل APIYI عبر «واجهة برمجة تطبيقات النماذج المخصصة». ويقوم المطوّرون بإعداد مزوّد منفصل لكل بروتوكول، وإدخال معرّفات النماذج التي تدعمها البوابة فعليًا، ثم ربط أدوات البحث عبر الإنترنت على نحو مستقل بحسب حاجة المهمة.

يدعم DeepSeek Harness إضافة بوابة API خارجية كمزوّد نماذج مخصص، مع أربعة بروتوكولات متاحة: OpenAI Chat Completions وOpenAI Responses وAnthropic Messages وGemini API. وبناءً على ذلك، يمكن لنسخة واحدة من Harness استدعاء نماذج من عدة شركات في الوقت نفسه عبر بوابة موحّدة مثل APIYI apiyi.com. ويتوقف نجاح الاتصال على أربعة أمور: تطابق البروتوكول مع Base URL، وتطابق معرّف النموذج مع ما تدعمه البوابة، وتوافق معاملات الاستدلال والإخراج، والتخطيط المستقل لأدوات الاتصال بالشبكة.

تشرح الأقسام التالية آلية تكييف النماذج في Harness وموقع البوابة منها، ثم تُنفّذ خطوة بخطوة إعدادًا واحدًا لمزوّد مخصص وفقًا لواجهة الإعدادات، مع تقديم قالب ملف إعدادات خاص بـ APIYI. بعد ذلك نستعرض مشكلات التوافق وأكواد الأخطاء الأكثر شيوعًا عند نجاح الاتصال بالواجهة وفشل الاستدعاء، ثم نميّز بين مسارين للاتصال بالشبكة: البحث المدمج في خادم DeepSeek، وSearch / Fetch المستقلَّين في APIYI، ونختم بتوصيات حول التصميم الطبقي والنشر لوكيل متعدد النماذج.

deepseek-harness-multi-model-api-gateway-config-ar-image-0

Table of Contents

لمعرفة: مصطلحات ربط النماذج المتعددة في DeepSeek Harness

المصطلح الشرح
Harness إطار تشغيل الوكيل (Agent)، وهو مسؤول عن ربط النماذج، واستدعاء الأدوات، والسياق، والجلسات، وحلقة تنفيذ المهام
API Gateway بوابة توجّه طلبات واجهات API لنماذج متعددة وتديرها بشكل موحّد، وتوفّر مدخلًا واحدًا للتعامل معها
Base URL العنوان الأساسي لطلب API، وتختلف بادئة المسار فيه حسب البروتوكول المستخدم
Provider مزوّد خدمة نموذج يُعدّ داخل Harness، ويقابله مجموعة من العنوان والبروتوكول والمفتاح
Model ID معرّف النموذج المحدد في الطلب، ويجب أن يطابق الاسم الذي توفّره البوابة فعليًا
Chat Completions واجهة إكمال المحادثة على نمط OpenAI، وهي البروتوكول الأكثر شيوعًا في البوابات المتوافقة
Responses API واجهة الاستجابة المهيكلة من OpenAI، الموجّهة لاستدعاء الأدوات والتفاعل على عدة جولات
Anthropic Messages واجهة الرسائل على نمط Anthropic، وهي البروتوكول الأصلي لنماذج سلسلة Claude
Reasoning Effort معامل مستوى تفكير النموذج، مثل off و low و medium و high و max
Tool Calling أن يقرّر النموذج أو الوكيل استدعاء أداة خارجية، ثم يستخدم نتيجتها في الاستدلال اللاحق
Search / Fetch يتولى Search البحث في الويب وإرجاع قائمة بالنتائج، ويتولى Fetch جلب النص الكامل لصفحة ويب محددة
API Key بيان اعتماد للهوية، ويحدد النماذج والواجهات التي يستطيع الطلب الوصول إليها

1 لماذا يُعدّ DeepSeek Harness مناسبًا لربط واجهات نماذج متعددة

1.1 آلية مزوّدي النماذج في DeepSeek Harness

أصدر DeepSeek Harness نسخته مفتوحة المصدر في 13 أغسطس 2026 كإصدار معاينة للمطوّرين، بموجب رخصة MIT، وتقوم بنيته الأساسية على مبدأ «كل شيء إضافة» (Everything is a Plugin). فمحوّلات النماذج والأدوات وSkills وإدارة التخزين والجلسات كلها إضافات قابلة للاستبدال، ولهذا أصبح ربط النماذج بندًا إعداديًا مفتوحًا، لا ارتباطًا بمزوّد واحد مثبّتًا داخل المنتج.

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

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

1.2 دور بوابة API في DeepSeek Harness

من منظور Harness، البوابة ما هي إلا مزوّد (Provider). وأربعة حقول تحدّد مصير كل طلب: عنوان Base URL يشير إلى عنوان البوابة، والبروتوكول يحدّد صيغة الطلب والاستجابة، ومفتاح API يثبت هوية المستدعي، ومعرّف النموذج (Model ID) يخبر البوابة بأي نموذج ينبغي توجيه الطلب إليه.

ولنأخذ APIYI على apiyi.com مثالًا: توفّر المنصّة بمفتاح API واحد نماذج OpenAI وClaude وGemini وDeepSeek، وتفتح ثلاثة مداخل بروتوكول: المتوافق مع OpenAI، وAnthropic الأصلي، وGemini. وفي Harness يكفي إنشاء المزوّد المقابل وفق البروتوكول، ليصبح تبديل النموذج مجرّد تعديل في Model ID، دون حاجة إلى فتح حساب منفصل لكل جهة والحفاظ على مفاتيح متعددة.

deepseek-harness-multi-model-api-gateway-config-ar-image-1

2 إعداد مزوّد نموذج مخصّص من الصفر في DeepSeek Harness

2.1 فتح واجهة إعداد النماذج في DeepSeek Harness

أسرع طريقة لتشغيل Harness محليًا هي أمر npm الرسمي، ويتطلب ذلك تثبيت Node.js مسبقًا:

npx @deepseek-ai/dsh web
# يفتح واجهة الويب المحلية افتراضيًا: http://127.0.0.1:3080

بعد الدخول إلى الواجهة، اضغط بالترتيب على الإعدادات ← النماذج ← إضافة مزوّد نموذج ← واجهة API لنموذج مخصّص، وستظهر لك استمارة إعداد المزوّد. يوفّر الإصدار المكتبي الرسمي حزم تنصيب لنظامي macOS Apple Silicon وWindows 64 بت، ومسار الإعداد هو نفسه في الحالتين.

2.2 إدخال معلومات مزوّد DeepSeek Harness

عنصر الإعداد الوظيفة نقاط الإدخال
Provider ID معرّف فريد للمزوّد يجب أن يكون بحروف صغيرة، ولا يمكن إعادة تسميته بعد الإنشاء، مثل apiyi
اسم العرض الاسم الظاهر في قائمة النماذج يمكن كتابته “APIYI متوافق مع OpenAI”
بروتوكول API تنسيق الطلب والاستجابة يجب أن يطابق Base URL، انظر 2.3
Base URL عنوان خدمة API انتبه إلى بادئة الإصدار، انظر 2.4
مفتاح API بيانات اعتماد المصادقة يُحفظ في ملف بيانات الاعتماد، وتعرض الواجهة معاينة مقنّعة فقط
Model ID اسم النموذج الذي يُستدعى فعليًا يجب أن يطابق قائمة نماذج البوابة تمامًا
نافذة السياق / الحد الأقصى لرموز الإخراج طول السياق والحد الأقصى للإخراج املأه حسب المواصفات الفعلية للنموذج
نوع الإدخال إدخال نصي أو صور لا تضع علامة على الصور إلا في النماذج البصرية
جهد الاستدلال مستوى التفكير وتعيين المعاملات أضف فقط المستويات التي يدعمها النموذج فعلاً

لا يمكن إعادة تسمية Provider ID لأن إعدادات النموذج وجلسات المحادثة السابقة ومراجع بيانات الاعتماد كلها تشير إلى هذا المعرّف. وإذا احتجت إلى التبديل، فأنشئ مزوّدًا جديدًا أولاً ثم احذف القديم.

يحاول زر “جلب النماذج المتاحة” في النموذج قراءة قائمة النماذج من البوابة. وإذا كانت البوابة لا توفر قائمة نماذج قياسية، أو كان تنسيق الاستجابة خارج نطاق ما يتعرّف عليه Harness، فما عليك إلا إضافة Model ID يدويًا، والنتيجة هي نفسها.

2.3 اختيار بروتوكول API لـ DeepSeek Harness

تدعم واجهة برمجة تطبيقات النماذج المخصصة في Harness أربعة بروتوكولات: OpenAI Chat Completions، وOpenAI Responses، وAnthropic Messages، وGemini API. يمكن ربط كل مزود ببروتوكول واحد فقط، وإذا كانت البوابة نفسها تتيح مداخل لثلاثة بروتوكولات، فستحتاج إلى إنشاء ثلاثة مزودين.

يتبع اختيار البروتوكول عائلة النموذج. أكثر ما يضمن الاستقرار هو استخدام OpenAI Chat Completions مع GPT وDeepSeek ومعظم النماذج الصينية المحلية؛ ويمكن لسلسلة Claude اختيار Anthropic Messages للحفاظ على الميزات الأصلية؛ وتستخدم سلسلة Gemini بروتوكول Gemini API. يناسب بروتوكول Responses السيناريوهات التي تحتاج إلى استجابات منظمة واستدعاء الأدوات، بشرط أن تدعم البوابة والنموذج المستهدف هذه الواجهة.

2.4 إعداد نسخة DeepSeek Harness باستخدام APIYI

توضح APIYI العلاقة بين البروتوكول وعنوان Base URL كما يلي:

البروتوكول عنوان Base URL في APIYI النماذج المناسبة المنصات المتاحة
متوافق مع OpenAI (Chat Completions) https://api.apiyi.com/v1 GPT وDeepSeek وغيرها APIYI apiyi.com وواجهات API الرسمية لكل مزوّد
Anthropic الأصلي https://api.apiyi.com سلسلة Claude APIYI وAnthropic الرسمي
Gemini https://api.apiyi.com/v1beta سلسلة Gemini APIYI وGoogle الرسمي

يستخدم بروتوكول Anthropic النطاق الجذري، ويتولى المحوّل بناء المسار اللاحق بنفسه. وإذا أضفت /v1 بعد النطاق الجذري فقد يتكرر المسار وتصلك استجابة 404. أما طريقة ربط بروتوكول Responses فيمكنك الرجوع إلى وثائق APIYI Responses API والتأكد منها قبل الكتابة.

إلى جانب الإعداد عبر الواجهة، يدعم Harness أيضًا تعديل ملف الإعداد يدويًا، وموقعه $DSH_HOME/profiles/web/cordis.patch.yml. وفيما يلي قالب مزوّد متوافق مع OpenAI في APIYI، مكتوب وفق بنية الإعداد الرسمية:

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY          # قراءة المفتاح من متغير البيئة
        api: openai-completions           # بروتوكول OpenAI Chat Completions
        baseURL: https://api.apiyi.com/v1 # مدخل APIYI المتوافق مع OpenAI
        models:
          - id: MODEL_ID_FROM_APIYI       # استبدله بمعرّف النموذج المتاح فعليًا في حسابك

خطوات الاستخدام:

  1. اضبط متغير البيئة APIYI_API_KEY؛
  2. استبدل MODEL_ID_FROM_APIYI باسم النموذج المتاح فعليًا في لوحة تحكم APIYI؛
  3. احفظ الإعداد، ثم اختر المزوّد apiyi والنموذج المقابل في منتقي النماذج داخل Harness؛
  4. ابدأ محادثة بسيطة للتأكد من أن الواجهة تعمل بشكل سليم.

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

قبل الربط مع Harness، يُستحسن التحقق من المفتاح ومعرّف النموذج بشكل منفصل عبر سكربت، بحيث تفصل بين مشكلتين: «هل البوابة تعمل» و«هل إعداد Harness صحيح»:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"  # مدخل APIYI apiyi.com المتوافق مع OpenAI
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_APIYI",  # حافظ على تطابقه مع Model ID المكتوب في Harness
    messages=[{"role": "user", "content": "عرّف عن نفسك في جملة واحدة"}],
    max_tokens=100
)
print(resp.choices[0].message.content)

🚀 نصيحة للبدء السريع: يمكن للمستخدمين الجدد التسجيل في APIYI apiyi.com والحصول على حصة تجريبية مجانية، ثم التحقق أولاً من أن معرّف النموذج متاح عبر السكربت أعلاه قبل كتابة إعداد Harness، فهذا يقصّر زمن استكشاف الأخطاء كثيرًا.


3 واجهة DeepSeek Harness قابلة للاتصال، فلماذا قد يفشل استدعاء النموذج رغم ذلك

توضح وثائق Harness الرسمية أنه حتى إذا كان عنوان API والمفتاح صحيحين، فقد ترفض البوابة الطلب. والسبب أن الواجهات المتوافقة المختلفة تختلف في متطلباتها بشأن أدوار الرسائل وطول المخرجات ومعاملات التفكير. تُستخدم معاملات compat الثلاثة التالية لمعالجة هذا النوع من المشكلات، ويُفعَّل كل منها حسب الخطأ الذي تعيده الواجهة فعليًا.

3.1 توافق دور المطوّر

أدخلت مواصفات OpenAI الجديدة الدور role: developer، لكن بعض البوابات المتوافقة لا تقبل إلا system. إذا ظهرت حالة «فشل جميع الطلبات» أو «فشل نماذج الاستدلال فقط»، فيمكن تعطيل دور developer:

compat:
  supportsDeveloperRole: false

بعد تفعيل هذا الخيار، يعدّل المهايئ طريقة التعامل مع الأدوار في الطلب، بحيث يصبح الطلب بالصيغة التي تقبلها البوابة.

3.2 توافق معامل الحد الأقصى للإخراج

تستخدم واجهة OpenAI الجديدة الاسم max_completion_tokens للتعبير عن الحد الأقصى للإخراج، بينما تقبل بعض البوابات الاسم التقليدي max_tokens فقط. المعنى واحد، لكن اختلاف اسم الحقل يؤدي إلى فشل التحقق من المعاملات. الإعداد المقابل هو:

compat:
  maxTokensField: max_tokens

3.3 توافق وضع التفكير في DeepSeek

بعض نماذج DeepSeek تفعّل التفكير افتراضيًا. عند ضبط مستوى الاستدلال على off داخل Harness، فإن بعض البروتوكولات المتوافقة تكتفي بحذف معامل الاستدلال، فيواصل النموذج التفكير وفق سلوكه الافتراضي، ما يسبب مشكلة «off لا يوقف التفكير». لذلك وفّرت الجهة الرسمية صيغة تفكير مخصّصة لـ DeepSeek:

compat:
  thinkingFormat: deepseek

بعد تفعيلها، يرسل المحوّل صراحةً {"thinking": {"type": "disabled"}} عند إيقاف التفكير، ويرسل {"thinking": {"type": "enabled"}} عند تفعيله. المثال الرسمي موجّه لنموذج DeepSeek V4 خلف بوابة متوافقة مع OpenAI. وفي بوابة متعددة النماذج يمكن ضبط هذا المعامل لنماذج DeepSeek وحدها، مع إبقاء النماذج مثل GPT وClaude على الإعداد الافتراضي.

أما بالنسبة لمستويات الاستدلال، فيسمح Harness بربط قيم off وlow وmedium وhigh وmax المعروضة في الواجهة بقيم المعاملات التي تقبلها API فعليًا. وإضافة المستويات التي يدعمها النموذج فعليًا فقط إلى الإعداد تحمي من فشل الطلب عندما يختار المستخدم مستوى غير صالح. وفيما يلي مثال كامل بعد دمج معاملات التوافق الثلاثة:

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY
        api: openai-completions
        baseURL: https://api.apiyi.com/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: MODEL_ID_FROM_APIYI

3.4 استكشاف سريع للأخطاء الشائعة في DeepSeek Harness

الخطأ أو العرض السبب المحتمل طريقة المعالجة
MISSING_CREDENTIAL المفتاح غير مُهيّأ تحقّق من مفتاح API واسم متغيّر البيئة
UNKNOWN_MODEL معرّف النموذج غير مسجّل أضف معرّف النموذج الصحيح لدى المزوّد
HTTP 401 المفتاح غير صالح أو الصلاحيات غير كافية راجع محتوى المفتاح والمجموعة التي ينتمي إليها
HTTP 404 مسار Base URL خاطئ راجع البروتوكول وبادئة الإصدار (/v1، النطاق الجذري، /v1beta)
قائمة النماذج فارغة البوابة لا تدعم واجهة قائمة النماذج القياسية أضف معرّف النموذج يدويًا
فشل جميع الطلبات تعارض في تنسيق الدور أو المعلمات تحقّق من معلمات التوافق compat
فشل نماذج الاستدلال فقط دور Developer غير متوافق اضبط supportsDeveloperRole: false
off لا يوقف التفكير النموذج يفعّل التفكير افتراضيًا اضبط thinkingFormat: deepseek
واجهة البحث تُرجع 503 مجموعة الرمز لا تملك صلاحية الأدوات استبدل الرمز برمز من مجموعة default أو svip
المحادثة تعمل لكن الاتصال بالإنترنت غير متاح أداة البحث غير مدمجة أو البروتوكول غير مدعوم تحقّق من قدرات الأدوات وإعدادات العميل

تستند البنود الثمانية الأولى إلى وثائق إعداد Harness الرسمية، أما المشكلات المتعلقة بالمجموعات فمصدرها وثائق APIYI الرسمية. ويُفضّل أن يكون ترتيب الاستكشاف من الأعلى إلى الأسفل: تأكّد من بيانات الاعتماد أولاً، ثم من معرّف النموذج، ثم من المسار، وأخيرًا من توافق المعلمات.


4 إضافة قدرة البحث عبر الإنترنت إلى DeepSeek Harness

4.1 التمييز بين البحث المدمج في النموذج وواجهة برمجة البحث المستقلة

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

توجد مساران تقنيان لقدرة الاتصال بالإنترنت في منظومة DeepSeek:

deepseek-harness-multi-model-api-gateway-config-ar-image-2

البعد المسار A: أداة من جانب الخادم مدمجة في النموذج المسار B: واجهة Search / Fetch مستقلة
طريقة الاستدعاء إعلان deepseek_web_search وdeepseek_read_url داخل طلب المحادثة يطلب البرنامج بنفسه /v1/tools/search و/v1/tools/fetch
من يقرر البحث النموذج يقرر بنفسه المطوّر أو منطق أدوات الـ Agent
تنفيذ الأداة ينفّذ خادم DeepSeek البحث وتركيب السياق يتولى العميل معالجة النتائج بنفسه بعد استلامها
نطاق النماذج الإعلان الرسمي يوجّه صراحةً إلى deepseek-flash مستقل عن النموذج، ويمكن لأي نموذج إعادة استخدام النتائج
أساس الفوترة تُحتسب حسب عدد كلمات البحث الفعلية وعدد صفحات الويب المسحوبة وغيرها تُحتسب حسب عدد الطلبات الناجحة، ولا تستهلك Tokens النموذج
القنوات المتاحة حاليًا واجهة DeepSeek الرسمية واجهة DeepSeek الرسمية و APIYI

4.2 كيف يعمل البحث المدمج في النموذج

في 13 نوفمبر 2026، أتاح DeepSeek عددًا من القدرات التطبيقية التي تعمل خلف تطبيق App، ومن بينها البحث عبر الإنترنت وقراءة الروابط، وذلك في صورة أدوات من جانب الخادم. يكفي أن تعلن عنها ضمن قائمة الأدوات في الطلب:

[
  {"type": "deepseek_web_search", "name": "deepseek_web_search"},
  {"type": "deepseek_read_url", "name": "deepseek_read_url"}
]

بعد الإعلان عنها، يقرر النموذج بنفسه ما إذا كان يحتاج إلى الاتصال بالإنترنت، ويولّد كلمات البحث، ثم ينفّذ خادم DeepSeek البحث ويعيد إجابة تتضمن مراجع المصادر. وعند تفعيل وضع التفكير، يتحول البحث إلى مسار متعدد الخطوات، فيستطيع النموذج البحث عن عدة كلمات مفتاحية، وفتح صفحات الويب، والبحث داخل الصفحة، والتحقق المتقاطع من المعلومات؛ وتشير الوثائق الرسمية إلى أنه يجيب بعد نحو 20 استدعاءً للأداة على الأكثر. ولا يتعرف deepseek_read_url إلا على عناوين URL الواردة في آخر رسالة مستخدم، مع مراعاة 10 روابط مختلفة كحد أقصى.

لا يزال يتعين على المطورين التعامل مع كتل المحتوى المعادة، ومعلومات الاقتباس، وأحداث البث، وسجل المحادثة متعدد الجولات. ووفقًا للإعلان الرسمي، يتولى deepseek-flash (DeepSeek-V4.1-Flash) دعم هذا التكامل الكامل لأدوات على مستوى المحادثة. ووفقًا لوثائق APIYI، لا يزال العمل على دعم الاستدعاء المتوافق لهذا النوع من البحث المدمج عبر البوابة من عملاء مثل Harness وClaude Code قيد التخطيط في مراحل لاحقة؛ وللاستفادة من المسار A حاليًا، ينبغي الاتصال مباشرة بواجهة API الرسمية لـ DeepSeek.

4.3 تكامل APIYI المستقل مع Search / Fetch

أصدرت APIYI في 21 أكتوبر 2026 واجهتين مستقلتين لأدوات DeepSeek Search & Fetch، وهما deepseek-search وdeepseek-fetch. تعيد Search نتائج بحث منظمة، بينما يجلب Fetch صفحة ويب محددة ويعيد نصها الأساسي بصيغة Markdown. لا تتطلب الطلبات تمرير معرّف النموذج، ولا تستهلك رموز النموذج (Tokens)، ويُحتسب السعر حسب عدد الاستدعاءات الناجحة.

يبحث المثال التالي أولاً، ثم يجلب صفحة الويب الأولى في ترتيب النتائج:

import os
import requests

BASE = "https://api.apiyi.com/v1/tools"  # واجهة الأدوات المستقلة في APIYI
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

search = requests.post(
    f"{BASE}/search",
    headers=headers,
    json={"query": "DeepSeek Harness 插件", "count": 5},
    timeout=60,
)
search.raise_for_status()
results = search.json()["results"]

if results:
    url = results[0]["url"]
    fetch = requests.post(
        f"{BASE}/fetch",
        headers=headers,
        json={"url": url},
        timeout=60,
    )
    if fetch.ok:
        print(fetch.json()["content"])

تحتاج مجموعات الرموز إلى انتباه خاص: تستطيع مجموعتا default وsvip استدعاء هاتين الواجهتين، بينما لا تستطيع رموز مجموعة ClaudeCode استدعاءهما مباشرة، وقد وثّقت الوثائق حالات إرجاع 503. تُظهر الاختبارات الذاتية في وثائق APIYI أن Search يعيد 5 نتائج خلال نحو 1.8 ثانية، وأن 20 طلبًا متزامنًا أعادت جميعها الرمز 200؛ بينما يفشل Fetch عند الوصول إلى صفحة غير قابلة للوصول ولا يتم خصم أي رسوم. هذه البيانات من اختبارات المنصة نفسها، وقد يتأثر الأداء الفعلي بالشبكة والموقع المستهدف. أما السعر، فتذكر الوثائق أن سعر المنصة هو $0.90 لكل 1000 استدعاء، ويصبح المبلغ المدفوع فعليًا أقل عند إضافة مكافأة إعادة الشحن، والمرجع النهائي هو لوحة التحكم.

لكي يتمكن الوكيل (Agent) في Harness من استخدام هذا المنطق تلقائيًا، يجب تغليفه كإضافة أداة. تُكتب إضافات Harness بلغة TypeScript، وتُسجّل الأدوات عبر كائن السياق ctx، وعند إلغاء تحميل الإضافة يزيل الإطار تلقائيًا الأدوات والأحداث المسجّلة. يُوصى عند التغليف بتسجيل search وfetch كأداتين مستقلتين، بحيث يحصل النموذج أولاً على قائمة النتائج، ثم يقرر أي الصفحات سيجلب.

💡 نصيحة تقنية: Search / Fetch المستقلان منفصلان عن النموذج، ويمكن تسليم النتائج البحثية نفسها إلى نماذج مختلفة مثل GPT وClaude وDeepSeek لمعالجتها. ومن خلال APIYI على apiyi.com يمكن إدارة استدعاءات النماذج وأدوات البحث معًا باستخدام مفتاح واحد، مما يسهّل في Harness مقارنة جودة إجابات النماذج المختلفة استنادًا إلى المصادر نفسها.


5 كيف ينبغي تصميم Harness متعدد النماذج لـ DeepSeek

5.1 اختيار النماذج المختلفة وفقًا للمهمة

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

وباستخدام نماذج DeepSeek الرسمية كمثال، فإن DeepSeek-V4.1-Flash يدعم فهم الصور، بينما لا يدعم DeepSeek-V4-Pro ذلك، كما تختلف أسعارهما عدة أضعاف. ويمكن في Harness إعدادهما كمعرّفَي Model ID تحت المزود نفسه، والتبديل بينهما حسب المهمة داخل الجلسة، بما يحقق التوازن بين الجودة والتكلفة.

5.2 الإدارة الطبقية لاستدعاء نموذج DeepSeek Harness وقدرات البحث

deepseek-harness-multi-model-api-gateway-config-ar-image-3

يقسم الهيكل المقترح إلى ثلاث طبقات. طبقة التنفيذ يتولاها Harness، وهي مسؤولة عن حلقة المهام وضغط السياق وتحميل الإضافات والتحكم في الأذونات؛ وطبقة النماذج تتولاها بوابة API، وهي مسؤولة عن تحويل البروتوكولات وتوجيه النماذج والفوترة؛ أما طبقة الأدوات فتقدّمها واجهات مستقلة مثل Search / Fetch لتوفير المعلومات الخارجية. وكل طبقة من الطبقات الثلاث قابلة للاستبدال على حدة: فاستبدال النموذج لا يحتاج إلا إلى تغيير Model ID، واستبدال خدمة البحث لا يحتاج إلا إلى تغيير إضافة الأداة، بينما يبقى منطق التنفيذ كما هو دون تغيير.

ويأتي هذا التقسيم الطبقي بفائدة أمنية إضافية. فقد أظهر تقييم مُتحكَّم به أجراه مختبر Zhuque التابع لشركة Tencent على Harness أن المحتوى غير الموثوق، مثل صفحات الويب والملفات وSkills، قد يؤثر في سلوك الـAgent عبر الحقن غير المباشر للموجهات. وبعد فصل طبقة الأدوات عن طبقة التنفيذ، أصبح من الممكن إدخال حلقة تصفية وتأكيد موحّدة قبل أن تصل نتائج البحث إلى السياق وقبل تنفيذ الأدوات الحساسة.

5.3 توصيات النشر العملي لـ DeepSeek Harness

  1. إعداد النماذج: كل بروتوكول يقابل مزودًا واحدًا، ويُكتب Provider ID بأحرف صغيرة ويُثبَّت من أول مرة؛ أما معرّفات النماذج فتُنسخ دائمًا من لوحة تحكم البوابة.
  2. إدارة المفاتيح: يخزّن Harness المفاتيح في $DSH_HOME/.credentials.yaml، وملف الإعدادات يكتفي بالإشارة إلى متغيرات البيئة، حتى لا يتسرّب المفتاح كنص صريح إلى إعدادات مشتركة أو مستودعات الشيفرة.
  3. اختبار التوافق: عند إضافة أي نموذج جديد، تحقّق بالترتيب من المحادثة العادية، ثم إيقاف التفكير، ثم المخرجات الطويلة، ثم إدخال الصور، وبعدها فعّل معامل compat وفقًا لرسالة الخطأ.
  4. استدعاء الأدوات: احرص على تقليل عدد الإضافات. تشير ملاحظات المجتمع إلى أنه بعد تثبيت أكثر من عشرة إضافات قد يحدث تجاوز لنافذة السياق وارتفاع في استهلاك الـ Tokens، كما أن الإبقاء على وصف مختصر لأدوات البحث يعطي نتائج أكثر استقرارًا.
  5. تسجيل التكاليف: تُحاسب Tokens النموذج واستدعاءات الأدوات بشكل منفصل، ويُفضّل إحصاء كل منهما على حدة في لوحة تحكم البوابة. تتيح لوحة تحكم APIYI على apiyi.com عرض الاستخدام حسب المفتاح، وهي مناسبة لتخصيص مفتاح مستقل لكل Agent بغرض تتبع التكلفة.

كذلك، احتفظ بنسخة احتياطية من الإعدادات الموجودة تحت $DSH_HOME قبل ترقية Harness. فقد سجّل المجتمع حالة ضاعت فيها إعدادات إضافات طرف ثالث بعد ترقية إصدار، واستغرقت استعادتها عدة ساعات.


الأسئلة الشائعة (FAQ)

س1: هل يقتصر DeepSeek Harness على نماذج DeepSeek فقط؟

يدعم Harness الاتصال بأي خدمة متوافقة مع أحد البروتوكولات الأربعة عبر واجهة برمجة نماذج مخصّصة (Custom Model API)، بما في ذلك سلاسل OpenAI وClaude وGemini ومختلف بوابات API وخدمات النماذج ذاتية الاستضافة. نماذج DeepSeek الرسمية ليست سوى خيار واحد من بينها.

س2: لماذا أنشئ عدة مزوّدين لنفس البوابة؟

يفرض Harness أن يرتبط كل مزوّد ببروتوكول واحد فقط. وتفتح APIYI ثلاث نقاط دخول في آنٍ واحد: المتوافقة مع OpenAI، وAnthropic، وGemini. فإذا أردت استدعاء GPT وClaude وGemini كلٌّ ببروتوكوله الأصلي، ستحتاج إلى إنشاء ثلاثة مزوّدين، بحيث يكون Base URL لكل منها `/v1` والنطاق الجذري و`/v1beta` على الترتيب.

س3: كيف أتأكد من مُعرّف النموذج (Model ID) الذي يجب أن أُدخله؟

جرّب أولاً ميزة «الحصول على النماذج المتاحة»؛ وإذا تعذّرت القراءة، فانسخ الاسم الدقيق من قائمة النماذج في لوحة تحكم APIYI على apiyi.com وأضفه يدويًا. مُعرّف النموذج حسّاس لحالة الأحرف وللاحقة الإصدار، وأي اختلاف سيؤدي إلى UNKNOWN_MODEL أو إلى خطأ من البوابة.

س4: بعد الاتصال عبر APIYI، هل يمكن استخدام deepseek_web_search مباشرة؟

تدعم APIYI حاليًا واجهتي Search / Fetch المستقلتين لدى DeepSeek، ولا يزال العمل على توافق استدعاء البحث المدمج في النموذج عبر عملاء مثل Harness قيد التخطيط. في هذه المرحلة نوصي بتغليف `/v1/tools/search` و`/v1/tools/fetch` من APIYI كأدوات لـ Agent؛ وإذا كنت بحاجة إلى البحث المدمج، فاتصل مباشرة بواجهة DeepSeek الرسمية.

س5: واجهة البحث تُرجع 503 بينما المحادثة تعمل بشكل طبيعي، فما السبب؟

السبب الأكثر شيوعًا هو مجموعة الرموز (Token group). فرموز مجموعة ClaudeCode لا تستطيع استدعاء واجهات الأدوات المستقلة مباشرة، ويكفي استبدالها بمفتاح من مجموعة default أو svip. يمكنك في لوحة تحكم APIYI على apiyi.com إنشاء رمز من المجموعة المناسبة لأداة البحث على حدة، وإدارته بشكل منفصل عن مفتاح استدعاء النموذج.

س6: ما القيود التي يفرضها DeepSeek Harness عند ربط عدة نماذج؟

لا يزال Harness نسخة معاينة للمطوّرين، وقد يتغيّر بنية الإعداد مع تغيّر الإصدارات؛ كما تختلف درجة تمرير Responses ومعاملات الاستدلال وبروتوكولات الأدوات من بوابة إلى أخرى، ما يتطلب التحقّق من كل نموذج على حدة. الإفراط في الإضافات يرفع تكلفة السياق والرموز (Tokens)، كما أن جودة تسليم المهام المعقّدة تعتمد على إعداد الإضافات وإدارة عملية التنفيذ.


الخلاصة

آلية تكييف النماذج المفتوحة في DeepSeek Harness تتيح لإطار Agent واحد استدعاء نماذج من عدة شركات عبر بوابة موحّدة. عند التطبيق العملي، احرص على النقاط التالية:

  1. البروتوكول يحدد المزوّد: أنشئ Provider واحدًا لكل بروتوكول، ويجب أن تتوافق بادئة الإصدار في Base URL مع البروتوكول بدقة.
  2. انسخ معرّف النموذج من البوابة: انسخه من لوحة التحكم، وإذا تعذّر قراءة القائمة فأضفه يدويًا.
  3. فعّل المعاملات المتوافقة عند الحاجة: تغطي ثلاثة عناصر — دور developer، والحقل max_tokens، وصيغة تفكير DeepSeek — معظم مشكلات «يمكن الاتصال ولكن لا يمكن الاستخدام».
  4. خطّط لقدرة الاتصال بالإنترنت بشكل منفصل: البحث المدمج يستخدم API DeepSeek الرسمي، بينما يمكن استدعاء Search / Fetch المستقلين عبر البوابة وتغليفهما كأدوات.
  5. الفصل والحوكمة: افصل طبقة التنفيذ وطبقة النموذج وطبقة الأدوات، وأدر المفاتيح والإصدارات والتكلفة كلًا على حدة.

يُوصى أولاً بتشغيل نموذج واحد لإتمام «التحقق عبر السكربت → إعداد Harness → محادثة بسيطة»، ثم إضافة المزيد من النماذج وأدوات البحث تدريجيًا. ونوصي بالحصول على رصيد اختبار مجاني عبر APIYI apiyi.com، وإتمام التحقق الشامل من النماذج المتعددة وSearch / Fetch باستخدام مفتاح API واحد.


📚 المراجع

  1. وثائق DeepSeek Harness لإعداد النماذج: حقول المزوّد المخصص ومعاملات التوافق compat
  2. الرابط: deepseek-harness.github.io/deepseek-harness/guide/providers
  3. الوصف: الشرح الرسمي لـ supportsDeveloperRole وmaxTokensField وthinkingFormat

  4. مستودع DeepSeek Harness على GitHub: الشيفرة المصدرية وإصدارات Releases وطريقة التشغيل

  5. الرابط: github.com/deepseek-ai/deepseek-harness
  6. الوصف: تحديثات الإصدارات وملاحظات مرحلة المعاينة للمطورين

  7. وثائق أدوات البحث عبر الإنترنت في DeepSeek: deepseek_web_search وdeepseek_read_url

  8. الرابط: api-docs.deepseek.com/zh-cn/guides/web_tools/
  9. الوصف: طريقة تعريف البحث المدمج وقيوده ومعايير الفوترة

  10. دليل إعداد Base URL في APIYI: شرح مسارات البروتوكولات الثلاثة

  11. الرابط: help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html
  12. الوصف: حالات استخدام /v1 والنطاق الجذري و/v1beta

  13. وثائق DeepSeek Search & Fetch في APIYI: واجهات الأدوات المستقلة ومتطلبات التجميع

  14. الرابط: docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview
  15. الوصف: معاملات الطلب وتجميع الرموز (Tokens) وتفاصيل الفوترة

المؤلف: فريق APIYI التقني
للتواصل التقني: إذا واجهت أي مشكلة أثناء عملية الإعداد، يمكنك التواصل معنا عبر الصفحة الرئيسية لموقع APIYI على apiyi.com، ولمزيد من تفاصيل الواجهات يمكنك مراجعة مركز الوثائق docs.apiyi.com

مقالات ذات صلة

موضوعات ذات صلة