مزودو النماذج

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

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

ما الذي يفعله إعداد المزود

EstaCoda تحمل إعداد المزود من ملف config.json الخاص بالملف الشخصي النشط. كحد أدنى، يحتاج مسار المزود إلى:

provider — معرف المزود
model — اسم النموذج

تحتاج المسارات التي تستخدم اعتمادًا أيضًا إلى apiKeyEnv، وهو متغير البيئة الذي يحتوي على مفتاح API. المسارات بلا اعتماد، مثل المسار الافتراضي للمزود local، يمكنها حذف هذا الحقل.

مثال للمسار الرئيسي:

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKeyEnv": "OPENAI_API_KEY"
  }
}

في وقت التشغيل، تقرأ EstaCoda process.env[apiKeyEnv] للمسارات التي تستخدم اعتمادًا وتمرره إلى منفذ المزود. المفتاح لا يُخزّن أبدًا في config.json. إذا كان مسار يعتمد على متغير بيئة مفقود، فإن المسار غير قابل للتشغيل وسيخبرك تدفق الإعداد بالضبط أي متغير غير موجود. المسارات المضبوطة بـ authMethod: "none" لا تحتاج بيانات اعتماد.

نقطة نهاية محلية / مخصصة

المزود المدمج local هو المسار البسيط لنقاط النهاية المحلية أو المخصصة المتوافقة مع OpenAI. يعمل هذا المسار مع أدوات مثل Ollama وLM Studio وخادم llama.cpp وvLLM وLiteLLM أو بوابة داخلية متوافقة مع OpenAI عندما تعرض نقطة النهاية شكل API المتوقع تحت /v1.

القيم الافتراضية:

معرف المزود: local
عنوان الأساس: http://localhost:11434/v1
الاعتماد: لا يتطلب مفتاح API
متغير مفتاح API الاختياري: OPENAI_COMPATIBLE_API_KEY

estacoda model setup local --base-url http://localhost:1234/v1 --model qwen2.5-coder
estacoda model setup local --base-url http://localhost:1234/v1 --model private-model --api-key <key>

عند تمرير --api-key، يخزن الإعداد المفتاح الخام فقط في ملف .env للملف الشخصي المختار باسم OPENAI_COMPATIBLE_API_KEY، ويخزن في الإعداد مرجع متغير البيئة فقط. عند عدم تمرير مفتاح، يبقى local مسارًا بلا اعتماد.

استخدم estacoda model setup custom عندما تحتاج معرف مزود OpenAI-compatible منفصلًا بدل استخدام المسار المدمج local.

في Setup Editor، اختر Local / Custom من منتقي النموذج الأساسي أو الاحتياطي أو المساعد لاستخدام تدفق نقطة النهاية نفسه. تؤكد EstaCoda نقطة نهاية الاستدلال أولًا، ثم تكتشف النماذج من /models عند توفرها، وتتيح اختيار نموذج مكتشف أو إدخال معرّف النموذج يدويًا، ثم تجمع المصادقة الاختيارية وتعرض اختبار إكمال محادثة قبل خطوة التطبيق بعد المراجعة.

في الجلسة التفاعلية، استخدم /providers لإعداد المزوّدين وحالتهم. يبقى /model أمر فحص النموذج النشط أو تغييره، و/models ليس أمرًا مائلًا؛ إنه فقط مسار HTTP API المتوافق مع OpenAI المستخدم أثناء اكتشاف نقطة النهاية.

كتالوج النماذج والاكتشاف

تحتفظ EstaCoda بكتالوج نماذج محلي مستند إلى بيانات تعريف models.dev. الكتالوج يعرف قدرات المزود، ونوافذ السياق، وتلميحات التسعير. لا يجلب البيانات عبر الشبكة إلا إذا مكّنت تحديث الكتالوج عبر الشبكة صراحةً.

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

المسار الرئيسي

المسار الرئيسي هو النموذج الذي تستخدمه EstaCoda للاستدلال العادي. يُعرّف تحت model في إعداد الملف الشخصي.

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

مسارات الاحتياطي

مسارات الاحتياطي تُهيأ تحت model.fallbacks. هي مرتبة. تحاول EstaCoda كل احتياطي فقط عندما يفشل المسار الرئيسي في وقت التنفيذ، وليس في وقت تحميل الإعداد.

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKeyEnv": "OPENAI_API_KEY",
    "fallbacks": [
      { "provider": "deepseek", "model": "deepseek-chat", "apiKeyEnv": "DEEPSEEK_API_KEY" }
    ]
  }
}

تحتفظ مسارات الاحتياطي ببيانات التعريف apiKeyEnv و baseUrl و apiMode و authMethod عند توفرها. يُسجّل تقييم الاحتياطي. إذا فشلت جميع الاحتياطات، يُبلغ الدور عن الخطأ ويتوقف.

مسارات الاحتياطي قابلة للإدارة عبر محرّر الإعدادات (edit-fallback-model-route) وعبر estacoda model fallback ....

الإنهاء، والبث، واستدعاءات الأدوات

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

أسباب الإنهاء الموحدة هي:

سبب الإنهاء	المعنى في وقت التشغيل
`stop`	اكتمال عادي.
`length`	توقف المزود عند حد الخرج. يمكن متابعة النص المرئي؛ أما استدعاءات الأدوات فتُعد غير آمنة حتى تُعاد المحاولة.
`tool_calls`	أنهى المزود استدعاءات الأدوات.
`content_filter`	توقف المزود بسبب سياسة أو ترشيح محتوى.
`incomplete`	أبلغ المزود عن استجابة غير مكتملة.
`unknown`	اكتمل النقل دون سبب إنهاء خاص بالمزود.

تُوحّد بيانات الاستخدام كالتالي: inputTokens وoutputTokens وtotalTokens وreasoningTokens. الحقل reasoningTokens قياس آمن للاستخدام فقط. لا يعني أن التفكير الخام كان متاحًا أو مستخرجًا أو مخزنًا أو معروضًا.

قواعد البث:

تُجمع أجزاء استدعاءات الأدوات المبثوثة محليًا بينما يكون البث مفتوحًا
أخطاء البث تتخلص من أجزاء الأدوات المتراكمة
التدفقات غير المكتملة تبقى إخفاقات مزود
معالجة النقل [DONE] داخلية وليست خرجًا مرئيًا للمستخدم
اكتمال النقل مع نص مرئي فقط قد ينتهي كـ finishReason: "unknown"
اكتمال النقل مع أجزاء أدوات غير منتهية يفشل كـ incomplete-stream
بث Responses API يبقى غير مدعوم ما لم يُنفذ صراحةً لاحقًا

قواعد سلامة استدعاءات الأدوات:

استدعاءات الأدوات المقطوعة بسبب length تُعاد محاولتها مرة واحدة على سلسلة المسار الناجح
إذا بقيت إعادة المحاولة مقطوعة بسبب length مع استدعاءات أدوات، ترفض EstaCoda بشكل حتمي بدلاً من تنفيذ وسائط غير مكتملة
JSON النهائي المشوه للأدوات يبقى خطأ في تخطيط الأدوات، لا فشل مزود
محاولات استدعاء الأدوات المقطوعة والمستبعدة يجب ألا تسرّب الوسائط الخام إلى الأحداث أو التنفيذ

قواعد نظافة التفكير:

التفكير الخام محلي للدور فقط، باستثناء providerReplayEcho المحدود والمستخدم كحالة بروتوكول حساسة لنفس المزود عندما يتطلب مسار إعادة تشغيل أصلي مختبر ذلك
الخرج المرئي يزيل كتل التفكير المخفية
التاريخ المرسل إلى المزود يزيل حقول التفكير افتراضيًا
الملخصات، والضغط الدلالي، والذاكرة، وتعلّم المهارات، والتصديرات تستهلك النص المرئي فقط
بيانات التفكير الآمنة قد تتضمن فقط present وchars وformat
صدى المزود ليس نص واجهة، ولا نص موجه عادي، ولا دخل تلخيص، ولا محتوى تشخيص، ولا ذاكرة، ولا مادة تصدير، ولا سجلات

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

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

تجاوزات نموذج الطفل المفوض

يمكن للمهام المفوضة أن تطلب modelOverride. تجاوزات النموذج على المزود نفسه ومسارات الطفل المراجعة عبر مزود آخر مدعومة لحلقة الطفل فقط. لا تعدّل session override للأب، أو route الأساسي للملف الشخصي، أو fallback routes، أو auxiliary routes، أو provider config.

مسارات الطفل عبر مزود آخر تُبنى من إعداد المزود الهدف بعد التطبيع. تحفظ EstaCoda حقول route الهدف مثل baseUrl، وapiKeyEnv، وapiMode، وauthMethod، وenableNetwork، وtimeoutMs، وstaleTimeoutMs، وتضبط provider preference على المزود الهدف، وتعطل fallback routes لذلك الطفل.

بيانات الاعتماد تأتي من إعداد المزود الحالي وapiKeyEnv. لا تُضاف credential pools. authMethod: "none" لا يحتاج بيانات اعتماد عندما يكون مضبوطًا. بيانات اعتماد env المفقودة وenableNetwork: false تُرفض قبل تنفيذ مزود الطفل. override metadata محدودة ومنقّحة ولا تتضمن raw credentials، أو env values، أو route objects، أو private config paths، أو prompts، أو diagnostic payloads، أو transcripts.

إعادة تشغيل تاريخ استدعاءات الأدوات الأصلي

يمكن لمسارات OpenAI-compatible Chat Completions المدعومة حفظ تاريخ استدعاءات الأدوات الأصلي من المزود. عند تفعيله، ترسل tool_calls السابقة من المساعد وردود tool المطابقة بالشكل البروتوكولي الذي يتوقعه المزود. المسارات غير المدعومة تبقى على fallback النص المسطح.

تنشط إعادة التشغيل الأصلية فقط عندما تتحقق الشروط كلها:

بيانات تعريف المزود تفعّل supportsNativeToolHistory
النموذج يدعم الأدوات
وضع API للمسار هو openai_chat_completions

تبقى مسارات Responses في وضع fallback/deferred لإعادة التشغيل الأصلية. وتبقى إعادة التشغيل الأصلية في Anthropic مؤجلة. المزودون المخصصون أو المعروفون في الكتالوج لا يرثون الدعم لمجرد أن الشكل OpenAI-compatible.

سلامة إعادة التشغيل

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

أمثلة عدم الأمان:

وسائط تحمل أسراراً
غياب argumentsText الصادقة
غياب صدى المزود المطلوب
تجاوز صدى المزود المطلوب للحد
مجموعات أدوات أصلية مشوهة أو غير مكتملة

لا تحفظ الوسائط الحاملة للأسرار بصدق. تحفظ الاستدعاءات المتأثرة argumentsRedacted: true، ويعلّم الدور كـ nativeReplaySafe: false. الأدوار غير الآمنة يبقى لها تاريخ مسطح منظف؛ لكنها لا تصدر رسائل بروتوكول أصلية للمساعد/الأداة.

الميزانية والضغط

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

صدى وضع التفكير

قد تطلب بعض مزودي وضع التفكير، بما في ذلك DeepSeek وKimi في مسارات Chat Completions المختبرة، صدى reasoning_content لأدوار استدعاء الأدوات الأصلية من المساعد. تحفظ EstaCoda ذلك فقط كـ providerReplayEcho محدود.

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

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

التشخيصات

تشخيصات إعادة التشغيل الأصلية هي أحداث جلسة مستمرة:

structured-tool-history-selected
structured-tool-history-repaired
structured-tool-history-skipped
structured-tool-history-serialized

الحمولات أعداد وأسباب فقط. يجب ألا تتضمن الوسائط، نتائج الأدوات، قيم الصدى، التفكير الخام، حمولات المزود، محتوى الرسائل، المسارات، التجزئات، أجسام الطلبات، أو بصمات المحتوى.

تبديل النموذج أثناء الجلسة

الأمر /model يغيّر النموذج للجلسة الحالية دون تعديل إعداد الملف الشخصي.

/model openai/gpt-4o

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

التغييرات الدائمة تتطلب تفويضًا صريحًا:

/model --global openai/gpt-4o

تُعدّل الكتابات العامة المسار الرئيسي على مستوى الملف الشخصي بعد اجتياز فحوصات الثقة. لا تجمع بيانات الاعتماد داخل جلسة الدردشة. استخدم estacoda model setup لجمع بيانات الاعتماد.

لإزالة تجاوز الجلسة:

/model clear

/model --global clear مرفوض.

مسار إعداد Codex

يمكن إعداد Codex من منتقي النماذج عندما يكون خيار OpenAI المتداخل مفعّلًا:

اختر OpenAI.
اختر Codex.

خيار OpenAI Models هو مسار مفتاح API لنماذج OpenAI العادية. خيار Codex هو مسار OAuth. يستخدم إعداد Codex المزوّد codex، والنموذج الافتراضي gpt-5.5، وطريقة المصادقة oauth_device_pkce، ونمط Responses API (openai_responses). لا يستخدم apiKeyEnv.

يبقى أمر CLI المباشر متاحًا:

estacoda model setup codex

يُشغّل هذا الأمر مصادقة OAuth عبر رمز الجهاز، ويخزّن الرموز في auth.json داخل الملف الشخصي المحدد، ويُهيئ مسار codex/gpt-5.5. لا تُطبع رموز OAuth الخام. يبقى إعداد المسار منفصلاً عن تخزين الرموز.

يمكن لمحرّر الإعدادات ضبط Codex للمسار الأساسي ومسارات الاحتياطي عبر تطبيق مُراجع. رموز OAuth التي يجمعها محرّر الإعدادات لا تُكتب إلا بعد موافقة المراجعة؛ إلغاء المراجعة بعد OAuth لا يحفظ الرموز.

يستخدم إعداد Codex النموذج الافتراضي الثابت gpt-5.5. لا تجلب EstaCoda قائمة نماذج Codex مباشرة في هذا المرور، ولا تحتفظ بقائمة احتياطية لنماذج Codex أو تطبقها في هذا المرور. يبقى onboarding الأولي من غير تغيير ولا يضيف إعداد Codex عبر OAuth. تبقى مسارات النماذج المساعدة من غير تغيير أيضًا؛ ولا تضيف إعداد Codex عبر OAuth في هذا المرور.

المسارات الإضافية

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

مثال على الإعداد:

{
  "auxiliaryModels": {
    "assessor": { "provider": "openai", "model": "gpt-4o-mini", "apiKeyEnv": "OPENAI_API_KEY" },
    "vision": { "provider": "openai", "model": "gpt-4o", "apiKeyEnv": "OPENAI_API_KEY" }
  }
}

المسار assessor يقود تصنيف الموافقة الذكية. يتطلب منفذ مزود عامل ونموذج قابل للتشغيل. إذا كان المسار assessor مفقودًا أو مشوهًا أو فاشلًا، يرجع النظام إلى الموافقة اليدوية. لا يوجد مسار auxiliaryModels.approval. المسار assessor قابل للإعداد عبر محرّر الإعدادات (edit-auxiliary-model-route) بالإضافة إلى تعديلات الإعداد المباشرة.

المسارات الإضافية المفقودة تفشل مغلقة أو ترجع حسبما وثقته النظام الفرعي المستدعي. لا تُسبب انهيار الجلسة.

إدارة المسارات الإضافية متوفرة عبر محرّر الإعدادات (edit-auxiliary-model-route).

فحص حالة المزود

تحقق من المسار الرئيسي الحالي وجاهزيته:

estacoda model show

شغّل تشخيصًا حيًا ضد المزود المُهيأ:

estacoda model diagnose

اعرض جميع المزودين المعروفين في الكتالوج:

estacoda model list

الأمر الإصلاحي يُصلح مسارًا معطلاً:

estacoda model setup

أوضاع الفشل والاسترداد

مفتاح API مفقود: المسار الذي يحتاج اعتمادًا يكون غير قابل للتشغيل. شغّل estacoda model setup أو اضبط متغير البيئة. المسار الافتراضي local لا يحتاج مفتاح API ما لم تضبطه أنت.

نقطة النهاية المحلية غير قابلة للوصول: تأكد أن الخادم المحلي أو الخاص المتوافق مع OpenAI يعمل، وأن baseUrl يحتوي على مسار /v1 عندما يتطلبه الخادم، وأن أي مفتاح اختياري موجود في ملف .env للملف الشخصي المختار.

اسم نموذج غير صالح: الكتالوج لا يتعرف على النموذج. راجع وثائق المزود وحدّث config.json.

انتهاء مهلة المزود: تجاوز الطلب المهلة المُهيأة. تحقق من اتصال الشبكة وحالة المزود. يُجرّب الاحتياطي إن وُجد.

فشل دقة استدعاء الأدوات: بعض المزودين (وبالأخص OpenRouter) يعيدون استدعاءات أدوات بتنسيقات تتطلب تسوية. إذا فشلت الاستدعاءات، راجع مسار التسوية الخاص بالمزود في سجلات المنفذ.

رفض استدعاء الأداة بعد القطع: توقف المزود مع finishReason: "length" أثناء توليد استدعاءات أدوات، ولم تنتج إعادة المحاولة وسائط كاملة. ارفع model.maxTokens، أو ضيّق الطلب، أو انتقل إلى مسار أكثر موثوقية في استدعاء الأدوات.

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

تاريخ الأدوات الأصلي لا يعاد تشغيله: افحص بيانات تعريف المزود، ودعم الأدوات في النموذج، ووضع API للمسار، وأحداث structured-tool-history-skipped. المزودون غير المدعومين، ومسارات Responses، ومسارات Anthropic، ومجموعات الأدوات المشوهة، والوسائط غير الآمنة، والصدى المطلوب المفقود كلها ترجع إلى التاريخ المسطح.

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

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

تراجع الموافقة الذكية: إذا كان المسار الإضافي assessor مفقودًا أو فاشلاً، يرجع النظام إلى الموافقة اليدوية. هذا آمن لكنه أبطأ.

مرتبطات

مرجع المزودين — جدول نضج المزودين وحدود القدرات
الإعداد — مخطط الإعداد الكامل
متغيرات البيئة — مرجع متغيرات البيئة
الأمان والموافقات — سلوك الموافقة

ما الذي يفعله إعداد المزود​

نقطة نهاية محلية / مخصصة​

كتالوج النماذج والاكتشاف​

المسار الرئيسي​

مسارات الاحتياطي​

الإنهاء، والبث، واستدعاءات الأدوات​

تجاوزات نموذج الطفل المفوض​

إعادة تشغيل تاريخ استدعاءات الأدوات الأصلي​

سلامة إعادة التشغيل​

الميزانية والضغط​

صدى وضع التفكير​

التشخيصات​

تبديل النموذج أثناء الجلسة​

مسار إعداد Codex​

المسارات الإضافية​

فحص حالة المزود​

أوضاع الفشل والاسترداد​

مرتبطات​