# فصل ۰۷ — صداقت بعد از انتشار

<div dir="rtl">

# فصل ۰۷ — صداقت بعد از انتشار

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

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

![یک برچسبِ مشخصاتِ فنی که کنارِ دستگاه نصب شده و بخشی از آن هشدار است](/lesson-assets/t5-s07-model-card/prompt/01-image-spec-label.png)

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

- خطای مدل را به‌تفکیکِ زیرگروه اندازه بگیری
- بگویی چرا خطای مطلق و نسبی دو داستانِ متفاوت می‌گویند
- `drift` را شبیه‌سازی کنی و اثرش را ببینی
- یک `model card` بنویسی که واقعاً به کار بیاید

## قبل از شروع

**از ترمِ ۳ فصل ۱۱:** تحلیلِ خطا و خطای علامت‌دار به‌تفکیکِ زیرگروه.

**از ترمِ ۳ فصل ۱۲:** اینکه هر الگویی در خطاها را باید با یک `random_state` دیگر تأیید کرد، وگرنه ممکن است نویز باشد.

**از فصل ۱:** بازهٔ نتیجه به‌جای یک عدد.

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

## ۱. عددِ کلی، بزرگ‌ترین دروغِ بی‌قصد

«خطای متوسطِ مدل ۱٫۴ میلیون است» جملهٔ درستی است و **تقریباً هیچ‌چیز نمی‌گوید**. میانگین روی همهٔ کاربران پخش می‌شود؛ ولی هیچ کاربری «میانگین» نیست. هر کدامشان در یک زیرگروه‌اند.

</div>

```python
import pandas as pd
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

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

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

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)
model = Pipeline([("prepare", prepare), ("model", Ridge(alpha=0.1))]).fit(X_train, y_train)

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

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

print(by_brand.to_string())
print("کل:", round(report["abs_error"].mean()), "| نسبی کل:", round(report["rel_error"].mean(), 1))
```

<div dir="rtl">

</div>

```text
        n    abs_mae  rel_pct
brand
اچ پی   7  1571178.5     13.3
لنوو    9  2090990.2      9.9
ایسوس  16  1118562.6      5.6
دل     12  1040295.9      4.8
اپل     4  1533205.6      4.0
کل: 1381886 | نسبی کل: 7.2
```

<div dir="rtl">

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

- بر اساسِ **خطای مطلق**، بدترین گروه «لنوو» است با ۲٫۰۹ میلیون.
- بر اساسِ **خطای نسبی**، بدترین گروه «اچ پی» است با ۱۳٫۳ درصد، و «اپل» با ۴ درصد **بهترین** است — با اینکه خطای مطلقش ۱٫۵۳ میلیون است.

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

**کدام‌یک درست است؟ به این بستگی دارد که چه کسی آسیب می‌بیند.** برای فروشنده‌ای که لپ‌تاپِ ارزان می‌فروشد، ۱۳ درصد خطا یعنی قیمت‌گذاریِ کاملاً غلط. **پس در کارتِ مدل هر دو را بنویس، و بگو کدام برای کاربردِ تو مهم‌تر است.**

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

## ۲. سوگیری، به معنای اندازه‌گیری‌شده

کلمهٔ «سوگیری» زیاد شنیده می‌شود و اغلب بدونِ عدد. **در کارِ ما معنای دقیقی دارد: مدل روی یک زیرگروه به‌طورِ سیستماتیک بدتر کار می‌کند.** و راهِ فهمیدنش دقیقاً همان جدولِ بالاست.

سه نکته که این اندازه‌گیری را از یک تمرینِ بی‌فایده جدا می‌کند:

- **زیرگروه‌ها را قبل از دیدنِ نتیجه انتخاب کن.** اگر بعد از دیدنِ خطاها دنبالِ گروهی بگردی که بدتر است، **همیشه یکی پیدا می‌کنی** — حتی در دادهٔ کاملاً تصادفی.
- **الگو را با یک `random_state` دیگر تأیید کن** — درسِ ترمِ ۳ فصلِ ۱۲، که همان‌جا یک «سوگیریِ سیستماتیک» با عوض کردنِ تقسیم تقریباً ناپدید شد.
- **سوگیری روی ویژگی‌های انسانی، از سوگیری روی برندِ لپ‌تاپ جنسِ متفاوتی دارد.** آنجا پای عدالت در میان است، نه فقط دقت — و آنجا اندازه‌گیری و گزارشِ صریح، حداقلِ کارِ لازم است، نه کارِ اضافی.

## ۳. `drift`: مدل کهنه می‌شود

مدلِ تو یک عکس از گذشته است. دنیا حرکت می‌کند و عکس نه.

</div>

```python
future = df.copy()
future["price"] = future["price"] * 1.25      # شبیه‌سازی: قیمت‌ها ۲۵ درصد بالا رفته‌اند
X_future = future[["year", "ram_gb", "brand", "city"]]

today = mean_absolute_error(y, model.predict(X))
tomorrow = mean_absolute_error(future["price"], model.predict(X_future))

print("MAE امروز:", round(today))
print("MAE فردا :", round(tomorrow))
print("نسبت     :", round(tomorrow / today, 1), "برابر بدتر")
```

<div dir="rtl">

</div>

```text
MAE امروز: 1449065
MAE فردا : 6618754
نسبت     : 4.6 برابر بدتر
```

<div dir="rtl">

**۲۵ درصد تغییرِ قیمت، خطا را ۴٫۶ برابر کرد.** و توجه کن: **نه کد عوض شد، نه مدل، نه ورودی‌ها.** فقط دنیا جلو رفت.

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

</div>

| نشانه | چه کاری |
|---|---|
| توزیعِ ورودی‌ها عوض شده | لاگِ ورودی‌ها را با دادهٔ آموزش مقایسه کن |
| خطا روی دادهٔ تازه بالا رفته | مدل را با دادهٔ تازه دوباره آموزش بده |
| مقدارهای ناشناخته زیاد شده | `handle_unknown` جلوی خطا را می‌گیرد، ولی جوابش هم بی‌معنا می‌شود |
| هیچ‌کدام، ولی چند ماه گذشته | باز هم دوباره بسنج — **زمان خودش یک نشانه است** |

<div dir="rtl">

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

## ۴. قالبِ `model card`

</div>

```text-file
# کارت مدل: برآورد قیمت لپ‌تاپ دست‌دوم

## چه می‌کند
با گرفتن سال ساخت، حافظه، برند و شهر، قیمت پیشنهادی آگهی را برآورد می‌کند.

## داده
۲۳۸ آگهی، پنج برند، پنج شهر، سال‌های ۲۰۱۶ تا ۲۰۲۴ (کمینه و بیشینهٔ واقعیِ ستون year).
اثر انگشت داده: 833b0ebd03779d4f

## کارایی
- خطای متوسط مطلق: ۱٫۳۸ میلیون سکه (روی ۴۸ نمونهٔ آزمون، random_state=0)
- بازهٔ نتیجه روی پنج seed مختلف: ۱٫۱۰ تا ۱٫۵۲ میلیون
- خطای متوسط نسبی: ۷٫۲ درصد
- خط پایه (حدس با میانه): ۷٫۷۹ میلیون

## کجا بدتر کار می‌کند
- اچ پی: ۱۳٫۳ درصد خطای نسبی (بدترین گروه، ۷ نمونه)
- اپل: فقط ۴ نمونه در آزمون — عدد این گروه قابل اتکا نیست

## به‌کارش نبر برای
- لپ‌تاپ‌های خارج از این پنج برند
- سال‌های خارج از بازهٔ ۲۰۱۶ تا ۲۰۲۴
- تصمیم مالی بدون بازبینی انسان

## کهنگی
آموزش‌دیده روی دادهٔ <تاریخ>. با ۲۵ درصد تغییر سطح قیمت‌ها، خطا حدود
۴٫۶ برابر می‌شود. دست‌کم هر سه ماه دوباره بسنج.
```

<div dir="rtl">

**هر عددِ این کارت از یک اندازه‌گیریِ واقعی آمده، نه از تخمین.** به بازهٔ سال دقت کن: ۲۰۱۶ تا ۲۰۲۴، چون `df["year"].min()` و `df["year"].max()` همین را می‌دهند — نه یک بازهٔ گِردشدهٔ خوش‌ظاهر و نه بازه‌ای که در فرمِ رابط گذاشته‌ای. **این ریزترین جایی است که یک کارتِ مدل دروغ می‌گوید:** کسی بازهٔ فرم را به‌جای بازهٔ داده می‌نویسد، و از آن به بعد سند ادعا می‌کند مدل سال‌هایی را دیده که ندیده. **هر عددی که در کارت می‌نویسی باید یک خطِ کد داشته باشد که آن را تولید کرده باشد.**

و بخشِ «کجا بدتر کار می‌کند» و «به‌کارش نبر برای» — که در بیشترِ پروژه‌ها اصلاً نوشته نمی‌شوند — **مفیدترین بخش‌های کارت‌اند.**

</div>

| ننویس | بنویس |
|---|---|
| «دقت بالا» | «خطای متوسط ۱٫۳۸ میلیون روی ۴۸ نمونهٔ آزمون» |
| «روی دادهٔ واقعی تست شده» | «۲۳۸ آگهی، پنج برند، پنج شهر» |
| «برای همه مناسب است» | «برای این پنج برند؛ بیرونش نه» |
| «ممکن است خطا داشته باشد» | «۱۳٫۳ درصد خطا روی اچ پی» |

<div dir="rtl">

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

> 🤖 **از دستیارت بپرس:** کارتِ مدلت را به دستیارت بده و بپرس: «یک کاربرِ بدبین چه سؤالی می‌پرسد که این کارت جوابش را ندارد؟» **هر سؤالی که جوابش را نداری، یا باید اندازه‌اش بگیری یا صریح بنویسی که نمی‌دانی.** این تمرین بارها مؤثرتر از خواندنِ چک‌لیستِ آماده است، چون سؤال‌ها مخصوصِ پروژهٔ خودت درمی‌آیند.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| model card | مادل کارت | سندِ کوتاهِ «این مدل چیست و چه محدودیتی دارد» |
| subgroup | ساب‌گروپ | زیرمجموعه‌ای از داده که جدا سنجیده می‌شود |
| bias | بایاس | بدترکارکردنِ سیستماتیک روی یک زیرگروه |
| drift | دریفت | فاصله گرفتنِ دنیا از دادهٔ آموزش، با گذرِ زمان |
| monitoring | مانیتورینگ | سنجشِ مداومِ مدل بعد از انتشار |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا خطای مطلق و نسبی زیرگروه‌ها را به دو ترتیبِ متفاوت رتبه‌بندی کردند؟

**تمرینِ اجباری:** همان جدولِ بخشِ ۱ را این بار به‌تفکیکِ **شهر** بساز، و بعد هر دو جدول را با `random_state=7` تکرار کن. **کدام یافته‌ها با تغییرِ تقسیم ماندند و کدام‌ها ناپدید شدند؟** فقط آن‌هایی که ماندند حق دارند وارد کارتِ مدل شوند.

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

## در فصل بعد

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

</div>

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