ربط الموفّرين الخارجيين والمستضافين ذاتيًا

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

يدعم Libre WebUI حاليًا صيغ اتصال الموفّرين الآتية:

• OpenAI Chat Completions؛
• OpenAI Responses؛
• Anthropic Messages؛ و
• محتويات Google Gemini واستدعاء الوظائف.

تستخدم تعريفات Anthropic وGemini المضمّنة محولات مخصصة يحددها معرّف الموفّر. أما الموفّر المستورد حديثًا فيستخدم دلالات OpenAI Chat Completions أو OpenAI Responses؛ ولا يؤدي توجيهه إلى API متوافقة مع Anthropic أو Gemini إلى اختيار تلك المحولات المضمّنة. يحتاج الموفّر ذو بنية مختلفة للطلبات أو التدفق أو استدعاءات الأدوات أو الاستجابات إلى محول في الواجهة الخلفية. يصف JSON الخاص بالإضافة التوجيه والإعداد؛ ولا يترجم بروتوكولًا غير ذي صلة.

فتح اتصالات الموفّرين

1. سجّل الدخول وافتح الإعدادات > الإضافات.
2. ابحث في قائمة الموفّرين في اللوحة اليسرى.
3. اختر موفّرًا لمراجعة حالة تفعيله وكتالوج نماذجه الفعلي.
4. فعّل الموفّر لحسابك.
5. اختر إعداد فقط عندما تحتاج إلى حفظ بيانات اعتماد أو تجاوز إعداد اتصال.

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

تعريفات الإضافات إعداد مشترك للمثيل، لذا لا يستطيع استيرادها أو تثبيتها أو تحديثها أو حذفها إلا المسؤولون. يتحكم كل مستخدم موثّق في حالة تفعيله وبيانات اعتماده وإعدادات التوليد المسموح بها.

إضافة اتصال بسرعة

يقدّم الإعدادات > الاتصالات مسارًا أقصر للحالة الشائعة: نقطة نهاية واحدة متوافقة مع OpenAI ومفتاح API واحد. يرى المسؤولون بطاقة لوقت تشغيل Ollama المحلي مع صحته وإصداره، وقائمة بالاتصالات المتوافقة مع OpenAI، ونموذجًا صغيرًا لإضافة اتصال آخر.

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

يعرض كل صف نقطة النهاية وعدد النماذج وما إذا كان مفتاح محفوظًا وزر التفعيل وتحديث النماذج والحذف. أما ما يتجاوز ذلك — أوضاع Responses API، وتجاوزات العنوان الأساسي، والكتالوجات لكل إمكانية، وسياسة معاملات التوليد — فيبقى في مساحة الإعدادات > الإضافات الكاملة المذكورة أعلاه.

Codex (تسجيل الدخول عبر ChatGPT)

لا يحتاج موفّر Codex (ChatGPT) المضمّن إلى مفتاح API. عندما يملك الخادم تسجيل دخول Codex CLI (تشغيل codex login كمستخدم نظام تشغيل الخادم)، يظهر الموفّر للمسؤولين ويقدم عائلة نماذج Codex الموثقة عبر جلسة ChatGPT. تُقرأ رموز الوصول من ملف CLI نفسه auth.json، وتُحدّث عبر عميل OAuth نفسه الذي تستخدمه CLI، ثم تُكتب من جديد كي تواصل CLI العمل؛ ولا تظهر قيم الرموز في السجلات أبدًا.

لأن الواجهة الخلفية ترسل الطلبات — لا حاوية المهمة — تستطيع هذه النماذج أيضًا تشغيل Work بحلقة الأدوات المعزولة المعتادة. يقتصر الموفّر على المسؤولين لأن كل استدعاء يستهلك اشتراك ChatGPT لمالك الخادم. أخفه تمامًا باستخدام CODEX_OAUTH_MODELS_ENABLED=false، أو استخدم تسجيل دخول مختلفًا عبر CODEX_HOME.

اختيار موفّر مضمّن أو مستورد

يتضمن Libre WebUI تعريفات لـOpenAI وAnthropic وGemini وGroq وMistral وOpenRouter وKimi Code من Moonshot AI وHugging Face وGitHub Models وMLX LM المحلي، وخدمات نماذج ووسائط أخرى. ابدأ بإدخال مضمّن عندما يطابق بروتوكوله وعقد مصادقته الخدمة المطلوبة.

لخدمة متوافقة أخرى، يستطيع المسؤول استيراد تعريف إضافة بصيغة JSON. يصف هذا المثال المختصر بوابة متوافقة مع OpenAI:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

استورد الملف من الإعدادات > الإضافات، وفعّله، واحفظ مفتاح API للحساب الذي سيستخدم الاتصال. أضف متغيرات اتصال إلى التعريف عندما يحتاج المسؤولون إلى حقول قابلة للتحرير للعنوان الأساسي أو المسار أو الاكتشاف أو نقاط نهاية خاصة بالإمكانات. يقدّم الملف المضمّن plugins/openai.json مثالًا كاملًا.

لبوابة مقصودة بلا مصادقة على شبكة موثوقة، عيّن auth.header وauth.key_env إلى سلسلتين فارغتين، واحذف auth.prefix. عندئذ لا يطلب Libre WebUI مفتاح API لهذه الإضافة ولا يرسله.

اختيار Chat Completions أو Responses

يمكن لإضافات الإكمال المتوافقة مع OpenAI استخدام أي من وضعي API:

وضع API	مسار الطلب الافتراضي	حقل الطلب المعتاد
chat_completions	/chat/completions	messages
responses	/responses	input

يعرض موفّر OpenAI المضمّن وضع API في إعداده. يربط Libre WebUI خرج Responses المكتمل والمتدفق بـChat وWork، بما في ذلك حالة إعادة تشغيل محدودة للاستدلال واستدعاءات الأدوات.

يؤثر تغيير الوضع في مسار العملية الافتراضي. لكنه لا يغير البروتوكول الذي يتحدث به الخادم الأعلى، لذا اختر Responses فقط عندما ينفذ الخادم بنى طلبات وأحداث Responses متوافقة.

إعداد عنوان أساسي أو نقطة نهاية كاملة

يحل Libre WebUI مسار الإكمال بهذا الترتيب:

1. تجاوز endpoint كامل غير افتراضي.
2. base_url مع api_path اختياري.
3. نقطة النهاية المعلنة في تعريف الإضافة.

استخدم العنوان الأساسي لجذر API:

https://gateway.example/v1

من دون مسار مخصص، يرسل وضع Chat Completions الطلبات إلى:

https://gateway.example/v1/chat/completions

ويرسل وضع Responses الطلبات بدلًا من ذلك إلى:

https://gateway.example/v1/responses

استخدم مسار API عندما يعرض الموفّر عملية متوافقة على مسار آخر نسبيًا إلى ذلك الجذر. ولا تستخدم نقطة النهاية الكاملة القديمة إلا إذا احتجت إلى تقديم عنوان العملية كاملًا؛ فالنقطة الكاملة الحقيقية تسبق العنوان الأساسي ومسار API.

تحدد لواحق نقاط النهاية المعروفة /chat/completions و/completions و/responses دلالات الطلب أيضًا. ويحافظ مسار عملية مخصص غير معروف على وضع API المحدد صراحة.

بعد تغيير مسار أو مفتاح API، احفظ الموفّر مجددًا قبل اختبار Chat. عندما تعلن الإضافة المصادقة، يتطلب مسار اتصال مخصص بيانات اعتماد محفوظة بواسطة الحساب نفسه. ويمكن لإضافة بلا مصادقة عمدًا ترك حقلي المصادقة فارغين. لا يرسل Libre WebUI مفتاح بيئة يديره المشغّل إلى وجهة يحددها المستخدم؛ فالرجوع إلى البيئة مخصص للمسار المضمّن الموثوق.

اكتشاف معرّفات النماذج أو صيانتها

اختر موفّر محادثة نشطًا واستخدم تحديث النماذج لتشغيل الاكتشاف. يعيد Libre WebUI تحميل كتالوج الموفّر المحدد وقائمة نماذج Chat.

يعمل الاكتشاف من تلقاء نفسه أيضًا: يُعاد اكتشاف كتالوج الموفّر النشط عندما يكون مفقودًا أو أقدم من PLUGIN_MODEL_DISCOVERY_TTL_MS، فتتبع النماذج الظاهرة الموفّر لا لحظة تفعيله. يجبر تحديث النماذج فحصًا فوريًا ويعرض ما حدث:

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

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

يختار الاكتشاف عنوان قائمة النماذج لمسار متوافق مع OpenAI كما يأتي:

• يُستخدم المسار المنتهي بـ/models كما هو؛
• تُستبدل اللاحقة المعروفة مثل /chat/completions أو /completions أو /responses أو /embeddings أو /messages بـ/models؛ و
• فيما عدا ذلك، يُضاف /models إلى المسار.

مثلًا، يشتق كلا مساري الإكمال العنوان نفسه للاكتشاف:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

عندما لا ينتج الاشتقاق العنوان الكامل الصحيح، اعرض models_endpoint في مصفوفة variables للإضافة:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

تسبق القيمة الافتراضية الموروثة أو المحفوظة للمسؤول العنوان المشتق. ولا تُقرأ خاصية models_endpoint في المستوى الأعلى من البيان. يتوقع الاكتشاف استجابة متوافقة مع OpenAI، وبها كائنات نماذج في مصفوفة data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

تُخزّن المعرّفات المكتشفة لكل مستخدم ولا تعيد كتابة ملف الإضافة المشترك. إذا لم ينفذ الموفّر اكتشافًا متوافقًا، فاحتفظ بمعرّفات النماذج الاحتياطية في model_map داخل JSON الإضافة. كتالوج اتصالات الموفّرين للقراءة فقط؛ وتصف تسميات الإمكانات أي مسار إضافة يعرض النموذج، ولا تمثل فحوص صحة.

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

إعداد توليد الصور بصورة مستقلة

يعرض موفّر OpenAI المضمّن توليد الصور عبر https://api.openai.com/v1/images/generations، ويستخدم حاليًا gpt-image-2 افتراضيًا للإعدادات الجديدة. وتظل معرّفات GPT Image الأقدم في كتالوجه الاحتياطي لعمليات النشر الحالية المتوافقة.

مسارا المحادثة والصور معزولان عمدًا. لا يتلقى عنوان Chat أساسي مخصص طلبات الصور تلقائيًا. اترك image_endpoint فارغًا لاستخدام نقطة الصور المعلنة في الإضافة، أو عيّنه إلى عنوان عملية Image API المتوافقة كاملًا عندما يوفرها الموفّر.

تُحدد خيارات الصور بحسب الموفّر، مثل خيارات Chat. فإذا عرضت إضافتان نشطتان معرّف نموذج الصور نفسه، يرسل Libre WebUI الطلب إلى الموفّر المحدد في لوحة الصور وحده.

ربط بوابة HTTP بأمان

يمكن لنقاط نهاية الموفّرين استخدام عناوين HTTP أو HTTPS مطلقة. يفيد HTTP لبوابة مستضافة ذاتيًا على LAN موثوقة أو شبكة Tailscale أو شبكة حاويات خاصة، لكنه يرسل مفاتيح API والمطالبات ونتائج الأدوات والمحتوى المولّد من دون تشفير أثناء النقل. فضّل HTTPS كلما عبر المسار حدًا شبكيًا أو دعمت البوابة TLS.

تنشأ الطلبات من الواجهة الخلفية لـLibre WebUI، لا من المتصفح. اختر عنوانًا تستطيع تلك الواجهة الوصول إليه:

موقع الواجهة الخلفية	مثال لجذر الموفّر
عملية أصلية على الجهاز نفسه	http://127.0.0.1:8081/v1
خدمة Docker Compose	http://ai-gateway:8080/v1
من حاوية إلى مضيف مدعوم	http://host.docker.internal:8081/v1
مضيف LAN أو Tailscale موثوق	http://192.168.1.20:8081/v1

يشير localhost داخل الحاوية إلى حاوية Libre WebUI نفسها، لا إلى خدمة Compose أخرى، ولا يصل تلقائيًا إلى المضيف.

لا يقبل Libre WebUI إلا عناوين موفّرين HTTP وHTTPS، ويتحقق من الوجهة النهائية قبل اختيار بيانات الاعتماد، ولا يتبع عمليات إعادة التوجيه لطلبات الموفّر أو الاكتشاف. اضبط عنوان العملية النهائي مباشرة.

التحقق من البوابة قبل تفعيلها

اختبر اكتشاف النماذج من الجهاز أو الحاوية التي تشغّل الواجهة الخلفية لـLibre WebUI:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

ثم اختبر العملية المطابقة لوضع API المحدد.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

بعد نجاح الاستدعاءين، اضبط المسار والوضع وبيانات الاعتماد ومعرّف النموذج نفسها في اتصالات الموفّرين. فعّل الموفّر، واختر تحديث النماذج، ثم اختر نموذجه المحدد بالموفّر في Chat. ويستطيع Work استخدامه أيضًا عندما يدعم النموذج استدعاء الأدوات بموثوقية.

استكشاف الأخطاء وإصلاحها

العارض	ما ينبغي فحصه
ما تزال الطلبات تصل إلى النقطة المضمّنة	أزل تجاوز نقطة كاملة قديمًا، ثم احفظ العنوان الأساسي ومسار API المطلوبين.
يتلقى الموفّر حمولة خاطئة	طابق وضع API مع بروتوكول Chat Completions أو Responses في الأعلى، وتحقق من اللاحقة النهائية.
لا يعيد تحديث النماذج أي معرّفات	اختبر /models، وتحقق من بنية data[].id، واعرض/اضبط متغير models_endpoint، أو احتفظ بـmodel_map.
يبقى نموذج سابق بعد تعديل المسار	احفظ تغيير الاتصال؛ يمسح Libre WebUI كتالوج ذلك المستخدم المكتشف والقديم قبل التحديث.
يُبلغ عن فقدان مفتاح API	احفظ بيانات اعتماد لكل مستخدم للمسار المخصص؛ ولا يتبع الرجوع إلى البيئة المضمّنة التجاوزات.
لا يستطيع نشر Docker الوصول إلى localhost	استخدم اسم خدمة Compose للبوابة أو اسم مضيف مدعومًا أو عنوان شبكة خاصة يمكن الوصول إليه.
تعمل المحادثة ولا يعمل توليد الصور	اضبط image_endpoint الكامل بصورة مستقلة واختر نموذجًا تعرضه إمكانية الصور.
تعمل المحادثة ويرفض Work النموذج	تأكد من دعم النموذج استدعاءات أدوات متوافقة؛ فإكمال النص العادي لا يكفي.
يعيد الموفّر توجيهًا	اضبط العنوان النهائي المتحقق منه مباشرة؛ ولا يتبع Libre WebUI توجيهات الموفّرين عمدًا.

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

شكر المجتمع

ساهم ZhengJin (@fangzhengjin) في تشكيل هذا الدليل وتجربة اتصالات الموفّرين في Libre WebUI 0.16.0، إذ ساعدت ملاحظاته المفصلة عن الموفّرين الخارجيين وتصوره لتجربة مستخدم بمساعدة الذكاء الاصطناعي في #163 على تحديد سير العمل.

مستندات ذات صلة

• الإضافات
• العمل مع النماذج
• MLX LM على Apple Silicon
• Work: مساحات العمل المعزولة
• استكشاف الأخطاء وإصلاحها