الأدلة الأساسية

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

احتفظ بالمعرفات اللازمة لتتبع الطلبات والمهام والتكاليف

احتفظ بمعرفات الطلبات والمهام والفواتير الخاصة بـ TokenLab في سجلاتك. فهي تربط إجراء المستخدم بنتيجته وتكلفته دون تخزين المطالبة (prompt) أو الوسائط الخاصة.

في Console، تظل تفاصيل الطلب والاستجابة التي تم التقاطها متاحة لمدة 30 يوماً من تاريخ الالتقاط، وينتهي الوصول إليها عند انتهاء الصلاحية تماماً حتى لو كان التنظيف الفعلي لا يزال في قائمة الانتظار. لهوية الطلب وسجل الفواتير/الاستخدام فترات صلاحية مستقلة. راجع الاحتفاظ بالبيانات.

من الطلب إلى التحقيق والدعم

  1. افتح Runs في مساحة العمل التي تملك الطلب. ابحث عن معرف الطلب (Request ID) الخاص به وحدد الصف.

  2. اختر Open full details لفتح صفحة مخصصة. يقوم خيار Back to requests باستعادة فلاتر القائمة. لا يمنح الرابط أبداً حق الوصول إلى مساحة عمل أخرى؛ استخدم حساباً مصرحاً له بتلك المساحة.

  3. بالنسبة للحالة المعلقة أو غير المعروفة، قم بتحديث التقدم أولاً. في حالة الفشل أو الاستجابة المتقطعة، اختر Investigate the issue عندما يكون ذلك متاحاً. يبدأ هذا تحقيقاً في ذلك الطلب داخل Agent المدمج في التطبيق؛ ولا يقوم بإعادة تشغيل طلب النموذج الأصلي. الطلبات الناجحة لا تحتاج إلى تحقيق بشكل افتراضي.

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

  5. بعد الإرسال، احتفظ بالتأكيد وتابع نفس المحادثة في Support. أعد استخدامها للردود والمعلومات الإضافية بدلاً من إرسال مكررات.

المعرفات التي يجب الاحتفاظ بها

المعرفأين يظهراستخدمه لـ
request_idنصوص الأخطاء، سجلات لوحة التحكم، سجلات الاستخدامدعم مستوى الطلب والمطابقة
id / task_idاستجابات الإنشاء والحالة غير المتزامنة (Async)استطلاع أي مهمة غير متزامنة باستخدام GET /v1/tasks/{id}
poll_urlاستجابات الإنشاء غير المتزامنةرابط الحالة؛ استطلع /v1/tasks/{id} باستخدام id
billing_transaction_idالاستجابات غير المتدفقة عند التسوية، استجابات حالة المهام غير المتزامنة، سجلات الاستخدام، X-Billing-Transaction-IDمطابقة التكاليف
X-Task-IDرؤوس استجابة المهام غير المتزامنةربط المهام على مستوى الرأس (Header)
معرف الوظيفة/المستخدم الخاص بكتطبيقكالعثور على طلب TokenLab لإجراء مستخدم معين

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

ما يجب تسجيله

سجل ما يكفي لتشخيص الطلب دون تسريب أسرار:

  • نقطة النهاية (Endpoint)، طريقة HTTP، النموذج، رمز الحالة، الطابع الزمني، وزمن الاستجابة (latency).
  • المعرفات العامة: request_id و task_id و poll_url و billing_transaction_id عند وجودها.
  • أسماء الحقول المرسلة في الطلب، وليس المطالبة الكاملة أو محتوى الوسائط الخاص.
  • استجابات الحالة النهائية غير المتزامنة وحقول الخطأ الآمنة.
  • عدد مرات إعادة المحاولة من جانب العميل وما إذا كانت إعادة المحاولة قد أنشأت مهمة جديدة أو استأنفت مهمة موجودة.

قم دائماً بحجب Authorization ومفاتيح API ورموز الإدارة (management tokens) والروابط الموقعة وروابط الوسائط الخاصة والمطالبات الكاملة والبيانات الشخصية للمستخدم ما لم يكن لديك إذن صريح بالاحتفاظ بها.

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

العرضالفحص الأولصفحة مفيدة
401 أو 403مفتاح API، رمز الإدارة، الوصول للمؤسسة، نطاق المفتاحالمصادقة
402الرصيد، حد إنفاق مفتاح APIالفواتير والأسعار
429فئة الحساب، حد معدل نقطة النهاية، سلوك إعادة المحاولةحدود المعدل
400 invalid_request_errorحقل غير مدعوم، نقطة نهاية خاطئة، حقل مطلوب مفقود، أو عدم تطابق طلب النموذجمعالجة الأخطاء
تعذر العثور على مهمة غير متزامنةمفتاح API خاطئ، معرف مكتوب بشكل خاطئ، أو مهمة منتهية الصلاحيةالوظائف غير المتزامنة والاستطلاع
التكلفة لا تتطابق مع واجهة المستخدمتوقيت التسوية أو مقارنة معرف خاطئالفواتير والأسعار

مطابقة الاستخدام

استخدم Management API للمطابقة من جانب الخادم:

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
  -H "Authorization: Bearer mt-your-management-token"

يمكن لـ GET /v1/management/api-keys/{keyId}/usage التصفية حسب scene و model و modelVendor و startDate و endDate. استخدم هذه السجلات بدلاً من كشط صفحات Console أو حساب التكاليف من عدد رموز الاستجابة فقط. يعني endDate الذي يحتوي على تاريخ فقط الساعة 00:00 بالتوقيت العالمي المنسق (UTC) في بداية ذلك اليوم؛ راجع الحصول على استخدام مفتاح API.

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

ما يجب إرساله للدعم

عند الاتصال بالدعم، قم بتضمين:

  • request_id.
  • task_id و poll_url للعمل غير المتزامن.
  • billing_transaction_id عند وجوده.
  • نقطة النهاية، الطريقة، النموذج، الطابع الزمني، ورمز الحالة.
  • أسماء حقول الطلب ونص الخطأ الآمن.
  • النتيجة المتوقعة وما رآه المستخدم فعلياً.

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

فحوصات تستحق الأتمتة

  • تنبيه عند تكرار استجابات 401 و 402 و 429 و 5xx بشكل منفصل؛ كل منها يحتاج إلى استجابة مختلفة.
  • تتبع الوظائف غير المتزامنة التي تظل غير نهائية لفترة أطول من اتفاقية مستوى الخدمة (SLA) الخاصة بمنتجك.
  • تتبع محاولات الإنشاء المكررة لنفس معرف وظيفة المستخدم.
  • قم بأخذ عينات من الوظائف المكتملة وتحقق من توافق الأصول المرئية للمستخدم، وسجل الاستخدام، وسجل المهام المخزن.

مرجع API

الموضوعالمرجع
معالجة الأخطاءمعالجة الأخطاء
حدود المعدلحدود المعدل
الفواتير والأسعارالفواتير والأسعار
الحصول على استخدام مفتاح APIالحصول على استخدام مفتاح API
الحصول على حالة المهمةالحصول على حالة المهمة

في هذه الصفحة