المزوّدون المخصصون يتيحون لـ PandaNpc استخدام حساب API أو بوابة خاصة أو نقطة نهاية نموذج محلية تتحكم بها. يُشار إلى هذا عادةً بـ BYOK: أحضر مفتاحك الخاص. يكون مفيدًا عندما تحتاج إلى نموذج خارج الكتالوج المدمج، أو فوترة من جانب المزوّد، أو خادم وسيط داخلي، أو Ollama، أو LM Studio، أو خدمة متوافقة مع OpenAI وتستضيفها بنفسك.
بالنسبة للدردشة المباشرة المدعومة، يرسل PandaNpc الطلب إلى نقطة النهاية التي قمت بتكوينها بدلاً من استبدال نموذج مدمج. يظل المزوّد الخارجي هو المتحكم في التسعير والاحتفاظ بالبيانات وحدود المعدل وتوافر النماذج والاستخدام المقبول.
المتطلبات الأساسية وحدود الأمان
قبل إضافة مزوّد، اجمع ما يلي:
- مفتاح API للمزوّد أو رمز المصادقة المحلي.
- عنوان API الأساسي (Base URL) الخاص به، وينتهي عادةً بـ
/v1لخدمة متوافقة مع OpenAI. - معرّف النموذج الدقيق الذي يقبله API.
- نافذة السياق الموثقة والحد الأقصى للمخرجات، إذا كنت تخطط لتجاوز الإعدادات الافتراضية.
استخدم مفتاحًا مخصصًا بأقل الصلاحيات اللازمة وحد إنفاق حيثما يدعم المزوّد ذلك. لا تضع المفتاح أبدًا في الوثائق أو مطالبات الدردشة أو لقطات الشاشة أو مخرجات وحدة تحكم المتصفح أو مستودع Git.
في متصفح الويب، تخضع الطلبات المباشرة لـ CORS. يجب أن يسمح المزوّد بالطلبات من https://pandanpc.com. عنوان Base URL مثل http://localhost:11434/v1 يشير إلى الكمبيوتر الذي يشغّل المتصفح، وليس تلقائيًا إلى جهاز PandaPaw البعيد. يمكن أن يكون تطبيق سطح المكتب أكثر ملاءمة لنقاط النهاية المحلية لأنه غير مقيد بـ CORS في المتصفح بالطريقة نفسها.
الخطوة 1: فتح إعدادات النموذج
سجّل الدخول إلى PandaNpc وافتح إعدادات النموذج (Model Configuration). المزوّدون والنماذج سجلات منفصلة: يخزن المزوّد تفاصيل الاتصال والمصادقة، بينما يخزن كل نموذج المعرّف والحدود المرسلة إلى ذلك الاتصال.
إذا ظهر مزوّد رسمي بالفعل، فقم بتكوينه أو نسخه بدلاً من ابتكار بروتوكول مختلف. للحصول على بوابة جديدة متوافقة مع OpenAI، اختر إضافة مزوّد (Add Provider).
الخطوة 2: إضافة المزوّد
أكمل نموذج المزوّد:
| الحقل | ما يجب إدخاله | مثال أو إرشاد |
|---|---|---|
| اسم العرض | تسمية تظهر لك | بوابة الذكاء الاصطناعي للشركة |
| معرّف المزوّد | معرّف داخلي ثابت | company-openai |
| API Key | السر المستخدم كرمز حامل (bearer token) | القيمة الصادرة من المزوّد |
| عنوان URL الأساسي | جذر API بدون /chat/completions |
https://gateway.example.com/v1 |
| البروتوكول | تنسيق API العلوي | اختر openai لخدمات الدردشة المتوافقة مع OpenAI |
| السر | سر اختياري ثانٍ | اتركه فارغًا إلا إذا كان المزوّد يتطلبه |
| المؤسسة | معرّف مؤسسة اختياري | فقط عندما يتطلبه المزوّد |
| المشروع | معرّف مشروع اختياري | فقط عندما يتطلبه المزوّد |
| دعم مصفوفة المحتوى | ما إذا كان محتوى الرسالة قد يستخدم مصفوفات منظمة | أبقِه مفعّلاً للمزوّدين الذين يقبلون محتوى رسائل متعددة الوسائط حديثة |
يزيل PandaNpc الشرطات المائلة في نهاية عنوان Base URL ويضيف /chat/completions لطلب الدردشة المباشر المتوافق مع OpenAI. لذلك أدخل:
https://api.example.com/v1وليس:
https://api.example.com/v1/chat/completionsاحفظ المزوّد قبل إضافة نموذج. عند تحرير مزوّد حالي، يعني حقل API Key أو Secret الفارغ "الاحتفاظ بالقيمة التي تم تكوينها"؛ ولا يعرض السر المخزن مرة أخرى في النموذج.
الخطوة 3: إضافة نموذج
اختر إضافة نموذج (Add Model) ضمن المزوّد وأكمل الحقول التالية:
| الحقل | المعنى | مثال |
|---|---|---|
| اسم العرض | تسمية اختيار قابلة للقراءة البشرية | نموذج البرمجة الخاص بي |
| قيمة النموذج | معرّف النموذج الدقيق من المزوّد | model-name-from-provider |
| نوع النموذج | تعيين القدرة/الفئة في PandaNpc | اختر قيمة حالية من النموذج |
| المزوّد | سجل المزوّد الذي تم إنشاؤه أعلاه | بوابة الذكاء الاصطناعي للشركة |
| نافذة السياق | إجمالي الرموز المدعومة | استخدم الحد الصحيح الموثق من المزوّد |
| الحد الأقصى للرموز | الحد الأقصى لرموز المخرجات المُولَّدة | استخدم قيمة موجبة لا تتجاوز حد المزوّد |
يمكن تغيير Display Name دون التأثير على استدعاء API. لا يمكن تخمين Model Value من اسم تسويقي؛ انسخه من وثائق API الخاصة بالمزوّد أو من نقطة نهاية قائمة النماذج.
اترك نافذة السياق والحد الأقصى للرموز فارغين إذا كنت غير متأكد. الإعداد الافتراضي المتحفظ أكثر أمانًا من تحديد نافذة سياق أكبر مما يدعمه الخادم. هذه الحقول مهمة بشكل خاص لـ PandaCode لأنها تؤثر على الضغط وميزانية المخرجات.
أمثلة على نقاط النهاية الشائعة
توضح الأنماط التالية شكل عنوان URL؛ يتوفر التوفر ومعرّفات النماذج حسب تثبيتك أو حساب المزوّد:
| نوع الخدمة | عنوان URL الأساسي النموذجي | ملاحظات |
|---|---|---|
| سحابة API متوافقة مع OpenAI | https://provider.example.com/v1 |
يجب أن تدعم Chat Completions المدفق ومصادقة الحامل |
| Ollama على الكمبيوتر الذي تشغّل منه المتصفح | http://localhost:11434/v1 |
شغّل نقطة نهاية Ollama المتوافقة مع OpenAI؛ قد يتطلب استخدام المتصفح إعداد CORS |
| LM Studio على الكمبيوتر الذي تشغّل منه المتصفح | http://localhost:1234/v1 |
شغّل الخادم المحلي وحدد معرّف النموذج المُحمَّل |
| بوابة شبكة خاصة | https://ai.internal.example/v1 |
يجب أن يتمكن عميل PandaNpc من حلّ المضيف والوصول إليه |
لا تفترض أن كل خدمة تعلن عن "متوافق مع OpenAI" تطبّق البث أو استدعاءات الأدوات أو الصور أو حقول التفكير أو استجابات أخطاء متطابقة. اختبر الميزات المحددة التي يحتاجها سير عملك.
التحقق من المزوّد والنموذج
استخدم مطالبة منخفضة التكلفة وغير حساسة قبل الاعتماد على التكوين:
- حدد النموذج الجديد في محادثة جديدة.
- أرسل
Reply with exactly: provider connected. - تأكد من أن الاستجابة تتدفق وأن لوحة تحكم المزوّد تسجّل الطلب.
- أرسل رسالة متابعة قصيرة للتحقق من سجل المحادثة.
- إذا كنت بحاجة إلى أدوات أو صور أو سياق طويل، فاختبر كل إمكانية بشكل منفصل.
بالنسبة لنقطة نهاية محلية، تحقق منها أولاً خارج PandaNpc. غالبًا ما تتوفر قائمة نماذج متوافقة مع OpenAI عبر:
curl http://localhost:11434/v1/modelsاستخدم الاستجابة فقط لتأكيد إمكانية الوصول ومعرّف النموذج. لا تضع مفتاح API إنتاجيًا مباشرةً في سجل الأوامر.
استخدام النماذج المخصصة مع PandaCode
يمكن أن يوفر PandaCode سير عمل برمجيًا بأسلوب Claude Code أثناء استخدام الواجهة الخلفية للنموذج التي تختارها، بما في ذلك DeepSeek أو Qwen أو بوابة متوافقة مع OpenAI أو خدمة داخلية. بعد تكوين المزوّد والنموذج، حدد هذا النموذج لاتصال أو مهمة PandaCode ذات الصلة.
يجب أن يدعم النموذج نمط التفاعل الذي يتطلبه محرك البرمجة. قد يفشل المزوّد الذي يعمل مع الدردشة البسيطة في استدعاءات الأدوات أو البث طويل الأمد أو المحتوى المنظم. راجع نماذج الذكاء الاصطناعي المدعومة من PandaNpc للتعرف على الفرق بين نماذج الدردشة ومحركات البرمجة المحلية، و تثبيت وأوامر PandaPaw لإعداد المحرك البعيد.
استكشاف الأخطاء وإصلاحها
خطأ مصادقة `401` أو `403`
أنشئ مفتاح مزوّد جديد، وتأكد من أنه نشط، وأعد إدخاله. تحقق مما إذا كانت الخدمة الخارجية تتطلب مؤسسة أو مشروعًا أو طريقة مصادقة مختلفة. المفتاح المقنّع المنسوخ من شاشة التحرير ليس السر الأصلي.
نقطة النهاية أو النموذج غير موجود (`404`)
أزل /chat/completions من عنوان Base URL المُعدّ لأن PandaNpc يضيفه. تأكد من وجود /v1 عند الحاجة ومن أن قيمة النموذج (Model Value) تطابق تمامًا معرّف النموذج الخارجي. قد يُرجع المزوّد نفس الخطأ 404 لكل من عنوان URL الخاطئ والنموذج غير المتاح.
المتصفح يبلغ عن خطأ في الشبكة أو CORS
افتح وحدة تحكم المطور في المتصفح فقط لتحديد المصدر المحظور؛ لا تلصق الأسرار هناك. قم بتكوين المزوّد للسماح بـ https://pandanpc.com، أو استخدم نقطة نهاية HTTPS الخاصة به، أو استخدم تطبيق سطح المكتب من PandaNpc. تمنع قواعد المحتوى المختلط صفحة HTTPS من استدعاء بعض نقاط نهاية HTTP العادية.
تعذر الوصول إلى Ollama أو LM Studio المحلي
تأكد من أن الخادم يعمل على نفس الكمبيوتر الذي يقدّم الطلب وأنه يستمع على الواجهة والمنفذ المُعدّين. إذا كان خادم النموذج يعمل على كمبيوتر آخر، فإن localhost غير صحيح؛ استخدم اسم مضيف خاص أو عنوان IP يمكن الوصول إليه وثبّت الخدمة قبل كشفها.
الاستجابة تبدأ ثم تتوقف أو لا تحتوي على محتوى
تأكد من أن API يدعم Chat Completions المدفق ويصدر أحداث data: القياسية. قلّل الحد الأقصى للرموز (Max Tokens)، واختبر رسالة نصية فقط، وعطّل مصفوفات المحتوى المنظمة فقط إذا كان المزوّد يوثق أنه يقبل محتوى نصيًا حصريًا.
تفشل الجلسات الطويلة قرب حد السياق
اخفض نافذة السياق المُعدّة إلى الحد الحقيقي الذي يدعمه المزوّد واترك مساحة للمخرجات وتعليمات النظام ونتائج الأدوات. ابدأ جلسة جديدة بعد تغيير تكوين النموذج حتى يتم تطبيق الحدود الجديدة بشكل متسق.
للحصول على تفاصيل حول الحصص على مستوى الحساب وتدفق البيانات، اقرأ حسابات PandaNpc والخطط وتكاليف API و سياسة الخصوصية.