وحدة طلبات TokenLab: تصحيح أخطاء استدعاءات API الخاصة بالذكاء الاصطناعي من لوحة تحكم واحدة

نادراً ما يعلن استدعاء واجهة برمجة تطبيقات (API) فاشل عن نفسه بوضوح. فغالباً ما تحصل على رمز حالة، وربما سلسلة نصية للخطأ، وقناة دعم يسأل فيها أحدهم "ما هو معرف الطلب (request ID)؟". إذا لم يكن المعرف في متناول يدك، فإن عملية التحقيق تتعطل قبل أن تبدأ. لقد قمنا ببناء وحدة تحكم طلبات TokenLab (TokenLab Request Console) لسد هذه الفجوة من خلال وضع تفاصيل الطلب في عرض لوحة تحكم واحدة. فهي تعرض النموذج، والمفتاح، وحالة التخزين المؤقت، وحالة الفوترة، والتوقيت، ومعاينة للحمولة (payload) مع حجب البيانات الحساسة. في خط أنابيبنا، نتعامل مع معرف الطلب كأول مفتاح للبحث.

أبرز النقاط

• تعد وحدة تحكم طلبات TokenLab واجهة لتصحيح أخطاء الطلبات داخل لوحة تحكم API الخاصة بـ TokenLab، وليست تقريراً للفوترة.
• كل طلب له معرف يمكنك البحث عنه مباشرة. يمكنك الانتقال برابط مباشر إلى طلب محدد باستخدام requestId في الرابط (URL).
• تعرض وحدة التحكم التوجيه، وحالة الفوترة، وحالة التخزين المؤقت، وسياق النموذج/المفتاح، ومعاينات للحمولة مع حجب البيانات الحساسة للطلبات الأخيرة.
• يقتصر الوصول على مؤسستك ويخضع لأذونات عضوية لوحة التحكم — حيث يرى زملاؤك ما يسمح به دورهم.
• لتصحيح أخطاء حادثة فردية، استخدم وحدة التحكم. أما لمراجعة التكاليف المجمعة عبر نطاقات زمنية، فاستخدم صادرات الاستخدام (usage exports) بدلاً من ذلك.

ما هي وحدة تحكم طلبات TokenLab؟

يمكنك الوصول إليها عبر /dashboard/api?tab=requestConsole، داخل قسم API في لوحة تحكم TokenLab. تقع لوحة تحكم API نفسها في /dashboard/api. بُنيت وحدة التحكم على فرضية واحدة: عندما يفشل الطلب، يأتي الإصلاح الأسرع من امتلاك سياقه الكامل أمامك، وليس من التخمين بناءً على رسالة خطأ فقط.

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

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

لوحة الفحص. بمجرد اختيار طلب ما، تُفتح لوحة الفحص بالتفاصيل الكاملة: النموذج الذي خدم الطلب، ومفتاح API المستخدم، وما إذا كان قد وصل إلى التخزين المؤقت، وما هي الحالة النهائية.

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

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

معاينة الحمولة. يتم عرض أجسام الطلب والاستجابة كمعاينات محجوبة البيانات عند توفرها، مما يمنحك الشكل والبنية دون كشف الأسرار الخام في الجسم.

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

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

ما الذي يجب فحصه أولاً؟

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

فرز الحقول الخمسة

الفحص	ما يخبرك به
معرف الطلب (Request ID)	يؤكد أنك تنظر إلى الاستدعاء الدقيق المعني، وليس استدعاءً مشابهاً
الحالة	مفوتر، معلق، مسترد، أو فاشل — يخبرك ما إذا كان هذا سؤال تكلفة أم سؤالاً تقنياً
النموذج	أي نموذج خدم الطلب فعلياً (مفيد إذا كنت توجه الطلبات عبر نماذج متعددة)
حالة التخزين المؤقت	ما إذا كان الوصول إلى التخزين المؤقت للمطالبة (prompt cache) قد غير التكلفة أو زمن الاستجابة
مصدر المفتاح	أي مفتاح API تم استخدامه، مفيد عندما تتشارك مفاتيح أو بيئات متعددة في تكامل واحد

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

/dashboard/api?tab=requestConsole&requestId=%3Crequest_id>

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

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

قراءة حقل الحالة بشكل صحيح

الحالات الأربع — مفوتر، معلق، مسترد، فاشل — تجيب على أسئلة مختلفة:

• مفوتر (Billed) يعني أن الاستدعاء اكتمل واستهلك أرصدة. إذا أبلغ مستخدم عن خطأ ولكن الطلب يظهر كمفوتر، فهذا يستحق الإبلاغ عنه بشكل منفصل. إنه يشير إلى أن الفشل حدث على جانب العميل بعد استجابة ناجحة.
• معلق (Pending) يعني أن الطلب لا يزال قيد التنفيذ أو بانتظار التسوية. لا تعامل هذا كفشل قبل الأوان.
• مسترد (Refunded) يعني أن TokenLab ألغت الرسوم، وعادة ما يرتبط ذلك بفشل من جانب المزود أو التوجيه.
• فاشل (Failed) يعني أن الاستدعاء لم يكتمل بنجاح ولم تتم فوترته.

معرفة أي من هذه الحالات ينطبق قبل التصعيد يوفر جولة من الأخذ والرد مع الدعم.

تأكيد حالة النموذج والتخزين المؤقت

إذا كنت تشغل طلبات مقابل نماذج مثل Claude Sonnet 5، أو DeepSeek V4 Pro، أو Gemini 3.5 Flash من خلال تكامل مشترك، تأكد من أن وحدة التحكم تعرض النموذج الذي توقعته. يمكن لعميل تم تكوينه بشكل خاطئ، أو متغير بيئة قديم، أو تجاوز توجيه (routing override) أن يرسل حركة المرور إلى النموذج الخطأ دون خطأ واضح من جانب العميل.

حالة التخزين المؤقت مهمة لسببين: التكلفة وزمن الاستجابة. عدم الوصول إلى التخزين المؤقت (cache miss) حيث توقعت الوصول (hit) يعني عادةً أن بادئة المطالبة قد تغيرت، حتى لو بشكل طفيف. ابحث عن طابع زمني، أو حقل تمت إعادة ترتيبه، أو مسافة بيضاء إضافية. يتيح لك فلتر حالة التخزين المؤقت في وحدة التحكم مقارنة طلبات الوصول وعدم الوصول جنباً إلى جنب.

كيف تعمل وحدة تحكم طلبات TokenLab مع صادرات الاستخدام

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

صُممت صادرات الاستخدام للمراجعة الإجمالية: الإنفاق عبر نطاق زمني، وتفاصيل حسب النموذج أو المفتاح، ونوع التقارير التي تقدمها لأصحاب المصلحة الماليين أو تستخدمها للتسوية الشهرية. إذا كنت تريد الإجابة على "كم أنفقنا على DeepSeek V4 Pro الأسبوع الماضي"، فهذا سؤال خاص بالتصدير، وليس سؤالاً خاصاً بوحدة التحكم. راجع دليل صادرات استخدام لوحة تحكم TokenLab لهذا المسار.

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

روتين تصحيح أخطاء عملي

يتحول تصحيح الأخطاء المخصص إلى تخمين تحت الضغط. الروتين القابل للتكرار يمنع الحوادث من أن تصبح أطول مما يجب أن تكون عليه.

قائمة التحقق: عندما يفشل طلب

1. احصل على معرف الطلب. من سجلات العميل، أو استجابة الخطأ، أو تقرير المستخدم. إذا كنت لا تسجل معرفات الطلبات من جانبك اليوم، فابدأ الآن. إنه أسرع مفتاح بحث لديك.
2. افتح وحدة التحكم باستخدام الرابط المباشر. استخدم معلمة الاستعلام requestId للانتقال مباشرة إلى أداة الفحص.
3. تحقق من حقل الحالة أولاً. مفوتر، معلق، مسترد، أو فاشل. هذا يؤطر بقية التحقيق.
4. تأكد من النموذج الذي خدم الطلب فعلياً. قارنه بما توقعت إرساله.
5. تحقق من حالة التخزين المؤقت. عدم الوصول إلى التخزين المؤقت حيث توقعت الوصول يمكن أن يفسر زمن استجابة أو تكلفة غير متوقعة.
6. تحقق من مصدر المفتاح. تأكد من استخدام مفتاح API والبيئة الصحيحين، خاصة في إعدادات الاختبار مقابل الإنتاج.
7. اقرأ سياق الخطأ ومعلومات التوجيه. هنا عادة ما يصبح السبب الجذري مرئياً.
8. راجع معاينة الحمولة المحجوبة. تأكد من أن شكل الطلب يطابق ما أرسله عميلك. غالباً ما تظهر المعلمات المشوهة هنا قبل أن تظهر في أي مكان آخر.
9. ارجع إلى مرجع API إذا لزم الأمر. يوثق مرجع API لإكمال الدردشة (chat completions) الخاص بـ TokenLab على https://docs.tokenlab.sh/api-reference/chat/create-completion أشكال الطلبات والاستجابات المتوقعة. استخدمه للتأكد مما إذا كانت الحمولة مشوهة من جانب العميل.
10. إذا كان نمطاً، وليس حالة فردية، انتقل إلى صادرات الاستخدام. طلب واحد فاشل هو مشكلة وحدة تحكم. عشرة طلبات فاشلة خلال ساعة هي نمط يستحق التصدير والمراجعة بشكل إجمالي.

اتباع هذا الترتيب — المعرف، الحالة، النموذج، التخزين المؤقت، المفتاح، الخطأ، الحمولة — يمنعك من تخطي الحقل الذي يفسر الفشل فعلياً.

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

كيف أجد طلباً فاشلاً بدون معرف طلب؟

استخدم فلاتر عرض القائمة في وحدة تحكم طلبات TokenLab. ضيق النطاق حسب النموذج، والنطاق الزمني، وحالة التخزين المؤقت للمطالبة، ومصدر المفتاح، والحالة. على سبيل المثال، قم بالتصفية حسب حالة "فاشل" خلال الساعة الأخيرة، ثم ابحث عن الاستدعاء الذي يسأل عنه المستخدم. بمجرد العثور عليه، افتح أداة الفحص وانسخ معرف الطلب للسجلات المستقبلية.

لماذا قد يظهر الطلب كمفوتر بينما يبلغ العميل عن خطأ؟

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

ما الذي يخبرني به عدم الوصول إلى التخزين المؤقت (cache miss) في أداة الفحص؟

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

هل يمكنني مشاركة رابط طلب مع زميل؟

نعم، إذا كانت أذونات عضوية لوحة التحكم الخاصة بهم تسمح بذلك. بيانات الطلب مقتصرة على مؤسستك. استخدم تنسيق الرابط المباشر /dashboard/api?tab=requestConsole&requestId=<request_id> لفتح أداة الفحص مباشرة. يرى الزملاء ما يسمح به دورهم.

متى يجب أن أنتقل من وحدة التحكم إلى صادرات الاستخدام؟

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

المصادر والحداثة

• وحدة تحكم طلبات TokenLab — /dashboard/api?tab=requestConsole — تمت ملاحظتها في 2026-07-09
• مرجع API لإكمال الدردشة من TokenLab — https://docs.tokenlab.sh/api-reference/chat/create-completion — تمت ملاحظته في 2026-07-09
• صادرات استخدام لوحة تحكم TokenLab — /blog/tokenlab-dashboard-usage-exports — تمت ملاحظتها في 2026-07-09
• دليل النماذج العام لـ TokenLab — /models — تمت ملاحظته في 2026-07-09
• لوحة تحكم مفاتيح API لـ TokenLab — /dashboard/api — تمت ملاحظتها في 2026-07-09

أمثلة النماذج المشار إليها (Claude Sonnet 5، DeepSeek V4 Pro، Gemini 3.5 Flash) تعكس النموذج الحالي SSOT اعتباراً من 2026-09-19. تمت ملاحظة لقطة المصدر لملاحظة وحدة التحكم هذه في 2026-07-09؛ كان تاريخ SSOT الأصلي للنموذج في المصدر هو 2026-07-07.

الخطوات التالية

إذا كنت تقوم حالياً بتصحيح أخطاء API للذكاء الاصطناعي عن طريق البحث في سجلات جانب العميل والرجوع إلى لوحة تحكم فوترة منفصلة، فإن وحدة تحكم الطلبات تزيل خطوة من تلك الحلقة. تقع وحدة التحكم في /dashboard/api?tab=requestConsole. توجد لوحة تحكم مفاتيح API في tokenlab.sh/dashboard/api. تم توثيق شكل طلب/استجابة إكمال الدردشة على https://docs.tokenlab.sh/api-reference/chat/create-completion. لمراجعة الإنفاق الإجمالي، استخدم صادرات الاستخدام. للحصول على تفاصيل تسعير النماذج ونوافذ السياق، راجع دليل النماذج. افتح وحدة التحكم وحدد موقع طلب فاشل حديث حسب المعرف.