# فصل ۰۹ — پروژه: مدلِ متنِ فارسیِ خودت

<div dir="rtl">

# فصل ۰۹ — پروژه: مدلِ متنِ فارسیِ خودت

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

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

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

![یک ترازوی سه‌کفه‌ای که سه گزینه را با یک بودجهٔ محدود می‌سنجد](/lesson-assets/t4-s09-project-text-model/prompt/01-image-three-way-choice.png)

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

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

## قبل از شروع

**از کلِ ترمِ ۴.** این فصل هیچ چیزِ تازه‌ای معرفی نمی‌کند.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/zharfa/term-4-language/session-09-project-text-model.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

> 💡 **نکته:** **زمانِ تخمینی روی CPU: کمتر از یک دقیقه** بعد از دانلودِ مدل. **اولین اجرا وزن‌های مدلِ چندزبانه را دانلود می‌کند** و چند دقیقه طول می‌کشد؛ اگر نوت‌بوک روی همان سلول ایستاد، خراب نشده.

## ۱. سناریو و بودجه

</div>

```python
import torch
import torch.nn as nn
from torch.utils.data import TensorDataset, DataLoader
from transformers import AutoTokenizer, AutoModel
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression

loss_fn = nn.CrossEntropyLoss()
BUDGET = 40

y_train = torch.tensor(train_labels)
y_val = torch.tensor(val_labels)
y_test = torch.tensor(test_labels)

print("بودجهٔ برچسب:", BUDGET, "نمونه")
print("توزیع کلاس‌ها در بودجه:", torch.bincount(y_train[:BUDGET], minlength=4).tolist())
print("موضوع‌ها:", TOPIC_NAMES)
```

<div dir="rtl">

</div>

```text
بودجهٔ برچسب: 40 نمونه
توزیع کلاس‌ها در بودجه: [7, 15, 12, 6]
موضوع‌ها: ['سفر', 'آشپزی', 'برنامه\u200cنویسی', 'سلامت']
```

<div dir="rtl">

**اولین کار، نگاه به توزیع است — و همان‌جا مشکل پیداست: ۱۵ نمونه برای یک کلاس و ۶ برای دیگری.**

**این نامتوازنی را ما نساختیم؛ نتیجهٔ طبیعیِ برداشتنِ چهل نمونهٔ اولِ یک مجموعهٔ بُرخورده است** — و دقیقاً همان چیزی که در پروژهٔ واقعی پیش می‌آید. **یادت باشد؛ در بخشِ ۴ توضیحِ ضعفِ مدل را می‌دهد.**

## ۲. سه نامزد، بودجهٔ یکسان

</div>

```python
NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = AutoTokenizer.from_pretrained(NAME)
base = AutoModel.from_pretrained(NAME)


def encode(texts):
    batch = tokenizer(texts, padding=True, truncation=True, max_length=32, return_tensors="pt")
    return batch["input_ids"], batch["attention_mask"]


@torch.no_grad()
def features(ids, mask, batch=64):
    base.eval()
    out = []
    for i in range(0, len(ids), batch):
        hidden = base(input_ids=ids[i:i + batch], attention_mask=mask[i:i + batch]).last_hidden_state
        m = mask[i:i + batch].unsqueeze(-1).float()
        out.append((hidden * m).sum(1) / m.sum(1))
    return torch.cat(out)


Ftr = features(*encode(train_texts))
Fva = features(*encode(val_texts))
Fte = features(*encode(test_texts))


@torch.no_grad()
def accuracy(model, X, y):
    model.eval()
    return float((model(X).argmax(1) == y).float().mean())


def fit_head(X, y, seed=0, epochs=60, lr=0.01, batch=16):
    torch.manual_seed(seed)
    head = nn.Linear(X.shape[1], 4)
    loader = DataLoader(TensorDataset(X, y), batch_size=batch, shuffle=True)
    opt = torch.optim.Adam(head.parameters(), lr=lr)
    for _ in range(epochs):
        head.train()
        for xb, yb in loader:
            opt.zero_grad()
            loss_fn(head(xb), yb).backward()
            opt.step()
    return head


pretrained = [accuracy(fit_head(Ftr[:BUDGET], y_train[:BUDGET], seed=s), Fva, y_val) for s in (0, 1, 2)]
print("مدل آماده  :", [round(v, 4) for v in pretrained], "| میانگین:", round(sum(pretrained) / 3, 4))

vec = TfidfVectorizer()
tfidf = LogisticRegression(max_iter=1000).fit(vec.fit_transform(train_texts[:BUDGET]), train_labels[:BUDGET])
print("خط پایه TF-IDF:", round(tfidf.score(vec.transform(val_texts), val_labels), 4))
```

<div dir="rtl">

</div>

```text
مدل آماده  : [0.8779, 0.8721, 0.9012] | میانگین: 0.8837
خط پایه TF-IDF: 0.5291
```

<div dir="rtl">

</div>

```python
words = sorted({w for t in sentences for w in t.split()})
VOCAB = {w: i + 1 for i, w in enumerate(words)}
LEN = max(len(s.split()) for s in sentences)


def encode_ids(texts):
    out = torch.zeros(len(texts), LEN, dtype=torch.long)
    for i, s in enumerate(texts):
        ids = [VOCAB[w] for w in s.split()][:LEN]
        out[i, :len(ids)] = torch.tensor(ids)
    return out


class Scratch(nn.Module):
    def __init__(self, dim=32):
        super().__init__()
        self.emb = nn.Embedding(len(VOCAB) + 1, dim, padding_idx=0)
        self.out = nn.Linear(dim, 4)

    def forward(self, x):
        mask = (x != 0).unsqueeze(-1).float()
        return self.out((self.emb(x) * mask).sum(1) / mask.sum(1).clamp_min(1))


scratch_scores = []
for s in (0, 1, 2):
    torch.manual_seed(s)
    model = Scratch()
    loader = DataLoader(TensorDataset(encode_ids(train_texts[:BUDGET]), y_train[:BUDGET]),
                        batch_size=16, shuffle=True)
    opt = torch.optim.Adam(model.parameters(), lr=0.01)
    for _ in range(60):
        model.train()
        for xb, yb in loader:
            opt.zero_grad()
            loss_fn(model(xb), yb).backward()
            opt.step()
    scratch_scores.append(accuracy(model, encode_ids(val_texts), y_val))

print("از صفر     :", [round(v, 4) for v in scratch_scores], "| میانگین:", round(sum(scratch_scores) / 3, 4))
```

<div dir="rtl">

</div>

```text
از صفر     : [0.814, 0.8372, 0.8372] | میانگین: 0.8295
```

<div dir="rtl">

**سه نتیجه، و ترتیبشان روشن است:**

</div>

| روش | میانگین | بازه | پارامترِ آموزش‌دیده |
|---|---|---|---|
| خط پایهٔ `TF-IDF` | ۰٫۵۲۹ | — | — |
| `embedding` از صفر | ۰٫۸۳۰ | ۰٫۸۱۴..۰٫۸۳۷ | ۲٬۶۹۲ |
| **مدلِ آماده** | **۰٫۸۸۴** | ۰٫۸۷۲..۰٫۹۰۱ | **۱٬۵۴۰** |

<div dir="rtl">

**و معیارِ ترمِ ۲ فصلِ ۷ را رویش اجرا کن: بازه‌ها هم‌پوشانی دارند یا نه؟**

- **مدلِ آماده (۰٫۸۷۲..۰٫۹۰۱) با مدلِ از صفر (۰٫۸۱۴..۰٫۸۳۷) هم‌پوشانی ندارد.** ولی این سه `seed` فقط مقداردهیِ اولیه را عوض کرده‌اند و هر سه روی همان چهل نمونه‌اند. روی ده انتخابِ تصادفیِ چهل‌تاییِ دیگر بازه‌ها کاملاً هم‌پوشانی دارند: ۰٫۸۰۲..۰٫۹۱۵ در برابرِ ۰٫۷۸۵..۰٫۹۱۳، و مدلِ آماده فقط ۶ بار از ۱۰ جلوتر است. پس این برتری روی همین چهل نمونه واقعی است، ولی برتریِ کلیِ مدلِ آماده را ثابت نمی‌کند.
- **و هر دو از خطِ پایه خیلی جلوترند** — سی تا سی‌وپنج واحد.

**نکتهٔ ظریف در ستونِ آخر:** مدلِ آماده **کمترین** پارامترِ آموزش‌دیده را دارد (فقط یک `Linear(384, 4)`) و بهترین نتیجه را. **دانشِ لازم قبلاً در ۱۱۷ میلیون پارامترِ قفل‌شده هست؛ ما فقط راهِ استفاده‌اش را یاد دادیم.**

## ۳. کجا ضعیف است

</div>

```python
head = fit_head(Ftr[:BUDGET], y_train[:BUDGET])
head.eval()
with torch.no_grad():
    predicted = head(Fva).argmax(1)

print("دقت هر کلاس:", [round(float((predicted[y_val == c] == c).float().mean()), 2) for c in range(4)])
print("تعداد در بودجه:", torch.bincount(y_train[:BUDGET], minlength=4).tolist())
```

<div dir="rtl">

</div>

```text
دقت هر کلاس: [0.69, 1.0, 1.0, 0.84]
تعداد در بودجه: [7, 15, 12, 6]
```

<div dir="rtl">

**دو ستون را کنارِ هم بخوان:**

- **«آشپزی» (۱۵ نمونه) و «برنامه‌نویسی» (۱۲ نمونه): دقتِ کامل.**
- **«سفر» (۷ نمونه): ۰٫۶۹. «سلامت» (۶ نمونه): ۰٫۸۴.**

**هر دو کلاسِ ضعیف همان دو کلاسِ کم‌نمونه‌اند** — و این را عددِ کلیِ ۰٫۸۸ پنهان می‌کرد.

**ولی به ترتیبشان دقت کن، چون درسِ دومی دارد: «سلامت» با ۶ نمونه از «سفر» با ۷ نمونه بهتر است.** یعنی رابطهٔ «نمونهٔ بیشتر ⇒ دقتِ بیشتر» یک **گرایش** است، نه یک قاعدهٔ دقیق. **با این عددهای کوچک — شش و هفت نمونه — تفاوتِ یک نمونه چیزی را ثابت نمی‌کند** (همان درسِ ترمِ ۲ فصلِ ۷). آنچه محکم است، شکافِ بینِ دو گروه است: دو کلاسِ پرنمونه ۱٫۰ و دو کلاسِ کم‌نمونه زیرِ ۰٫۸۵.

> 📏 **اندازه بگیر:** **و همین جدول، عملی‌ترین توصیهٔ پروژه را می‌دهد: بودجهٔ برچسبِ بعدی‌ات را روی «سفر» خرج کن، نه پخش‌شده.** هفت نمونهٔ تازه برای کلاسِ ضعیف از هفت نمونهٔ تصادفی بهتر است: در ده اجرا دقتِ کل ۰٫۹۲۴ در برابرِ ۰٫۹۰۶. ولی جای هفتاد نمونهٔ تصادفی را نمی‌گیرد، که ۰٫۹۶۸ می‌دهد. **این نوع تصمیم فقط از دقتِ هر کلاس درمی‌آید، نه از عددِ کلی.**

## ۴. آن یک بارِ نهایی

</div>

```python
print("برنده روی آزمون (یک بار):", round(accuracy(head, Fte, y_test), 4))
```

<div dir="rtl">

</div>

```text
برنده روی آزمون (یک بار): 0.8736
```

<div dir="rtl">

**۰٫۸۷۴ روی آزمون در برابرِ ۰٫۸۸۴ میانگینِ اعتبارسنجی — یک واحد پایین‌تر، کاملاً در محدودهٔ انتظار.**

## ۵. گزارشِ نهایی

</div>

| | |
|---|---|
| **مسئله** | طبقه‌بندیِ چهار موضوعِ متنِ فارسی، روی دادهٔ ساختگی از شش قالبِ جمله |
| **محدودیت** | فقط ۴۰ نمونهٔ برچسب‌خورده |
| **داده** | ۱۷۲ اعتبارسنجی، ۱۷۴ آزمون؛ توزیعِ بودجه: ۷/۱۵/۱۲/۶ |
| **روش** | ویژگیِ مدلِ چندزبانهٔ قفل‌شده + یک `Linear(384, 4)` |
| **پارامترِ آموزش‌دیده** | ۱٬۵۴۰ از ۱۱۷ میلیون |
| **اعتبارسنجی** | ۰٫۸۸۴ میانگین روی سه `seed`، بازهٔ ۰٫۸۷۲..۰٫۹۰۱ |
| **آزمون (یک بار)** | **۰٫۸۷۴** |
| **رقبا** | از صفر ۰٫۸۳۰ (روی این چهل نمونه بی‌هم‌پوشانی؛ روی ده انتخابِ دیگر با هم‌پوشانی) — `TF-IDF` ۰٫۵۲۹ |
| **ضعف** | «سفر» ۰٫۶۹ با ۷ نمونه، «سلامت» ۰٫۸۴ با ۶ نمونه |
| **توصیهٔ عملی** | بودجهٔ برچسبِ بعدی روی دو کلاسِ کم‌نمونه |
| **به‌کارش نبر برای** | متنِ خارج از این چهار موضوع، یا متنی که ساختارش با پیکرهٔ آموزش فرق دارد |
| **هشدارِ مهم** | **از حدودِ ۲۰۰ نمونه به بعد، `TF-IDF` به ۱٫۰ می‌رسد و از این مدل بهتر است** |

<div dir="rtl">

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

> ✅ **چک کن:** قبل از باور کردنِ هر برتری، **آزمونِ نشتیِ ترمِ ۲ فصلِ ۷ را اجرا کن:** برچسب‌های آموزش را تصادفی بُر بزن و دوباره بسنج. دقت باید به حدودِ ۰٫۲۵ سقوط کند (چهار کلاس). **اگر نکرد، جایی نشتی داری.**

> 🔧 **اگر کار نکرد:** **عددها با کتاب نمی‌خوانند** — `torch.manual_seed` یا ترتیبِ داده فرق دارد؛ سلولِ راه‌اندازی را از نو اجرا کن. **مدلِ از صفر `KeyError` می‌دهد** — `VOCAB` را از `sentences` بساز نه از زیرمجموعهٔ بودجه. **دقتِ آزمون خیلی پایین‌تر است** — روی اعتبارسنجی `overfit` کرده‌ای؛ تعدادِ آزمایش‌هایت را بشمار.

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

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا مدلی که کمترین پارامترِ آموزش‌دیده را دارد، بهترین نتیجه را گرفت؟

**تمرینِ اجباری:** `BUDGET` را ۲۰، ۸۰ و ۲۰۰ بگذار و **جدولِ سه‌نامزدی را برای هر کدام کامل کن** (هر کدام با سه `seed`). منحنیِ هر سه روش را روی یک نمودار بکش. **از کدام بودجه به بعد، خطِ پایه به بقیه می‌رسد؟** آن عدد، مرزِ تصمیمِ عملیِ توست.

**تمرینِ ستاره‌دار ⭐:** بودجه را متوازن کن — به‌جای چهل نمونهٔ اول، **ده نمونه از هر کلاس** بردار. با همان چهل برچسب، **دقتِ هر کلاس چقدر عوض می‌شود؟** و دقتِ کلی؟ جوابت این سؤال را جواب می‌دهد: **آیا انتخابِ هوشمندانهٔ نمونه‌ها می‌تواند جای دادهٔ بیشتر را بگیرد؟** (این ایده اسم دارد: `active learning`.)

## در فصل بعد

ترمِ ۴ اینجا تمام می‌شود. سه چیز را با خودت ببر:

- **`attention` ساده است.** ضربِ داخلی، `softmax`، میانگینِ وزن‌دار — و کلِ مدل‌های زبانی روی همین بنا شده‌اند.
- **مالیاتِ فارسی خاصیتِ زبان نیست، خاصیتِ توکنایزر است** — و انتخابِ درست هزینه‌ات را سه برابر کم می‌کند.
- **ارزشِ مدلِ آماده در کم بودنِ داده است**، نه در سقفِ دقت.

و ترمِ ۵ سؤالِ بعدی را جواب می‌دهد: **حالا که می‌دانی این مدل‌ها چطور کار می‌کنند، چطور یک سامانهٔ واقعی رویشان بسازی که خرابی‌اش را بتوانی اندازه بگیری؟**

</div>

---
Source: https://yaadestan.com/courses/zharfa/lessons/t4/s09-project-text-model (یادستان, Yaadestan)
