ملاحظة الكاتب: إذا نجح طلب curl لكن العميل أعاد خطأ 401 أو 404 أو 400، أو تعذّر عليه الاتصال، فتحقّق من 7 نقاط في خدمة وكيل API بترتيب محدد. يتضمن المقال جدولًا لمقارنة رموز الأخطاء وقائمة تشخيص تستغرق 10 دقائق.
باستخدام المفتاح نفسه والنموذج نفسه، قد يعيد طلب curl استجابة 200، بينما يظهر خطأ 401 أو 404 أو 400 في Cherry Studio أو Chatbox أو Cursor أو Cline أو Claude Code أو Codex CLI، أو تنتهي المهلة أو تكون الاستجابة فارغة. في هذه الحالة، ابدأ بالتحقق من إعدادات العميل بدلًا من تغيير المفتاح. نجاح طلب curl يثبت أن المفتاح صالح وأن الشبكة تسمح بالوصول؛ والأرجح أن الطلب الذي يرسله العميل فعليًا يختلف عما تتوقعه.
ترتيب التشخيص المقترح هو: عنوان Base URL ← البروتوكول ونقطة النهاية ← ترويسة المصادقة ← معرّف النموذج ← متن الطلب ← الشبكة. وقبل ذلك، تأكد أولًا من أن العميل يقرأ الإعدادات التي عدّلتها. يقسّم هذا المقال مسار الطلب إلى 7 نقاط تحقق، ويوضح في كل نقطة الأعراض والسبب وطريقة التحقق والإصلاح. والهدف هو مساعدتك على تحديد ما إذا كانت المشكلة في العميل أو البوابة أو الخدمة الأصلية خلال 10 دقائق.
هذا ليس مقالًا آخر يشرح أساسيات API، بل دليل عملي لاستكشاف الأخطاء يمكنك اتباعه خطوة بخطوة.
لماذا ينجح curl بينما يفشل العميل في الاتصال؟ أهم خطوات تشخيص خدمة وكيل API
يتحقق curl من جزء صغير فقط من المسار: تحليل DNS، ومصافحة TLS، وإمكانية الوصول عبر الشبكة، وصلاحية المفتاح، وعمل نقطة النهاية التي طلبتها يدويًا. لكنه لا يتحقق مما إذا كان العميل قد قرأ الإعدادات التي عدّلتها، أو كيف يُركّب Base URL، أو ما إذا كانت ترويسات الطلب ومتنُه متطابقين مع طلب curl.
يمر الطلب الذي يرسله العميل، تقريبًا، بالمسار التالي: إعدادات العميل (متغيرات البيئة، ملف الإعدادات، الواجهة الرسومية) ← تركيب Base URL ← البروتوكول ونقطة النهاية ← ترويسة المصادقة ← معرّف النموذج وتعيينه ← متن الطلب (الرسائل، الأدوات، المحتوى متعدد الوسائط، البث) ← الوكيل وTLS والشبكة ← البوابة ← نموذج المصدر. نجاح curl يعني فقط أن المسار الذي كتبته يدويًا يعمل؛ وقد يسلك العميل مسارًا مختلفًا تمامًا.
| نقطة الفحص | الأعراض الشائعة | ما يُفضّل التحقق منه أولًا |
|---|---|---|
| 1. قراءة الإعدادات | لا تسري التعديلات، ويظل الخطأ كما كان قبلها | افحص عنوان URL الفعلي للطلب في سجلات العميل |
| 2. تركيب Base URL | خطأ 404، أو ظهور /v1/v1 أو // في المسار |
قارن عنوان URL في السجلات بعنوان URL في طلب curl |
| 3. البروتوكول ونقطة النهاية | خطأ 404 أو 400، أو فشل تحليل صيغة الاستجابة | تأكد من البروتوكول الذي يستخدمه العميل |
| 4. ترويسة المصادقة | خطأ 401، رغم أن المفتاح يعمل مع curl | قارن ترويسات الطلبين |
| 5. معرّف النموذج | خطأ 404 أو 400 يفيد بأن النموذج غير موجود | قارنه حرفيًا بقائمة النماذج في البوابة |
| 6. متن الطلب | ينجح النص وحده، لكن إضافة صورة أو أداة تؤدي إلى خطأ 400 | أضف المتغيرات تدريجيًا لإعادة ظهور المشكلة |
| 7. الشبكة والبث | انتهاء مهلة، أو stream disconnected، أو استجابة فارغة |
أوقف البث للمقارنة، وافحص الوكيل |
نقطتا التشخيص 1-2 لخدمة وكيل API: قراءة إعدادات العميل وتركيب عنوان Base URL
نقطة التحقق 1: هل يقرأ العميل الإعدادات التي عدّلتها فعلًا؟
الأعراض: غيّرت عنوان Base URL ومفتاح API، لكن رسالة الخطأ لم تتغير؛ أو أن الإعدادات تعمل في مشروع، لكنها لا تعمل في مشروع آخر.
السبب: تستمد معظم العملاء إعداداتها من أكثر من مصدر. من الحالات الشائعة أن تتجاوز إعدادات الواجهة الرسومية متغيرات البيئة، أو يحتوي ملف الإعدادات على عدة ملفات تعريف (profiles) ولا يكون الملف النشط هو الذي عدّلته، أو تتجاوز إعدادات المشروع الإعدادات العامة. وقد تكون العملية القديمة لا تزال تعمل وتستخدم القيم التي حمّلتها عند بدء التشغيل. وتشيع الحالة الأخيرة خصوصًا مع أدوات سطر الأوامر: فقد تغيّر متغيرات البيئة في الطرفية، لكن عملية IDE أو Agent قيد التشغيل لن ترى القيم الجديدة.
كيف تتحقق؟ افتح سجلات العميل أو مخرجات التصحيح، وتأكد من أن عنوان URL الفعلي للطلب والأحرف الأولى من المفتاح يطابقان القيم التي أدخلتها للتو. وإذا تعذّر الاطلاع على السجلات، فغيّر عنوان Base URL عمدًا إلى عنوان خاطئ بوضوح، ثم تحقّق مما إذا كانت رسالة الخطأ ستتغير. بهذه الطريقة تعرف ما إذا كانت الإعدادات قد طُبّقت.
كيف تصلح المشكلة؟ ابدأ بمعرفة ترتيب أولوية الإعدادات في العميل. عادةً ما تكون لإعدادات الواجهة الرسومية أو المشروع أولوية أعلى من ملف الإعدادات العام، ولملف الإعدادات أولوية أعلى من متغيرات البيئة. لكن القواعد تختلف بين العملاء، لذا ارجع إلى وثائق العميل. بعد ذلك، عدّل الإعدادات في المصدر ذي الأولوية الأعلى فقط، واحذف القيم المتعارضة من المصادر الأخرى، ثم أغلق عملية العميل بالكامل وأعد تشغيلها.
نقطة التحقق 2: الشرطة المائلة في نهاية Base URL وتكرار /v1 وبادئة المسار
المشكلة: يظهر خطأ 404، ويحتوي عنوان URL في السجل على /v1/v1/chat/completions أو //chat/completions، أو يتحول إلى /v1/chat/completions/chat/completions.
السبب: تتعامل البرامج العميلة مع حقل Base URL بطرق مختلفة. فبعضها يطلب العنوان الأساسي ويضيف /v1 تلقائيًا، وبعضها يطلب العنوان حتى /v1 ثم يضيف /chat/completions، بينما يخصص بعضها حقلين منفصلين لـ Base URL ونقطة النهاية الكاملة. إذا أدخلت https://api.apiyi.com/v1/chat/completions كاملًا في حقل يقبل بادئة المسار فقط، أو أضفت شرطة مائلة إلى نهاية عنوان يتضمن /v1 بالفعل، فقد يكون المسار الناتج غير صحيح.
كيف تتحقق؟ قارن عنوان URL الكامل للطلب في السجل بالعنوان الذي استخدمته مع curl حرفًا بحرف. ركّز على عدد مرات ظهور /v1، ووجود شرطة مائلة مزدوجة، وأي جزء زائد في نهاية المسار.
كيف تصلح المشكلة؟ أدخل العنوان وفقًا لوثائق البرنامج العميل. عادةً ما تستخدم البرامج المتوافقة مع OpenAI العنوان https://api.apiyi.com/v1 من دون شرطة مائلة في النهاية. أما إذا كان البرنامج يضيف /v1 تلقائيًا، فاحذف /v1 الذي أدخلته يدويًا. بعد التعديل، راجع عنوان URL في السجل مرة أخرى وتأكد من أن المسار النهائي يتبع الصيغة القياسية مثل https://api.apiyi.com/v1/chat/completions.
🎯 نصيحة للإعداد: عنوان الوصول المتوافق مع OpenAI في APIYI (apiyi.com) هو
https://api.apiyi.com/v1، ويُكتب بالصيغة نفسها المستخدمة مع OpenAI SDK الرسمي. يمكنك الاطلاع على قائمة النماذج المتاحة في لوحة التحكم، أو الحصول عليها بطلب واجهة قائمة النماذج باستخدام Base URL نفسه. استخدم هذه الخطوة أولًا للتأكد من صحة المفتاح والعنوان، ثم اضبط البرنامج العميل.
نقطتا الفحص 3 و4 لخدمة وكيل API: نقاط نهاية البروتوكولات وترويسات المصادقة
نقطة الفحص 3: هل يتطابق البروتوكول مع نقطة النهاية؟
المشكلة: يبدو عنوان Base URL صحيحًا، لكن الطلب لا يزال يُرجع الخطأ 404 أو 400؛ أو ينجح الطلب، لكن العميل يُبلغ عن «تعذّر تحليل الاستجابة» أو يعرض محتوى فارغًا.
السبب: توجد اليوم عدة بروتوكولات شائعة لواجهات نماذج اللغة الكبيرة. فقد يدعم العميل Chat Completions فقط، بينما توجّهه إلى نقطة نهاية لا تدعم سوى Responses. ويستخدم Claude Code بروتوكول Anthropic Messages، وليس OpenAI Chat Completions. كما تختلف مسارات الطلبات وأجسامها تمامًا بين تنسيق Gemini الأصلي والتنسيق المتوافق مع OpenAI. قد تكتب نقطة النهاية الصحيحة يدويًا في curl، بينما يرسل العميل طلباته وفق بروتوكوله الافتراضي.
| نوع البروتوكول | مسار نقطة النهاية المعتاد | أدوات تستخدمه عادةً | طريقة المصادقة |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
العديد من العملاء مثل Cherry Studio وChatbox وCline | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
أدوات منظومة OpenAI الأحدث | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
أدوات Anthropic الأصلية مثل Claude Code | x-api-key مع anthropic-version |
| Gemini الأصلي | واجهة أصلية يتضمن مسارها اسم النموذج | Gemini SDK الأصلي | وفقًا لوثائق الجهة الرسمية والبوابة |
كيف تتحقق: راجع الجزء الأخير من مسار الطلب في سجلات العميل لتحديد البروتوكول المستخدم، ثم تأكد من أن نقطة نهاية البوابة التي اخترتها تدعمه. وإذا كانت في العميل قائمة منسدلة لاختيار «نوع المزود» أو «تنسيق API»، فتأكد من أن الخيار يطابق البروتوكول الذي تريد استخدامه.
كيف تصلح المشكلة: تأكد من توافق نوع البروتوكول في العميل وعنوان Base URL والنموذج معًا. عند استخدام التنسيق المتوافق مع OpenAI، اختر مزودًا من نوع OpenAI؛ وأعدّ الأدوات الأصلية مثل Claude Code وفق بروتوكول Anthropic؛ وعندما تحتاج إلى إمكانات Gemini الأصلية، استخدم تنسيق Gemini. تدعم APIYI كلاً من التنسيق المتوافق مع OpenAI وتنسيقات API الأصلية مثل Claude وGemini. ارجع إلى وثائق docs.apiyi.com لمعرفة عناوين الاتصال الخاصة بكل تنسيق أصلي، ولا تركّب المسارات اعتمادًا على الذاكرة.
نقطة التحقق 4: هل تتوافق ترويسات المصادقة مع البروتوكول؟
العَرَض: يظهر الخطأ 401، لكن مفتاح API نفسه يعمل دون مشكلة مع curl.
السبب: تستخدم الواجهات المتوافقة مع OpenAI عادةً Authorization: Bearer <Key>، بينما تستخدم واجهة Anthropic الأصلية عادةً x-api-key مع anthropic-version. وتطلب بعض المنصات أيضًا ترويسات خاصة بالمؤسسة أو المشروع. قد تكون ترويسات curl صحيحة، لكن العميل يرسل ترويسات مختلفة وفق بروتوكول آخر، أو يضيف ترويسة مؤسسة لا تتعرف عليها البوابة، فتفشل المصادقة.
كيف تتحقق: قارن ترويسات الطلب بين curl وسجلات العميل، وركز على حقول مثل Authorization وx-api-key وContent-Type وOpenAI-Beta. تحقق أيضًا من عدم وجود مسافات أو أسطر جديدة أو علامات اقتباس زائدة قبل المفتاح أو بعده؛ فهذا شائع عند النسخ واللصق من صفحة ويب.
كيف تصلح المشكلة: يجب أن تتوافق ترويسات المصادقة مع البروتوكول. عند اختيار البروتوكول الصحيح، سيرسل معظم العملاء الترويسات المناسبة تلقائيًا. وإذا كان العميل يسمح بتخصيص ترويسات الطلب، فاحذف ترويسات المؤسسة أو المشروع غير الضرورية، وأعد لصق المفتاح مع التأكد من عدم وجود أي محارف زائدة.
نقاط استكشاف أخطاء وكيل API وإصلاحها 5-7: معرّف النموذج وجسم الطلب والبث عبر الشبكة
نقطة التحقق 5: معرّف النموذج وتعيين النماذج
المشكلة: يظهر خطأ 404 أو 400 يفيد بأن النموذج غير موجود أو غير صالح، أو يفشل نموذج واحد فقط بينما تعمل النماذج الأخرى بصورة طبيعية.
السبب: يجب أن يتطابق معرّف النموذج مع قائمة نماذج البوابة حرفًا بحرف. تشمل الاختلافات الشائعة حالة الأحرف، ولاحقة الإصدار، وطريقة كتابة البادئة، مثل صيغة provider/model، والأسماء المستعارة. وقد يختلف اسم النموذج نفسه من منصة إلى أخرى. وربما لا تتضمن قائمة النماذج المدمجة في العميل المعرّف الذي تريده أصلًا، فيستبدله العميل بالقيمة الافتراضية دون تنبيه.
كيف تتحقق: انسخ معرّف النموذج من واجهة قائمة النماذج في البوابة أو من لوحة التحكم، وقارنه حرفًا بحرف بقيمة الحقل model في جسم الطلب ضمن سجلات العميل. إذا كان نموذج واحد فقط يفشل، فتحقق أولًا من تطابق معرّف النموذج مع نقطة النهاية، ثم تأكد من أن حسابك يملك صلاحية الوصول إليه.
كيف تصلح المشكلة: أضف نموذجًا مخصصًا يدويًا في العميل، والصق المعرّف الذي توفره البوابة مباشرةً بدلًا من كتابته. وإذا كان العميل يجري تعيينًا للنماذج، فتأكد من صحة الاسم الناتج عن التعيين.
💡 نصيحة بشأن معرّف النموذج: عند استخدام مفتاح واحد عبر APIYI apiyi.com لاستدعاء نماذج من OpenAI وClaude وGemini وDeepSeek وQwen وغيرها، اعتمد معرّفات النماذج الواردة في قائمة لوحة التحكم. قد يختلف اسم النموذج نفسه بين المنصات، ونسخه من لوحة التحكم هو أسهل طريقة لتجنب الأخطاء. تحقق أيضًا من توفر النموذج في لوحة التحكم والوثائق.
نقطة التحقق 6: متن الطلب وتنسيق المحتوى متعدد الوسائط
العَرَض: تعمل المحادثة النصية بشكل طبيعي، لكن إرسال صورة أو استدعاء أداة أو تفعيل معاملات الاستدلال يؤدي إلى الخطأ 400.
السبب: تظهر مشكلات توافق متن الطلب عادةً في بنية مصفوفة content متعددة الوسائط، أو طريقة كتابة حقل image_url، أو غياب بادئة MIME مثل data:image/png;base64, عن الصور المرمّزة بصيغة base64. وقد يكون تنسيق حقول استدعاء الأدوات غير متوافق مع البروتوكول الحالي، أو تختلف متطلبات max_tokens وmax_completion_tokens من نموذج إلى آخر. كذلك، لا تقبل معاملات الاستدلال إلا بعض النماذج. فمعاملات الشركات المختلفة ليست متوافقة تمامًا فيما بينها.
كيف تتحقق: أضف المتغيرات تدريجيًا. ابدأ بطلب نصي، ثم فعّل البث بعد نجاحه، وأضف استدعاء الأدوات، وأخيرًا المحتوى متعدد الوسائط. اختبر بعد كل إضافة؛ فالخطوة التي يبدأ عندها الفشل تكشف الحقل المسبب للمشكلة. تشير رسالة الخطأ عادةً إلى الحقل المعني، لذا احرص على قراءة استجابة الخطأ كاملةً.
كيف تصلح المشكلة: عطّل المعاملات المتقدمة التي لا تحتاج إليها في العميل، واضبط الحقول وفقًا لتوثيق النموذج المستهدف. استخدم بادئة base64 الصحيحة للصور أو عنوان URL يمكن الوصول إليه، واكتب تعريفات الأدوات بالتنسيق الذي يتطلبه البروتوكول الحالي.
نقطة التحقق 7: الشبكة والوكيل وTLS وتخزين الاستجابات المتدفقة
الأعراض: انتهاء مهلة الاتصال، أو ظهور stream disconnected، أو تلقي رد فارغ بعد انتظار طويل، أو نجاح الطلب غير المتدفق وفشل الطلب المتدفق.
السبب: قد يستخدم العميل وكيل النظام أو الوكيل المحدد في متغيرات البيئة، بينما لا يستخدمه curl، أو العكس. وقد تمنع جدران الحماية في المؤسسات، أو التحقق من شهادات TLS، أو تحليل عناوين IPv6، أو DNS العميل من الاتصال. وعند استخدام التدفق، تخزّن بعض الوكلاء الاستجابة مؤقتًا ولا تمررها إلا بعد اكتمالها، فلا يتلقى العميل أي بيانات ويحكم بانتهاء المهلة أو انقطاع التدفق.
كيف تتحقق: ميّز أولًا بين «عدم إنشاء الاتصال» و«انقطاع التدفق». في الحالة الأولى، تحقق من وجود أخطاء TLS أو الاتصال؛ أما في الثانية، فعادةً ما يكون العميل قد تلقى جزءًا من المحتوى. عطّل التدفق وحاول مجددًا؛ إذا نجح الطلب غير المتدفق، فالسبب على الأرجح هو تخزين الوكيل للاستجابة مؤقتًا أو إعدادات المهلة. تحقق أيضًا من تطابق متغيرات بيئة الوكيل في العميل والطرفية.
كيف تصلح المشكلة: وحّد إعدادات الوكيل بين العميل وcurl، واستبعد الوكلاء الذين يخزّنون الاستجابات مؤقتًا من مسار الطلبات المتدفقة، وزد مهلة العميل عند الحاجة. وإذا كان انقطاع الخدمة المصدرية يحدث أحيانًا، فيمكن إعادة المحاولة عددًا محدودًا من المرات، أو التبديل مؤقتًا إلى نموذج آخر للتحقق مما إذا كانت المشكلة تخص مصدرًا واحدًا.
البدء السريع مع خدمة وكيل API: جدول رموز الأخطاء وقائمة التحقق من إعدادات العميل
عند ظهور خطأ، استخدم رمزه أولًا لتضييق نطاق المشكلة، ثم راجع قائمة الإعدادات بندًا بندًا.
جدول رموز الأخطاء
| رمز الخطأ | الأسباب الشائعة | ما يجب التحقق منه أولًا |
|---|---|---|
| 401 | مفتاح API غير صالح أو منتهي الصلاحية أو معطّل؛ تنسيق ترويسة الطلب غير صحيح؛ عدم تطابق المؤسسة أو المشروع | نقطتا التحقق 1 و4 |
| 403 | مفتاح API صالح، لكن سياسة النموذج أو المؤسسة أو المنطقة ترفض الطلب؛ قائمة IP المسموح بها؛ لم يُفعّل الوصول إلى النموذج | نقطة التحقق 5 وأذونات الحساب |
| 404 | مسار Base URL غير صحيح؛ نقطة النهاية أو معرّف النموذج غير موجود؛ البوابة لا تدعم هذا المسار | نقاط التحقق 2 و3 و5 |
| 400 | متن الطلب أو المعلمات أو معرّف النموذج أو حقول الوسائط المتعددة غير صالحة؛ عدم توافق معلمات المزوّد | نقطتا التحقق 5 و6 |
| 429 | تجاوز حد الطلبات أو نفاد الرصيد | راجع Retry-After، ثم أخّر إعادة المحاولة تدريجيًا أو بدّل النموذج |
| 500/502/503/529 | خطأ في الخدمة المصدرية أو البوابة، وغالبًا ما يشير 529 إلى الضغط الزائد | أعد المحاولة لعدد محدود من المرات، وراجع سجلات البوابة |
| انتهاء المهلة، stream disconnected | انقطاع في الشبكة أو الوكيل أو TLS أو الخدمة المصدرية | نقطة التحقق 7 |
قائمة التحقق من إعدادات العميل
| البند | ما يجب التأكد منه |
|---|---|
| مصدر الإعدادات | هل تعدّل متغيرات البيئة أم ملف الإعدادات أم واجهة المستخدم الرسومية؟ أيها له الأولوية؟ هل توجد ملفات تعريف أو إعدادات مشاريع متعددة تتجاوز بعضها؟ |
| Base URL | هل يتضمن /v1؟ هل يضيف العميل /v1 تلقائيًا؟ هل توجد شرطة مائلة زائدة في النهاية؟ |
| نوع نقطة النهاية | هل تستخدم Chat Completions أو Responses، أم واجهة Claude أو Gemini الأصلية؟ هل يدعم إصدار العميل ذلك؟ |
| ترويسة المصادقة | هل تستخدم Authorization: Bearer أم x-api-key؟ هل تحتاج إلى anthropic-version؟ |
| معرّف النموذج | هل يطابق قائمة نماذج البوابة تمامًا، بما في ذلك حالة الأحرف والبادئة؟ |
| متن الطلب | هل يتضمن أدوات أو صورًا أو معلمات reasoning؟ هل يتوافق الحقل max_tokens مع النموذج المستهدف؟ |
| البث والشبكة | هل البث مفعّل؟ هل يحجز الوكيل البيانات مؤقتًا؟ هل إعدادات الوكيل في العميل وcurl متطابقة؟ |
إعادة إنتاج المشكلة بطلب بسيط للمقارنة
الطريقة الأكثر فعالية هي إجراء مقارنة مع تثبيت المتغيرات: استخدم Base URL ومفتاح API والنموذج ومتن الطلب نفسها، وأرسل الطلب أولًا باستخدام curl، ثم باستخدام العميل. اتبع الخطوات التالية:
- تحقّق من مفتاح API وBase URL باستخدام واجهة قائمة النماذج، مثل إرسال طلب إلى
https://api.apiyi.com/v1/models؛ - تحقّق من نقطة النهاية ومعرّف النموذج باستخدام طلب chat بسيط يحتوي على نص فقط؛
- فعّل البث للتحقق من الشبكة والوكيل؛
- أضف استدعاء الأدوات أو الوسائط المتعددة للتحقق من متن الطلب؛
- راجع سجلات العميل وسجلات البوابة في كل خطوة.
🚀 نصيحة لاستكشاف الأخطاء: تتيح لوحة تحكم APIYI عرض إحصاءات الاستخدام وسجلات الاستدعاءات التفصيلية. إذا ظهر خطأ في العميل ولم يظهر أي سجل للاستدعاء في لوحة التحكم، فهذا يعني أن الطلب لم يصل إلى البوابة، وأن المشكلة في إعدادات العميل أو الشبكة المحلية. أما إذا ظهر سجل يتضمن رسالة خطأ، فيمكنك استخدامه لتحديد ما إذا كانت المشكلة في المعلمات أم في الخدمة المصدرية.
الأسئلة الشائعة FAQ
Q1: إذا نجح الاتصال باستخدام curl لكن العميل لم يتصل، هل يفيد تغيير المفتاح؟
عادةً لا. نجاح curl يثبت أن المفتاح صالح. وغالبًا ما يبدو أن تغيير المفتاح حل المشكلة لأن العميل أُعيد تشغيله أو تغيّر ملف الإعدادات (profile) أثناء ذلك، فأُعيد تحميل الإعدادات. بدلًا من تغيير المفتاح، أغلق العميل تمامًا وأعد تشغيله، ثم تحقق من عنوان Base URL والمفتاح المستخدمين فعليًا في السجلات. يمكنك أيضًا التحقق من حالة المفتاح وسجل استدعاءاته في لوحة تحكم APIYI للتأكد من وجود مشكلة فيه فعلًا.
Q2: لماذا تعمل واجهة /models بينما يفشل طلب chat؟
تتحقق واجهة قائمة النماذج فقط من صحة المصادقة وعنوان Base URL بشكل أساسي، ولا تختبر نقطة نهاية chat أو معرّف النموذج أو متن الطلب. إذا فشل chat، فتحقق بالترتيب من توافق البروتوكول الذي يستخدمه العميل مع نقطة النهاية (نقطة التحقق 3)، ومن تطابق معرّف النموذج حرفيًا مع ما ورد في القائمة (نقطة التحقق 5)، ومن عدم احتواء متن الطلب على معلمات لا يدعمها النموذج المطلوب (نقطة التحقق 6).
Q4: إذا فشل نموذج واحد فقط بينما تعمل بقية النماذج، فما أول ما يجب التحقق منه؟
تحقق أولًا من معرّف النموذج ونقطة النهاية، ثم من صلاحيات الحساب. أكثر الأسباب شيوعًا هي الاختلافات في حالة الأحرف أو البادئة أو الاسم المستعار لمعرّف النموذج. وقد يتطلب النموذج أيضًا بروتوكولًا مختلفًا، مثل التنسيق الأصلي. وبعد ذلك، تحقق من الصلاحيات أو مدى توفر النموذج. يتيح لك APIYI التبديل بين نماذج من عدة مزودين باستخدام مفتاح واحد؛ لذا جرّب مؤقتًا نموذجًا مشابهًا للمقارنة، لتحديد ما إذا كانت المشكلة خاصة بنموذج واحد أم بالإعدادات عمومًا.
Q5: كيف أحدد ما إذا كانت المشكلة في العميل أم في البوابة؟
ركز على نقطتين: هل وصلت الطلبات إلى البوابة، وهل ينجح الطلب نفسه عند إرساله باستخدام curl؟ إذا لم يكن للطلب سجل في البوابة، فالمشكلة غالبًا في العميل أو الشبكة المحلية. وإذا نجح الطلب نفسه باستخدام curl وفشل من العميل، فالمشكلة غالبًا في كيفية تركيب العميل للطلب أو في متن الطلب. أما إذا فشل الطلب نفسه باستخدام curl أيضًا وأظهرت السجلات خطأ 5xx، فعندها يلزم التواصل مع دعم البوابة.
الخلاصة: قائمة تشخيص خدمة وكيل API في 10 دقائق ومتى تطلب المساعدة
إذا كان طلب curl ينجح بينما يتعذر على العميل الاتصال، فلا تتسرع في تغيير المفتاح. راجع هذه القائمة خلال 10 دقائق:
- راجع سجلات العميل: احصل على عنوان URL والترويسات ومتن الطلب الفعلي، وتأكد من تطبيق الإعدادات؛
- تحقق من Base URL: تأكد من ظهور
/v1مرة واحدة فقط، وعدم وجود شرطة مائلة مزدوجة أو أجزاء مسار مكررة؛ - تحقق من بروتوكول نقطة النهاية: هل تستخدم Chat Completions أم Responses أم Claude Messages أم بروتوكول Gemini الأصلي؟ تأكد من توافقه مع نوع العميل؛
- تحقق من ترويسة المصادقة: استخدم
Authorization: Bearerأوx-api-key، وأزل ترويسات المؤسسة الزائدة والمسافات من طرفي المفتاح؛ - تحقق من معرّف النموذج: قارنه حرفيًا بقائمة نماذج البوابة؛
- أرسل طلبًا مبسطًا: استخدم المفتاح والنموذج ومتن الطلب نفسها، وأرسل الطلب مرة عبر curl ومرة عبر العميل للمقارنة؛
- فعّل البث التدريجي: إذا فشل، فتحقق من التخزين المؤقت في الوكيل ومهلات الاتصال؛
- أضف الأدوات أو المحتوى متعدد الوسائط: إذا فشل الطلب، فتحقق من حقول متن الطلب؛
- حدد مصدر المشكلة أخيرًا: استند إلى سجلات البوابة لتحديد ما إذا كانت المشكلة في العميل أم البوابة.
متى يكون الخلل في العميل؟ عندما لا يظهر أي سجل للاستدعاء لدى البوابة، أو ينجح طلب curl باستخدام عنوان URL والترويسات ومتن الطلب نفسها تمامًا بينما يفشل العميل، بعد التأكد من صحة الإعدادات ودعم الإصدار لنقطة النهاية المستخدمة. عندها، حدّث إصدار العميل أو أبلغ عن المشكلة في مشروعه.
متى تتواصل مع دعم البوابة؟ عندما يفشل الطلب المبسط نفسه عبر curl أيضًا، ويظهر سجل الاستدعاء في البوابة مع رمز خطأ 5xx؛ أو عندما يستمر نموذج معين في إرجاع الأخطاء بينما تعمل النماذج الأخرى بشكل طبيعي، بعد استبعاد مشكلات معرّف النموذج والصلاحيات. عند التواصل مع الدعم، أرفق وقت الطلب ومعرّف النموذج ورمز الخطأ ورسالة الخطأ من السجلات لتسريع التشخيص.
بالنسبة إلى أدوات الفرق التي تتطلب استقرارًا، يُعد تعدد النماذج ومسارات الاتصال وسيلة بحد ذاته لتشخيص المشكلات: إذا تعطل نموذج أو مسار، يمكنك التبديل إلى آخر وإجراء اختبار مقارن لتحديد نطاق المشكلة فورًا. يتيح APIYI على apiyi.com الوصول بمفتاح واحد إلى الصيغة المتوافقة مع OpenAI والصيغ الأصلية لـ Claude وGemini، مع الاستفادة من بيانات الاستخدام والسجلات في لوحة التحكم للتحقق السريع. راجع لوحة التحكم والوثائق للاطلاع على الأسعار والتوافر.
الكاتب: الفريق التقني في APIYI
للتواصل التقني: يسعدنا تواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI
