الأدلة الأساسية
السجلات واستكشاف الأخطاء وإصلاحها
احتفظ بالمعرفات اللازمة لتتبع الطلبات والمهام والتكاليف
احتفظ بمعرفات الطلبات والمهام والفواتير الخاصة بـ TokenLab في سجلاتك. فهي تربط إجراء المستخدم بنتيجته وتكلفته دون تخزين المطالبة (prompt) أو الوسائط الخاصة.
في Console، تظل تفاصيل الطلب والاستجابة التي تم التقاطها متاحة لمدة 30 يوماً من تاريخ الالتقاط، وينتهي الوصول إليها عند انتهاء الصلاحية تماماً حتى لو كان التنظيف الفعلي لا يزال في قائمة الانتظار. لهوية الطلب وسجل الفواتير/الاستخدام فترات صلاحية مستقلة. راجع الاحتفاظ بالبيانات.
من الطلب إلى التحقيق والدعم
-
افتح Runs في مساحة العمل التي تملك الطلب. ابحث عن معرف الطلب (Request ID) الخاص به وحدد الصف.
-
اختر Open full details لفتح صفحة مخصصة. يقوم خيار Back to requests باستعادة فلاتر القائمة. لا يمنح الرابط أبداً حق الوصول إلى مساحة عمل أخرى؛ استخدم حساباً مصرحاً له بتلك المساحة.
-
بالنسبة للحالة المعلقة أو غير المعروفة، قم بتحديث التقدم أولاً. في حالة الفشل أو الاستجابة المتقطعة، اختر Investigate the issue عندما يكون ذلك متاحاً. يبدأ هذا تحقيقاً في ذلك الطلب داخل Agent المدمج في التطبيق؛ ولا يقوم بإعادة تشغيل طلب النموذج الأصلي. الطلبات الناجحة لا تحتاج إلى تحقيق بشكل افتراضي.
-
إذا كنت لا تزال بحاجة إلى مساعدة، اختر إجراء دعم بشري من الطلب أو التحقيق. سيفتح هذا معاينة مع الطلب والمحادثة المرتبطة به عند توفرها. راجع الملخص وقم بإزالة المحتوى الخاص، ثم حدد Submit بشكل صريح. التحقيق أو المعاينة وحدها لا ترسل طلب دعم.
-
بعد الإرسال، احتفظ بالتأكيد وتابع نفس المحادثة في 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 |
| الحصول على حالة المهمة | الحصول على حالة المهمة |