المكونات الإضافية

يستخدم Libre WebUI المكونات الإضافية للاتصال بمزوّدي الذكاء الاصطناعي الخارجيين وقدرات النماذج إلى جانب Ollama المحلي.

أنواع المكونات

النوع	الغرض
المحادثة/الإكمال	نماذج النص والمحادثة من واجهات المزوّدين
التضمينات	تضمينات متجهية للبحث في المستندات والذاكرة
توليد الصور	نماذج الصور وخلفيات شبيهة بـ ComfyUI
تحويل النص إلى كلام	مزوّدو توليف الصوت
تحويل الكلام إلى نص	مزوّدو النسخ
توليد الصوت	مزوّدو إنشاء الأصوات والمقاطع الصوتية
توليد الفيديو	مزوّدو إنشاء الفيديو غير المتزامن

يمكن للمكونات عرض خرائط نماذج ثابتة، وتحديث المتاح من API المزوّد حيث يُدعم.

عائلات المزوّدين المضمنة

يتضمن Libre WebUI تعريفات للخدمات الشائعة:

OpenAI وواجهات متوافقة مع OpenAI
Anthropic
Google Gemini
Groq
Kimi Code من Moonshot AI
Mistral
OpenRouter
Hugging Face
GitHub Models
MLX LM للاستدلال المحلي على Apple Silicon
ComfyUI
ElevenLabs

تتغير كتالوجات المزوّدين كثيرًا. اعتبر الواجهة مصدر الحقيقة للاكتشاف المباشر عندما يدعمه المكوّن.

الملكية والتصريح

تعريفات المكونات تهيئة مشتركة للمثيل. تتطلب كل مسارات /api/plugins المصادقة، ولا يستطيع رفع تعريف أو تثبيته أو تحديثه أو حذفه إلا المسؤول. أما التنشيط فمختلف: يستطيع كل مستخدم موثق تنشيط مكوّن مشترك أو تعطيله لحسابه فقط. تُخزن الحالة في SQLite وتبقى بعد إعادة التشغيل بلا تأثير في مزوّدي الآخرين.

عند الترقية، تُنسخ قائمة التنشيط العامة القديمة .status.json مرة إلى الحسابات القائمة، ولكن للتعريفات المطابقة تمامًا لمراسي الثقة المترجمة في Libre WebUI فقط. تظل التعريفات القديمة المخصصة أو الحاجبة في الحجر وغير نشطة. وتبدأ الحسابات المنشأة بعد الترحيل بلا مكونات نشطة.

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

تُقسم متغيرات المكوّن حسب الغرض. لا يخزن متغيرات توجيه الاتصال المعروفة إلا المسؤولون:

endpoint وbase_url وapi_path وmodels_endpoint وapi_url وimage_endpoint وembedding_endpoint وstt_endpoint وtts_endpoint وvoice_clone_endpoint وapi_mode وmodel وmodel_id. كما تُعد config.endpoint_variable أو config.models_endpoint_variable أو config.voice_clone_endpoint_variable المعلنة ضمن قدرة توجيه اتصال حتى باسم مختلف.

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

بيانات الاعتماد

تأتي بيانات الاعتماد من البيئة أو إعدادات المستخدم.

أمثلة:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...

في النشر المشترك، تكون بيانات كل مستخدم أفضل عادة لأنه يتحكم في فوترته وحدوده. ومفاتيح البيئة مفيدة للتثبيت الفردي والعروض والنشر المُدار.

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

تنطبق القاعدة على الاكتشاف وChat وWork وفحوص التوفر وكتالوجات القدرات، فتمنع نقطة مخصصة أو بيانًا قديمًا من تلقي سر يديره المشغّل.

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

المزوّدون المتوافقون مع OpenAI

تعرض مزوّدات كثيرة API متوافقة مع OpenAI. يمكن للمكوّن تعريف:

عنوان API كاملًا
متغير بيئة مفتاح API
سلوك نقطة المحادثة
دعم التضمينات
سلوك اكتشاف النماذج
خريطة نماذج احتياطية اختيارية

إذا لم يدعم المزوّد الاكتشاف، يستخدم Libre WebUI الخريطة. يهيئ JSON المستورد مزوّدًا يتحدث أصلًا أحد التنسيقات المدعومة: OpenAI Chat Completions أو OpenAI Responses أو Anthropic Messages أو Gemini. لا يترجم JSON بروتوكولًا احتكاريًا عشوائيًا؛ ويحتاج اختلاف شكل الطلب أو التدفق أو الأدوات أو الاستجابة إلى مهايئ صغير في الخادم.

توليد الصور عبر OpenAI

يعرض مزوّد OpenAI المضمّن API الصور على https://api.openai.com/v1/images/generations. النموذج الحالي gpt-image-2. ويحتفظ الكتالوج بالمعرفات المهملة gpt-image-1.5 وgpt-image-1 وgpt-image-1-mini للتثبيتات القائمة؛ وعلى الجديدة اختيار gpt-image-2.

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

تُقيّد اختيارات الصور بالمزوّد. إذا عرض مكوّنان معرف النموذج نفسه، يرسل Libre WebUI إلى المحدد في لوحة الصور فقط. تستخدم استجابات GPT Image بيانات base64؛ يحولها Libre إلى صورة ويحفظها في معرض المستخدم. تتطلب المسارات المصادقة، ويجب أن تتضمن الطلبات المباشرة pluginId وmodel. ويمكن ضبط n على عدد JSON صحيح من 1 إلى 10؛ وتُرفض السلاسل الرقمية والكسور قبل المزوّد.

وضعي Chat Completions وResponses API

تستخدم مكونات الإكمال المتوافقة دلالات chat_completions أو responses. يعرض مكوّن OpenAI الخيار في الإعدادات ← المكونات الإضافية.

تُحل إعدادات الاتصال بالترتيب:

تجاوز endpoint كامل، إذا ضُبط.
base_url مع api_path اختياري.
endpoint القديم للمكوّن.

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

المسار الافتراضي /chat/completions في وضع Chat Completions و/responses في Responses. يجب أن يكون base_url جذر API مثل https://api.example.com/v1؛ واستخدم api_path لمسار نسبي مختلف. يجب أن يتضمن العنوان الكامل مسار العملية ويتقدم عليهما. ويحدد لاحق معروف /chat/completions أو /completions أو /responses دلالة الطلب، بينما تحتفظ المسارات المخصصة بـ api_mode.

يمكن لـ JSON مستورد توفير القيم نفسها:

{
  "endpoint": "https://api.example.com/v1/chat/completions",
  "api_mode": "responses",
  "base_url": "https://api.example.com/v1",
  "api_path": "/responses"
}

تستخدم طلبات Responses ‏input وmax_output_tokens وأدوات دوال مسطحة وstore: false وتطلب محتوى استدلال مشفرًا للمتابعة بلا حالة. تُوحّد المخرجات المكتملة والمتدفقة إلى أحداث Chat وWork. لا تُحفظ حالة الإعادة إلا إذا كان ترتيب Items الكامل لا يتجاوز 64 Items و90 KB؛ تبقى Items دقيقة ولا تُقتطع حقولها. تتطلب العناصر القابلة للإعادة معرفات وأنواعًا فريدة غير فارغة، وتُتحقق بنى الرسائل والاستدلال واستدعاء الدوال قبل إصدار أداة. تعود حالة Chat الضخمة إلى السجل المرئي الموحّد. ويتخلص Chat من Items استدعاء الدوال الخام لأنه لا يحفظ نتائجها. وتُرفض استجابات Work ذات الأدوات بلا حالة دقيقة محدودة قبل أي أثر.

يشفّر تخزين Chat في SQLite حالة المزوّد مع الرسالة؛ ويخزن Work حالة الأدوات في صفوف سياق مخفية لا تعيدها API. تربط بصمة نطاق الإعادة بالمزوّد والنموذج ووضع Responses ونقطة النهاية النهائية وبصمة أحادية الاتجاه لبيانات الاعتماد. عند تغير النطاق، بما فيه تدوير المفتاح، يعود Libre إلى سجل الرسائل بدل إرسال Items خاصة عبر حد مصادقة. كما يبصم تشغيل Work توجيهه وبياناته ويعيد التحقق قبل كل جولة؛ ويوقف تغيير الوضع أو العنوان أو المفتاح التشغيل قبل استلام طلب جديد للحالة القديمة.

يجب أن تلائم حالة الأدوات حد الإعادة وغلاف البيانات الدائم الكامل 100 KB قبل أثر Work. وإذا انقطعت دفعة محفوظة، تُستعاد كل نتيجة مفقودة بمعرف الاستدعاء الدقيق وتحذير أن النتيجة مجهولة ليعاين المزوّد المساحة بدل تكرار أثر محتمل. لا تُعد نتيجة Responses غير مكتملة نجاحًا؛ ويُحفظ incomplete_details.reason ويُعرض.

يشتق اكتشاف النماذج /models من مسار العملية. مثلًا يكتشف https://api.example.com/v1/responses من https://api.example.com/v1/models. يمكن للمزوّد بلا قائمة متوافقة استخدام model_map. يُقيد الاكتشاف بمتغيرات وبيانات المستخدم وتُحفظ النتائج لكل مستخدم لا في البيان المشترك. يعمل بعد التنشيط والتحديث الصريح وتغيير المفتاح أو الاتصال وإعادة الضبط؛ ولا يطلق حفظ متغير توليد غير متعلق طلبًا.

ويعمل الاكتشاف تلقائيًا عند قراءة قائمة مكوّن نشط بلا كتالوج أو أقدم من PLUGIN_MODEL_DISCOVERY_TTL_MS. يمنع التراجع الخاص بالمزوّد استطلاعه مع كل طلب، وتمنع مهلة مزوّدًا بطيئًا من تأخير الاستجابة؛ ويُقدم التحديث المتأخر في الطلب التالي. ويُفحص URL النهائي قبل قراءة البيانات أو بناء Authorization، حتى من بيان مستورد. ولا يتبع الاكتشاف أو القدرات إعادة توجيه. اضبط النقطة النهائية لـ Chat وWork والقائمة والصور والتضمين والنسخ والكلام والاستنساخ والصوت والفيديو مباشرة، كي لا تمر البيانات إلى وجهة غير متحققة.

تقبل نقاط المزوّد HTTP أو HTTPS. يرسل HTTP المفاتيح والمطالبات والنتائج والمحتوى بلا تشفير نقل، فاستخدمه فقط لبوابة مستضافة ذاتيًا على شبكة موثوقة وفضّل HTTPS. تأتي الطلبات من الخادم؛ ففي الحاوية استخدم خدمة مثل http://ai-gateway:8080/v1، بينما يشير localhost إلى حاوية Libre WebUI نفسها. تحل مسارات القدرات العناوين والبيانات للحساب الموثق المستدعي. ولا يملك Libre WebUI وضع مستخدم واحد غير موثق.

نقاط نهاية خاصة بالقدرات

تُعزل تجاوزات Chat عن الصور والتضمينات والنسخ والكلام والصوت والفيديو. يمكن لمكوّن متعدد القدرات عرض image_endpoint أو embedding_endpoint أو stt_endpoint أو tts_endpoint أو متغير في config.endpoint_variable. ويمكن للاستنساخ تسمية config.voice_clone_endpoint_variable. الفراغ يستخدم نقطة المكوّن، ولا يُستخدم endpoint العام كتجاوز قدرة.

يرث GitHub Models المضمّن نقطته models.github.ai/inference/chat/completions عندما يكون التجاوز فارغًا. ويستخدم Hugging Face مسارات وحمولات hf-inference/models/{model} الخاصة بالمهام للتضمينات والصور والكلام بدل نقطة Chat.

تجاوز نقاط النهاية

endpoint هو URL الطلب الكامل، بما فيه مسار العملية. عادة يستخدم مكوّن محادثة https://provider.example/v1/chat/completions لا https://provider.example. قد تسمي تهيئة قديمة المتغير api_url؛ يقبله Libre لكن endpoint غير الفارغ يتقدم.

تُقبل عناوين HTTP وHTTPS المطلقة وتُرفض البروتوكولات الأخرى. HTTP لبوابات موثوقة لأنه يرسل البيانات بلا تشفير. فضّل HTTPS لأي مسار خارج الحد الخاص. الفراغ يستخدم نقطة التعريف؛ والتجاوز غير الصالح يُرفض بدل الرجوع بصمت.

لا تتبع الطلبات إعادة التوجيه. اضبط URL العملية النهائي؛ ويُبلغ الرد المعيد للتوجيه كخطأ بدل تمرير البيانات إلى قفزة أخرى.

تأتي الطلبات من الخادم؛ localhost داخل حاوية يعني الحاوية نفسها. استخدم اسم خدمة البوابة أو host.docker.internal حيث توفره البيئة.

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

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

لمزوّدي المحادثة والإكمال، يشغّل تحديث النماذج الاكتشاف ثم يعيد تحميل كتالوج المكونات وقائمة Chat. الكتالوج للقراءة فقط؛ تأتي صفوفه من معرفات المستخدم المكتشفة وخرائط القدرات. تصف التسميات أي مسار يسرد النموذج، وليست فحوص سلامة. أضف المعرفات اليدوية إلى model_map في JSON لا إلى صف مكتشف.

عند التنشيط، يحاول Libre WebUI الاكتشاف بنقطة الحساب وبياناته. يتطلب مسار المسؤول المخصص بيانات الحساب نفسه؛ ولا يستخدم بديل البيئة إلا لمسار البيان الموثوق. يشتق Libre قائمة النماذج:

URL ينتهي بـ /models يُستخدم كما هو؛
تُستبدل لواحق /chat/completions و/completions و/responses و/embeddings و/messages بـ /models؛
وإلا يُضاف /models.

يمكن للمكوّن استخدام models_endpoint كعنوان قائمة صريح، فيتقدم على الاشتقاق ويخضع للسياسة نفسها بلا إعادة توجيه. يؤدي حفظ أو إعادة ضبط endpoint أو api_url أو models_endpoint أو base_url أو api_path أو api_mode إلى مسح كتالوج المستخدم وتحديثه.

تُحل المسارات المخصصة وتُفحص قبل اختيار البيانات. لا يعود مسار مخزن إلى مفتاح البيئة؛ اضبط مفتاحًا للمستخدم. البديل محفوظ لنقطة التعريف الموثوق.

يتوقع الاكتشاف استجابة متوافقة مع OpenAI فيها IDs في مصفوفة data. ينتظر التنشيط المحاولة حتى تشمل أول قائمة النتائج. تُخزن النتائج لكل مستخدم ولا يُعاد كتابة JSON أو كشفها للآخرين. إذا غابت نقطة متوافقة أو تعذر الوصول أو اختلف الشكل، يحتفظ التنشيط العادي بالنتيجة السابقة. أما تغيير حقل الاتصال عمدًا فيمسحها أولًا ويعود إلى model_map عند الفشل.

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

تستخدم حالة المكوّن وتوفر Work والكتالوجات والقدرات سياق المستخدم وحد البيانات نفسه. مثلًا تُحل صور ونقاط وبيانات المستخدم المستدعي.

اختيار المزوّد الدقيق في Chat

معرفات النماذج ليست فريدة عالميًا؛ قد يعرض Ollama ومكونات متعددة example-model. لذلك يخزن Chat المعرف الخام وهوية اختيارية:

providerType: "ollama" لمسار Ollama؛
providerType: "plugin" مع providerId لمكوّن محدد.

تُستخدم القيم المؤهلة والمشفرة في URL مفاتيح آمنة من التصادم داخل المحدد فقط. وترسل الطلبات المعرف الخام. تبقى الأسماء المكررة اختيارات مستقلة، وتستعيد إعادة فتح المحادثة الاختيار المحفوظ.

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

قد تكون providerType وproviderId غير مضبوطة أو null في السجلات القديمة. تحتفظ بالتوجيه حسب الاسم للتوافق لأن الأصل لا يمكن استنتاجه. يعرض المحدد «المزوّد غير مسجل» بدل التخمين. اختيار إدخال محدد يسجله مستقبلًا. وتحافظ الشخصيات على هوية persona:<id> وتُسجل الجديدة كمدعومة بـ Ollama.

إعدادات المزوّد والوراثة

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

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

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

وهذا مهم للعناوين المخصصة: يترك المسؤول الحقل فارغًا ليرث المضمن أو يدخل URL متوافقًا كاملًا لتجاوزه في اتصاله.

المكونات في Work

يستخدم Work مكونات completion وchat النشطة إلى جانب Ollama وOllama Cloud. لا يُقبل تشغيل عبر مكوّن إلا إذا:

كان المكوّن نشطًا؛
كان النموذج في كتالوج المستخدم أو خريطة المكوّن؛
توفرت بيانات للمسؤول الحالي.

يحتفظ Work بنوع المزوّد ومعرف المكوّن مع المهمة وكل تشغيل، فيعتمد التوجيه على الاختيار الدقيق لا الاسم. لا يعيد تنشيط اسم يطابق Ollama توجيه مهمة قائمة.

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

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

التضمينات

تظهر المكونات ذات التضمين في إعدادات المستندات. ويكتشف Libre أيضًا نماذج Ollama المرجحة مثل nomic-embed-text وbge وe5 وgte.

وعند عدم اكتشاف نموذج، تستخدم الواجهة nomic-embed-text مرشحًا محليًا افتراضيًا.

ملاحظات تطوير المكونات

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

عند إضافة مزوّد:

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

أنواع المكونات​

عائلات المزوّدين المضمنة​

الملكية والتصريح​

بيانات الاعتماد​

المزوّدون المتوافقون مع OpenAI​

توليد الصور عبر OpenAI​

وضعي Chat Completions وResponses API​

نقاط نهاية خاصة بالقدرات​

تجاوز نقاط النهاية​

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

اختيار المزوّد الدقيق في Chat​

إعدادات المزوّد والوراثة​

المكونات في Work​

التضمينات​

ملاحظات تطوير المكونات​

وثائق ذات صلة​