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

بناء تكامل موثوق مع TokenLab

حافظ على التحكم في التكاليف، وإعادة المحاولات، ومفاتيح API، وسجلات الطلبات

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

اختر النماذج ذات البيانات الحالية

تتغير أسماء النماذج وقدراتها وأسعارها. اقرأ Models API أو صفحات النماذج بدلاً من الاحتفاظ بقائمة دائمة في الكود أو الوثائق.

لحالة استخدام جديدة:

  1. قم بتصفية النماذج حسب القدرة التي يحتاجها منتجك.
  2. قارن أسعارها الحالية في TokenLab.
  3. اختبر مجموعة صغيرة منها باستخدام طلبات مستخدم تمثيلية.
  4. اجعل معرف النموذج (model ID) صريحاً في كل طلب.

لا تقم بتبديل النماذج بصمت. فالتغيير قد يؤثر على جودة المخرجات، أو السعر، أو طول السياق، أو الأدوات المتاحة، أو دعم الوسائط.

ضع حداً أقصى للتكلفة

بالنسبة لنماذج النصوص، حدد المخرجات بالطول الذي يمكن لمنتجك استخدامه فعلياً. يعتمد اسم المعلمة (parameter) على الـ API والنموذج، لذا تحقق من صفحة النموذج قبل إرسال max_tokens أو max_output_tokens.

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

بالنسبة لطلبات الصور، والفيديو، والموسيقى، والـ 3D، وWorlds، تعتمد التكلفة غالباً على عدد المخرجات، أو المدة، أو الدقة، أو خيارات وسائط أخرى. اعرض التقدير الحالي قبل أن يؤكد المستخدم عملية توليد مكلفة كلما أمكن للـ API توفير ذلك.

بث استجابات النصوص الطويلة

يعرض البث (Streaming) الإجابة فور وصولها ويتجنب جعل المستخدم ينتظر الاستجابة الكاملة. هذا لا يقلل من تكلفة الرموز (tokens).

للحصول على مثال كامل مع إعداد العميل وفحوصات الإكمال، راجع البث (Streaming).

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

أعد المحاولة فقط عندما يكون ذلك آمناً

أعد محاولة استجابات 429 بعد Retry-After أو retry_after. التراجع الأسي القصير (exponential backoff) مناسب لاستجابات 5xx العابرة. تتطلب أخطاء المصادقة، والتحقق، والرصيد، وطول السياق تغييراً من التطبيق أو المستخدم؛ فإرسال نفس الطلب مرة أخرى لن يحلها.

راجع حدود المعدل (Rate limits) للحصول على مثال لإعادة المحاولة المحدودة التي تحترم Retry-After وتعطل عمليات إعادة المحاولة المكررة في الـ SDK.

قم بتعيين حد لإعادة المحاولة وحد أقصى للوقت الإجمالي. بالنسبة لإنشاء الوسائط، احفظ معرف المهمة (task ID) المرتجع. بالنسبة للطلبات المدرجة في Retry safely with an idempotency key، أرسل Idempotency-Key حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى تشغيل أو محاسبة نفس الطلب مرتين.

احتفظ بمفاتيح API على الخادم

لا تقم أبداً بتضمين مفتاح TokenLab API في JavaScript الخاص بالمتصفح، أو حزمة تطبيق الهاتف المحمول، أو مستودع عام، أو سجل مرئي للعميل.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

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

احتفظ بسجلات طلبات مفيدة

قم بتخزين المعرفات التي تتيح لك ربط إجراء المستخدم بسجلات الاستخدام والدعم:

  • request_id لطلب الـ API
  • task_id للتوليد غير المتزامن
  • billing_transaction_id عند إرجاعه
  • معرف النموذج ونقطة النهاية (endpoint)
  • معرف المستخدم أو المشروع أو الوظيفة الخاص بك

لا تقم بتسجيل مفاتيح API، أو رموز الإدارة (management tokens)، أو المطالبات الخاصة الكاملة (private prompts)، أو الوسائط الخاصة، أو الروابط الموقعة (signed URLs). سجلات الاستخدام في Console وManagement API هي المصدر للمبالغ المفوترة؛ فقد لا تصف أعداد رموز استجابة النموذج وحدها التكلفة النهائية.

صمم للعمل غير المتزامن

قد تعود واجهات برمجة تطبيقات الصور، والفيديو، والموسيقى، والـ 3D، وWorlds قبل أن تكون النتيجة جاهزة. احفظ معرف المهمة، وقم بعمل استطلاع (poll) لـ GET /v1/tasks/{id}، وتوقف فقط عند completed أو failed. حالة الفشل في البحث لا تعني أن عملية التوليد نفسها قد فشلت.

راجع المهام غير المتزامنة (Async jobs) والاستطلاع (Polling) للتعامل مع الإلغاء، والمهلة، والطلبات المكررة.

قبل الإطلاق

  • قم بتشغيل طلبات تمثيلية باستخدام النموذج وتنسيق الـ API الدقيق الذي ستطلقه.
  • تحقق من استجابات النجاح وأخطاء الشائعة.
  • تأكد من أن السعر المعروض في منتجك يطابق سعر TokenLab الحالي.
  • اجعل عمليات التحديث، ومهلات الشبكة، والنقرات المتكررة آمنة.
  • اجعل من الممكن تتبع النتيجة المرئية للمستخدم وصولاً إلى معرف الطلب (Request ID) الخاص بها.

في هذه الصفحة