API Hop

الوثائق

وثائق API Hop

الاتصال والاستخدام

خطوات تشخيص إخفاقات الاتصال وأخطاء النماذج والطلبات وانقطاع المحادثات.

عند فشل استدعاء أو انقطاع محادثة، تحقق أولا من ثلاثة أمور بطلب بسيط: المصادقة ومسار نقطة النهاية وإتاحة النموذج.

يتعذر الاتصال بالمنصة؟

تحقق مما يلي:

  • ضبط مفتاح API بصورة صحيحة دون مسافات أو أسطر جديدة إضافية.
  • صحة Base URL وعدم احتوائه على مسارات مكررة.
  • مطابقة مسار نقطة النهاية لبروتوكول العميل، مثل المسار المتوافق مع OpenAI لعملاء OpenAI.
  • عدم حجب الطلبات بواسطة الشبكة المحلية أو وكيل الشركة أو الجدار الناري أو DNS أو فحص HTTPS.
  • عدم انتهاء صلاحية مفتاح API أو حذفه أو تبعيته لحساب مقيد.

للاستدعاءات المتوافقة مع OpenAI، اختبر بطلب بسيط دون بث:

bash
curl https://api.apihop.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "user", "content": "Reply with OK only." }
    ],
    "stream": false
  }'

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

اخترت النموذج لكن لا توجد استجابة أو يظهر خطأ؟

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

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

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

ماذا أفعل عند خطأ المحادثة أو انقطاعها؟

حدد موضع الإخفاق:

  • قبل بدء الطلب: تحقق من المصادقة والمسار والنموذج والمعاملات.
  • أثناء البث: تحقق من مهلة العميل وسلسلة الوكلاء وتحليل SSE.
  • مع سياق أو إخراج طويل: تحقق من حجم الطلب وحدود الإخراج ومهلة الخدمة.

المعالجة المقترحة:

  1. اقرأ حقول الخطأ المحددة.
  2. انتقل مؤقتا إلى الوضع دون بث لتمييز إخفاق النموذج عن إخفاق تحليل البث.
  3. أضف إعادة محاولة بتأخير تدريجي لأخطاء 429 وعدم استقرار الشبكة وبعض أخطاء 5xx.
  4. أدرج السياق المطلوب عند إعادة المحاولة بدلا من افتراض حفظ حالة المحادثة على الخادم.
  5. سجل X-Request-ID إذا استمرت المشكلة.