# فصل ۰۲ — Hugging Face در سه خط

<div dir="rtl">

# فصل ۰۲ — Hugging Face در سه خط

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

فصلِ قبل دیدی که مدلِ خودمان روی بیست جمله عملاً هیچ یاد نگرفت. حالا اولین مدلِ آماده را به‌کار می‌بری — در سه خط کد، بدونِ یک ثانیه آموزش. `transformers` کتابخانه‌ای است که ده‌ها هزار مدلِ آماده را با یک رابطِ واحد در دسترست می‌گذارد، و `pipeline` ساده‌ترین درِ ورودی‌اش است.

![یک قفسهٔ ابزارِ استاندارد با ده‌ها ابزارِ متفاوت که همه دستهٔ یکسانی دارند](/lesson-assets/t4-s02-hf-pipeline/prompt/01-image-shared-handle.png)

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

- با `pipeline` یک مدلِ آماده را در سه خط به‌کار ببری
- چند کارِ متفاوت (احساسات، `NER`، `zero-shot`) را با همان رابط انجام بدهی
- مدلِ مناسبِ زبانِ فارسی را انتخاب کنی
- بگویی چرا اولین اجرا کند است و بعدی‌ها سریع

## قبل از شروع

**از فصل ۱:** `pretrained model`، `inference`، و خطِ پایهٔ ۰٫۳ که باید شکسته شود.

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

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

## ۱. نصب و اولین `pipeline`

</div>

```bash
pip install -q transformers sentencepiece
```

<div dir="rtl">

</div>

```python
# build-notebooks: no-run
from transformers import pipeline

classifier = pipeline("sentiment-analysis")
result = classifier("این لپ‌تاپ عالی بود و خیلی راضی هستم.")
print(result)
```

<div dir="rtl">

</div>

```text-approx
[{'label': 'POSITIVE', 'score': 0.5545071959495544}]
```

<div dir="rtl">

سه خط، و یک مدلِ آموزش‌دیده جواب داد. برچسب درست است، ولی `score` نزدیکِ ۰٫۵ است، یعنی مدل مطمئن نیست. دلیلش را بخشِ ۲ می‌گوید: این مدلِ پیش‌فرض انگلیسی است.

`pipeline("sentiment-analysis")` سه کار را با هم انجام می‌دهد: مدلِ پیش‌فرضِ آن وظیفه را **دانلود** می‌کند، `tokenizer` مناسبش را برمی‌دارد، و هر دو را در یک شیءِ قابلِ صدا زدن می‌بندد.

خروجی همیشه یک `list` از `dict` است — همان ساختارِ آشنای ترمِ ۱ — با `label` و `score`. آن `score` **اطمینانِ مدل** است، نه احتمالِ درست بودن؛ تفاوتش مهم است و در فصلِ ۴ همین ترم بازش می‌کنیم.

> ✅ **چک کن:** خروجی باید یک `list` تک‌عضوی باشد که تویش `label` و `score` هست. اگر خطای دانلود گرفتی، اینترنتِ Colab را چک کن و همان سلول را دوباره اجرا کن — دانلودِ ناقص خودش را با یک خطای عجیبِ فایل نشان می‌دهد، نه با پیامِ «شبکه».

> 💡 **نکته:** اولین اجرا کُند است چون مدل دانلود می‌شود؛ اجراهای بعدی از حافظهٔ محلی می‌خوانند و سریع‌اند. در Colab این حافظه با قطعِ `runtime` پاک می‌شود — پس در هر نشستِ تازه یک بار دیگر دانلود می‌شود. **این را در زمان‌بندی‌ات حساب کن.**

## ۲. یک رابط، وظیفه‌های متفاوت

قدرتِ اصلیِ `pipeline` این است که برای همهٔ وظیفه‌ها **یک شکل** دارد:

</div>

```python
# build-notebooks: no-run
tasks = [
    "sentiment-analysis",
    "ner",
    "fill-mask",
    "zero-shot-classification",
]
for task in tasks:
    print(task)
```

<div dir="rtl">

</div>

```text
sentiment-analysis
ner
fill-mask
zero-shot-classification
```

<div dir="rtl">

هر کدام مدلِ متفاوتی زیرش دارد، ولی الگوی استفاده یکی است: `pipeline(نام وظیفه)` بساز، صدایش بزن، `dict` بگیر.

در آموزش‌های قدیمی‌تر `summarization` و `question-answering` را هم در این فهرست می‌بینی. این دو از `transformers` نسخهٔ ۵ حذف شده‌اند و صدا زدنشان چنین خطایی می‌دهد:

</div>

```python-broken
pipeline("summarization")
```

<div dir="rtl">

</div>

```text
KeyError: 'The task summarization has been removed from transformers. Use the `text-generation` pipeline with a chat model instead. See the migration guide for more details: https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#pipelines'
```

<div dir="rtl">

برای خلاصه‌سازی و پرسش‌وپاسخ سراغِ یک مدلِ زبانی برو. فصل‌های ۳ و ۶ همین را با API انجام می‌دهند. این هم همان درسِ کهنگی است: **نامِ وظیفه‌ها را از مستنداتِ نسخهٔ خودت بردار، نه از یک آموزشِ قدیمی.**

آخری — **`zero-shot-classification`** — جالب‌ترین برای مسئلهٔ ماست: می‌توانی دسته‌ها را **در زمانِ فراخوانی** بدهی، بدونِ اینکه مدل هرگز آن‌ها را دیده باشد.

</div>

```python
# build-notebooks: no-run
zero_shot = pipeline("zero-shot-classification",
                     model="joeddav/xlm-roberta-large-xnli")

result = zero_shot(
    "بلیت هواپیما را دو هفته زودتر بخری ارزان‌تر است.",
    candidate_labels=["سفر", "آشپزی", "برنامه‌نویسی", "سلامت"],
)
print(result["labels"][0], round(result["scores"][0], 3))
```

<div dir="rtl">

</div>

```text-approx
سفر 0.968
```

<div dir="rtl">

**بدونِ یک نمونهٔ آموزشی، موضوع را درست تشخیص داد** — کاری که مدلِ ما با بیست نمونه نتوانست.

آن نامِ `joeddav/xlm-roberta-large-xnli` شکلِ استانداردِ نامِ مدل در Hugging Face است: `<نام کاربر>/<نام مدل>`. حرفِ `xlm` در آن یعنی **چندزبانه** — و همان است که کارش را برای فارسی ممکن می‌کند. آن `sentencepiece` در خطِ نصب هم برای همین مدل است: بدونش `tokenizer` بار نمی‌شود.

> ⚠️ **مواظب باش:** مدلِ **پیش‌فرضِ** بیشترِ وظیفه‌ها انگلیسی‌زبان است. اگر `pipeline("sentiment-analysis")` را بدونِ گفتنِ مدل روی متنِ فارسی صدا بزنی، جواب می‌گیری — ولی جوابی که مدل با حدس‌زدن از روی الگوهای انگلیسی ساخته. **برای فارسی همیشه مدل را صریح مشخص کن** و دنبالِ کلمه‌های `multilingual`، `xlm` یا نامِ فارسی مثلِ `parsbert` بگرد.

## ۳. سنجیدنِ مدلِ آماده در برابرِ خطِ پایه

حالا همان کاری را می‌کنیم که کلِ ترمِ ۳ یادمان داد: **عدد بگیریم.**

در کدِ زیر یک خط سه چیزِ تازه دارد که ارزشِ ایستادن دارند — همان خطی که با `sum(...)` و `zip(...)` تعدادِ درست‌ها را می‌شمارد.

**`zip(a, b)`** دو دنباله را **جفت‌به‌جفت** کنارِ هم می‌گذارد: عنصرِ اولِ `a` با عنصرِ اولِ `b`، دومی با دومی، و همین‌طور تا آخر. اینجا هر پیش‌بینی را کنارِ برچسبِ درستش می‌گذارد.

بعد `p == t` برای هر جفت یک `True` یا `False` می‌دهد، و `sum` رویشان **تعدادِ `True`ها** را می‌شمارد — همان ترفندِ ماسکِ ترمِ ۲ فصلِ ۲ (`True` مثلِ ۱ و `False` مثلِ ۰ جمع می‌شود).

و آن عبارت **بدونِ کروشه** داخلِ `sum(...)` یک `list comprehension` نیست؛ شکلِ تنبلِ آن است که عنصرها را یکی‌یکی می‌سازد و به `sum` می‌دهد، بدونِ اینکه فهرستِ کامل را در حافظه بسازد. برای شمردن دقیقاً همین را می‌خواهی. (اگر کروشه بگذاری — `sum([...])` — نتیجه یکی است، فقط حافظهٔ بیشتری می‌گیرد.)

</div>

```python
# build-notebooks: no-run
import pandas as pd

docs = pd.read_csv("docs.csv")
labels = ["سفر", "آشپزی", "برنامه‌نویسی", "سلامت"]

predictions = []
for text in docs["text"]:
    out = zero_shot(text, candidate_labels=labels)
    predictions.append(out["labels"][0])

correct = sum(p == t for p, t in zip(predictions, docs["topic"]))
print("درست:", correct, "از", len(docs))
print("accuracy مدل آماده:", round(correct / len(docs), 3))
print("accuracy مدل خودمان (فصل ۱):", 0.3)
print("خط پایه:", 0.25)
```

<div dir="rtl">

</div>

```text-approx
درست: 18 از 20
accuracy مدل آماده: 0.9
accuracy مدل خودمان (فصل ۱): 0.3
خط پایه: 0.25
```

<div dir="rtl">

**از ۰٫۳ به ۰٫۹ — و بدونِ یک نمونهٔ آموزشی.**

عددِ دقیقِ تو ممکن است کمی فرق کند (مدل‌ها به‌روز می‌شوند)، ولی جهتش قطعی است: برای مسئله‌ای که ذاتاً «فهمیدنِ زبان» است، مدلِ آماده با فاصلهٔ زیاد برنده است.

> 📏 **اندازه بگیر:** توجه کن که این مقایسه **روی همان بیست جمله** انجام شد، و برای مدلِ آماده این کاملاً منصفانه است چون آن مدل هیچ‌کدام از این جمله‌ها را ندیده — برای او هر بیست تا «دادهٔ آزمون» هستند. ولی برای مدلِ خودمان از `cross-validation` استفاده کردیم، چون آن روی همین جمله‌ها آموزش دیده بود. **مقایسهٔ منصفانه یعنی هر طرف با شرایطِ خودش سنجیده شود، نه با یک قالبِ یکسان.** این ظرافت را خیلی‌ها جا می‌اندازند و نتیجه‌شان بی‌معنا می‌شود.

## ۴. جدولِ مقایسهٔ ترم

ردیفِ دوم را پُر کن:

</div>

| روش | accuracy | هزینه | اینترنت | دادهٔ خروجی‌شده |
|---|---|---|---|---|
| خطِ پایه (حدس) | ۰٫۲۵ | صفر | ندارد | هیچ |
| مدلِ خودمان (TF-IDF) | ۰٫۳ | ناچیز | ندارد | هیچ |
| **مدلِ آمادهٔ محلی** | **~۰٫۹** | دانلودِ بیش از دو گیگابایت | فقط برای دانلود | **هیچ** |
| API (فصلِ ۳) | نامعلوم | سهمیه | همیشه | متنِ تو |

<div dir="rtl">

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

## ۵. یک خطای واقعی: مدلی که وجود ندارد

</div>

```python-broken
pipeline("sentiment-analysis", model="parsbert-sentiment")
```

<div dir="rtl">

</div>

```text
OSError: parsbert-sentiment is not a local folder and is not a valid model
identifier listed on 'https://huggingface.co/models'
```

<div dir="rtl">

نامِ مدل باید **کاملِ مسیرش** باشد: `<نام کاربر>/<نام مدل>`. نامِ کوتاه فقط برای چند مدلِ خیلی معروف کار می‌کند.

> 🔧 **اگر کار نکرد:** قبل از نوشتنِ نامِ مدل، در `huggingface.co/models` جست‌وجویش کن و نام را از همان‌جا **کپی** کن. و اگر خطای دانلود گرفتی، دو دلیلِ رایج دارد: نبودِ اینترنت، یا مدلی که دسترسی‌اش محدود است و باید در سایت قبولش کنی.

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| transformers | ترنسفورمرز | کتابخانهٔ Hugging Face برای مدل‌های آماده |
| pipeline | پایپ‌لاین | رابطِ ساده‌شدهٔ «وظیفه ← مدل ← جواب» |
| zero-shot | زیرو-شات | تشخیصِ دسته‌هایی که مدل هرگز آموزش ندیده |
| zip | زیپ | دو دنباله را جفت‌به‌جفت کنارِ هم می‌گذارد |
| multilingual | مالتی‌لینگوال | مدلی که چند زبان را می‌فهمد، از جمله فارسی |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `zero-shot-classification` می‌تواند دسته‌هایی را تشخیص بدهد که هرگز ندیده؟

**تمرینِ اجباری:** همان بیست جمله را با `zero-shot` طبقه‌بندی کن و `confusion_matrix` بگیر (از ترمِ ۳ فصلِ ۵). کدام موضوع بیشترین اشتباه را دارد؟ جمله‌هایی را که اشتباه شدند با چشمِ خودت بخوان — آیا برای یک انسان هم مبهم‌اند؟

**تمرینِ ستاره‌دار ⭐:** `candidate_labels` را عوض کن و اثرش را اندازه بگیر. یک بار برچسب‌ها را طولانی‌تر و توصیفی‌تر بنویس («توصیه‌های مربوط به سفر و مسافرت» به‌جای «سفر»)، و یک بار برچسبِ پنجمی اضافه کن که هیچ جمله‌ای به آن تعلق ندارد. `accuracy` چطور تغییر می‌کند؟ **این تمرین نشان می‌دهد که خروجیِ یک مدلِ آماده به چیزی که تو می‌نویسی حساس است** — و همان چیزی است که در فصل‌های بعد با نامِ `prompt` جدی‌تر می‌شود.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t4/s02-hf-pipeline (یادستان, Yaadestan)
