Python میں AI ایجنٹ ٹوکن لاگت ٹریک کریں: usage، بجٹ، اسٹاپ

آپ کا ایجنٹ دس منٹ تک چلا اور بل کام سے بڑا ہے۔ اس کی وجہ جاننے کے لیے، ہر API جواب میں usage آبجیکٹ پڑھیں، اسے فی کام جمع کریں اور ماڈل کی فی 1M ٹوکن قیمت سے ضرب دیں۔ اسے محدود کرنے کے لیے، ہر قدم کے بعد اس رننگ ٹوٹل کا بجٹ سے موازنہ کریں اور جب یہ تجاوز کر جائے تو لوپ روک دیں۔ نیچے ایک چھوٹی Python کلاس ہے جو بالکل یہی کرتی ہے۔

مثال OpenAI-کمپیٹیبل اینڈپوائنٹ https://api.cheaptokens.dev/v1 اور ماڈل آئی ڈی deepseek-ai/DeepSeek-V4-Flash-0731 استعمال کرتی ہے (380K کانٹیکسٹ، فی جواب زیادہ سے زیادہ 32,768 آؤٹ پٹ ٹوکن)۔ اگر آپ رن شروع کرنے سے پہلے اس کا تخمینہ لگانا چاہتے ہیں، تو یہ ایک مختلف کام ہے، اور How to estimate the cost of an AI agent اس کا احاطہ کرتا ہے۔ یہ مضمون رن کے دوران پیمائش اور محدود کرنے کے بارے میں ہے۔

نمبر کہاں ہیں: usage آبجیکٹ#

ہر نان اسٹریمنگ چیٹ کمپلیشن ایک usage آبجیکٹ کے ساتھ واپس آتا ہے۔ DeepSeek کی API ریفرنس (26 اکتوبر 2026 کو چیک شدہ) یہ فیلڈز بتاتی ہے:

• prompt_tokens — اس بار آپ نے جو کچھ بھیجا: سسٹم پرامپٹ، ہسٹری، ٹول نتائج۔
• completion_tokens — ماڈل نے جو واپس لکھا۔
• total_tokens — دونوں کا مجموعہ۔

DeepSeek اختیاری اضافی چیزیں بھی دستاویز کرتا ہے: prompt_cache_hit_tokens اور prompt_cache_miss_tokens (یہ prompt_tokens تک جمع ہوتے ہیں)، اور سوچنے والے ماڈلز کے لیے completion_tokens_details.reasoning_tokens۔ صفحہ کوئی اشاعت کی تاریخ نہیں دکھاتا، اور یہ اضافی چیزیں OpenAI فارمیٹ کی توسیعات ہیں، اس لیے نیچے دیا گیا کوڈ انہیں اختیاری سمجھتا ہے اور صرف پہلے دو فیلڈز پر انحصار کرتا ہے۔

ہر قدم لاگ کیوں کریں اور صرف آخری نہیں؟ کیونکہ ایک ایجنٹ ہر بار اپنا بڑھتا ہوا کانٹیکسٹ دوبارہ بھیجتا ہے۔ قدم 1 شاید 2,000 ان پٹ ٹوکن بھیجے، قدم 30 شاید 9,000، اور بل ان سب کا مجموعہ ہے۔ وجہ why a long chat costs more میں بیان کی گئی ہے، اور ان پٹ/آؤٹ پٹ کی تقسیم input vs output tokens میں۔

ایک میٹر جو ایجنٹ کو روکتا ہے#

یہ پوری چیز ہے: ایک میٹر جو ٹوکن جمع کرتا ہے، فی قدم ایک لائن پرنٹ کرتا ہے اور بجٹ تجاوز کرنے پر خرابی اٹھاتا ہے، نیز اس کے گرد ایک سادہ ایجنٹ لوپ۔ SDK کو pip install openai سے انسٹال کریں اور اپنی کلید CHEAPTOKENS_API_KEY میں رکھیں۔

import os
from openai import OpenAI

client = OpenAI(
    base_url='https://api.cheaptokens.dev/v1',
    api_key=os.environ['CHEAPTOKENS_API_KEY'],
)
MODEL = 'deepseek-ai/DeepSeek-V4-Flash-0731'

# example prices, USD per 1M tokens: use the current ones from the pricing table
PRICE_IN = 0.10
PRICE_OUT = 0.40


class BudgetExceeded(Exception):
    pass


class TaskMeter:
    def __init__(self, budget_usd):
        self.budget = budget_usd
        self.steps = 0
        self.tokens_in = 0
        self.tokens_out = 0
        self.reasoning = 0

    @property
    def cost(self):
        return (self.tokens_in * PRICE_IN + self.tokens_out * PRICE_OUT) / 1_000_000

    def add(self, usage):
        self.steps += 1
        self.tokens_in += usage.prompt_tokens
        self.tokens_out += usage.completion_tokens
        details = getattr(usage, 'completion_tokens_details', None)
        self.reasoning += getattr(details, 'reasoning_tokens', 0) or 0
        print(f'step {self.steps}: in={usage.prompt_tokens} '
              f'out={usage.completion_tokens} task=${self.cost:.4f}')
        if self.cost > self.budget:
            raise BudgetExceeded(
                f'budget ${self.budget:.2f} crossed at step {self.steps}: '
                f'${self.cost:.4f}')


def run_task(goal, budget_usd=0.50, max_steps=40):
    meter = TaskMeter(budget_usd)
    messages = [
        {'role': 'system', 'content': 'Work step by step. Reply DONE when finished.'},
        {'role': 'user', 'content': goal},
    ]
    for _ in range(max_steps):
        resp = client.chat.completions.create(
            model=MODEL, messages=messages, max_tokens=1024)
        meter.add(resp.usage)  # log first, then decide
        reply = resp.choices[0].message.content or ''
        messages.append({'role': 'assistant', 'content': reply})
        if 'DONE' in reply:
            break
        messages.append({'role': 'user', 'content': 'Continue.'})
    return meter


try:
    meter = run_task('Summarise the main risks of a database migration.')
    print(f'finished: {meter.steps} steps, ${meter.cost:.4f}')
except BudgetExceeded as err:
    print('stopped:', err)

اس میں تین انتخاب نقل کرنے کے قابل ہیں۔

فیصلہ کرنے سے پہلے لاگ کریں۔ meter.add پہلے قدم ریکارڈ کرتا ہے اور پھر بجٹ چیک کرتا ہے، اس لیے روکا گیا رن بھی مکمل ٹریس چھوڑتا ہے۔ چیک اس کال کے بعد ہوتا ہے جس نے حد تجاوز کی، اس لیے آپ زیادہ سے زیادہ ایک قدم سے آگے بڑھ سکتے ہیں۔ max_tokens=1024 اس آخری قدم کے آؤٹ پٹ کو محدود کرتا ہے۔

دو سخت اسٹاپ، ایک نہیں۔ max_steps ایسے ایجنٹ کو پکڑتا ہے جو زیادہ خرچ کیے بغیر لوپ کرتا ہے؛ ڈالر بجٹ ایسے کو پکڑتا ہے جو فی قدم بہت خرچ کرتا ہے۔ آپ کو دونوں چاہیے۔

قیمتیں ایک جگہ رہتی ہیں۔ PRICE_IN اور PRICE_OUT پلیس ہولڈر نمبر ہیں۔ اپنے ماڈل کے لیے موجودہ اقدار pricing page سے کاپی کریں؛ اس وقت DeepSeek-V4-Flash فی 1M ان پٹ ٹوکن $0.015 اور فی 1M آؤٹ پٹ ٹوکن $0.10 ہے۔

40 قدم کا رن کتنا بنتا ہے#

فرض کریں آپ کا ایجنٹ 40 قدم لیتا ہے، اور چونکہ کانٹیکسٹ بڑھتا ہے، اوسط قدم 6,000 ان پٹ ٹوکن بھیجتا ہے اور 400 ٹوکن واپس لیتا ہے۔ یہ کام کے لیے 40 × 6,000 = 240,000 ان پٹ ٹوکن اور 40 × 400 = 16,000 آؤٹ پٹ ٹوکن ہے۔

DeepSeek-V4-Flash پر اس کی لاگت $0.0052 ہے۔ جدول وہی کام دیگر ماڈلز پر چلاتا ہے اور OpenRouter کی حوالہ قیمت ہماری کے ساتھ رکھتا ہے:

مجموعی طور پر، ان پٹ اور آؤٹ پٹ کو ملا کر، اس کام کے لیے DeepSeek-V4-Flash OpenRouter سے سستا نکلتا ہے۔ یہ بھی دیکھیں کہ ٹوکن کہاں ہیں: 256,000 میں سے 240,000 ان پٹ ہیں۔ آپ کا ایجنٹ جو کانٹیکسٹ ساتھ لے کر چلتا ہے وہی بل ہے، اسی لیے آپ کے لاگ میں فی قدم in= نمبر دیکھنے والا ہے۔ اوپر کی مثال میں فی کام $0.50 کا بجٹ بے قابو ہونے پر حد ہے، ہدف نہیں۔

ماڈل تبدیل کرنے کا مطلب صرف MODEL بدلنا ہے۔ آئی ڈی CheapTokens docs سے منتخب کریں: نام فراہم کنندگان کے درمیان مختلف ہوتے ہیں، اور قیمت کے لیبل سے مختصر آئی ڈی API میں کام نہیں کرے گی۔ طویل ایجنٹ لوپس کے لیے، DeepSeek-V4-Flash کی دن کے کسی بھی وقت ایک ہی قیمت ہے، اس لیے ایک کام کی لاگت دوپہر اور رات 3 بجے یکساں ہوتی ہے۔ اس کی حدود کے لیے DeepSeek page دیکھیں۔

جب ماڈل سوچ رہا ہو#

اگر کوئی جواب ٹوکن میں آپ کے دیکھے جانے والے متن سے بہت لمبا ہے، تو reasoning_tokens دیکھیں۔ سوچنے والے ٹوکن آؤٹ پٹ میں شمار ہوتے ہیں، اس لیے استدلال سے بھرا قدم نظر آنے والے متن سے کہیں زیادہ آؤٹ پٹ ٹوکن پیدا کر سکتا ہے، اور ان کا بل آؤٹ پٹ کے طور پر ہوتا ہے۔ اوپر کا میٹر انہیں meter.reasoning میں جمع کرتا ہے جب API فیلڈ واپس کرتی ہے اور جب نہیں کرتی تو اسے 0 پر چھوڑ دیتا ہے، اس لیے غائب کلید پر کبھی کریش نہیں ہوتا۔ اگر آپ دیکھنا چاہتے ہیں کہ آؤٹ پٹ کا کتنا حصہ سوچ تھا تو اسے out= کے ساتھ پرنٹ کریں۔ Reasoning effort and thinking tokens وجہ بیان کرتا ہے۔

اسٹریمنگ: usage آخر میں آتا ہے#

اگر آپ کا ایجنٹ اسٹریم کرتا ہے، تو عام چنکس میں usage نہیں ہوتا۔ OpenAI فارمیٹ میں آپ اسے stream_options={'include_usage': True} کے ساتھ مانگتے ہیں۔ DeepSeek کی ریفرنس (26 اکتوبر 2026 کو چیک شدہ) کہتی ہے کہ یہ آپشن صرف stream=True کے ساتھ کام کرتا ہے (ورنہ API 400 جواب دیتی ہے)، کہ usage ہر چنک میں null ہے سوائے ایک کے، اور کہ data: [DONE] سے پہلے آخری چنک پوری درخواست کے ٹوٹل رکھتا ہے۔ اس لیے اسٹریمنگ لوپ میں، meter.add ایک بار کال کریں، اس چنک پر جہاں usage خالی نہ ہو۔ اوپر کا نان اسٹریمنگ لوپ شروع کرنے کی سب سے آسان جگہ ہے؛ streaming in Python میں لوپ خود موجود ہے۔

اگر نمبر غلط لگیں#

• usage None ہے۔ آپ include_usage کے بغیر اسٹریم کر رہے ہیں۔ اسے شامل کریں، یا نان اسٹریمنگ کال پر سوئچ کریں۔
• کل بیلنس کمی سے کم ہے۔ چیک کریں کہ ہر کال میٹر سے گزرتی ہے: ری ٹرائیز، خلاصہ کرنے والی کال یا ٹول منتخب کرنے والی کال جو run_task سے باہر کی گئی ہو، آسانی سے چھوٹ سکتی ہے۔ client.chat.completions.create کو ایک فنکشن میں لپیٹیں اور سب کچھ اسی سے گزار دیں۔
• فی قدم لاگت بڑھتی رہتی ہے۔ یہ ایسے لوپ کے لیے معمول ہے جو سب کچھ messages میں شامل کرتا ہے۔ پرانے ٹول آؤٹ پٹ کو تراشیں یا ہسٹری کا خلاصہ کریں؛ tool output out of context خیال دکھاتا ہے۔
• BudgetExceeded قدم 2 پر فائر ہوتا ہے۔ آپ کا بجٹ ایک قدم سے چھوٹا ہے۔ چیک کریں کہ PRICE_IN فی 1M ٹوکن ہے، فی 1K نہیں۔

نمبروں کو محفوظ کرنے کے لیے، meter.steps، meter.tokens_in، meter.tokens_out اور meter.cost کو فی کام ایک JSON لائن کے طور پر لکھیں۔ ان لائنوں کا ایک ہفتہ آپ کو آپ کے ایجنٹ کے لیے فی قدم اصل ٹوکن بتاتا ہے، جو بعد میں ہر تخمینے میں ڈالنے والا نمبر ہے۔ ماڈلز، قیمتیں اور پہلی درخواست docs میں ہیں؛ ٹول کالز function calling in Python میں شامل ہیں۔