# فصل ۰۷ — توکن، هزینه، و مرزها

<div dir="rtl">

# فصل ۰۷ — توکن، هزینه، و مرزها

## در این فصل چه یاد می‌گیری

مدل‌های آماده رایگان به‌نظر می‌رسند تا وقتی که برنامه‌ات چند کاربرِ واقعی پیدا کند. آن‌وقت سه چیز ناگهان مهم می‌شوند: **توکن، سهمیه، و زمان.** در این فصل واحدِ شمارشِ این دنیا را می‌شناسی، هزینه را قبل از خرج‌کردن تخمین می‌زنی، و سه تکنیکِ ساده یاد می‌گیری که مصرف را چند برابر پایین می‌آورند. و یک واقعیت را با عدد می‌بینی که هیچ آموزشِ انگلیسی‌زبانی به تو نمی‌گوید: **متنِ فارسی می‌تواند چند برابرِ متنِ انگلیسی توکن مصرف کند.**

![یک کنتور با عقربه‌ای که به ناحیهٔ قرمز نزدیک می‌شود، کنارِ چند سکه](/lesson-assets/t4-s07-limits-cost/prompt/01-image-meter.png)

آخر این فصل می‌توانی:

- توکن را بشماری و بگویی چرا واحدِ شمارش کلمه نیست
- هزینهٔ یک کارِ مشخص را **قبل از** اجرا تخمین بزنی
- با `cache` و `batch` و انتخابِ درستِ مدل مصرف را کم کنی
- بگویی هزینهٔ فارسی چقدر بیشتر است و چه کارش می‌شود کرد

## قبل از شروع

**از فصل ۳:** فراخوانیِ API، `timeout`، و کدهای وضعیت.

**از فصل ۶:** اینکه `index` را یک بار می‌سازی، نه هر بار.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-4-pretrained-models/session-07-limits-cost.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

> 💡 **نکته:** این فصل هم مثلِ فصلِ ۴ **هیچ فراخوانیِ واقعی‌ای نمی‌کند**. همه‌چیز محلی و قابلِ تکرار است، چون موضوعِ فصل «حساب کردنِ هزینه» است، نه «خرج کردنِ آن».

## ۱. توکن: واحدِ شمارشِ این دنیا

مدل‌های زبانی نه با نویسه کار می‌کنند نه با کلمه، بلکه با **توکن**: تکه‌هایی که یک الگوریتم بر اساسِ تکرارشدنشان در دادهٔ آموزشی ساخته. کلمهٔ پرتکرار یک توکن می‌شود، کلمهٔ کمیاب به چند تکه می‌شکند.

</div>

```bash
pip install -q tiktoken
```

<div dir="rtl">

</div>

```python
import tiktoken

encoding = tiktoken.get_encoding("cl100k_base")

sentence = "سلام دنیا"
ids = encoding.encode(sentence)

print("متن:", sentence)
print("تعداد نویسه:", len(sentence))
print("تعداد توکن:", len(ids))
print("تکه‌ها:", [encoding.decode([i]) for i in ids])
```

<div dir="rtl">

</div>

```text
متن: سلام دنیا
تعداد نویسه: 9
تعداد توکن: 7
تکه‌ها: ['س', 'ل', 'ام', ' د', 'ن', 'ی', 'ا']
```

<div dir="rtl">

> ✅ **چک کن:** «سلام دنیا» باید ۷ توکن بدهد. اگر عددِ دیگری گرفتی، توکنایزرِ دیگری بار شده — `cl100k_base` را حرف‌به‌حرف چک کن. و اگر خطای شبکه گرفتی، `tiktoken` بارِ اول جدولِ توکن‌ها را دانلود می‌کند؛ همان سلول را دوباره اجرا کن.

**دو کلمهٔ فارسی، هفت توکن — و پنج تای آن‌ها یک حرفِ تنهاست.** این‌جا نه کلمه واحدِ شمارش است، نه هجا. حتی «دنیا» که کلمه‌ای کاملاً معمولی است، حرف‌حرف شکسته.

> ⚠️ **مواظب باش:** `cl100k_base` توکنایزرِ یک خانوادهٔ مشخص از مدل‌هاست، نه قانونِ جهانی. هر مدل توکنایزرِ خودش را دارد و شمارشش فرق می‌کند. **برای تخمین عالی است، برای صورت‌حساب نه** — عددِ دقیق را همیشه از پاسخِ خودِ API بگیر، که معمولاً بخشی به نامِ `usage` دارد.

## ۲. مالیاتِ فارسی

</div>

```python
persian = "برای اینکه برنج شفته نشود، آب را دقیقاً اندازه بگیر."
english = "To keep the rice from getting mushy, measure the water exactly."

for name, text in [("فارسی ", persian), ("انگلیسی", english)]:
    n = len(encoding.encode(text))
    print(f"{name}: {len(text):>3} نویسه -> {n:>3} توکن  ({round(len(text) / n, 1)} نویسه در هر توکن)")
```

<div dir="rtl">

</div>

```text
فارسی :  52 نویسه ->  40 توکن  (1.3 نویسه در هر توکن)
انگلیسی:  63 نویسه ->  14 توکن  (4.5 نویسه در هر توکن)
```

<div dir="rtl">

دو جمله که **یک چیز می‌گویند**. جملهٔ انگلیسی حتی بلندتر است. ولی فارسی ۴۰ توکن می‌خورد و انگلیسی ۱۴ — **نزدیک به سه برابر.**

دلیلش تبعیض نیست، آمار است: این توکنایزرها روی پیکره‌هایی ساخته شده‌اند که غالبشان انگلیسی است، پس تکه‌های پرتکرارِ انگلیسی در واژگانشان جا گرفته‌اند و فارسی به حروفِ تنها می‌شکند.

**سه پیامدِ عملی، و هر سه واقعی‌اند:**

- **هزینه‌ات بیشتر است، گاهی چند برابر،** اگر با متنِ فارسی کار می‌کنی. هر تخمینی که از یک منبعِ انگلیسی خواندی، برای تو کم‌برآورد است.
- **پنجرهٔ زمینه زودتر پر می‌شود.** حدِ ورودیِ مدل به توکن است، نه به صفحه؛ پس متنِ فارسیِ کمتری در آن جا می‌شود.
- **تکه‌های فصلِ ۶ را با توکن بسنج، نه با نویسه** — اگر حدِ تکه را بر اساسِ تعدادِ نویسه گذاشته‌ای، در فارسی خیلی بزرگ‌تر از تصورت است.

> 📏 **اندازه بگیر:** این عددها را برای متنِ **خودت** دربیاور، نه برای جملهٔ من. یک نمونهٔ واقعی از دادهٔ کاری‌ات بردار، `encode` کن، و نسبتِ نویسه به توکن را حساب کن. متنِ فنی با کلمه‌های انگلیسیِ زیاد، نسبتِ کاملاً متفاوتی از متنِ محاوره‌ای دارد.

**ولی این عدد به توکنایزر بسته است.** `cl100k_base` نسلِ قدیمی‌تری است. همان دو جمله را با `o200k_base`، توکنایزرِ نسلِ تازه‌ترِ همان شرکت، بشمار:

</div>

```python
modern = tiktoken.get_encoding("o200k_base")

for name, text in [("فارسی ", persian), ("انگلیسی", english)]:
    print(f"{name}: cl100k_base = {len(encoding.encode(text)):>2} توکن | o200k_base = {len(modern.encode(text)):>2} توکن")
```

<div dir="rtl">

</div>

```text
فارسی : cl100k_base = 40 توکن | o200k_base = 17 توکن
انگلیسی: cl100k_base = 14 توکن | o200k_base = 14 توکن
```

<div dir="rtl">

فارسی از ۴۰ توکن به ۱۷ رسید و انگلیسی همان ۱۴ ماند. یعنی فاصله از نزدیک به سه برابر به حدودِ ۱٫۲ برابر آمد. **مالیاتِ فارسی واقعی است، ولی اندازه‌اش به مدل بستگی دارد.** پس آن را برای همان مدلی بسنج که واقعاً به‌کار می‌بری، از بخشِ `usage` پاسخِ API. بقیهٔ این فصل با `cl100k_base` می‌ماند تا عددها با بالا بخوانند.

## ۳. تخمینِ هزینه، قبل از خرج

فرمول همیشه یک شکل دارد و سه ورودی می‌خواهد: تعدادِ توکنِ ورودی، تعدادِ توکنِ خروجی، و نرخِ هرکدام.

</div>

```python
import pandas as pd

docs = pd.read_csv("docs.csv")
corpus = "\n".join(docs["text"])
input_tokens = len(encoding.encode(corpus))

# این دو عدد را از صفحهٔ قیمتِ سرویسِ خودت بگذار — نمونه‌اند، نه واقعی.
PRICE_INPUT = 0.10    # به ازای هر یک میلیون توکن ورودی
PRICE_OUTPUT = 0.40   # به ازای هر یک میلیون توکن خروجی
OUTPUT_TOKENS = 200   # تخمینِ طولِ جواب
CALLS = 1000

cost = CALLS * (input_tokens * PRICE_INPUT + OUTPUT_TOKENS * PRICE_OUTPUT) / 1_000_000

print("کل پیکره:", len(corpus), "نویسه،", input_tokens, "توکن")
print(f"هزینهٔ تخمینی {CALLS} فراخوانی: {round(cost, 2)} واحد")
```

<div dir="rtl">

</div>

```text
کل پیکره: 1162 نویسه، 848 توکن
هزینهٔ تخمینی 1000 فراخوانی: 0.16 واحد
```

<div dir="rtl">

عددِ نهایی اینجا مهم نیست — **فرمول مهم است.** نرخ‌ها مدام عوض می‌شوند، پس آن دو ثابت را همیشه از صفحهٔ قیمتِ سرویسی که واقعاً به‌کار می‌بری بردار.

</div>

| آنچه باید بدانی | کجا پیدایش می‌کنی |
|---|---|
| نرخِ توکنِ ورودی و خروجی | صفحهٔ قیمتِ سرویس — **در زمان خواندن چک شود** |
| سهمیهٔ رایگان | همان صفحه — **در زمان خواندن چک شود** |
| حدِ درخواست در دقیقه | مستنداتِ `rate limit` |
| مصرفِ واقعیِ هر فراخوانی | بخشِ `usage` در پاسخِ API |

<div dir="rtl">

> ⚠️ **مواظب باش:** آن `input_tokens` بالا فقط کلِ پیکره است. اگر الگوی `RAG` فصلِ ۶ را به‌کار ببری، در هر فراخوانی **فقط سه تکه** می‌فرستی نه کلِ پیکره را. **یعنی بازیابی، پیش از آنکه تکنیکِ کیفیت باشد، تکنیکِ هزینه است** — و برای پیکرهٔ بزرگ، تفاوتش بینِ «ممکن» و «غیرممکن» است، چون کلِ پیکره اصلاً در پنجرهٔ زمینه جا نمی‌شود.

## ۴. `cache`: جوابی را که یک بار گرفته‌ای دوباره نخر

</div>

```python
cache = {}
counter = {"calls": 0}      # dict به‌جای متغیر ساده، تا تابع بتواند تغییرش بدهد

def pretend_call(prompt):
    """جای یک فراخوانیِ واقعی — فقط می‌شمارد که چند بار صدا زده شده."""
    counter["calls"] += 1
    return f"جواب برای: {prompt}"

def ask_cached(prompt):
    if prompt not in cache:
        cache[prompt] = pretend_call(prompt)
    return cache[prompt]

questions = ["قیمت چند است", "ساعت کاری", "قیمت چند است", "آدرس کجاست", "ساعت کاری", "قیمت چند است"]
for q in questions:
    ask_cached(q)

print("تعداد سؤال‌ها:", len(questions))
print("فراخوانی‌های واقعی:", counter["calls"])
print("صرفه‌جویی:", round((1 - counter["calls"] / len(questions)) * 100), "درصد")
```

<div dir="rtl">

</div>

```text
تعداد سؤال‌ها: 6
فراخوانی‌های واقعی: 3
صرفه‌جویی: 50 درصد
```

<div dir="rtl">

شمارنده را عمداً `dict` گذاشتیم و نه یک عددِ ساده: تابعی که عددِ بیرونی را تغییر بدهد در پایتون کارِ اضافه لازم دارد (همان `UnboundLocalError` ترمِ ۱ فصلِ ۷)، ولی **تغییرِ محتوای یک `dict` از داخلِ تابع بی‌دردسر کار می‌کند**.

شش سؤال، سه فراخوانی. **در یک سامانهٔ واقعی این نسبت معمولاً خیلی بهتر است**، چون سؤال‌های کاربران به‌شدت تکراری‌اند: چند سؤالِ پرتکرار بیشترِ ترافیک را می‌سازند.

سه نکته که یک `cache` را از کارآمد به خطرناک می‌برند:

- **کلید باید کلِ چیزی باشد که جواب به آن وابسته است** — نه فقط سؤال، بلکه نامِ مدل و متنِ سامانه و هر تنظیمی که فرستاده‌ای. کلیدِ ناقص یعنی جوابِ مدلِ قدیمی را به مدلِ جدید نسبت می‌دهی.
- **`cache` با پایانِ برنامه پاک می‌شود.** برای ماندگاری، در فایل یا پایگاه‌داده ذخیره‌اش کن.
- **جوابِ کهنه هم مشکل است.** اگر سؤال دربارهٔ چیزی است که تغییر می‌کند، `cache` باید تاریخِ انقضا داشته باشد.

## ۵. `batch`: چند تا با هم

</div>

```python
def pretend_batch(prompts):
    """یک درخواست، چند ورودی — یعنی یک بار سربارِ شبکه به‌جای چند بار."""
    counter["calls"] += 1
    return [f"جواب برای: {p}" for p in prompts]

counter["calls"] = 0
for item in ["الف", "ب", "ج", "د"]:
    pretend_call(item)
one_by_one = counter["calls"]

counter["calls"] = 0
pretend_batch(["الف", "ب", "ج", "د"])
batched = counter["calls"]

print("یکی‌یکی:", one_by_one, "درخواست")
print("دسته‌ای:", batched, "درخواست")
```

<div dir="rtl">

</div>

```text
یکی‌یکی: 4 درخواست
دسته‌ای: 1 درخواست
```

<div dir="rtl">

**دقت کن `batch` تعدادِ توکن را کم نمی‌کند** — همان چهار متن باید پردازش شوند. چیزی که کم می‌کند **تعدادِ درخواست** است، و این دو جای متفاوت اثر دارد: سربارِ شبکه (که در کارِ زیاد جمع می‌شود) و **حدِ درخواست در دقیقه**، که معمولاً زودتر از حدِ توکن به دیوار می‌خورد.

همان `encoder.encode(docs["text"].tolist())` فصلِ ۶ هم دقیقاً همین بود: یک فراخوانی برای بیست جمله، نه بیست فراخوانی.

## ۶. وقتی به دیوار می‌خوری

سرویس‌ها حدِ درخواست دارند و رد شدن از آن جوابِ `429` می‌گیرد — همان جدولِ فصلِ ۳. کارِ درست **تلاشِ دوباره با فاصلهٔ فزاینده** است:

</div>

```python
def wait_seconds(attempt, base=1.0):
    """فاصلهٔ انتظار قبل از تلاشِ بعدی: هر بار دو برابر."""
    return base * (2 ** attempt)

for attempt in range(5):
    print(f"تلاش {attempt + 1} -> صبر {wait_seconds(attempt)} ثانیه")
```

<div dir="rtl">

</div>

```text
تلاش 1 -> صبر 1.0 ثانیه
تلاش 2 -> صبر 2.0 ثانیه
تلاش 3 -> صبر 4.0 ثانیه
تلاش 4 -> صبر 8.0 ثانیه
تلاش 5 -> صبر 16.0 ثانیه
```

<div dir="rtl">

به این `exponential backoff` می‌گویند. منطقش ساده است: اگر سرویس شلوغ است، **فشارِ بیشتر وضع را بدتر می‌کند**؛ عقب کشیدن به آن فرصتِ نفس می‌دهد.

در کدِ واقعی این‌طور به‌کارش می‌بری:

</div>

```python-broken
import time
import requests

for attempt in range(5):
    response = requests.post(URL, json=payload, timeout=30)
    if response.status_code != 429:
        break
    time.sleep(wait_seconds(attempt))
```

<div dir="rtl">

> ⚠️ **مواظب باش:** روی `429` و خطاهای موقتِ سرور (`5xx`) دوباره تلاش کن؛ روی `401` و `400` **هرگز**. کلیدِ غلط با تلاشِ دوباره درست نمی‌شود و پرامپتِ بدساخت هم همین‌طور — فقط سهمیه‌ات را می‌سوزانی و خطای واقعی را دیرتر می‌بینی. **همان قاعدهٔ ترمِ ۱ فصلِ ۸: فقط خطایی را بگیر که می‌دانی با آن چه کنی.**

## ۷. جدولِ تصمیم

وقتی هزینه یا کندی مشکل شد، ترتیبِ کارها این است — از ارزان‌ترین تلاش به گران‌ترین:

</div>

| مشکل | اولین کاری که باید بکنی |
|---|---|
| سؤال‌های تکراری زیاد | `cache` |
| ورودیِ خیلی بلند | بازیابی (`RAG`) به‌جای فرستادنِ کلِ متن |
| درخواست‌های زیاد و کوچک | `batch` |
| `429` مکرر | `backoff` + کم کردنِ نرخِ ارسال |
| هزینهٔ کلی بالا | مدلِ کوچک‌تر برای کارهای ساده |
| کندیِ محسوس | مدلِ کوچک‌تر، یا خروجیِ کوتاه‌تر بخواه |

<div dir="rtl">

آن ردیفِ آخر را جدی بگیر: **تولیدِ هر توکنِ خروجی زمان می‌برد.** جوابِ ۵۰۰ توکنی حدودِ پنج برابرِ جوابِ ۱۰۰ توکنی طول می‌کشد. اگر در پرامپت بنویسی «حداکثر سه جمله»، هم سریع‌تر می‌شود هم ارزان‌تر — و اغلب مفیدتر.

> 🤖 **از دستیارت بپرس:** «اگر یک سامانهٔ پرسش‌وپاسخ روی هزار سند فارسی بسازم، کجاهای مسیر هزینه ایجاد می‌شود؟» بعد جوابش را با این فصل بسنج: **آیا مالیاتِ فارسی را گفت؟** بیشترِ دستیارها نمی‌گویند، چون دادهٔ آموزشی‌شان انگلیسی است. **این دقیقاً همان جایی است که تو باید بیشتر از دستیارت بدانی.**

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| token | توکن | کوچک‌ترین واحدی که مدل متن را با آن می‌شمارد |
| context window | کانتکست ویندو | حداکثر توکنی که در یک درخواست جا می‌شود |
| rate limit | ریت لیمیت | حدِ تعدادِ درخواست در واحدِ زمان |
| cache | کش | نگه‌داشتنِ جوابِ محاسبه‌شده برای دفعهٔ بعد |
| batch | بچ | فرستادنِ چند ورودی در یک درخواست |
| exponential backoff | اکسپوننشال بک‌آف | تلاشِ دوباره با فاصله‌های دوبرابرشونده |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `batch` هزینهٔ توکن را کم نمی‌کند ولی هنوز ارزشش را دارد؟

**تمرینِ اجباری:** پنج متنِ فارسی و پنج متنِ انگلیسیِ **هم‌معنا** بردار و برای هر جفت نسبتِ توکن را حساب کن. میانگین بگیر. حالا با آن میانگین، هزینهٔ یک سامانهٔ فرضی با ده هزار پرسشِ فارسی در ماه را تخمین بزن و همان را برای انگلیسی. **تفاوت را با عدد بنویس** — این عددی است که در هر تصمیمِ معماریِ فارسی باید در ذهنت باشد.

**تمرینِ ستاره‌دار ⭐:** `ask_cached` را طوری بازنویسی کن که کلیدش ترکیبِ (پرامپت، نامِ مدل، دما) باشد و `cache` را در یک فایل `json` ذخیره و بازخوانی کند. بعد به این فکر کن: **اگر دو کاربرِ متفاوت یک سؤال بپرسند، آیا باید جوابِ کش‌شده را به دومی بدهی؟** جواب همیشه «بله» نیست — بگو در چه حالتی نه، و چه چیزی باید به کلید اضافه شود.

## در فصل بعد

هفت فصل ابزار جمع کردی: مدلِ آماده، API، خروجیِ ساختارمند، `embedding`، بازیابی، و مهارِ هزینه. فصلِ آخرِ ترم همه را در یک ابزارِ کامل جمع می‌کند: **یک دستیارِ پرسش‌وپاسخ روی متن‌های خودت** — با بازیابی، اعتبارسنجی، `cache`، و رفتارِ درست وقتی جواب را نمی‌داند.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t4/s07-limits-cost (یادستان, Yaadestan)
