چیت‌شیت
هزینه، کش‌کردن و Batch APIهای LLM
LLM Cost, Caching and Batch APIs
قیمت‌گذاری هر فراخوانی، کش پیشوندها و معانی، دسته‌ای کردن کارهای آفلاین و محدودسازی سقف هزینه. پایتون و راست از درس‌ها.
فهرست مطالب
وظایف
کار و کد| وظیفه | کد |
|---|---|
| محاسبه هزینه یک فراخوانی | calculate_cost(model, input_tokens, output_tokens, cached_input_tokens=0) |
| علامت‌گذاری یک بلوک قابل‌کش | "cache_control": {"type": "ephemeral"} |
| نگه‌داشتن بلوک برای یک ساعت | "cache_control": {"type": "ephemeral", "ttl": "1h"} |
| خواندن اصابت‌های کش Anthropic | response.usage.cache_read_input_tokens |
| خواندن اصابت‌های کش OpenAI | resp.usage.prompt_tokens_details.cached_tokens |
| ساخت یک کش Gemini | client.caches.create(model=<model>, config=...) |
| استفاده از کش Gemini | config=types.GenerateContentConfig(cached_content=cache.name) |
| مسیریابی یک کوئری به ارزان‌ترین مدل | route_model(query, tier="pro") |
کش کردن پیشوند ثابت
کدpython
SYSTEM = [{
"type": "text",
"text": RUBRIC, # متن ثابت در ابتدا
"cache_control": {"type": "ephemeral"}, # مدت اعتبار 5 دقیقه (TTL)
}]
response = client.messages.create(
model="<model>", max_tokens=1024,
system=SYSTEM,
messages=[{"role": "user", "content": code}], # متن متغیر در انتها
)
response.usage.cache_creation_input_tokens # هزینه با ضریب 1.25 برابر
response.usage.cache_read_input_tokens # هزینه با ضریب 0.1 برابر
اعدادی که اهمیت دارند
مفهوم‌ها- نوشتن در کش
- 1.25 برابر قیمت پایه برای TTL پنج‌دقیقه‌ای؛ 2 برابر پایه برای TTL یک‌ساعته.
- خواندن از کش
- 0.30 دلار به ازای هر میلیون در برابر 3.00 دلار به ازای هر میلیون حالت تازه؛ 10 برابر ارزان‌تر.
- نقطه سر‌به‌سر
- 1 بار نوشتن و 1 بار خواندن برابر 0.675 برابر؛ 1 بار نوشتن و 10 بار خواندن برابر 0.205 برابر.
- قاعده بازاستفاده
- بلوکی را کش کنید که در طول TTL حداقل 3 بار خوانده می‌شود.
- پردازش دسته‌ای (Batch)
- 50٪ تخفیف ورودی و خروجی؛ تضمین 24 ساعته، معمولاً 2 تا 6 ساعته.
- دسته به‌همراه کش
- حدود 10٪ از صورت‌حساب حالت همگام و بدون کش.
- مسیریابی مدل
- 40 تا 70٪ صرفه‌جویی در هزینه مدل.
- ترکیب تمام اهرم‌ها
- حدود 5 تا 10٪ خط مبنای اولیه و خام.
محافظ‌های بودجه به ترتیب اجرا
گام‌به‌گام- محدودیت نرخ درخواستبه ازای هر مستأجر در 2 تا 3 برابر اوج مورد انتظار؛ بازگرداندن 429 همراه با
Retry-After. - سقف هزینه روزانه1.5 تا 3 برابر سقف قرارداد؛ محدودتر کردن نرخ درخواست و ارسال هشدار.
- سوییچ قطع اضطراریامتیاز z-score هزینه بالای 4 نسبت به خط مبنای مستأجر؛ توقف خودکار و ارسال پیام به نوبت پاسخگویی (آنکال).
- 70٪ بودجه
CostTrackerیک هشدار اخطار ثبت می‌کند. - 85٪ بودجهاعمال محدودیت (throttle)؛ مسیریابی صرفاً به مدل‌های ارزان‌تر.
- 95٪ بودجهتوقف کامل؛ ارائه پاسخ‌ها صرفاً از روی کش.
دو لایه کش
معماریکش کردن پرامپت در ارائه‌دهندگان مختلف
مقایسه| فاکتور | Anthropic | OpenAI | Gemini |
|---|---|---|---|
| سبک API | نشانگرهای cache_control | پیشوند خودکار | API مربوط به CachedContent |
| قیمت اصابت | 90٪ تخفیف روی ورودی | 50٪ تخفیف روی ورودی | حدود 25٪ حالت عادی |
| هزینه نوشتن | 25٪ هزینه اضافی | رایگان | هزینه ذخیره‌سازی به ازای هر توکن-ساعت |
| TTL پیش‌فرض | 5 دقیقه، با گزینه 1 ساعته | تا 1 ساعت | تعریف‌شده توسط کاربر، 1 ساعت |
| حداقل طول پیشوند | 1,024 توکن، 2,048 توکن برای Haiku | 1,024 توکن | 4,096 توکن برای Flash، 32,768 توکن برای Pro |
| زمان استفاده | پرامپت پایدار بالای 10 هزار، نوبت‌های گفت‌وگوی متعدد | محیط Serverless، بدون زیرساخت سفارشی | بازاستفاده چندروزه از یک پیکره متنی |
مقادیر پیش‌فرض در کد
پیش‌فرض‌ها| تنظیم | پیش‌فرض | توضیحات |
|---|---|---|
similarity_threshold | 0.85 | SemanticCache. نسخه دمو از 0.75 استفاده می‌کند |
ttl_seconds | 3600 | کش‌های دقیق و معنایی |
max_size | 1000 | ExactCache. قدیمی‌ترین ورودی را حذف می‌کند |
temperature | 0.0 | بالاتر از 0 کش دقیق نادیده گرفته می‌شود |
monthly_budget | 1000.0 | مبنای هشدار CostTracker |
spend_cap_multiplier | 2.0 | سقف برابر حاصل‌ضرب قرارداد در این مقدار است |
kill_z_score | 4.0 | مستأجر فراتر از این مقدار متوقف می‌شود |
Anthropic TTL | 5 min | "ttl": "1h" برای یک ساعت |
ارسال یک دسته (batch)
کدpython
requests.append({
"custom_id": f"request-{i}", # تطبیق نتایج با ورودی‌ها
"method": "POST", "url": "/v1/chat/completions",
"body": {"model": "<model>", "messages": [{"role": "user", "content": query}]},
})
batch_file = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h", # 50٪ تخفیف، نتایج طی 24 ساعت
)
عیب‌یابی
عیبیابینرخ اصابت نزدیک به 7٪
- علت
- زمان یا شناسه درخواست در پیشوند آمده است
- راه‌حل
- متن پویا را بعد از مرز کش قرار دهید
فراخوانی‌های موازی: N بار نوشتن
- علت
- فراخوانی‌ها پیش از اولین نوشتن اجرا می‌شوند
- راه‌حل
- درخواست 1 را تنها بفرستید، سپس بقیه را ارسال کنید
cache_read_input_tokensصفر می‌ماند- علت
- دریفت در کلیدهای کش رخ می‌دهد
- راه‌حل
- هر دو فیلد مصرف را در CI بررسی کنید
بلوک کش نمی‌شود
- علت
- کمتر از 1,024 توکن (2,048 برای Haiku)
- راه‌حل
- اندازه بلوک کش‌شده را بزرگ‌تر کنید
اصابت‌های OpenAI پس از استقرار متوقف می‌شوند
- علت
- تغییر ترتیب ابزارها یا فیلد جدید
user - راه‌حل
- ابزارها را با یک ترتیب پایدار سریال‌سازی کنید
cached exceeds input- علت
- توکن‌های کش‌شده جداگانه و اضافه شمرده شده‌اند
- راه‌حل
- توکن‌های کش‌شده زیرمجموعه‌ای از ورودی هستند
اجرای کد
دستورها| دستور | عملکرد |
|---|---|
python main.py | اجرای شبیه‌ساز درس در code/ |
python3 scripts/project_test.py <project> --stage 1 --path <workspace> | ارزیابی یک مرحله |
python3 scripts/project_test.py <project> --all --solution --strict | ارزیابی راه‌حل مرجع |
python3 <workspace>/usage.py <usage-file> --out usage-ledger.json | بازپخش مصرف ثبت‌شده در یک دفتر کل |
python3 cli.py samples/input.json --mode execute --output budget.json | اجرای وظایف برنامه‌ریز بودجه |
دفاتر کل پروژه
مفهوم‌ها- نرخ‌ها
- نانودلار صحیح به ازای هر توکن؛ ورودی‌های مجموعه‌داده‌ی نمونه، نه قیمت‌های ارائه‌دهنده.
- تخمین (estimate)
- حاصل
text.chars().count()تقسیم برchars_per_token، گردشده به بالا؛ نسبت 0 خطاست. - هزینه (cost)
- حاصل
usage.input - usage.cachedبا نرخ ورودی، به‌علاوه مقادیر کش و خروجی؛ هرکدام باchecked_mul. - رزرو (reserve)
- اگر
spent + sum(holds) + amount > limitباشد خطایbudget exceededمی‌دهد. - تسویه (settle)
- هزینه واقعی بیشتر از مقدار رزرو خطای
actual cost exceeds reservationمی‌دهد. - وضعیت‌ها
completed،rejected،needs_reconciliation.- اجرای نمونه
- 190 واحد در برابر محدودیت 100 واحدی؛ دو کار قبول می‌شوند؛ 95 واحد تسویه می‌شود.
پرسش و پاسخ
پرسش و پاسخ- کش پرامپت یا کش معنایی؟
- کش پرامپت: توکن‌های یکسان؛ کش معنایی: مفهوم و معنای یکسان.
- کدام آستانه معنایی؟
- 0.92 تا 0.95؛ در 0.85 پاسخ‌های نادرست دیده می‌شوند.
- کدام متریک واحد؟
- هزینه به ازای هر کوئری حل‌شده، نه دلار به ازای میلیون توکن.
نکات کاربردی
نکته‌ها- مقادیر
user_id،task_id،routeوtenant_idرا روی تمام فراخوانی‌ها ثبت کنید. - تفکیک توکن‌ها: پرامپت، ابزار، حافظه، پاسخ.
- استقرار را منوط به سهم خواندن از کش بالای 80٪ کنید.