# فصل ۰۸ — یک مدلِ آمادهٔ چندزبانه روی فارسی: ویژگی‌گیری و `fine-tune`

<div dir="rtl">

# فصل ۰۸ — یک مدلِ آمادهٔ چندزبانه روی فارسی: ویژگی‌گیری و `fine-tune`

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

فصلِ ۷ مدلی با ۱۱۰ هزار پارامتر ساخت. حالا سراغِ مدلی می‌رویم با **۱۱۷ میلیون پارامتر** که برای حدودِ پنجاه زبان — از جمله فارسی — ساخته شده، و همان کاری را می‌کنیم که در ترمِ ۳ برای تصویر کردیم.

**بیشترِ این فصل `feature extraction` است، یعنی مدل قفل می‌ماند و فقط یک لایهٔ خطی آموزش می‌بیند؛ `fine-tuning` را در بخشِ ۵ با عدد می‌سنجیم.**

**و بالاخره به سؤالِ فصلِ ۱ جواب می‌دهیم:** آنجا `TF-IDF` دقتِ ۱٫۰ گرفت و پرسیدیم پس چرا سراغِ چیزِ پیچیده‌تر برویم. **جوابش در تعدادِ نمونه است** — و با عدد نشانش می‌دهیم.

![یک ابزارِ ساخته‌شده و آزموده که با یک تنظیمِ کوچک به کارِ تازه‌ای می‌آید](/lesson-assets/t4-s08-finetune-text/prompt/01-image-ready-tool.png)

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

- یک مدلِ آمادهٔ چندزبانه را بار کنی و از آن ویژگی بگیری
- `attention_mask` را درست به‌کار ببری
- نتیجه را با خطِ پایه در **اندازه‌های مختلفِ داده** مقایسه کنی
- بگویی مدلِ آماده دقیقاً کجا ارزشش را دارد

## قبل از شروع

**از ترمِ ۳ فصل ۴ و ۵:** `feature extraction` در برابرِ `fine-tuning`، و اندازه‌گیریِ سهمِ آموزشِ قبلی.

**از فصل ۶:** توکنایزر، و اینکه باید همانی باشد که مدل با آن آموزش دیده.

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

> 💡 **نکته:** **زمانِ تخمینی روی CPU: کمتر از یک دقیقه** بعد از دانلودِ مدل. اولین اجرا وزن‌ها را دانلود می‌کند.

## ۱. مدل و توکنایزرش، با هم

</div>

```python
import torch
import torch.nn as nn
from torch.utils.data import TensorDataset, DataLoader
from transformers import AutoTokenizer, AutoModel

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


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


ids_train, mask_train = encode(train_texts)
ids_val, mask_val = encode(val_texts)
ids_test, mask_test = encode(test_texts)
y_train, y_val, y_test = torch.tensor(train_labels), torch.tensor(val_labels), torch.tensor(test_labels)

print("شکل ورودی:", tuple(ids_train.shape))
print("پارامترهای مدل آماده:", sum(p.numel() for p in base.parameters()))
```

<div dir="rtl">

</div>

```text
شکل ورودی: (806, 14)
پارامترهای مدل آماده: 117653760
```

<div dir="rtl">

> ✅ **چک کن:** شکلِ ورودی باید `(806, 14)` باشد — ۸۰۶ جمله و ۱۴ توکن. **اگر عددِ دوم خیلی بزرگ‌تر بود، `padding=True` را با `padding='max_length'` اشتباه گرفته‌ای** و داری ۳۲ توکن پردازش می‌کنی که بیشترش خالی است.

**۱۱۷ میلیون پارامتر — هزار برابرِ مدلِ فصلِ ۷.** و بیشترش در لایهٔ `Embedding` است، چون واژگانش ۲۵۰ هزار توکن دارد (فصلِ ۶).

**و `AutoTokenizer` و `AutoModel` را با یک نام صدا زدیم.** این اجباری است، نه سلیقه: **توکنایزرِ متفاوت یعنی شناسه‌های متفاوت یعنی ورودیِ بی‌معنا** — و هیچ خطایی نمی‌گیری.

آن `padding=True` هم همهٔ جمله‌ها را به طولِ بلندترینشان می‌رساند: ۱۴ توکن.

## ۲. `attention_mask`: چیزی که نباید جا بیفتد

</div>

```python
@torch.no_grad()
def features(model, ids, mask, batch=64):
    model.eval()
    out = []
    for i in range(0, len(ids), batch):
        hidden = model(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(base, ids_train, mask_train)
Fva = features(base, ids_val, mask_val)
Fte = features(base, ids_test, mask_test)
print("شکل ویژگی‌ها:", tuple(Ftr.shape))
```

<div dir="rtl">

</div>

```text
شکل ویژگی‌ها: (806, 384)
```

<div dir="rtl">

**`attention_mask` دو جا لازم است و هر دو حیاتی‌اند:**

- **داخلِ مدل** — تا `attention` به توکن‌های `padding` توجه نکند. بدونش، جمله‌های کوتاه با «هیچ» آلوده می‌شوند.
- **در میانگین‌گیری** — همان `masked mean` فصلِ ۲. بدونش، بردارهای توکن‌های `padding` هم در میانگین می‌آیند و هرچه جمله کوتاه‌تر باشد سهمشان بیشتر است، **و طولِ جمله به یک ویژگیِ ناخواسته تبدیل می‌شود.**

**این دومی رایج‌ترین اشتباهِ خاموشِ کارِ با `transformers` است.** نتیجه‌اش برداری است که نه فقط به معنا، که به طولِ `padding` هم بستگی دارد.

## ۳. یک لایهٔ خطی، روی ویژگی‌های آماده

</div>

```python
@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=40, lr=0.01, batch=32):
    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


scores = [accuracy(fit_head(Ftr, y_train, seed=s), Fva, y_val) for s in (0, 1, 2)]
print("سرِ خطی روی ویژگی‌های آماده، سه seed:", [round(v, 4) for v in scores])
```

<div dir="rtl">

</div>

```text
سرِ خطی روی ویژگی‌های آماده، سه seed: [1.0, 0.9884, 0.9942]
```

<div dir="rtl">

**میانگینِ ۰٫۹۹۴ — و خطِ پایهٔ `TF-IDF` فصلِ ۱ دقیقاً ۱٫۰ بود.**

**یعنی مدلِ ۱۱۷ میلیون پارامتری، با کلِ داده، از یک `TfidfVectorizer` بهتر نشد — حتی کمی بدتر.**

این را همین‌طور صریح می‌نویسیم، چون **دقیقاً همان چیزی است که یک گزارشِ صادقانه باید بگوید.** پس ارزشِ مدلِ آماده کجاست؟

## ۴. جوابِ سؤالِ فصلِ ۱

</div>

```python
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression

for n in (16, 40, 100):
    head = fit_head(Ftr[:n], y_train[:n], epochs=60, batch=16)
    vec = TfidfVectorizer()
    tfidf = LogisticRegression(max_iter=1000).fit(vec.fit_transform(train_texts[:n]), train_labels[:n])
    print(f"  n={n:>3}: مدل آماده={accuracy(head, Fva, y_val):.4f} | "
          f"TF-IDF={tfidf.score(vec.transform(val_texts), val_labels):.4f}")
```

<div dir="rtl">

</div>

```text
  n= 16: مدل آماده=0.6453 | TF-IDF=0.3895
  n= 40: مدل آماده=0.8779 | TF-IDF=0.5291
  n=100: مدل آماده=0.9709 | TF-IDF=0.9535
```

<div dir="rtl">

**و اینجا جوابِ کاملِ سؤال است:**

- **با ۱۶ نمونه: ۰٫۶۵ در برابرِ ۰٫۳۹** — بیست‌وشش واحد اختلاف.
- **با ۴۰ نمونه: ۰٫۸۸ در برابرِ ۰٫۵۳** — سی‌وپنج واحد.
- **با ۱۰۰ نمونه: ۰٫۹۷ در برابرِ ۰٫۹۵** — فقط دو واحد.
- **با ۸۰۶ نمونه: مساوی، و حتی کمی به نفعِ خطِ پایه.**

**ارزشِ مدلِ آماده در کم بودنِ داده است، نه در سقفِ دقت.**

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

> 📏 **اندازه بگیر:** **این منحنی — برتری در دادهٔ کم، همگرایی در دادهٔ زیاد — الگوی عمومیِ `transfer learning` است** و در ترمِ ۳ برای تصویر هم همین را دیدی. **و کاربردِ عملی‌اش این است: قبل از سرمایه‌گذاری روی برچسب‌زدنِ دادهٔ بیشتر، اول با مدلِ آماده و صد نمونه امتحان کن.** اگر همان‌جا به عددِ قابلِ قبول رسیدی، هزاران برچسبِ بعدی شاید لازم نباشند.

## ۵. `feature extraction` یا `fine-tuning`؟

اینجا `backbone` را کاملاً قفل کردیم و فقط یک لایهٔ خطی آموزش دادیم. **گزینهٔ دیگر باز کردنِ لایه‌های بالایی است** — دقیقاً همان جدولِ ترمِ ۳ فصلِ ۵، و همان قاعده‌ها:

</div>

| وضعیت | انتخاب |
|---|---|
| دادهٔ کم، فارسیِ عمومی | **قفلِ کامل** — همین کاری که کردیم |
| دادهٔ متوسط، دامنهٔ تخصصی (پزشکی، حقوقی) | باز کردنِ چند لایهٔ آخر، `lr` خیلی کوچک |
| دادهٔ زیاد و دامنهٔ دور | `fine-tuning` کامل |
| فقط چند ده نمونه | قفلِ کامل، و حتی سراغِ `prompt` رفتن (ترمِ ۵) |

<div dir="rtl">

**و مزیتِ عملیِ قفلِ کامل را دستِ‌کم نگیر:** ویژگی‌ها **یک بار** حساب می‌شوند و بعد هر تعداد آزمایش رویشان تقریباً رایگان است. **همان کاری که در بخشِ ۴ کردیم — سه اندازهٔ داده، در چند ثانیه.** با `fine-tuning` هر کدام یک آموزش بود که باید از کلِ ۱۱۷ میلیون پارامتر رد شود.

**و خودِ `fine-tuning` را هم بسنجیم، چون تا اینجا فقط ویژگی گرفته‌ایم.** کدِ زیر لایهٔ آخرِ مدل را باز می‌کند و با نرخی خیلی کوچک همراهِ سرِ خطی آموزش می‌دهد، و با قفلِ کامل مقایسه می‌کند:

</div>

```python
import copy


class Tuned(nn.Module):
    def __init__(self, backbone):
        super().__init__()
        self.backbone = backbone
        self.head = nn.Linear(384, 4)

    def forward(self, ids, mask):
        hidden = self.backbone(input_ids=ids, attention_mask=mask).last_hidden_state
        m = mask.unsqueeze(-1).float()
        return self.head((hidden * m).sum(1) / m.sum(1))


def fine_tune(n, seed, epochs=20, lr_body=2e-5, lr_head=0.01):
    torch.manual_seed(seed)
    model = Tuned(copy.deepcopy(base))
    for p in model.backbone.parameters():
        p.requires_grad = False
    last = model.backbone.encoder.layer[-1]
    for p in last.parameters():
        p.requires_grad = True
    opt = torch.optim.Adam([{"params": last.parameters(), "lr": lr_body},
                            {"params": model.head.parameters(), "lr": lr_head}])
    loader = DataLoader(TensorDataset(ids_train[:n], mask_train[:n], y_train[:n]), batch_size=16, shuffle=True)
    for _ in range(epochs):
        model.train()
        for xb, mb, yb in loader:
            opt.zero_grad()
            loss_fn(model(xb, mb), yb).backward()
            opt.step()
    model.eval()
    with torch.no_grad():
        right = sum(int((model(ids_val[i:i + 64], mask_val[i:i + 64]).argmax(1) == y_val[i:i + 64]).sum())
                    for i in range(0, len(ids_val), 64))
    return right / len(ids_val)


for n in (40, 100):
    locked = [accuracy(fit_head(Ftr[:n], y_train[:n], seed=s, epochs=60, batch=16), Fva, y_val) for s in (0, 1, 2)]
    tuned = [fine_tune(n, s) for s in (0, 1, 2)]
    print(f"n={n:>3}: قفلِ کامل={[round(v, 4) for v in locked]} | بازکردنِ لایهٔ آخر={[round(v, 4) for v in tuned]}", flush=True)
```

<div dir="rtl">

</div>

```text
n= 40: قفلِ کامل=[0.8779, 0.8721, 0.9012] | بازکردنِ لایهٔ آخر=[0.9012, 0.907, 0.8953]
n=100: قفلِ کامل=[0.9709, 0.9709, 0.9709] | بازکردنِ لایهٔ آخر=[0.9593, 0.9535, 0.9535]
```

<div dir="rtl">

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


> ⚠️ **مواظب باش:** `base.eval()` را جا نینداز. مدل‌های `transformer` پر از `Dropout` هستند، و در حالتِ `train` ویژگی‌هایی که استخراج می‌کنی **بینِ دو اجرا فرق می‌کنند**. جنسش همان تلهٔ `BatchNorm` ترمِ ۳ است، یعنی لایه‌ای که در `train` و `eval` رفتارِ متفاوت دارد. (`LayerNorm` چنین فرقی ندارد.) آن دکوراتورِ `@torch.no_grad()` و `model.eval()` داخلِ `features` برای همین‌اند.

> 🔧 **اگر کار نکرد:** **دانلودِ مدل قطع می‌شود** — سلول را دوباره اجرا کن؛ بخش‌های دانلودشده کش می‌مانند. **`OutOfMemoryError`** — `batch` در `features` را کم کن یا `max_length` را. **دقت خیلی پایین است** — اول `model.eval()` و نامِ مدل و توکنایزر را چک کن. نگرفتنِ میانگینِ ماسک‌دار خطایی نمی‌دهد و روی این داده دقت را هم کم نکرد، ولی بردار را به طولِ `padding` وابسته می‌کند. **`Some weights were not initialized`** هشدارِ عادی است وقتی سرِ طبقه‌بندی نداری؛ ما خودمان سر می‌سازیم.

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| AutoModel | اتو-مدل | بارگذاریِ خودکارِ معماری از روی نام |
| attention_mask | اتنشن ماسک | کدام توکن‌ها واقعی‌اند و کدام `padding` |
| last_hidden_state | لست هیدن استیت | خروجیِ آخرین لایه، یک بردار برای هر توکن |
| pooling | پولینگ | تبدیلِ چند بردارِ توکن به یک بردارِ جمله |
| few-shot | فیو-شات | یادگیری با تعدادِ خیلی کمِ نمونه |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا مدلِ ۱۱۷ میلیون پارامتری با کلِ داده از `TF-IDF` بهتر نشد، ولی با ۱۶ نمونه خیلی بهتر بود؟

**تمرینِ اجباری:** جدولِ بخشِ ۴ را با `n` برابرِ ۸، ۲۴، ۶۰ و ۲۰۰ کامل کن و **منحنیِ هر دو روش را روی یک نمودار بکش.** نقطهٔ تقاطعشان کجاست؟ **آن نقطه، عددِ عملیِ تصمیم‌گیریِ توست:** زیرش مدلِ آماده می‌ارزد، بالایش شاید نه.

**تمرینِ ستاره‌دار ⭐:** به‌جای میانگینِ ماسک‌دار، از بردارِ توکنِ جایگاهِ صفر استفاده کن. (این توکنایزر اسمش را `<s>` گذاشته؛ نقشش همان `[CLS]` است.) **دقت چه می‌شود؟** بعد **میانگین را بدونِ ماسک** بگیر و همان را بسنج. **سه عدد را کنارِ هم بگذار.** و این سؤال را جواب بده: چرا نسخهٔ بدونِ ماسک روی این داده شاید تفاوتِ کمی نشان بدهد، ولی باز هم باید ماسک بگیری؟

## در فصل بعد

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

</div>

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