كيف تضع سقفاً لإنفاقك على واجهة API للذكاء الاصطناعي

ميزة ذكاء اصطناعي بلا سقف إنفاق هي ميزة قادرة على أن تحمّلك فاتورة بلا حدود. حلقة وكيل واحدة منفلتة، أو مستخدم واحد يلصق رواية كاملة في صندوق المحادثة، أو prompt واحد يجعل النموذج يثرثر بأربعة آلاف توكن — أيٌّ من هذه يضاعف فاتورتك بهدوء. الحل ضابطان رخيصان مملان: قيّد كل نداء عبر max_tokens، وتتبّع الإنفاق لكل مستخدم من كائن usage حتى تتمكن من قطع أحدهم قبل أن تتجاوز كلفته قيمته.

لا شيء من هذا صعب. الجزء الصعب هو الثقة بالأرقام التي تحدّد السقف على أساسها. الميزانية لا تساوي إلا قدر أعداد التوكنات التي تغذّيها — فإذا نفخ الـ gateway قيمة usage أو حاسبك على نداءات فاشلة، فإن سقفك المحسوب بعناية بمقدار $1 لكل مستخدم يومياً هو في الحقيقة $1.40، ولن تدري قط. لذا يفعل هذا المقال شيئين: يريك الآلية، ويشرح لماذا الفوترة الصادقة هي ما يجعل الآلية تعمل من الأساس.

الخطوة الأولى — قيّد كل نداء عبر max_tokens

المخرجات هي النصف الأغلى من معظم الفواتير. على Claude Sonnet 4.6، تبلغ المخرجات $12.75 لكل مليون توكن — خمسة أضعاف سعر المدخلات البالغ $2.55. الرد الذي توقعته في ثلاث جمل فإذا به يعود في اثنتي عشرة فقرة ليس مشكلة جودة؛ إنه مشكلة تكلفة. max_tokens هو السقف الصارم الذي يجعل أسوأ الاحتمالات معلوماً مسبقاً.

# حدِّد سقف تكلفة كل نداء على حدة عبر max_tokens.
# فهو يقيّد *المخرجات* — النصف الأغلى من معظم الفواتير — بسقف
# صارم. يتوقف النموذج عند الحد بدلاً من الإطالة بلا نهاية.
from openai import OpenAI

client = OpenAI(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com/v1",
)

# Claude Sonnet 4.6: ‏$2.55 مدخلات / ‏$12.75 مخرجات لكل مليون توكن.
# دون سقف، قد يمتد رد ثرثار إلى أكثر من 4000 توكن مخرجات.
# مع max_tokens=500 تقيّد تكلفة مخرجات هذا النداء تحديداً عند:
#   ‏500 × $12.75 / 1M = $0.0064 — مهما «أراد» النموذج أن يقول.
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    max_tokens=500,                 # يُحترم أصلياً — توقّف صارم حقيقي
    messages=[
        {"role": "system", "content": "Answer in at most 3 sentences."},
        {"role": "user", "content": user_question},
    ],
)

# تحقّق دائماً من سبب التوقّف. القيمة "length" تعني أنك بلغت السقف
# وقد يكون الرد مبتوراً — وهي إشارة لرفع السقف لهذا الصنف من
# المهام تحديداً، لا على مستوى عام.
if resp.choices[0].finish_reason == "length":
    print("Truncated at the cap — consider a higher max_tokens here.")

print(resp.choices[0].message.content)
print(resp.usage)  # أعداد مدخلات/مخرجات صادقة — انظر القسم التالي

يحترم Brievio قيمة max_tokens أصلياً مقابل النموذج الأصلي — فهي توقّف حقيقي لا تلميح. اضبطها لكل صنف من المهام، لا مرة واحدة على نحو عام: المصنِّف يحتاج ربما 5 توكنات، ورد المحادثة 500، والملخّص الطويل 2000. الانضباط هو أن تختار رقماً لكل موضع نداء وتراقب finish_reason. وحين يعود بقيمة "length"، فأنت قد بترت رداً حقيقياً وعليك رفع السقف لذلك المسار — لا أن ترفعه في كل مكان بلا تمييز فتفقد الحماية.

الخطوة الثانية — سعّر كائن usage بنفسك

كل رد من Brievio يحمل كائن usage فيه الأعداد الحقيقية لتوكنات المدخلات والمخرجات لذلك النداء، ويُسجَّل كل طلب بتوكناته الحقيقية وتكلفته. هذا يعني أنك لست مضطراً لانتظار فاتورة آخر الشهر لتعرف تكلفة أي شيء — يمكنك تسعير كل نداء في اللحظة التي يعود فيها:

• usage.prompt_tokens — توكنات المدخلات المُرسَلة فعلاً.
• usage.completion_tokens — توكنات المخرجات المُولَّدة فعلاً (وهذا ما يقيّده max_tokens).
• usage.total_tokens — المجموع، لتحقّق سريع من سلامة الرقم.

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

الخطوة الثالثة — تتبّع الإنفاق لكل مستخدم واقطع عند الميزانية

تحميك السقوف لكل نداء من نداء سيئ واحد. وتحميك الميزانيات لكل مستخدم منفاعل سيئ واحد — الحساب الذي يشغّل آلاف النداءات يومياً، سواء بدافع الحماس أو الأتمتة أو إساءة الاستخدام. النمط هو رقم واحد دائم لكل مستخدم تفحصه قبل النداء وتزيده بعده:

# تتبّع الإنفاق لكل مستخدم من كائن usage، ثم اقطع عند حد الميزانية.
# يعيد usage الأعداد الحقيقية لتوكنات المدخلات/المخرجات للنداء. تسعّرها
# محلياً مقابل السعر المنشور لكل نموذج وتضيفها إلى إجمالي جارٍ مفهرس
# حسب المستخدم.
from decimal import Decimal

# أسعار Brievio المنشورة، بالدولار لكل مليون توكن (≈15% دون القائمة الرسمية).
RATES = {
    "claude-sonnet-4-6": {"in": Decimal("2.55"), "out": Decimal("12.75")},
    "claude-haiku-4-5":  {"in": Decimal("0.85"), "out": Decimal("4.25")},
}

def cost_usd(model: str, usage) -> Decimal:
    r = RATES[model]
    million = Decimal("1000000")
    return (usage.prompt_tokens     * r["in"]  / million +
            usage.completion_tokens * r["out"] / million)

# مخزنك المفضّل — عدّاد Redis، عمود SQL، أياً كان. المهم رقم واحد
# دائم لكل مستخدم. النداءات الفاشلة 4xx/5xx مجانية على Brievio،
# فلا تضيف تكلفة إلا للنداءات التي أعادت نتيجة فعلاً.
DAILY_BUDGET = Decimal("1.00")  # ‏$1 لكل مستخدم يومياً

def chat_for_user(user_id: str, question: str, model="claude-sonnet-4-6"):
    spent = get_spent_today(user_id)            # Decimal، قيمته الافتراضية 0
    if spent >= DAILY_BUDGET:
        raise BudgetExceeded(f"{user_id} hit ${DAILY_BUDGET}/day")

    resp = client.chat.completions.create(
        model=model,
        max_tokens=500,
        messages=[{"role": "user", "content": question}],
    )

    add_spent_today(user_id, cost_usd(model, resp.usage))  # سجّل التكلفة الحقيقية
    return resp.choices[0].message.content

اختر العتبة من اقتصاديات وحدتك: إذا كان المقعد المدفوع بـ $20 شهرياً وأردت للذكاء الاصطناعي أن يبقى دون، لنقل، 20% من الإيراد، فتلك ميزانية تقارب $0.13 لكل مستخدم يومياً. حذّر بليونة عند 80% (لافتة، بريد إلكتروني)، واقطع بحزم عند 100% (مسار BudgetExceeded أعلاه). أما لمستخدمي الباقة المجانية، فاضبط السقف منخفضاً وانزل بدرجة النموذج — فنقل الحركة غير الحرجة من Sonnet إلى Haiku 4.5 بسعر $0.85 مدخلات / $4.25 مخرجات يخفض التكلفة لكل توكن نحو الثلثين مع الإبقاء على القياس الصادق نفسه.

لماذا تجعل الفوترة الصادقة الحساب جديراً بالثقة

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

• النداءات الفاشلة مجانية. على Brievio، لا يكلّف رد 4xx أو 5xx شيئاً — فأنت تُحاسَب على النتائج لا المحاولات. وهذا يهمّ للميزانيات تحديداً: عاصفة إعادات محاولة ضد خدمة تابعة متقلّبة ينبغي ألا تستنزف مخصّص المستخدم اليومي. ولأنك لا تحتسب التكلفة إلا على النداءات التي أعادت نتيجة، فإن منحنى إنفاقك يتتبّع القيمة المُسلَّمة، لا الأخطاء المُستوعَبة.
• الأعداد غير منفوخة. يعكس كائن usage التوكنات التي عالجها النموذج الأصلي فعلاً — لا prompt محشو، ولا مخرجات وهمية مضافة إلى العدّاد. والتصرّف الصادق ألا تأخذ ذلك على الثقة: أرسل prompt ثابتاً معروفاً، واقرأ قيمة prompt_tokens العائدة، وتأكّد من مطابقتها لما يقول الـ tokenizer إنه ينبغي أن يكون. وقد كتبنا اختباراً ذاتياً لنفخ التوكنات من 20 سطراً يفعل هذا بالضبط — شغّله ضد أي gateway، بما فيه gateway الخاص بنا، قبل أن تثق بأرقامه.

الصلة مباشرة: ميزانية محسوبة من أعداد منفوخة تقطع المستخدمين مبكراً وتبالغ في تقدير تكلفتك؛ وأخرى تشمل النداءات الفاشلة تعاقب المستخدمين على أيام بنيتك التحتية السيئة. القياس الصادق هو ما يجعل سقف $1 يومياً يعني دولاراً فعلاً. ويسعّر Brievio المحادثة بنحو 15% دون القائمة الرسمية، بنظام الدفع حسب الاستخدام، مع رصيد لا تنتهي صلاحيته أبداً — فالسقف الذي تضبطه هو السقف الذي تحصل عليه، والميزانية غير المستخدمة تبقى لك.

وضع كل ذلك معاً

وضعية الإنفاق الجاهزة للإنتاج هي أربع عادات صغيرة، لا تستغرق أيٌّ منها أكثر من بعد ظهيرة واحد:

• كل موضع نداء يضبط max_tokens بحجم يناسب مهمته. لا مخرجات بلا سقف، في أي مكان.
• كل رد يُسعَّر من usage بالسعر المنشور ويُضاف إلى إجمالي لكل مستخدم.
• كل مستخدم له ميزانية بتحذير ليّن وقطع صارم مستمدّين من اقتصاديات وحدتك.
• الحركة الأرخص تنزل بدرجتها إلى نموذج أصغر (Haiku، أو صنف mini) بدلاً من دفع أسعار الفئة الرائدة لعمل لا يحتاجها.

افعل هذه الأربعة فيصبح أسوأ احتمال لفاتورتك رقماً اخترته أنت، لا رقماً تكتشفه. وللروافع الأعمق — تخزين الـ prompt مؤقتاً، والمعالجة على دفعات، واختيار النموذج، وتقليم الـ prompt — انظر دليل تحسين التكلفة، والوثائق للاطّلاع على مخطط usage الكامل ومعاملات OpenAI المتوافقة التي يدعمها Brievio. ضبط التكلفة ليس ميزة تركّبها بعد أن تخيفك الفاتورة — إنه سطران وعدّاد، ويعمل في أفضل حالاته على عدّاد تستطيع الوثوق به.