الرموز والاستخدام

الرمز (token) هو وحدة معالجة النماذج ووحدة فوترة واجهة API. توضح هذه الصفحة كيفية تقديره قبل الاستدعاء وكيفية قراءة الاستهلاك الفعلي بعده.

ما هو الرمز#

الرمز جزء من نص: كلمة قصيرة، جزء من كلمة طويلة، رقم أو علامة ترقيم. مقاييس تقريبية مفيدة :

قراءة استهلاك طلب ما#

تحتوي كل استجابة غير مُبَثّة على العدّ :

"usage": {
  "prompt_tokens": 1240,      // ce que vous avez envoyé (contexte inclus)
  "completion_tokens": 318,   // ce que le modèle a généré
  "total_tokens": 1558
}

في البث المباشر، أضيفوا "stream_options": {"include_usage": true} : سيحمل حدث أخير، بعد النص، الحقل usage.

على واجهة Anthropic، يُسمى نفس العدّ usage.input_tokens / usage.output_tokens.

ما يُحتسب في prompt_tokens#

• رسالة system، تُعاد إرسالها في كل استدعاء.
• كل تاريخ المحادثة الذي تعيدون إرساله؛ واجهة API عديمة الحالة (sans état) : ما لا تُرسلونه غير موجود بالنسبة للنموذج.
• تعريفات الأدوات (tools) ونتائج الأدوات.

هذا هو بند الإنفاق الذي ينمو أسرع من غيره: في محادثة من 20 جولة، يمثل السياق غالبًا أكثر من 90 % من الرموز المفوترة.

تقليل الاستهلاك#

• اختصار التاريخ : أعيدوا إرسال آخر N جولة فقط، أو ملخصًا للجولات الأقدم.
• تقصير رسالة النظام : تُفوتَر في كل طلب.
• تحديد الإخراج بـmax_tokens : رمز الإخراج يكلف نحو ثلاثة أضعاف رمز الإدخال في كل النماذج. السياق يحدد عدد الرموز، والإخراج يحدد سعرها ، تصرفوا على الاثنين معًا.
• اختيار النموذج المناسب : فارق السعر بين mina-flash وmina-low وmina-full مهم؛ قارنوها على النماذج والأسعار قبل اختيار الأكبر افتراضيًا.
• عدم إرسال مستندات كاملة حين يكفي مقتطف ذو صلة.

التقدير قبل الاستدعاء#

لميزانية تقديرية، يكفي تقريب «عدد الأحرف ÷ 4» :

def estimer_jetons(texte: str) -> int:
    """Approximation ± 20 % - pour un budget, pas pour une facture."""
    return max(1, len(texte) // 4)

def cout_da(entree: int, sortie: int, prix_in: float, prix_out: float) -> float:
    return (entree * prix_in + sortie * prix_out) / 1_000_000

# tarifs mina-low, à reprendre sur la page Modèles et prix
print(cout_da(8000, 2000, 350, 1000))  # 4.8 DA

const estimerJetons = (texte) => Math.max(1, Math.floor(texte.length / 4));

const coutDa = (entree, sortie, prixIn, prixOut) =>
  (entree * prixIn + sortie * prixOut) / 1_000_000;

// tarifs mina-low, à reprendre sur la page Modèles et prix
console.log(coutDa(8000, 2000, 350, 1000)); // 4.8

تتبع الاستهلاك#

تعرض صفحة Usage في المنصة، يوميًا ولكل نموذج : عدد الطلبات، رموز الإدخال والإخراج، والتكلفة بالدينار. يقابل كل سطر طلبًا حقيقيًا ويحمل معرّفه (X-Request-Id)، مما يتيح مطابقته مع سجلاتكم الخاصة.

الرصيد المتبقي مقروء أيضًا عبر واجهة API :

curl https://api.cloudzir.com/v1/user/balance \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY"

انظروا رصيد الحساب.