# فصل ۰۸ — پروژهٔ پایانی: از سؤال تا اپِ منتشرشده

<div dir="rtl">

# فصل ۰۸ — پروژهٔ پایانی: از سؤال تا اپِ منتشرشده

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

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

![یک نقشهٔ مسیر با هشت ایستگاه که از یک علامتِ سؤال شروع می‌شود و به یک تابلوی عمومی می‌رسد](/lesson-assets/t5-s08-capstone/prompt/01-image-question-to-public.png)

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

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

## قبل از شروع

**از کلِ دوره.** این فصل هیچ چیزِ تازه‌ای معرفی نمی‌کند و همه‌چیزش قبلاً آمده.

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

## ۱. ترتیب، و چرا نباید عوضش کنی

</div>

| # | قدم | اگر جا بیفتد |
|---|---|---|
| ۱ | سؤال را دقیق بنویس | تا آخر نمی‌دانی چه چیزی را بهینه می‌کنی |
| ۲ | دروازهٔ داده | دادهٔ خراب بی‌صدا وارد می‌شود |
| ۳ | تقسیم | نشتی |
| ۴ | خطِ پایه | هیچ عددی معنا ندارد |
| ۵ | چند نامزد با `cross-validation` | مدلِ اول را با بهترین اشتباه می‌گیری |
| ۶ | یک ارزیابیِ نهایی روی `test` | عددت خوش‌بینانه است |
| ۷ | بازه و زیرگروه | یک عدد، همه‌چیز را پنهان می‌کند |
| ۸ | شناسنامه و انتشار | شش ماه بعد هیچ‌کس نمی‌داند این چیست |

<div dir="rtl">

**سؤالِ این پروژه:** برای یک لپ‌تاپِ دستِ‌دوم با سال، حافظه، برند و شهرِ مشخص، قیمتِ منصفانهٔ آگهی چقدر است؟ کاربردش کمک به فروشنده برای قیمت‌گذاری است، و **تصمیمِ نهایی با انسان است، نه با مدل**.

## ۲. قدمِ ۲: دروازهٔ داده

</div>

```python
import hashlib
import json
from pathlib import Path

import numpy as np
import pandas as pd
from pandas.api.types import is_numeric_dtype

FEATURES = ["year", "ram_gb", "brand", "city"]
TARGET = "price"
NUMERIC = ["year", "ram_gb", "price"]


def check_data(frame):
    problems = [f"ستون {c} نیست" for c in FEATURES + [TARGET] if c not in frame.columns]
    if problems:
        return problems
    problems = [f"ستون {c} عددی نیست" for c in NUMERIC if not is_numeric_dtype(frame[c])]
    if problems:
        return problems
    if frame[TARGET].isna().any():
        problems.append("قیمت خالی دارد")
    if frame[TARGET].min() <= 0:
        problems.append("قیمت غیرمثبت دارد")
    if frame.duplicated().any():
        problems.append("ردیف تکراری دارد")
    return problems


def fingerprint(frame):
    digest = hashlib.sha256(pd.util.hash_pandas_object(frame, index=True).values.tobytes())
    return digest.hexdigest()[:16]


df = pd.read_csv("laptops_clean.csv")
problems = check_data(df)

print("مشکلات داده:", problems)
print("اثر انگشت  :", fingerprint(df))
print("اندازه     :", df.shape)
assert not problems, "بدون دادهٔ سالم جلو نرو"
```

<div dir="rtl">

</div>

```text
مشکلات داده: []
اثر انگشت  : 833b0ebd03779d4f
اندازه     : (238, 5)
```

<div dir="rtl">

آن `assert` در انتها عمدی است: **اگر داده سالم نیست، ادامه دادن ضرر دارد، نه فایده.** بهتر است همین‌جا بایستد تا اینکه سی سلول بعد یک عددِ بی‌معنا بدهد.

## ۳. قدمِ ۳ تا ۵: تقسیم، خطِ پایه، نامزدها

</div>

```python
from sklearn.compose import ColumnTransformer
from sklearn.dummy import DummyRegressor
from sklearn.ensemble import RandomForestRegressor
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.model_selection import KFold, cross_val_score, train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

X, y = df[FEATURES], df[TARGET]
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=11)

prepare = ColumnTransformer([
    ("num", Pipeline([("fill", SimpleImputer(strategy="median")),
                      ("scale", StandardScaler())]), ["year", "ram_gb"]),
    ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
])

folds = KFold(5, shuffle=True, random_state=0)
CANDIDATES = {
    "خط پایه (میانه)": DummyRegressor(strategy="median"),
    "خطی (Ridge)": Ridge(alpha=0.1),
    "جنگل": RandomForestRegressor(n_estimators=200, random_state=0),
}

for name in CANDIDATES:
    pipe = Pipeline([("prepare", prepare), ("model", CANDIDATES[name])])
    cv = -cross_val_score(pipe, X_train, y_train, cv=folds, scoring="neg_mean_absolute_error")
    print(f"{name}: {round(cv.mean())} ± {round(cv.std())}")
```

<div dir="rtl">

</div>

```text
خط پایه (میانه): 7981053 ± 859462
خطی (Ridge): 1518561 ± 199766
جنگل: 2118368 ± 207774
```

<div dir="rtl">

مدلِ خطی برنده است و فاصله‌اش از جنگل (۶۰۰ هزار) از نوسانِ هر دو بیشتر است — پس تفاوت واقعی است. **و همهٔ این مقایسه روی `X_train` انجام شد؛ دادهٔ آزمون هنوز دست‌نخورده است.**

## ۴. قدمِ ۶: آن یک بارِ نهایی

</div>

```python
final = Pipeline([("prepare", prepare), ("model", Ridge(alpha=0.1))]).fit(X_train, y_train)
baseline = DummyRegressor(strategy="median").fit(X_train, y_train)

test_mae = mean_absolute_error(y_test, final.predict(X_test))
baseline_mae = mean_absolute_error(y_test, baseline.predict(X_test))

print("MAE مدل روی آزمون:", round(test_mae))
print("MAE خط پایه      :", round(baseline_mae))
print("بهبود            :", round((1 - test_mae / baseline_mae) * 100, 1), "درصد")
```

<div dir="rtl">

</div>

```text
MAE مدل روی آزمون: 1607631
MAE خط پایه      : 8681250
بهبود            : 81.5 درصد
```

<div dir="rtl">

## ۵. قدمِ ۷: و اینجا نتیجهٔ ناخوشایند

</div>

```python
spread = []
for seed in range(5):
    a_train, a_test, b_train, b_test = train_test_split(X, y, test_size=0.2, random_state=seed)
    m = Pipeline([("prepare", prepare), ("model", Ridge(alpha=0.1))]).fit(a_train, b_train)
    spread.append(mean_absolute_error(b_test, m.predict(a_test)))

spread = np.array(spread)
print("بازهٔ MAE روی ۵ تقسیم:", round(spread.min()), "تا", round(spread.max()))
print("میانه                :", round(float(np.median(spread))))
```

<div dir="rtl">

</div>

```text
بازهٔ MAE روی ۵ تقسیم: 1100034 تا 1521409
میانه                : 1390108
```

<div dir="rtl">

**عددی که در بخشِ ۴ گزارش کردیم — ۱٬۶۰۷٬۶۳۱ — از کلِ این بازه بیرون است.**

هیچ اشتباهی نکردیم: تقسیم قبل از همه‌چیز انجام شد، `test` فقط یک بار دیده شد، نشتی نبود. **فقط `random_state=11` تصادفاً مجموعهٔ آزمونِ سخت‌تری ساخت.**

**و این دقیقاً همان درسی است که کلِ دوره به آن ختم می‌شود:** یک عدد از یک تقسیم، حتی وقتی همه‌چیز درست انجام شده، فقط **یک نمونه** از عددهای ممکن است. **صادقانه‌ترین گزارش این است: «MAE بینِ ۱٫۱ و ۱٫۶ میلیون، میانه حدودِ ۱٫۴».**

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

</div>

```python
report = X_test.copy()
report["actual"] = y_test
report["abs_error"] = (final.predict(X_test) - y_test).abs()
report["rel_error"] = report["abs_error"] / report["actual"] * 100

by_brand = report.groupby("brand").agg(
    n=("abs_error", "size"),
    rel_pct=("rel_error", "mean"),
).round(1).sort_values("rel_pct", ascending=False)

print(by_brand.to_string())
```

<div dir="rtl">

</div>

```text
        n  rel_pct
brand
اچ پی   7     13.2
لنوو    7     11.3
دل     15     11.2
ایسوس  12      4.6
اپل     7      1.4
```

<div dir="rtl">

**«اچ پی» با ۱۳٫۲ درصد بدترین است و «اپل» با ۱٫۴ درصد بهترین** — نزدیک به ده برابر تفاوت. هیچ‌کدام از این دو گروه در عددِ کلی دیده نمی‌شدند.

> ✅ **چک کن:** بدترین زیرگروهت اینجا **اچ پی** درآمد، همان که در فصلِ ۷ با تقسیمِ دیگری هم بدترین بود. وسوسه می‌شوی بگویی چون دو بار تکرار شد، واقعی است. ولی این گروه‌ها در هر آزمون چند نمونه بیشتر ندارند، و دو تقسیم برای چنین گروه‌هایی کم است. **همین را با ۳۰ تقسیم سنجیدیم:** اچ پی فقط ۸ بار بدترین بود و لنوو ۱۴ بار. یافته‌ای که فقط یک یا دو بار دیده شده، هنوز یک حدس است، پس قبل از اینکه واردِ کارتِ مدل شود، روی تقسیم‌های بیشتری بسنجش.

## ۶. قدمِ ۸: شناسنامه و انتشار

</div>

```python
import joblib

card = {
    "data_fingerprint": fingerprint(df),
    "rows": int(len(df)),
    "features": FEATURES,
    "model": "Ridge(alpha=0.1) در Pipeline",
    "test_mae": round(test_mae),
    "baseline_mae": round(baseline_mae),
    "mae_range_over_5_splits": [round(spread.min()), round(spread.max())],
    "worst_subgroup": by_brand["rel_pct"].idxmax(),
}

joblib.dump(final, "capstone_model.joblib")
Path("model_card.json").write_text(
    json.dumps(card, ensure_ascii=False, indent=2), encoding="utf-8"
)

print(json.dumps(card, ensure_ascii=False, indent=2))
```

<div dir="rtl">

</div>

```text
{
  "data_fingerprint": "833b0ebd03779d4f",
  "rows": 238,
  "features": [
    "year",
    "ram_gb",
    "brand",
    "city"
  ],
  "model": "Ridge(alpha=0.1) در Pipeline",
  "test_mae": 1607631,
  "baseline_mae": 8681250,
  "mae_range_over_5_splits": [
    1100034,
    1521409
  ],
  "worst_subgroup": "اچ پی"
}
```

<div dir="rtl">

یک نکتهٔ کوچک در ساختنِ کارت: `by_brand["rel_pct"].idxmax()` را با `.max()` اشتباه نگیر. **`max` بزرگ‌ترین *مقدار* را می‌دهد و `idxmax` *برچسبِ* ردیفی را که آن مقدار در آن است.** اینجا برچسب همان نامِ برند است — و آن چیزی است که در کارت می‌خواهیم، نه خودِ عدد.

**این فایل ماشین‌خوان است و همین ارزشش را چند برابر می‌کند:** یک برنامهٔ دیگر می‌تواند بخواندش و مثلاً هشدار بدهد که اثرِ انگشتِ دادهٔ امروز با آنچه مدل روی آن آموزش دیده فرق دارد. `ensure_ascii=False` هم لازم است، وگرنه «اچ پی» به‌صورتِ کدهای `\u06...` ذخیره می‌شود و هیچ انسانی نمی‌تواند فایل را بخواند.

## ۷. چک‌لیستِ قبل از انتشار

</div>

| | |
|---|---|
| ☐ | نوت‌بوک با `Restart and run all` از بالا تا پایین اجرا می‌شود |
| ☐ | همهٔ `random_state`ها گذاشته شده‌اند |
| ☐ | `requirements.txt` با نسخهٔ قفل‌شده |
| ☐ | تست‌ها سبزند و **دستِ‌کم یکی‌شان را عمداً شکسته‌ای** |
| ☐ | هیچ کلید، رمز یا دادهٔ شخصی در مخزن نیست |
| ☐ | خروجی‌های نوت‌بوک قبل از `commit` پاک شده‌اند |
| ☐ | ورودی‌های رابط محدودند و پیامِ خطا فارسی و روشن است |
| ☐ | کارتِ مدل نوشته شده و **بخشِ «به‌کارش نبر برای» را دارد** |
| ☐ | عدد به‌صورتِ بازه گزارش شده، نه یک رقمِ تنها |
| ☐ | تاریخِ آموزش کنارِ مدل ثبت شده |

<div dir="rtl">

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

## پنج ترم، در سه جمله

</div>

| ترم | چه چیزی ساختی | چه چیزی فهمیدی |
|---|---|---|
| ۱ | اولین برنامه‌های پایتون | نوت‌بوک دروغ می‌گوید اگر ترتیب را رها کنی |
| ۲ | پاک‌سازی و کاوشِ داده | داده همیشه کثیف است و **اول باید ببینی‌اش** |
| ۳ | مدل‌های یادگیری ماشین | بدونِ خطِ پایه هیچ عددی معنا ندارد |
| ۴ | ابزارهای مبتنی بر مدلِ آماده | خروجیِ غیرقطعی باید سنجیده شود، نه باور |
| ۵ | یک اپِ منتشرشده | عددی که بازه ندارد، نصفِ حقیقت است |

<div dir="rtl">

سه قاعده‌ای که از فصلِ اولِ ترمِ ۱ تا همین‌جا تکرار شدند و از هر کتابخانه‌ای که یاد گرفتی دوام بیشتری دارند:

- **اول داده را ببین.**
- **اول یک خطِ پایه بساز.**
- **روی چیزی که مدل ندیده امتحان کن.**

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

## تمرین‌ها

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

**تمرینِ ستاره‌دار ⭐:** پروژه‌ات را به کسی بده که موضوع را می‌شناسد ولی برنامه‌نویسی بلد نیست، و از او بخواه پیش‌بینی‌ها را برای ده مورد که خودش جوابشان را می‌داند بسنجد. **جایی که او مدل را غلط می‌داند و مدل مطمئن است، مهم‌ترین چیزی است که پیدا خواهی کرد** — چون دقیقاً همان‌جاست که مدلت در دنیای واقعی هزینه می‌سازد، و هیچ متریکی نشانت نمی‌داد.

## در فصل بعد

سرنخ تمام شد. اگر می‌خواهی جلوتر بروی، **[ژرفا](/courses/zharfa)** از همین‌جا شروع می‌شود: `PyTorch` از پایه، شبکه‌های عصبی، بینایی ماشین، `transformer`، و مهندسیِ سامانه‌های زبانی — با همان سه قاعده و همان اصرار بر اندازه‌گیری.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t5/s08-capstone (یادستان, Yaadestan)
