استكشاف الأخطاء وإصلاحها

اتبع العَرَض الذي يطابق ما تراه. في جميع الحالات تقريبًا، تكون علامة التبويب Logs أسرع أداة تشخيص، إذ تعرض حالة كل طلب ونمط الإخفاق (مفتاح واحد؟ نموذج واحد؟ كل شيء؟). راجع النشاط والسجلات.

الطلبات محظورة

كل طلب يفشل بالخطأ 402 insufficient_credits

السبب: الوحدة غير مفعّلة لهذه المنشأة، أو نفد الرصيد المدفوع مسبقًا (ستعرض علامة التبويب Overview الرسالة "Your balance is depleted. Inference requests will be blocked until you top up."). بالنسبة إلى مفاتيح API، تُرجع المنشأة التي لم يُفعَّل فيها Model Router الخطأ 403 "Model Router is not enabled for this facility" بدلًا من ذلك.

الحل: فعّل Model Router من صفحة Welcome to Model Router (راجع بدء الاستخدام)، ثم اشحن الرصيد من Budgets & Limits ← Balance & Top-up. تُستأنف الطلبات خلال لحظات من إضافة الرصيد. لمنع تكرار ذلك، فعّل الشحن التلقائي. راجع الميزانيات وعمليات الشحن.

تفشل الطلبات بالخطأ 402 budget_exceeded

السبب: بلغ الإنفاق أحد الحدود. توضح رسالة الخطأ الفترة المعنية (يومية / شهرية / مدى الحياة)، وبالنسبة إلى الفترتين اليومية والشهرية، توضح بالضبط موعد إعادة التعيين بحسب المنطقة الزمنية لمنشأتك. قد يكون الحد على مستوى الحساب بأكمله أو حدًا على مفتاح معيّن أو خدمة متصلة معيّنة (تذكر الرسالة "This key's" / "This agent's" عندما يكون الحد محدد النطاق).

الحل: إما أن تنتظر موعد إعادة التعيين المذكور، أو ترفع الحد (Budgets & Limits ← Spend Limits، أو من إعدادات المفتاح أو الخدمة)، أو تستخدم Reset hard cap بالنسبة إلى السقف الثابت مدى الحياة. تعرض صفحة Spend Limits بالضبط الحدود التي وصلت إلى الحالة "Limit reached".

تفشل الطلبات بالخطأ 403 content_policy_violation

السبب: طابقت المطالبة عامل تصفية محتوى في وضع block أو درع الحماية من حقن المطالبات.

الحل: راجع Settings ← Guardrails. إذا كان أحد التكاملات يحتاج فعلًا إلى قواعد مختلفة، فاستخدم مفتاح التبديل Override facility guardrails الخاص به بدلًا من تخفيف السياسة المطبقة على مستوى المنشأة بأكملها. راجع Guardrails.

تفشل الطلبات بالخطأ 429

السبب: تجاوز المفتاح أو الخدمة المتصلة حد المعدل Requests / min أو Tokens / min.

الحل: تمهّل ثم أعد المحاولة، أو ارفع حدود المعدل في إعدادات المفتاح أو الخدمة (الحقل الفارغ = بلا حد). راجع مفاتيح API.

نموذج معيّن يُرجع أخطاء بينما تعمل النماذج الأخرى

السبب: قد يكون النموذج معطّلًا لمنشأتك، أو مستبعدًا بموجب تقييد النماذج في المفتاح، أو قد يواجه المزود مشكلات.

الحل: تحقق من Settings ← Models (هل النموذج مفعّل؟)، ومن قائمة Restrict models في المفتاح، ومن Activity ← Performance ← Reliability & performance by model لمعرفة معدل أخطاء النموذج بمرور الوقت.

مشكلات مفاتيح API

401 Unauthorized

السبب: مع الرمز invalid_api_key ("Missing or invalid API key")، يكون الترويسة Authorization: Bearer … مفقودة أو مشوّهة. ومن دون رمز ("Invalid API key")، يكون المفتاح غير معروف (خطأ في الكتابة، أو سر قديم بعد عملية rotate) أو revoked.

الحل: تأكد من تنسيق الترويسة، وتحقق من حالة المفتاح في Settings ← Service Access & API Keys. أعد تنشيط المفتاح الملغى، أو حدّث خدمتك لتستخدم السر الجديد إذا جرى تدوير المفتاح.

فقدت سر المفتاح

يُعرض السر مرة واحدة فقط عند الإنشاء ولا يمكن استرداده. استخدم Rotate: يُصدَر سر جديد (يُعرض مرة واحدة) ويحتفظ المفتاح بتسميته وحدوده وسجله. حدّث كل خدمة تستخدم المفتاح: "You will need to reconfigure any services still using the old key."

المفتاح يعمل لكن الاستخدام يظهر تحت اسم خاطئ

تُعرَّف المفاتيح بواسطة Label الخاصة بها في Activity وLogs. عدّل المفتاح وعيّن تسمية ذات معنى، وامنح كل نظام مفتاحه الخاص بدلًا من مشاركة مفتاح واحد.

مشكلات الوكلاء

يظهر الوكيل في حالة Offline

السبب: الجهاز مطفأ أو لا يتوفر له اتصال، وهذه مسألة اتصال بالجهاز وليست إعدادًا في Model Router.

الحل: تحقق من طاقة الجهاز وشبكته. لا تتأثر إعدادات الوصول الخاصة به، وتعود إلى العمل فور إعادة اتصاله.

توقف الوكيل عن الاستجابة لطلبات الذكاء الاصطناعي

تحقق بالترتيب التالي:

1. الرصيد: يؤدي نفاد الرصيد إلى حظر جميع الوكلاء (يعرض الوكيل حالة تتطلب رصيدًا). اشحن الرصيد.
2. الحدود لكل خدمة: Settings ← Service Access & API Keys ← Connected Services: هل يعرض الوكيل "Limit reached"؟ ارفع الحد أو انتظر انتهاء فترته.
3. حدود الحساب: Budgets & Limits ← Spend Limits.
4. Logs: صفِّ حسب الوكيل لرؤية الخطأ الفعلي في طلباته.

أسئلة الرصيد والفوترة

أرقام الإنفاق تبدو متأخرة

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

لم يُنفَّذ الشحن التلقائي

تحقق من وجود شريط تنبيه في صفحة Balance & Top-up: لا توجد بطاقة محفوظة، أو البطاقة تحتاج إلى مصادقة، أو رُفضت البطاقة. أصلح البطاقة (Update card / Edit payment details) أو اشحن الرصيد يدويًا. تُجرى عمليات التحقق من الشحن التلقائي كل 15 دقيقة تقريبًا، لذا قد يستغرق تفعيل الشحن بعد تجاوز الحد للتو بضع دقائق.

فشلت عملية شحن

"Additional card authentication is required. Please try again.": أعد المحاولة، فقد يطلب منك البنك التحقق. "Top-up could not be completed.": رُفضت عملية الخصم، فتحقق من البطاقة أو جرّب مبلغًا آخر. لا يُضاف أي رصيد ما لم تنجح عملية الخصم.

خُصم المبلغ مني لكن الرصيد لم يتغير

تُضاف عمليات الشحن فورًا، لذا حدّث الصفحة. إذا ظل الرصيد لا يعكس عملية خصم ناجحة، فدوّن Transaction ID وPayment reference من درج تفاصيل المعاملة (أو من كشف حساب بطاقتك) وقدّم طلب دعم.

أسئلة السجلات والتحليلات

طلب أجريته للتو لا يظهر في Logs بعد

شغّل التحديث Live (أو انقر على Refresh now). تظهر الطلبات عادةً خلال لحظات، وقد يستغرق الأمر وقتًا أطول قليلًا عند الضغط.

تعرض السجلات نموذجًا لم أطلبه

إذا أرسلت model: "auto"، فستعرض السجلات النموذج الذي اختاره فعليًا Auto Router؛ افتح تفاصيل الطلب لرؤية Requested model: auto. هذا سلوك متوقع. راجع النماذج.

تعرض الصفوف "No charge"

تحمل الاستجابات الفاشلة أو الفارغة التي لا تكلف شيئًا الشارة No charge؛ فهي مسجلة للاكتمال لكنها لم تستهلك من الرصيد.

ملف CSV الذي صدّرته أصغر من المتوقع

يقتصر التصدير الأولي على 25,000 صف كحد أقصى، لذا ضيّق النطاق الزمني أو استخدم تصديرًا موجزًا. لاحظ أيضًا: "Summaries cover whole days, so a sub-day or graph selection is widened to full days."