تتبع إنفاق API لكل مشروع واحصل على تنبيهات الميزانية في Python

أضف سطر JSON واحد إلى ملف بعد كل استدعاء API، ووسمه باسم مشروع، ودع سكربت Python من 30 سطرًا يحوّل ذلك الملف إلى تقرير تكلفة لكل مشروع وتحذير عند 50 و75 و95 و100% من ميزانيتك الشهرية. إنه نفس العرض الذي قدمته Anthropic مؤخرًا لفرق Claude Enterprise، مبنيًا من سجلك الخاص.

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

ما أصدرته Anthropic، وما يمكنك نسخه#

يغطي إعلان Anthropic (28 أكتوبر 2026) تقارير ذكية واستبيانات داخل التطبيق وميزانيات جماعية مشتركة، متاحة عمومًا على خطط Claude Enterprise فقط (المصدر). يهمنا هنا جزآن. التقرير يجمع عمل الفريق في مسارات عمل ويعرض إنفاق كل منها. الميزانية المشتركة هي رقم شهري واحد مشترك، ويتلقى مسؤولو الفوترة بريدًا إلكترونيًا عند 50% و75% و95% و100% منها. وتضيف Anthropic أن التقارير مخصصة لتخطيط الاستثمار، لا للحكم على الأفراد.

لا تحتاج إلى خطة enterprise للحصول على نفس الشكل. مسار العمل هو مجرد تسمية تختارها، والعتبات الأربع هي قائمة واحدة في الكود. جمّع حسب المشروع، لا حسب الشخص، للسبب الذي ذكرته Anthropic.

السجل: سطر واحد لكل طلب#

كل استجابة chat completion تحمل كائن usage مع prompt_tokens وcompletion_tokens. هذا كل ما يحتاجه التقرير، بالإضافة إلى تسمية مشروع تضيفها بنفسك. هذا الغلاف يرسل الطلب ويضيف سطرًا واحدًا إلى ملف شهري (يتغير اسم الملف كل شهر، لذا يبدأ الشهر الجديد من الصفر):

import json, os, time
from openai import OpenAI

client = OpenAI(base_url="https://api.cheaptokens.dev/v1",
                api_key=os.environ["CHEAPTOKENS_API_KEY"])

def ask(project, model, messages):
    r = client.chat.completions.create(model=model, messages=messages)
    with open(time.strftime("usage-%Y-%m.jsonl"), "a") as f:
        f.write(json.dumps({"project": project, "model": model,
                            "prompt_tokens": r.usage.prompt_tokens,
                            "completion_tokens": r.usage.completion_tokens}) + "\n")
    return r

ask("support-bot", "zai-org/GLM-5.3-Flash",
    [{"role": "user", "content": "Where is my order?"}])

استخدم معرّف النموذج الكامل من وثائق CheapTokens (deepseek-ai/DeepSeek-V4-Flash-0731، zai-org/GLM-5.3-Flash)؛ الأسماء المختصرة من جداول الأسعار لا يقبلها API. يأتي المفتاح من متغير بيئة، وليس من الملف أبدًا.

السكربت: التكلفة لكل مشروع وتنبيهات العتبات#

احفظ هذا باسم report.py. الأسعار هي عناصر نائبة: انسخ الأسعار الحالية من جدول الأسعار (كلا النموذجين يشتركان في سعر مثال واحد هنا فقط للحفاظ على قابلية قراءة الحساب).

import json, os, sys, time
from collections import defaultdict

LOG = time.strftime("usage-%Y-%m.jsonl")
BUDGET = float(os.environ.get("BUDGET_USD", "10"))  # example, substitute your own
STATE = LOG + ".alert"
LEVELS = [50, 75, 95, 100]
PRICES = {  # USD per 1M tokens (input, output): example, substitute current prices
    "deepseek-ai/DeepSeek-V4-Flash-0731": (1.0, 2.0),
    "zai-org/GLM-5.3-Flash": (1.0, 2.0),
}

spend = defaultdict(float)
with open(LOG) as f:
    for line in f:
        r = json.loads(line)
        p_in, p_out = PRICES[r["model"]]
        spend[r["project"]] += (r["prompt_tokens"] * p_in
                                + r["completion_tokens"] * p_out) / 1_000_000

total = sum(spend.values())
if total == 0:
    sys.exit("log is empty")

for name, usd in sorted(spend.items(), key=lambda kv: -kv[1]):
    print(f"{name:<8} ${usd:6.2f} {usd / total:5.0%}")
print(f"{'total':<8} ${total:6.2f} of ${BUDGET:.2f} ({total / BUDGET:.0%})")

last = int(open(STATE).read()) if os.path.exists(STATE) else 0
crossed = [l for l in LEVELS if total >= BUDGET * l / 100 and l > last]
if crossed:
    print(f"WARNING: budget passed {crossed[-1]}%")
    open(STATE, "w").write(str(crossed[-1]))

الأسطر الأربعة الأخيرة هي الجزء الذي ينساه الناس. بدون ملف الحالة الصغير، سيصرخ السكربت "تجاوز 50%" في كل تشغيل لبقية الشهر. معه، كل مستوى ينطلق مرة واحدة.

شغّله واقرأ النتيجة#

خذ سجلًا تجريبيًا من أربعة أسطر (السجل الحقيقي فيه سطر لكل طلب، أي الآلاف):

{"project": "agent", "model": "deepseek-ai/DeepSeek-V4-Flash-0731", "prompt_tokens": 2400000, "completion_tokens": 300000}
{"project": "agent", "model": "deepseek-ai/DeepSeek-V4-Flash-0731", "prompt_tokens": 1000000, "completion_tokens": 100000}
{"project": "blog", "model": "zai-org/GLM-5.3-Flash", "prompt_tokens": 800000, "completion_tokens": 400000}
{"project": "bot", "model": "zai-org/GLM-5.3-Flash", "prompt_tokens": 500000, "completion_tokens": 100000}

مع أسعار المثال وميزانية 10، يطبع python report.py:

agent    $  4.20   65%
blog     $  1.60   25%
bot      $  0.70   11%
total    $  6.50 of $10.00 (65%)
WARNING: budget passed 50%

الوكيل يمثل ما يقرب من ثلثي الفاتورة، وجاء التحذير عند 50%، وليس في النهاية. شغّله مرة أخرى ويبقى التحذير صامتًا حتى يصل الإجمالي إلى 75%.

لجعل هذا يعمل كل شهر، تحتاج إلى ثلاث خطوات:

كيف يبدو الشهر على النماذج الرخيصة#

تصبح الأرقام مفيدة بمجرد أن تكون أرقامك. افترض أن الوكيل من السجل التجريبي يستهلك في المتوسط 30,000 رمز إدخال و2,000 رمز إخراج لكل خطوة، و20 خطوة لكل مهمة، ومهمتان يوميًا. خطوة واحدة على DeepSeek-V4-Flash تكلف $0.00065؛ وعلى GLM-5.3-Flash، $0.00068. اليوم 40 خطوة، والشهر 1,200. حرّك المنزلقات لتطابق وكيلك:

والشهر عند 1,200 خطوة، مع احتساب الإدخال والإخراج معًا:

في المجموع، مع احتساب الإدخال والإخراج معًا، يخرج كلا النموذجين أرخص من أسعار OpenRouter المرجعية في ذلك الجدول، بسعر واحد في أي ساعة ودون رسوم إضافية للذروة. كما يسمح DeepSeek-V4-Flash بما يصل إلى 32,768 رمز إخراج لكل إجابة وسياق 380K؛ وGLM-5.3-Flash لديه سياق 390K. بمجرد أن يُظهر التقرير أي مشروع هو الثقيل، فإن تبديل سلسلة model لذلك المشروع فقط هو تغيير من سطر واحد، ورصيد واحد يغطي كل النماذج. لمعرفة عدد الرموز التي يستهلكها طلب واحد فعليًا، راجع كم عدد الرموز التي يستهلكها طلب API؛ لإيقاف تشغيل وكيل في منتصف الطريق، راجع تتبع تكلفة رموز وكيل الذكاء الاصطناعي. الأسعار والنماذج على صفحة نماذج CheapTokens.

أين يخطئ هذا#

• نموذج مفقود من PRICES. يتوقف السكربت مع KeyError يذكر النموذج. أضفه؛ لا تعتمد على الصفر، وإلا يبدو المشروع مجانيًا.
• استدعاءات البث. الجزء الأخير يحمل الاستخدام فقط إذا طلبته (stream_options={"include_usage": True} في OpenAI SDK). وإلا فسجلّك به فجوات.
• الطلبات الفاشلة. سجّل فقط الاستجابات التي تحتوي على كائن usage؛ الطلب الذي فشل ليس فيه ما يُحتسب.
• تقارير لكل شخص. أبقِ التسمية على اسم مشروع أو وكيل. التقرير عن الأشخاص يدعو إلى استنتاجات خاطئة.