# فصل ۰۷ — پروژهٔ نهایی: یک سامانهٔ کامل

<div dir="rtl">

# فصل ۰۷ — پروژهٔ نهایی: یک سامانهٔ کامل

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

**فصلِ آخرِ ژرفا. مفهومِ تازه‌ای ندارد** — هر چه لازم داری در ۵۰ فصلِ قبل ساخته‌ای.

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

و یک عددِ آخر: **پروژه‌ای که فقط «کار می‌کند»، ۳ از ۱۲ می‌گیرد.**

![یک دستگاهِ کامل با برچسبِ بازرسی](/lesson-assets/t6-s07-capstone/prompt/01-image-finished-and-inspected.png)

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

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

## قبل از شروع

**همهٔ شش ترم.** به‌طورِ مشخص: خطِ پایه (سرنخ ترمِ ۳)، `eval` و `bootstrap` (ترمِ ۵ فصلِ ۶)، هزینه (ترمِ ۵ فصلِ ۸)، و `model card` (فصلِ قبل).

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

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/zharfa/term-6-going-further/session-07-capstone.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. سیاههٔ داوری

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

</div>

```python
RUBRIC = [
    ("مسئله در یک جمله", lambda p: len(p.get("problem", "")) > 20),
    ("تصمیمی که این سامانه عوض می‌کند", lambda p: bool(p.get("decision"))),
    ("منبع و اندازهٔ داده", lambda p: bool(p.get("data")) and p.get("n_train", 0) > 0),
    ("مجموعهٔ ارزیابی جدا از آموزش", lambda p: p.get("n_eval", 0) > 0),
    ("خطِ پایه دارد", lambda p: "baseline" in p.get("scores", {})),
    ("مدلِ اصلی از خطِ پایه بهتر است", lambda p: p.get("scores", {}).get("model", 0)
        > p.get("scores", {}).get("baseline", 1)),
    ("تفاوت از نویز بیرون زده", lambda p: bool(p.get("beats_noise"))),
    ("تفکیکِ خطا بر اساسِ دسته", lambda p: len(p.get("per_kind", {})) >= 2),
    ("هزینه شمرده شده", lambda p: p.get("cost_per_call") is not None),
    ("حدِ شناخته‌شده اعلام شده", lambda p: len(p.get("limits", [])) > 0),
    ("سوگیری یا ریسک بررسی شده", lambda p: bool(p.get("risk_check"))),
    ("راهِ اجرای دوباره مستند است", lambda p: bool(p.get("how_to_run"))),
]


def review(project):
    passed = []
    for label, check in RUBRIC:
        try:
            ok = bool(check(project))
        except Exception:
            ok = False
        passed.append((label, ok))
    return passed


half_done = {"problem": "دسته‌بندیِ خودکارِ پیام‌های پشتیبانی به چهار موضوع",
             "data": "پیام‌های واقعیِ تیکت", "n_train": 800, "n_eval": 200,
             "scores": {"model": 0.91}}

for label, ok in review(half_done):
    print(f"  {'✓' if ok else '✗'} {label}")
print(f"\n  {sum(ok for _, ok in review(half_done))} از {len(RUBRIC)}")
```

<div dir="rtl">

</div>

```text
  ✓ مسئله در یک جمله
  ✗ تصمیمی که این سامانه عوض می‌کند
  ✓ منبع و اندازهٔ داده
  ✓ مجموعهٔ ارزیابی جدا از آموزش
  ✗ خطِ پایه دارد
  ✗ مدلِ اصلی از خطِ پایه بهتر است
  ✗ تفاوت از نویز بیرون زده
  ✗ تفکیکِ خطا بر اساسِ دسته
  ✗ هزینه شمرده شده
  ✗ حدِ شناخته‌شده اعلام شده
  ✗ سوگیری یا ریسک بررسی شده
  ✗ راهِ اجرای دوباره مستند است

  3 از 12
```

<div dir="rtl">

**این پروژه دقتِ ۰٫۹۱ دارد و ۳ از ۱۲ می‌گیرد.**

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

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

- **خطِ پایه** — بدونش هیچ عددی معنا ندارد (سرنخ ترمِ ۳، و در هر ترمِ ژرفا تکرار شد).
- **تفاوت از نویز بیرون زده** — بدونش نمی‌دانی بهبود واقعی است یا شانس (ترمِ ۵ فصلِ ۶).
- **حدِ شناخته‌شده** — بدونش سامانه‌ات در دستِ کسی می‌افتد که مرزش را نمی‌داند (ترمِ ۵ فصلِ ۱۰).

## ۲. چرخهٔ کامل، در چهار سلول

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

</div>

```python
import numpy as np
import torch
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.linear_model import LogisticRegression
from transformers import AutoModel, AutoTokenizer

NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = AutoTokenizer.from_pretrained(NAME)
encoder = AutoModel.from_pretrained(NAME)
encoder.eval()


@torch.no_grad()
def vec(texts):
    b = tokenizer(texts, padding=True, truncation=True, max_length=32, return_tensors="pt")
    hidden = encoder(**b).last_hidden_state
    m = b["attention_mask"].unsqueeze(-1).float()
    return torch.nn.functional.normalize((hidden * m).sum(1) / m.sum(1), dim=1).numpy()


N = 60
tfidf = TfidfVectorizer()
baseline = LogisticRegression(max_iter=2000).fit(
    tfidf.fit_transform(train_texts[:N]), train_labels[:N])
model = LogisticRegression(max_iter=2000).fit(vec(train_texts[:N]), train_labels[:N])

base_right = baseline.predict(tfidf.transform(val_texts)) == np.array(val_labels)
model_right = model.predict(vec(val_texts)) == np.array(val_labels)
print("خطِ پایه (TF-IDF):", f"{base_right.mean():.4f}")
print("مدلِ آماده       :", f"{model_right.mean():.4f}")
```

<div dir="rtl">

</div>

```text
خطِ پایه (TF-IDF): 0.8081
مدلِ آماده       : 0.8663
```

<div dir="rtl">

> ✅ **چک کن:** خطِ پایه باید عددِ **آبرومندی** بگیرد، نه صفر. اگر `TF-IDF` نزدیکِ ۰٫۲۵ درآمد (یعنی شانس با چهار کلاس)، معمولاً برچسب‌ها با متن‌ها جفت نیستند، مثلاً یکی را جدا به‌هم ریخته‌ای. **خطِ پایهٔ ضعیف، مدلت را بی‌دلیل خوب نشان می‌دهد.** و اگر `TfidfVectorizer` را روی اعتبارسنجی دوباره `fit` کنی، عددِ بدی نمی‌بینی، خطا می‌گیری: همان خطای آخرِ فصل.

**۰٫۸۱ در برابرِ ۰٫۸۷.** و اینجا جایی است که بیشترِ گزارش‌ها تمام می‌شوند: «مدلِ ما شش واحد بهتر است».

**ولی شش واحد در چه نمونه‌ای؟ و آیا با شصت نمونهٔ دیگر هم همین می‌شد؟**

## ۳. آیا اختلاف واقعی است؟

</div>

```python
import random


def bootstrap_gap(a, b, rounds=2000, seed=0):
    rng = random.Random(seed)
    n = len(a)
    gaps = []
    for _ in range(rounds):
        idx = [rng.randrange(n) for _ in range(n)]
        gaps.append(np.mean([a[i] for i in idx]) - np.mean([b[i] for i in idx]))
    gaps.sort()
    return gaps[int(0.05 * rounds)], gaps[int(0.95 * rounds)]


low, high = bootstrap_gap(model_right, base_right)
print(f"اختلافِ دقت: {model_right.mean() - base_right.mean():+.4f}")
print(f"بازهٔ ۹۰٪ اختلاف: {low:+.4f} تا {high:+.4f}")
print("از نویز بیرون زده؟", low > 0)
```

<div dir="rtl">

</div>

```text
اختلافِ دقت: +0.0581
بازهٔ ۹۰٪ اختلاف: +0.0058 تا +0.1163
از نویز بیرون زده؟ True
```

<div dir="rtl">

**بله — ولی به‌زحمت. کفِ بازه ۰٫۰۰۶ است، یعنی تقریباً چسبیده به صفر.** آن‌قدر چسبیده که با `seed=2` همین `bootstrap` کف را دقیقاً صفر می‌دهد و جوابِ «بیرون زده؟» عوض می‌شود. **و این بازه فقط مجموعهٔ اعتبارسنجی را بازنمونه‌گیری می‌کند.** سؤالِ «با شصت نمونهٔ دیگر چه؟» را جواب نمی‌دهد.

> 📏 **اندازه بگیر:** **و به یک ریزه‌کاریِ مهم دقت کن: ما اختلاف را روی همان نمونه‌های بازنمونه‌شده حساب کردیم، نه دو بازهٔ جدا.** این «آزمونِ جفت‌شده» است و **خیلی حساس‌تر است**، چون نویزِ مشترکِ دو سامانه (سختیِ خودِ نمونه‌ها) حذف می‌شود. اگر دو بازهٔ اطمینانِ جدا می‌کشیدی، روی هم می‌افتادند و نتیجه می‌گرفتی «تفاوتی نیست» — **که غلط بود.** **هر وقت دو سامانه را روی یک مجموعه می‌سنجی، جفت‌شده حساب کن.**

## ۴. کجا خراب است

</div>

```python
per_kind = {}
for text, right in zip(val_texts, model_right):
    bucket = "کوتاه" if len(text.split()) <= 6 else "بلند"
    hit, total = per_kind.get(bucket, (0, 0))
    per_kind[bucket] = (hit + int(right), total + 1)
for bucket, (hit, total) in sorted(per_kind.items()):
    print(f"  {bucket:<6} {hit}/{total} = {hit / total:.4f}")
```

<div dir="rtl">

</div>

```text
  بلند   93/106 = 0.8774
  کوتاه  56/66 = 0.8485
```

<div dir="rtl">

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

</div>

```python
short_hits = model_right[[len(t.split()) <= 6 for t in val_texts]]
long_hits = model_right[[len(t.split()) > 6 for t in val_texts]]
rng = random.Random(0)
gaps = []
for _ in range(2000):
    a = [short_hits[rng.randrange(len(short_hits))] for _ in short_hits]
    b = [long_hits[rng.randrange(len(long_hits))] for _ in long_hits]
    gaps.append(np.mean(b) - np.mean(a))
gaps.sort()
print(f"بلند منهای کوتاه: {long_hits.mean() - short_hits.mean():+.4f}")
print(f"بازهٔ ۹۰٪: {gaps[100]:+.4f} تا {gaps[1900]:+.4f}")
```

<div dir="rtl">

</div>

```text
بلند منهای کوتاه: +0.0289
بازهٔ ۹۰٪: -0.0600 تا +0.1178
```

<div dir="rtl">

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

**و تفکیک را با چیزی بکن که به مسئله‌ات مربوط است**، نه با چیزی که راحت است: طولِ متن، زبان، منبعِ داده، کاربرِ تازه در برابرِ قدیمی، ساعتِ روز. **هر بُعدی که ممکن است رفتار در آن فرق کند، یک ستونِ گزارش است.**

## ۵. و حالا گزارشِ کامل

</div>

```python
project = {
    "problem": "دسته‌بندیِ خودکارِ پیام‌های فارسی به چهار موضوع، با شصت نمونهٔ برچسب‌خورده",
    "decision": "پیام به صفِ کدام تیم برود",
    "data": "پیکرهٔ ساختگیِ ترمِ ۴", "n_train": N, "n_eval": len(val_texts),
    "scores": {"baseline": round(float(base_right.mean()), 4),
               "model": round(float(model_right.mean()), 4)},
    "beats_noise": bool(low > 0),
    "per_kind": {k: round(h / t, 4) for k, (h, t) in per_kind.items()},
    "cost_per_call": "۳۲ توکن ورودی، یک forward از مدلِ ۱۱۷ میلیونی",
    "limits": ["فقط چهار موضوع", "روی متنِ محاوره‌ای سنجیده نشده"],
    "risk_check": "سوگیریِ جنسیتیِ مدلِ پایه در فصلِ ۶ اندازه گرفته شد",
    "how_to_run": "نوت‌بوکِ همین فصل، سلول‌ها به‌ترتیب",
}

result = review(project)
for label, ok in result:
    print(f"  {'✓' if ok else '✗'} {label}")
print(f"\n  {sum(ok for _, ok in result)} از {len(RUBRIC)}")
```

<div dir="rtl">

</div>

```text
  ✓ مسئله در یک جمله
  ✓ تصمیمی که این سامانه عوض می‌کند
  ✓ منبع و اندازهٔ داده
  ✓ مجموعهٔ ارزیابی جدا از آموزش
  ✓ خطِ پایه دارد
  ✓ مدلِ اصلی از خطِ پایه بهتر است
  ✓ تفاوت از نویز بیرون زده
  ✓ تفکیکِ خطا بر اساسِ دسته
  ✓ هزینه شمرده شده
  ✓ حدِ شناخته‌شده اعلام شده
  ✓ سوگیری یا ریسک بررسی شده
  ✓ راهِ اجرای دوباره مستند است

  12 از 12
```

<div dir="rtl">

**همان مدل، همان دقتِ ۰٫۸۷ — و این بار ۱۲ از ۱۲.**

**تفاوت در مدل نبود، در گزارش بود.** و آن گزارش چیزی است که به کسی اجازه می‌دهد **رویش تصمیم بگیرد** — که تمامِ هدفِ کار است.

## ۶. پروژهٔ خودت

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

</div>

| ایده | چه چیزی از این دوره لازم دارد |
|---|---|
| دستیارِ پرسش‌وپاسخ روی مستنداتِ خودت | ترمِ ۵ کامل — `RAG`، `eval`، ایمنی |
| دسته‌بندِ نظرها یا تیکت‌های فارسی | ترمِ ۴ فصلِ ۸، و `LoRA` فصلِ ۱ همین ترم |
| خلاصه‌سازِ متنِ فارسی با ارزیابیِ انسانی | ترمِ ۵ فصلِ ۶ — چون متریکِ خودکار اینجا ضعیف است |
| جست‌وجوی معناییِ آرشیوِ شخصی | ترمِ ۴ فصلِ ۲ و ترمِ ۵ فصلِ ۴ |
| تشخیصِ تصویر روی دادهٔ خودت | ترمِ ۳ کامل، و فصلِ ۳ همین ترم |
| ابزارِ کمکی برای یک کارِ تکراریِ خودت | هر چه لازم شد — **و بهترین انتخاب همین است** |

<div dir="rtl">

**و قواعدی که پروژه را از یک تمرین به یک کارِ واقعی تبدیل می‌کنند:**

- **از کوچک‌ترین نسخهٔ کارآمد شروع کن.** بیست نمونه، یک خطِ پایه، یک عدد. **قبل از هر چیزِ پیچیده‌ای.**
- **دادهٔ ارزیابی را همان روزِ اول جدا کن و تا آخر دست نزن.**
- **هر تغییری را با یک عدد توجیه کن.** «حس می‌کنم بهتر شد» قبول نیست — این را در شش ترم بارها دیدی.
- **نتایجِ منفی را هم بنویس.** در ترمِ ۵ پنج تکنیکِ معروف را امتحان کردیم و کار نکردند؛ **آن بخش‌ها به‌اندازهٔ بخش‌های موفق ارزش داشتند.**
- **و تمامش کن.** پروژهٔ کوچکِ تمام‌شده از پروژهٔ بزرگِ نیمه‌کاره بی‌نهایت بیشتر می‌ارزد.

## ۷. از اینجا به کجا

</div>

| اگر این را دوست داشتی | مسیرِ بعدی |
|---|---|
| ترمِ ۴ — ساختنِ `transformer` | معماری‌های تازه، آموزشِ مدل از صفر، بهینه‌سازیِ آموزش |
| ترمِ ۵ — سامانه‌سازی دورِ مدل | مهندسیِ داده، پایگاه دادهٔ برداری، پایشِ سامانه‌های زنده |
| ترمِ ۵ فصلِ ۶ — `eval` | ارزیابی و سنجش، طراحیِ آزمایش، آمارِ کاربردی |
| فصلِ ۲ و ۵ همین ترم | اجرای کارآمد، کرنل‌نویسی، سرو در مقیاس |
| فصلِ ۶ — مسئولیت | ایمنی و سیاست‌گذاریِ هوش مصنوعی، حریمِ خصوصی |
| ریاضیاتش | [ریشه](/courses/risheh) — به‌ویژه ترمِ ۷ و ۸ |
| فهمِ اجتماعی‌اش | [هم‌هوش](/courses/hamhoosh) |

<div dir="rtl">

**و یک توصیهٔ عملی برای ادامه: مقاله بخوان، ولی کد بزن.** یک مقالهٔ خوانده‌شده و پیاده‌نشده، چند روز بعد از یادت می‌رود؛ **یک ایدهٔ پیاده‌شده — حتی بد و ناقص — می‌ماند.** همان کاری که در این دوره با `attention` و `LoRA` و `diffusion` کردی.

## ۸. و آخر

**در ابتدای این دوره `model.fit()` را صدا می‌زدی و کار می‌کرد.**

حالا می‌دانی داخلِ آن پرانتز چه می‌گذرد — گرادیان، `attention`، `tokenizer` — و مهم‌تر از آن، **می‌دانی چطور بفهمی که واقعاً کار کرده**: با خطِ پایه، با مجموعهٔ طلایی، با بازهٔ اطمینان، و با اعتراف به آنچه نمی‌داند.

**بیشترِ آنچه در این شش ترم یاد گرفتی، تکنیک نبود. انضباط بود:**

- **اندازه بگیر، حدس نزن.**
- **خطِ پایه بگذار، وگرنه هیچ عددی معنا ندارد.**
- **وقتی چیزی کار نکرد، بنویسش.**
- **و حدِ کارت را خودت اعلام کن، قبل از اینکه کسی کشفش کند.**

**این‌ها کهنه نمی‌شوند.** مدل‌ها عوض می‌شوند، کتابخانه‌ها عوض می‌شوند، و این چهار جمله سرِ جایشان می‌مانند.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| rubric | روبریک | معیارِ داوریِ از پیش نوشته‌شده |
| paired test | پیرد تست | مقایسهٔ دو سامانه روی **همان** نمونه‌ها |
| slice analysis | اسلایس انالیسیس | تفکیکِ نتیجه بر اساسِ زیرگروه‌های داده |
| definition of done | دفینیشن آف دان | فهرستِ روشنِ اینکه «تمام شد» یعنی چه |

<div dir="rtl">

> 🔧 **اگر کار نکرد:** سه خطای واقعیِ همین چرخه، و هر سه وقتی می‌آیند که `N` را عوض کنی. **`ValueError: Found input variables with inconsistent numbers of samples: [60, 806]`** یعنی ویژگی‌ها را از `N` نمونه ساخته‌ای و برچسب‌ها را از کلِ دادهٔ آموزش — **`[:N]` را در هر دو طرف بگذار.** **`NotFittedError`** با پیامی دربارهٔ `fit` نشده بودن، یعنی `transform` را قبل از `fit_transform` صدا زده‌ای. و **`ValueError: X has 82 features, but LogisticRegression is expecting 76 features as input`** یعنی بعد از آموزشِ مدل، `TfidfVectorizer` را دوباره `fit` کرده‌ای و واژگانش عوض شده — **`fit` فقط یک بار، روی دادهٔ آموزش.** **هر سه‌تایشان یک ریشه دارند: دادهٔ آموزش و ارزیابی باید از یک قرارداد پیروی کنند.**

> 🤖 **از دستیارت بپرس:** «پروژهٔ من این است: [توضیحش را بنویس]. با این سیاههٔ دوازده‌بندی داوری‌اش کن و بگو کدام بندها را رد می‌کنم.» **و بعد جوابش را باور نکن تا خودت هر بند را با عدد بررسی کنی** — همان درسِ ترمِ ۵ فصلِ ۶ دربارهٔ داورِ مدلی.

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا پروژه‌ای با دقتِ ۰٫۹۱ ممکن است ۳ از ۱۲ بگیرد؟

**تمرینِ اجباری:** `N` را ۲۰ و ۶۰ و ۲۰۰ بگذار و برای هر کدام **هر چهار سلولِ بخشِ ۲ تا ۵ را تکرار کن**. **در کدام اندازهٔ داده، اختلافِ مدل و خطِ پایه از نویز بیرون می‌زند و در کدام نه؟** و جوابِ نهایی: **اگر فقط بیست نمونه داشتی، صادقانه‌ترین جمله‌ای که می‌توانستی در گزارش بنویسی چه بود؟**

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

## در فصل بعد

**فصلِ بعدی وجود ندارد.** ژرفا اینجا تمام می‌شود.

آنچه از اینجا به بعد می‌سازی، دیگر تمرین نیست.

</div>

---
Source: https://yaadestan.com/courses/zharfa/lessons/t6/s07-capstone (یادستان, Yaadestan)
