المزودون المخصصون

يدعم AISCouncil أي LLM API يُنفّذ تنسيق إكمال المحادثة OpenAI. هذا يتيح لك الاتصال بالنماذج المستضافة ذاتيًا، بوابات LLM المؤسسية، المزودين البديلين، وخوادم الاستدلال المحلية.

ما هي المزودون المخصصون

المزودون المخصصون هم نقاط نهاية LLM معرفة من المستخدم تستخدم تنسيق API المتوافق مع OpenAI (/v1/chat/completions مع تدفق SSE). معظم خوادم الاستدلال الحديثة وبوابات LLM تُنفّذ هذا التنسيق، مما يجعله المعيار الفعلي لواجهات LLM API.

حالات الاستخدام

• النماذج المستضافة ذاتيًا -- اتصل بـ vLLM أو Text Generation Inference أو LocalAI التي تعمل على عتادك الخاص
• بوابات LLM المؤسسية -- مرّر عبر وكيل API لشركتك مع المصادقة والتسجيل
• الوكلاء المحليون -- استخدم LiteLLM أو أدوات مشابهة لتوحيد مزودين متعددين خلف نقطة نهاية واحدة
• المزودون البديلون -- اتصل بأي مزود لم يُبنَ بعد في التطبيق
• النماذج المضبوطة بدقة -- الوصول لنماذجك المضبوطة بدقة المخصصة على أي منصة استضافة متوافقة
• النشرات المعزولة -- استخدم نماذج تعمل على شبكة محلية بدون وصول إنترنت

إضافة مزود مخصص عبر الإعدادات

1. افتح الإعدادات (انقر أيقونة الترس أو اضغط Ctrl+Shift+S)
2. انتقل لقسم مفاتيح API
3. انتقل للأسفل لـ المزودون المخصصون
4. املأ الحقول:

الحقل	مطلوب	الوصف
معرف المزود	نعم	معرف قصير (مثل my-llm). يجب أن يكون فريدًا، حروف صغيرة، بدون مسافات
اسم العرض	نعم	اسم مقروء بشري يُعرض في القائمة المنسدلة للمزود
URL نقطة النهاية	نعم	URL كامل لنقطة نهاية إكمال المحادثة (مثل https://my-api.example.com/v1/chat/completions)
مفتاح API	لا	رمز Bearer للمصادقة (اتركه فارغًا إذا لم يكن مطلوبًا)
النماذج	نعم	قائمة مفصولة بفواصل لمعرفات النماذج المتاحة عند هذه النقطة

5. انقر حفظ
6. يظهر المزود في القائمة المنسدلة للمزود عند إنشاء أو تكوين بوت

التسجيل البرمجي

يمكنك تسجيل مزودين مخصصين من وحدة تحكم المتصفح أو من سكربت:

AIS.Providers.registerCustom("my-provider", {
  name: "My Provider",
  endpoint: "https://my-api.example.com/v1/chat/completions",
  models: [
    { id: "my-model-7b", name: "My Model 7B" },
    { id: "my-model-70b", name: "My Model 70B" },
  ],
  apiStyle: "openai",
});

خيارات التسجيل

الخيار	النوع	الافتراضي	الوصف
name	نص	معرف المزود	اسم العرض
endpoint	نص	مطلوب	URL كامل لنقطة نهاية إكمال المحادثة
models	مصفوفة	[{id: 'default', name: id}]	النماذج المتاحة
apiStyle	نص	'openai'	تنسيق API (حاليًا فقط 'openai' مدعوم)
extraHeaders	كائن	{}	ترويسات HTTP إضافية لتضمينها في كل طلب
pricing	كائن	null	معلومات التسعير (لتتبع التكلفة)
maxInput	رقم	0	الحد الأقصى لطول سياق الإدخال (للعرض فقط)

ترويسات إضافية

إذا كانت نقطة نهايتك تتطلب ترويسات مخصصة (مثل أنظمة المصادقة غير رموز Bearer):

AIS.Providers.registerCustom("corp-gateway", {
  name: "Corporate Gateway",
  endpoint: "https://llm.corp.internal/v1/chat/completions",
  models: [{ id: "gpt-4o", name: "GPT-4o (via gateway)" }],
  extraHeaders: {
    "X-Corp-Token": "your-internal-token",
    "X-Department": "engineering",
  },
});

الاستمرار

تُحفظ المزودون المخصصون تلقائيًا في localStorage تحت المفتاح ais-custom-providers. يُستعادون عند كل تحميل للصفحة، لذا تحتاج لتسجيلهم مرة واحدة فقط.

إدارة المزودين المخصصين

قائمة المزودين المخصصين المسجلين

const customIds = AIS.Providers.listCustom();
// ['my-provider', 'corp-gateway']

إزالة مزود مخصص

AIS.Providers.removeCustom("my-provider");

هذا يزيله من كل من سجل وقت التشغيل و localStorage.

قائمة جميع المزودين (مدمج + مخصص)

const all = AIS.Providers.list();
// [{ name: 'anthropic', models: [...] }, { name: 'my-provider', models: [...] }, ...]

كيف يعمل داخليًا

يستخدم المزودون المخصصون نفس مصنع التدفق SSE openaiCompatible() الذي يُشغّل المزودين المدمجين OpenAI و xAI و OpenRouter و DeepSeek و Groq ومزودين آخرين. هذا المصنع:

1. يبني جسم طلب OpenAI القياسي (model، messages، temperature، max_tokens، stream، إلخ)
2. يرسل طلب POST مع ترويسة Authorization: Bearer {apiKey}
3. يحلل تدفق SSE (أسطر data: {...}) لدلتا المحتوى
4. يعالج كلا تنسيقي الاستجابة المتدفقة (delta) وغير المتدفقة (message)
5. يستخرج استخدام الرموز من الحقل usage إن وجد

جميع حقول الإعدادات تعمل مع المزودين المخصصين: temperature، top_p، frequency_penalty، presence_penalty، متواليات التوقف، تنسيق الرد، وجهد الاستدلال.

الخدمات المتوافقة

الخدمات التالية تُنفّذ تنسيق API المتوافق مع OpenAI وتعمل كمزودين مخصصين:

الخدمة	نقطة النهاية	ملاحظات
LiteLLM	http://localhost:4000/v1/chat/completions	وكيل يوحّد أكثر من 100 مزود
LocalAI	http://localhost:8080/v1/chat/completions	شغّل نماذج مفتوحة المصدر محليًا
vLLM	http://localhost:8000/v1/chat/completions	خادم استدلال عالي الأداء
Text Generation Inference	http://localhost:8080/v1/chat/completions	خادم استدلال Hugging Face
Ollama	http://localhost:11434/v1/chat/completions	مدمج بالفعل، لكن يمكن إضافته كمخصص أيضًا
llama.cpp (وضع الخادم)	http://localhost:8080/v1/chat/completions	استدلال C++ خفيف
Jan	http://localhost:1337/v1/chat/completions	تطبيق سطح مكتب مع نماذج محلية
LM Studio	http://localhost:1234/v1/chat/completions	تطبيق سطح مكتب مع إدارة النماذج
Cloudflare Workers AI	https://api.cloudflare.com/client/v4/accounts/{id}/ai/v1/chat/completions	مدمج، لكن يمكن تخصيصه
Azure OpenAI	https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-02-01	يتطلب ترويسة api-key

استكشاف الأخطاء

أخطاء CORS

CORS (مشاركة الموارد عبر الأصول)

عندما يستدعي المتصفح نقطة نهاية API مباشرة، يجب أن يضمّن الخادم ترويسات CORS في رده. بدونها، يحظر المتصفح الطلب لأسباب أمنية.

إذا رأيت خطأ CORS في وحدة التحكم، نقطة نهايتك المخصصة تحتاج لإرجاع هذه الترويسات:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: POST, OPTIONS

للخدمات المحلية:

• Ollama: اضبط متغير البيئة OLLAMA_ORIGINS=* قبل البدء
• vLLM: أضف علامة --allowed-origins '*'
• LiteLLM: أضف علامة --cors أو اضبط LITELLM_ALLOW_ORIGINS=*
• LocalAI: CORS مفعّل افتراضيًا

للخدمات البعيدة خلف وكيل عكسي (Nginx):

location /v1/ {
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
    add_header 'Access-Control-Allow-Methods' 'POST, OPTIONS' always;

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    proxy_pass http://localhost:8000;
}

رفض الاتصال

• تحقق من أن URL نقطة النهاية صحيح والخدمة تعمل
• للخدمات المحلية، تأكد أن الخادم يستمع على المنفذ المتوقع
• لخدمات localhost، جرب 127.0.0.1 بدلاً من ذلك (أو العكس)
• تحقق من عدم حجب جدار الحماية للمنفذ

أخطاء المصادقة

• تحقق من أن مفتاح API الخاص بك صحيح
• بعض الخدمات تستخدم ترويسات مصادقة مختلفة -- استخدم extraHeaders إذا كانت الخدمة لا تستخدم تنسيق Authorization: Bearer القياسي
• Azure OpenAI يستخدم ترويسة api-key بدلاً من Authorization

ردود فارغة أو مشوهة

• تأكد أن نقطة النهاية تُرجع تنسيق SSE المتوافق مع OpenAI (data: {"choices":[{"delta":{"content":"..."}}]})
• بعض الخدمات تتطلب stream: true في جسم الطلب (التطبيق يرسل هذا افتراضيًا)
• تحقق من أن معرف النموذج يطابق ما تتوقعه الخدمة
• افتح تبويب Network في DevTools للمتصفح لفحص الطلب والاستجابة الخام