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

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

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

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

النقاط الرئيسية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://tokenlab.sh/en/dashboard/api?tab=requestConsole&requestId=<request_id>

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

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

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

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

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

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

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

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

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

كيف تعمل مع صادرات الاستخدام

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

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

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

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

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

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

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

1. احصل على معرف الطلب. من سجلات العميل، أو استجابة الخطأ، أو تقرير المستخدم. إذا كنت لا تسجل معرفات الطلبات من جانبك اليوم، ابدأ الآن — فهو أسرع مفتاح بحث لديك.
2. افتح وحدة التحكم بالرابط المباشر. استخدم معامل الاستعلام requestId للقفز مباشرة إلى أداة الفحص.
3. تحقق من حقل الحالة أولاً. مفوتر، معلق، مسترد، أو فاشل — هذا يضع إطاراً لبقية التحقيق.
4. تأكد من النموذج الذي خدم الطلب فعلياً. قارنه بما توقعت إرساله.
5. تحقق من حالة التخزين المؤقت. عدم الوصول إلى التخزين المؤقت حيث توقعت الوصول يمكن أن يفسر زمن الاستجابة أو التكلفة غير المتوقعة.
6. تحقق من مصدر المفتاح. تأكد من استخدام مفتاح واجهة برمجة التطبيقات والبيئة الصحيحين، خاصة في إعدادات الاختبار مقابل الإنتاج.
7. اقرأ سياق الخطأ ومعلومات التوجيه. هذا هو المكان الذي يظهر فيه السبب الجذري الفعلي عادةً.
8. راجع معاينة الحمولة المحجوبة. تأكد من أن شكل الطلب يطابق ما أرسله عميلك — غالباً ما تظهر المعاملات المشوهة هنا قبل أن تظهر في أي مكان آخر.
9. ارجع إلى مرجع واجهة برمجة التطبيقات إذا لزم الأمر. يوثق مرجع واجهة برمجة تطبيقات إكمال الدردشة لـ TokenLab أشكال الطلب والاستجابة المتوقعة، وهو مفيد للتأكد مما إذا كانت الحمولة مشوهة من جانب العميل.
10. إذا كان نمطاً، وليس حالة فردية، انتقل إلى صادرات الاستخدام. طلب واحد فاشل هو مشكلة وحدة تحكم. عشرة طلبات فاشلة على مدار ساعة هي نمط يستحق التصدير والمراجعة بشكل إجمالي.

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

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

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

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

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

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

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

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

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

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

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

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