# فصل ۱۲ — پروژه: از سؤال تا مدلِ ارزیابی‌شده

<div dir="rtl">

# فصل ۱۲ — پروژه: از سؤال تا مدلِ ارزیابی‌شده

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

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

![یک تختهٔ کارِ ترتیبی با هفت ایستگاه که از یک سؤال شروع می‌شود و به یک برگهٔ گزارشِ مهرخورده می‌رسد](/lesson-assets/t3-s12-project-end-to-end/prompt/01-image-ml-workflow.png)

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

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

## قبل از شروع

**از کلِ ترمِ ۳:** خطِ پایه، تقسیم، `Pipeline`، `cross-validation`، `GridSearchCV`، تحلیلِ خطا.

**از ترمِ ۲:** پاک‌سازی و گزارش‌نویسی.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-3-machine-learning/session-12-project-end-to-end.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. ترتیبِ درست

قبل از هر کدی، ترتیب را حفظ کن. **هر جابه‌جایی در این هفت قدم یا نشتی می‌سازد یا وقت هدر می‌دهد:**

1. **سؤال را دقیق بنویس** — چه چیزی، برای چه کسی، با چه ورودی‌ای.
2. **تقسیم کن** — قبل از هر نگاهِ جدی به داده.
3. **خطِ پایه بگیر** — پنج دقیقه، و مرجعِ همهٔ عددهای بعدی.
4. **چند نامزد را با `cross-validation` مقایسه کن** — روی دادهٔ آموزش.
5. **بهترین را تنظیم کن** — باز هم روی آموزش.
6. **یک بار روی `test` بسنج** — و فقط یک بار.
7. **تحلیلِ خطا و گزارش.**

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

## ۲. قدمِ ۲ و ۳: تقسیم و خطِ پایه

</div>

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

df = pd.read_csv("laptops_clean.csv")
X = df[["year", "ram_gb", "brand", "city"]]
y = df["price"]

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=7)

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

print("آموزش:", X_train.shape, "| آزمون:", X_test.shape)
```

<div dir="rtl">

</div>

```text
آموزش: (190, 4) | آزمون: (48, 4)
```

<div dir="rtl">

توجه کن `random_state=7` است، نه ۴۲. **عمدی است:** اگر همان تقسیمی را به‌کار می‌بردیم که در یازده فصلِ گذشته بارها نگاهش کردیم، عملاً به آن `test` هم overfit کرده بودیم — همان نشتیِ انتخابی که فصلِ ۹ توضیح داد، فقط در مقیاسِ کلِ ترم.

## ۳. قدمِ ۴: مقایسهٔ نامزدها

</div>

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

for name in candidates:
    pipe = Pipeline([("prepare", preprocess), ("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
خط پایه (میانه): 8017895 ± 313379
خطی (Ridge): 1590461 ± 140142
جنگل: 2116797 ± 151524
```

<div dir="rtl">

مدلِ خطی برنده است و فاصله‌اش از جنگل (۵۲۶ هزار) خیلی بیشتر از نوسانِ هر دو است — پس این تفاوت **واقعی** است، نه تصادفِ تقسیم.

توجه کن این مقایسه روی `X_train` انجام شد. دادهٔ آزمون هنوز دست‌نخورده است.

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

## ۴. قدمِ ۵: تنظیم

</div>

```python
tuned = GridSearchCV(
    Pipeline([("prepare", preprocess), ("model", Ridge())]),
    {"model__alpha": [0.01, 0.1, 1, 10, 100]},
    cv=folds,
    scoring="neg_mean_absolute_error",
).fit(X_train, y_train)

print("بهترین alpha:", tuned.best_params_)
print("MAE در cross-validation:", round(-tuned.best_score_))
```

<div dir="rtl">

</div>

```text
بهترین alpha: {'model__alpha': 0.1}
MAE در cross-validation: 1554566
```

<div dir="rtl">

تنظیم حدودِ ۳۶ هزار بهتر کرد — که در برابرِ نوسانِ ۱۴۰ هزار **ناچیز** است. **پس صادقانه‌اش این است: تنظیم اینجا تقریباً بی‌اثر بود.**

نوشتنِ همین در گزارش مهم است. یک پروژهٔ صادق می‌گوید کدام قدم‌ها کمک کردند و کدام‌ها نه؛ گزارشی که فقط قدم‌های موفق را می‌گوید، خواننده را گمراه می‌کند دربارهٔ اینکه کجا باید وقت بگذارد.

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

</div>

```python
final_mae = mean_absolute_error(y_test, tuned.predict(X_test))
baseline_mae = mean_absolute_error(
    y_test, DummyRegressor(strategy="median").fit(X_train, y_train).predict(X_test)
)

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

<div dir="rtl">

</div>

```text
MAE مدل روی test: 1364575
MAE خط پایه روی test: 8139583
بهبود: 83.2 درصد
```

<div dir="rtl">

**۸۳ درصد بهتر از حدسِ ساده.** و این عدد قابلِ دفاع است، چون:

- روی داده‌ای گرفته شد که مدل **هرگز ندیده** بود.
- خطِ پایه روی **همان** دادهٔ آزمون سنجیده شد.
- کلِ پیش‌پردازش داخلِ `Pipeline` بود، پس نشتی ندارد.
- تنها یک بار به `test` نگاه کردیم.

مقایسه‌اش کن با فصلِ ۳ که «۳۸ درصد بهبود» گرفتیم و بعد معلوم شد آن عدد روی دادهٔ آموزش بود. **مسیرِ این ترم دقیقاً همین بود: از عددی که خوب به‌نظر می‌رسید تا عددی که می‌شود رویش ایستاد.**

## ۶. قدمِ ۷: تحلیلِ خطا

</div>

```python
errors = X_test.copy()
errors["error"] = tuned.predict(X_test) - y_test
errors["abs_error"] = errors["error"].abs()

print("سوگیری به‌تفکیک برند (میانگین خطای علامت‌دار):")
print(errors.groupby("brand")["error"].mean().round(0).to_string())
print()
print("بدترین خطا:", round(errors["abs_error"].max()))
print("میانه خطا:", round(errors["abs_error"].median()))
```

<div dir="rtl">

</div>

```text
سوگیری به‌تفکیک برند (میانگین خطای علامت‌دار):
brand
اپل       -2105.0
اچ پی     50501.0
ایسوس     96785.0
دل      -174332.0
لنوو      61179.0

بدترین خطا: 5837178
میانه خطا: 1143690
```

<div dir="rtl">

**سوگیری‌ها این‌بار تقریباً ناپدید شده‌اند.** بزرگ‌ترینشان ۱۷۴ هزار است، در برابرِ ۱٫۸۵ میلیونِ فصلِ ۱۱. با یک تقسیمِ متفاوت، آن سوگیریِ به‌ظاهر سیستماتیکِ ایسوس تقریباً از بین رفت.

**و این خودش یک یافتهٔ مهم است:** آنچه در فصلِ ۱۱ «سوگیریِ سیستماتیک» به‌نظر می‌رسید، عمدتاً **تصادفِ آن تقسیمِ خاص** بوده. اگر همان‌جا شروع می‌کردی به ساختنِ featureهای پیچیده برای رفعش، وقتت را صرفِ نویز کرده بودی.

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

و به فاصلهٔ میانه (۱٫۱۴ میلیون) و بدترین (۵٫۸۴ میلیون) نگاه کن: **برای نیمیِ آگهی‌ها خطا زیرِ ۱٫۱۴ میلیون است** و چند موردِ نادر خیلی بدترند. این تصویرِ دقیق‌تری از `MAE` تنها می‌دهد.

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

</div>

```python
report = [
    "مسئله: تخمین قیمت آگهی لپ‌تاپ دست‌دوم از روی سال، حافظه، برند و شهر.",
    f"داده: {len(df)} ردیف پس از پاک‌سازی؛ {len(X_train)} آموزش، {len(X_test)} آزمون.",
    f"مدل: رگرسیون خطی با مهار (Ridge, alpha={tuned.best_params_['model__alpha']})، داخل Pipeline.",
    f"نتیجه: MAE = {round(final_mae):,} سکه روی داده‌ای که مدل ندیده بود.",
    f"در برابر خط پایه ({round(baseline_mae):,}) یعنی {round((1 - final_mae / baseline_mae) * 100, 1)}٪ بهبود.",
    f"برای نیمی از آگهی‌ها خطا زیر {round(errors['abs_error'].median()):,} سکه است.",
    "",
    "محدودیت‌ها:",
    "۱) داده ساختگی است و فقط چهار ستون دارد؛ وضعیت ظاهری، پردازنده و باتری در آن نیست.",
    "۲) دو آگهی که با این چهار ستون تفکیک‌پذیر نیستند تا ۷ میلیون تفاوت قیمت دارند — سقفی که هیچ مدلی رد نمی‌کند.",
    "۳) داده آزمون فقط ۴۸ ردیف دارد؛ هر عدد به‌تفکیک برند بی‌ثبات است.",
    "۴) تنظیم alpha اثر معناداری نداشت (۳۶ هزار در برابر نوسان ۱۴۰ هزار).",
    "",
    "پیشنهاد برای گام بعد: جمع‌آوری ستون «وضعیت ظاهری» — تحلیل خطا نشان داد",
    "بزرگ‌ترین خطاها جایی‌اند که دو آگهی مشابه قیمت متفاوت دارند.",
]
for line in report:
    print(line)
```

<div dir="rtl">

</div>

```text
مسئله: تخمین قیمت آگهی لپ‌تاپ دست‌دوم از روی سال، حافظه، برند و شهر.
داده: 238 ردیف پس از پاک‌سازی؛ 190 آموزش، 48 آزمون.
مدل: رگرسیون خطی با مهار (Ridge, alpha=0.1)، داخل Pipeline.
نتیجه: MAE = 1,364,575 سکه روی داده‌ای که مدل ندیده بود.
در برابر خط پایه (8,139,583) یعنی 83.2٪ بهبود.
برای نیمی از آگهی‌ها خطا زیر 1,143,690 سکه است.

محدودیت‌ها:
۱) داده ساختگی است و فقط چهار ستون دارد؛ وضعیت ظاهری، پردازنده و باتری در آن نیست.
۲) دو آگهی که با این چهار ستون تفکیک‌پذیر نیستند تا ۷ میلیون تفاوت قیمت دارند — سقفی که هیچ مدلی رد نمی‌کند.
۳) داده آزمون فقط ۴۸ ردیف دارد؛ هر عدد به‌تفکیک برند بی‌ثبات است.
۴) تنظیم alpha اثر معناداری نداشت (۳۶ هزار در برابر نوسان ۱۴۰ هزار).

پیشنهاد برای گام بعد: جمع‌آوری ستون «وضعیت ظاهری» — تحلیل خطا نشان داد
بزرگ‌ترین خطاها جایی‌اند که دو آگهی مشابه قیمت متفاوت دارند.
```

<div dir="rtl">

سه بخش، و هر سه اجباری: **نتیجه** با عدد و مرجع، **محدودیت‌ها** با صراحت، و **گامِ بعد** بر اساسِ شواهد نه حدس.

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

> 🔧 **اگر کار نکرد:** اگر عددهایت با اینجا فرق دارند، اول `random_state` هر دو جا را چک کن — هم `train_test_split` و هم `KFold`. اگر همان‌اند و باز فرق دارد، `X_train.shape` را مقایسه کن؛ احتمالاً `dropna` اضافه‌ای در کدت مانده که با `SimpleImputer` تداخل دارد.

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

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا برای پروژهٔ نهایی `random_state` را عوض کردیم؟

**تمرینِ اجباری:** کلِ این هفت قدم را برای مسئلهٔ **طبقه‌بندی** تکرار کن: پیش‌بینیِ `is_expensive` (قیمت بالای میانه) از روی سال، حافظه، برند و شهر. خطِ پایه با `DummyClassifier`، سه نامزد، تنظیم، ارزیابیِ یک‌باره، و `classification_report`. گزارشِ نهایی را با همان سه بخش بنویس. **این تمرین کلِ ترم را در یک مسیرِ تازه می‌سنجد.**

**تمرینِ ستاره‌دار ⭐:** پایداریِ کلِ نتیجه را بسنج. کلِ این مسیر را در یک تابع بگذار که `random_state` را پارامتر بگیرد، و روی ده مقدارِ متفاوت اجرا کن. حالا جواب بده: (۱) میانگین و انحرافِ `MAE` نهایی چقدر است؟ (۲) آیا همیشه همان مدل برنده می‌شود؟ (۳) آیا `alpha` منتخب ثابت می‌ماند؟ **حالا گزارشِ بخشِ ۷ را با این عددها بازنویسی کن** — به‌جای «MAE برابرِ ۱٫۳۶ میلیون» بنویس «۱٫۴ میلیون با نوسانِ فلان». این تفاوتِ یک گزارشِ خوب و یک گزارشِ دقیق است.

## در فصل بعد

ترمِ ۳ تمام شد. حالا می‌توانی یک مدل بسازی، صادقانه بسنجی‌اش، و نتیجه‌ات را دفاع کنی — و این خودش یک مهارتِ کاملِ شغلی است.

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

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t3/s12-project-end-to-end (یادستان, Yaadestan)
