دليل استكشاف أخطاء واجهة برمجة التطبيقات Ollama وإصلاحها

فهم بنية نقطة نهاية واجهة برمجة تطبيقات Ollama

The ollama endpoint يتبع نمط RESTful صارم يعكس هيكل واجهة برمجة تطبيقات OpenAI. تتفاعل معها بإرسال طلبات POST إلى /v1/chat/completions وطلب النماذج المتاحة عبر GET /v1/models. يتيح لك هذا التوحيد القياسي تبديل النماذج الأساسية دون إعادة كتابة رمز العميل.

يفترض العديد من المطورين أن نقطة النهاية تدعم التضمينات (Embeddings) أو توليد الصور بشكل افتراضي. لا تفعل. خدمتنا المستضافة، على سبيل المثال، تقدم فقط إكمالات نصية بنموذج غير خاضع للرقابة واحد. تحقق دائماً من GET /v1/models الاستجابة لمعرفة الميزات المعروضة بالضبط. إذا رأيت قائمة بالنماذج، تحقق من معرفاتها قبل إرسال الطلبات.

عند استخدام نسخة محلية، يعمل نقطة النهاية عادة على http://localhost:11434. بالنسبة لمقدمي الخدمات السحابية، ستستخدم عنوان URL أساسي مخصص. تأكد من أن عميل HTTP الخاص بك يتعامل مع الرؤوس بشكل صحيح، خاصة Content-Type: application/json. غالباً ما يسبب الرأس المفقود إخفاقات صامتة تبدو كأخطاء في النموذج.

العناصر الهيكلية الرئيسية:

• model: المعرف النصي للنموذج اللغوي الكبير (LLM) المحدد.
• messages: مصفوفة من كائنات المحتوى القائمة على الأدوار.
• stream: علم منطقي يمكّن أحداث الإرسال عبر الخادم (SSE).

لماذا قد تفشل استدعاءات واجهة برمجة التطبيقات الخاصة بـ ollama

عادةً ما تفشل مكالمات واجهة برمجة التطبيقات بسبب عناوين URL الأساسية غير الصحيحة، أو انتهاء صلاحية المفاتيح، أو حمولات JSON غير صحيحة. الخطأ الأكثر شيوعًا هو استجابة 401 غير مصرح به، مما يعني أن مفتاح واجهة برمجة التطبيقات الخاص بك مفقود أو غير صالح. مشكلة متكررة أخرى هي 404 غير موجود، مما يشير إلى أن نقطة النهاية لا تدعم المسار أو معرف النموذج المطلوب.

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

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

رموز الأخطاء الشائعة:

• 400: طلب غير صالح (JSON غير صحيح أو معلمات غير صالحة).
• 401: غير مصرح (مفتاح API غير صالح أو مفقود).
• 429: عدد كبير من الطلبات (تم تجاوز حد المعدل).
• 500: خطأ في الخادم الداخلي (فشل تحميل النموذج).

تكوين نماذج ollama غير الخاضعة للرقابة بشكل صحيح

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

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

عدّل ال temperature المعامل للتحكم في الإبداع. قيمة 0.7 هي نقطة بداية جيدة للاستجابات المتوازنة. تزيد القيم الأعلى من العشوائية، وهو أمر مفيد للكتابة الإبداعية ولكنه قد يقلل من الدقة الواقعية. تجعل القيم الأقل الإخراج أكثر حتمية.

نصائح التكوين:

• استخدام top_p بجانب temperature للتحكم الأفضل.
• تعيين stop التسلسلات لمنع الحلقات اللانهائية.
• تضمين دائمًا system رسالة لتحديد الدور.

معالجة التدفق وحدود الرموز

تعيد الاستجابات التدفقية البيانات في أجزاء عبر أحداث Server-Sent Events (SSE). يحتوي كل جزء على إكمال جزئي. يجب عليك تجميع هذه الأجزاء للحصول على الاستجابة الكاملة. تتضمن خدمتنا إحصائيات استخدام الرمز في الجزء الأخير، مما يتيح لك تتبع التكاليف في الوقت الفعلي.

حدود الرموز حاسمة للمحادثات الطويلة. يدعم طرفنا نافذة سياق بسعة 100,000 رمز مميز، مما يجمع بين المطالبة والإكمال. ومع ذلك، الحد الأقصى للإخراج لكل طلب هو 16,000 رمز مميز. إذا لم تضبط max_tokens, الافتراضي هو 2,048 رمزًا. يمكن أن يؤدي هذا إلى اقتطاع الإجابات الطويلة بشكل غير متوقع.

أثناء التدفق، تعامل مع انقطاعات الشبكة بسلاسة. إذا انقطع الاتصال، يمكنك الاستئناف من آخر قطعة تم استقبالها إذا كان الخادم يدعم ذلك. خلاف ذلك، قد تحتاج إلى إعادة محاولة الطلب بالكامل. راقب دائمًا usage field في القطعة النهائية لتجنب مفاجآت الفوترة.

أفضل ممارسات البث:

• تحليل أحداث SSE بشكل صحيح، متجاهلاً الأسطر الفارغة.
• تراكم الأجزاء في الذاكرة أو المخزن المؤقت.
• تحقق من usage كائن في القطعة الأخيرة لعدد الرموز.

أخطاء الفوترة والحساب الحسابي للرموز

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

لا تترجم الرموز (Tokenizers) دائماً بنسبة 1:1 مع الأحرف. يمكن أن تكون الكلمة الواحدة عدة رموز. إذا قدرت التكاليف بناءً على عدد الأحرف، فقد تقلل من تقدير الفاتورة. استخدم مكتبة ترميز موثوقة في العميل الخاص بك للحصول على counts دقيقة قبل إرسال الطلبات.

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

نصائح الفوترة:

• تتبع استخدام الرموز في كل استجابة.
• أعد إعداد تنبيهات لعتبات الرصيد المنخفض.
• استخدام max_tokens حصر التكاليف المحتملة.

مشاكل الأمان وفحص المنافذ

غالبًا ما يتم تعريض نقاط نهاية Local Ollama للشبكة بشكل افتراضي. هذا يجعلها عرضة لماسحات المنافذ التي تبحث عن موارد حوسبة مجانية. إذا قمت بتعريض المنفذ 11434 بدون مصادقة، يمكن لأي شخص استخدام موارد GPU الخاصة بك. يمكن أن يؤدي ذلك إلى فواتير كهرباء عالية وأداء بطيء.

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

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

خطوات الأمان:

• تغيير المنفذ الافتراضي إذا كنت تعرضه للإنترنت.
• استخدم وسيطاً عكسياً مع HTTPS والمصادقة.
• راقب حركة مرور الشبكة بحثاً عن نشاط غير عادي.

استخدام واجهة برمجة التطبيقات المحلية مقابل السحابية

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

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

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

مقارنة:

• محلي: الخصوصية، التحكم، اعتماد العتاد.
• السحابي: الراحة، القابلية للتوسع، نقل البيانات.

أخطاء جانب العميل الشائعة

ينسى المطورون غالبًا التعامل مع حدود المعدل. تسمح خدمتنا بـ 300 طلب في الدقيقة لكل مفتاح. إذا تجاوزت هذا الحد، ستتلقى خطأ 429. نفذ تراجعًا أسيًا في عميلك للتعامل مع هذه الأخطاء بسلاسة.

خطأ آخر هو عدم تعيين stream بشكل صحيح. إذا توقعت التدفق (streaming) ولكن لم تضبط stream: true, ستنتظر الاستجابة الكاملة قبل تلقي أي بيانات. هذا يمكن أن يجعل تطبيقك يبدو بطيئاً.

أخطاء وضع JSON شائعة أيضاً. إذا قمت بـ response_format: {type: "json_object"}, يجب أن تُرجع النموذج JSON صالحًا. إذا لم تفعل ذلك، سيفشل المفسر الخاص بك. أضف معالجة الأخطاء لالتقاط ومحاولة إعادة تحليل أخطاء JSON.

قائمة مراجعة:

• قم بتنفيذ معالجة حدود معدل الطلب.
• تعيين stream: true للتحديثات في الوقت الفعلي.
• تحقق من مخرجات JSON عند استخدام وضع JSON.