OpenWebUI API: دردش مع أي صفحة ويب بنماذجك الخاصة

إن كنت تشغّل OpenWebUI، فقد أنجزت الجزء الأصعب بالفعل. نماذجك جاهزة ومفاتيحك مجمّعة في مكان واحد، ربما مع Ollama على خادم منزلي، ومزوّد سحابي أو اثنين، وبضعة نماذج مساحة عمل (workspace models) مخصّصة ضبطتها بنفسك.

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

وهنا يأتي دور SurfMind. فـ OpenWebUI ليس مجرد واجهة دردشة؛ إذ يعمل أيضًا كخادم API من خلال OpenWebUI API، ولذلك يستطيع SurfMind استخدامه كخلفية (backend). تواصل إدارة نماذجك في OpenWebUI، ويصبح SurfMind الواجهة الأمامية لها داخل المتصفح.

يشرح هذا الدليل ما هو OpenWebUI API، وعلاقته بـ SurfMind، والروابط الدقيقة التي تلصقها، وكيف تصلح الأخطاء التي يواجهها الناس فعلًا.

OpenWebUI وSurfMind: متشابهان في الظاهر، مختلفان في المهمة

للوهلة الأولى يبدو الاثنان متنافسين. فكلاهما واجهة للذكاء الاصطناعي، وكلاهما يتصل بالعديد من مزوّدي نماذج LLM، وكلاهما يتيح لك الدردشة مع النماذج. لكن لكلٍّ منهما استخدامًا مختلفًا:

OpenWebUI مساحة عمل للذكاء الاصطناعي تستضيفها بنفسك. أما SurfMind فهو ذكاء اصطناعي داخل المتصفح الذي تستخدمه أصلًا. والصف الأهم في الجدول هو الصف المكتوب بخط عريض. فلأن OpenWebUI قادر على تقديم نماذجك عبر API، يكمّل كلٌّ منهما الآخر.

لماذا تربط OpenWebUI بـ SurfMind؟

تخيّل إعدادًا معتادًا. لديك OpenWebUI على خادم منزلي أو خادم VPS صغير، وخلفه:

• Llama أو Qwen أو Gemma تعمل محليًا عبر Ollama
• نماذج GPT أو Claude عبر مفتاح API سحابي
• نموذج يقدّمه vLLM على بطاقة GPU خاصة بك
• بضعة نماذج مساحة عمل بنيتها في OpenWebUI، لكلٍّ منها موجّه نظام (system prompt) وإعدادات خاصة

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

يمكنك أن تعيد إضافة كل مزوّد إلى SurfMind واحدًا تلو الآخر: Ollama، ثم مفتاح OpenAI، ثم نقطة نهاية vLLM. لكن ذلك مرهق، ويكرّر مفاتيحك في أكثر من مكان، كما أن نماذج مساحة العمل التي بنيتها لن تنتقل معك.

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

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

الخطوة 1: أنشئ مفتاح OpenWebUI API

مفاتيح الـ API معطّلة افتراضيًا، لذا يستغرق الأمر دقيقة في المرة الأولى.

إن كنت المسؤول (admin)، ففعّل مفاتيح الـ API:

1. سجّل الدخول إلى OpenWebUI بحساب مسؤول.
2. انتقل إلى Settings → Admin → Authentication.
3. فعّل API Keys وانقر Save.

وإن لم تكن مسؤولًا، فاطلب من المسؤول منحك صلاحية ميزة API Keys. ويضبطها المسؤول من Admin Panel → Users → Groups، إما في Default Permissions للجميع أو ضمن مجموعة بعينها.

ثم أنشئ مفتاحك:

1. انقر أيقونة ملفك الشخصي أسفل اليسار.
2. افتح Settings → Account.
3. في قسم API keys، انقر Show بجوار Secrets. القسم مطويّ افتراضيًا، لذا من الطبيعي أن تبدو المنطقة هنا فارغة.
4. انقر Create new secret key وانسخ المفتاح. وهو يبدأ بـ sk-.

بعض الأمور التي يجدر معرفتها، من وثائق مفاتيح الـ API في OpenWebUI:

• مفتاح واحد لكل حساب. إنشاء مفتاح جديد يحلّ محل القديم، ويتوقف المفتاح القديم عن العمل فورًا. فإن كانت أداة أخرى تستخدم مفتاحك بالفعل، فإن إنشاء مفتاح جديد لـ SurfMind سيعطّل تلك الأداة. ويمكنك تجنّب ذلك بحساب مخصص لـ SurfMind بلا صلاحيات إدارية.
• المفتاح يتصرّف باسمك. فهو يرى النماذج نفسها ويملك الصلاحيات نفسها التي يملكها الحساب الذي أنشأه.
• لا تستخدم رمز JWT الذي يظهر للمسؤولين في اللوحة نفسها. فذلك رمز جلسة المتصفح الخاصة بك، وتنتهي صلاحيته.

الخطوة 2: أضِف OpenWebUI إلى SurfMind

في SurfMind، انقر اسم النموذج أسفل اللوحة، ثم Show all → Custom → Add Custom Models. اختر الإعداد الجاهز العام OpenAI-compatible واملأ الحقول التالية:

إن كان OpenWebUI يعمل على الجهاز نفسه الذي عليه متصفحك، فالمضيف يكون عادةً http://localhost:3000 (ربط المنافذ الشائع في Docker) أو http://localhost:8080 (عند التثبيت عبر pip أو مباشرةً على النظام):

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

احفظ الإعداد، واختر أحد نماذج OpenWebUI من القائمة، وافتح أي مقال، واطلب من SurfMind تلخيصه.

خطآن في المسار يجب تجنّبهما. الصق نقطة النهاية الكاملة المنتهية بـ /api/chat/completions، لا المضيف وحده ولا /api. فحقل API URL في SurfMind لا يضيف المسار نيابةً عنك. ولا تضِف /v1 في أي موضع. فلا /api/v1/chat/completions ولا /v1/chat/completions هي نقطة نهاية الدردشة في OpenWebUI.

استكشاف الأخطاء: "النماذج تظهر لكن الدردشة تفشل"

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

أولًا، اختبر الأمر خارج SurfMind. أمر curl سريع من الطرفية يخبرك إن كانت المشكلة في OpenWebUI أم في إعدادات SurfMind. استبدل المضيف والمفتاح ومعرّف النموذج بقيمك الخاصة:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

استخدم معرّف النموذج تمامًا كما يظهر في قائمة النماذج في SurfMind (أو في GET /api/models). فإن نجح الأمر، فراجع حقول SurfMind من جديد. وإن فشل هو الآخر، فالخطأ الذي يعيده سيدلّك على أحد الأسباب التالية.

1. مسار الدردشة خاطئ. الـ Models URL والـ API URL حقلان منفصلان، لذا قد يكون أحدهما صحيحًا والآخر خاطئًا. تأكّد أن الـ API URL ينتهي بـ /api/chat/completions بالضبط، دون /v1، ودون شرطة مائلة في النهاية، ودون أخطاء مطبعية.

2. قيود نقاط النهاية تحجب الدردشة. يستطيع المسؤولون تفعيل API Key Endpoint Restrictions، وهي قائمة سماح بالمسارات التي يحق لمفاتيح الـ API استدعاؤها. فإن تضمّنت /api/models دون /api/chat/completions، فستظهر لك هذه المشكلة تحديدًا، وعادةً على شكل خطأ 403. اطلب من المسؤول إضافة /api/chat/completions.

3. إعداد في النموذج يفرض وضع بث معيّنًا. في OpenWebUI إعداد اسمه Stream Chat Response، يُضبط لكل نموذج في معاملاته المتقدمة أو كإعداد افتراضي من المسؤول ضمن Settings → Admin → Models. ووفقًا لوثائق OpenWebUI، يحدّد هذا الإعداد ما إذا كان الرد يُبثّ تدريجيًا بصرف النظر عمّا طلبه العميل. فإن فُرض على نموذج وضعٌ لا يتوقعه العميل، فقد يعود الرد بصيغة لا يستطيع العميل قراءتها. وإن كانت الدردشة تفشل مع نماذج معيّنة فقط، فتحقّق من هذا الإعداد فيها وأعِده إلى Default.

4. خادم وكيل عكسي (reverse proxy) لا يمرّر ترويسة Authorization. إن كان OpenWebUI يعمل خلف بوابة تستخدم Authorization لتسجيل الدخول الخاص بها (basic auth، أو SSO، أو بوابة API)، فلن يصل مفتاحك إلى OpenWebUI أبدًا. ويقبل OpenWebUI المفتاح أيضًا في ترويسة مخصصة، وهي x-api-key افتراضيًا. في هذه الحالة اختر x-api-key في حقل API Key Header في SurfMind. وإن غيّر المسؤول اسم الترويسة عبر CUSTOM_API_KEY_HEADER، فيجب أن يمرّر الوسيط تلك الترويسة.

5. معرّف النموذج غير مطابق. اختر من القائمة المنسدلة بدلًا من الكتابة. فمعرّفات نماذج Ollama في OpenWebUI تتضمن الوسم (llama3.2:latest)، ونماذج مساحة العمل تستخدم المعرّف الذي منحته إياها، لا اسم العرض.

6. المزوّد الذي يقف خلف OpenWebUI هو الذي يفشل. حين يرفض المزوّد الأصلي طلبًا ما، يمرّر OpenWebUI رمز الحالة كما هو. فخطأ 429 مصدره حدّ الاستخدام لدى المزوّد، لا OpenWebUI ولا SurfMind. جرّب النموذج نفسه في صفحة الدردشة الخاصة بـ OpenWebUI. فإن فشل هناك أيضًا، فالمشكلة لدى المزوّد.

أخطاء أخرى باختصار

وللاطلاع على القواعد العامة التي تنطبق على كل نقطة نهاية مخصصة (المنافذ، وhttp مقابل https، والرابط الأساسي مقابل نقطة النهاية الكاملة)، راجع دليل ربط الذكاء الاصطناعي المخصص الخاص بنا.

هل تستخدم OpenWebUI أم SurfMind أم كليهما؟

ليس عليك الاختيار بينهما.

• OpenWebUI وحده خيار ممتاز إن كان معظم استخدامك للذكاء الاصطناعي محادثات طويلة في تبويب مخصص: الدردشة مع المستندات في قواعد معرفتك، وتشغيل خطوط المعالجة (pipelines)، وإدارة النماذج لفريق كامل.
• SurfMind وحده خيار ممتاز إن كان معظم استخدامك للذكاء الاصطناعي ينطلق مما يظهر على شاشتك، ولا تمانع ربط المزوّدين أو مشغّل محلي مثل Ollama مباشرةً.
• كلاهما معًا منطقيّ حين تكون قد استثمرت في إعداد OpenWebUI وتريده متاحًا في كل صفحة دون أن تضبط كل شيء مرتين.

التقسيم بسيط: OpenWebUI يدير نماذجك، وSurfMind يشغّلها لك داخل المتصفح.

الأسئلة الشائعة

هل لدى OpenWebUI واجهة API؟ نعم. OpenWebUI API هي واجهة REST API تعتمد المصادقة برموز Bearer. ونقطتا النهاية اللتان تحتاجهما معظم الأدوات هما GET /api/models لسرد النماذج وPOST /api/chat/completions للدردشة، وهي تقبل طلبات على نمط OpenAI.

هل OpenWebUI API متوافق مع OpenAI؟ صيغة الطلب والرد متوافقة، أما المسارات فليست المسارات القياسية: إذ يستخدم OpenWebUI المسار /api/chat/completions بدلًا من /v1/chat/completions. ويمكن لأي عميل يتيح لك ضبط رابط نقطة النهاية الكامل، مثل SurfMind، أن يستخدمه.

أين أجد مفتاح OpenWebUI API الخاص بي؟ انتقل إلى Settings → Account → API keys، وانقر Show، ثم Create new secret key. وإن لم يظهر القسم، فعلى المسؤول تفعيل API Keys من Settings → Admin → Authentication ومنح حسابك صلاحية API Keys.

هل يمكنني استخدام نماذج مساحة العمل من OpenWebUI في SurfMind؟ نعم. تظهر نماذج مساحة العمل في /api/models مثل أي نموذج آخر. وعند استدعائها، يطبّق OpenWebUI إعداداتها المحفوظة.

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

هل هو مجاني؟ نعم. نقاط النهاية المخصصة في SurfMind لا تكلّف شيئًا ولا نفرض عليها أي حدود استخدام. تدفع فقط ما يتقاضاه مزوّدوك أنفسهم، ولا شيء على الإطلاق مع النماذج المحلية.

هل ما زالت المشكلة قائمة؟

إن نجح اختبار curl وظل SurfMind يرفض الدردشة مع نماذج OpenWebUI، فراسلنا عبر البريد على wave@surfmind.ai. واذكر الـ API URL الخاص بك (دون المفتاح)، ورمز حالة HTTP، وما إذا كانت نماذج بعينها تفشل أم جميعها. فإعدادات الاستضافة الذاتية تتفاوت كثيرًا، وهذه البلاغات تساعدنا على جعل SurfMind يعمل معها بسلاسة.

احصل على SurfMind ←