# فصل ۰۵ — رابط: مدلت را قابلِ‌استفاده کن

<div dir="rtl">

# فصل ۰۵ — رابط: مدلت را قابلِ‌استفاده کن

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

مدلت کار می‌کند، تست دارد، و ذخیره شده. ولی برای به‌کار بردنش هنوز باید پایتون بلد باشی، نوت‌بوک باز کنی و یک `DataFrame` بسازی. **یعنی عملاً فقط خودت می‌توانی ازش استفاده کنی.** در این فصل با `Gradio` در چند خط یک رابطِ گرافیکی می‌سازی — و مهم‌تر از کدش، یاد می‌گیری **ورودی را چطور طراحی کنی که کاربر نتواند اشتباه کند.**

![یک دستگاه با چند دکمهٔ بزرگ و شفاف که همان مکانیزمِ پیچیدهٔ پشتش را ساده کرده](/lesson-assets/t5-s05-gradio/prompt/01-image-simple-panel.png)

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

- با `Gradio` یک رابط برای هر تابعی بسازی
- ورودی‌ها را طوری محدود کنی که خطای کاربر ممکن نباشد
- مدلِ ذخیره‌شده را به رابط وصل کنی
- بگویی چه چیزی را نباید در رابط بگذاری

## قبل از شروع

**از فصل ۱:** `joblib` و بارگذاریِ مدل.

**از فصل ۲:** `class PriceModel` و پوشهٔ پروژه.

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

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

## ۱. `Gradio` در سه خط

</div>

```bash
pip install -q gradio
```

<div dir="rtl">

</div>

```python
# build-notebooks: no-run
import gradio as gr


def greet(name):
    return f"سلام {name}!"


demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()
```

<div dir="rtl">

</div>

```text-approx
Running on local URL:  http://127.0.0.1:7860
```

<div dir="rtl">

این خط را روی ماشینِ خودت می‌بینی. در Colab به آدرسِ محلی دسترسی نداری، پس `launch()` خودش یک آدرسِ عمومیِ موقت می‌سازد. آنجا اول پیامِ `Colab notebook detected` می‌آید و بعد آدرسی که به `gradio.live` ختم می‌شود، و زیرِ سلول یک قابِ زنده باز می‌شود: کادرِ `name`، کادرِ `output` و دکمهٔ `Submit`. اگر در کادر بنویسی «مینا» و `Submit` بزنی، در `output` می‌آید «سلام مینا!».

**کلِ ایدهٔ `Gradio` همین است: یک تابع بده، یک رابط بگیر.** `fn` همان تابعِ پایتونیِ توست، `inputs` می‌گوید ورودی‌اش را چطور از کاربر بگیرد، و `outputs` می‌گوید نتیجه را چطور نشان بدهد.

هیچ HTML، هیچ CSS، هیچ JavaScript. **و این دقیقاً همان چیزی است که برای یک پروژهٔ داده می‌خواهی** — رابط قرار نیست محصولِ تو باشد، فقط قرار است مدلت را در دسترس بگذارد.

## ۲. ورودیِ درست، نه ورودیِ آزاد

اینجا مهم‌ترین درسِ فصل است، و ربطی به `Gradio` ندارد.

`inputs="text"` یعنی کاربر هر چیزی می‌تواند بنویسد. برای مدلِ قیمت فاجعه است: کاربر برند را «اپل» یا «Apple» یا «apple» یا «اپل ۱۳ اینچ» می‌نویسد، و مدل برای هیچ‌کدام جز شکلِ دقیقِ زمانِ آموزش، جوابِ درست نمی‌دهد.

**قاعده: هر ورودی که مجموعهٔ مقادیرِ مجازش را می‌دانی، باید انتخابی باشد، نه نوشتنی.**

کدِ پایین فایلِ `price_model.joblib` را لازم دارد. اگر جلسهٔ Colab تازه است، آن فایل دیگر روی دیسک نیست و باید همان مدلِ فصلِ ۱ را دوباره بسازی:

</div>

```python
import joblib
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

frame = pd.read_csv("laptops_clean.csv")
X = frame[["year", "ram_gb", "brand", "city"]]
y = frame["price"]
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)

prepare = ColumnTransformer([
    ("num", Pipeline([("fill", SimpleImputer(strategy="median")),
                      ("scale", StandardScaler())]), ["year", "ram_gb"]),
    ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
])
trained = Pipeline([("prepare", prepare), ("model", Ridge(alpha=0.1))]).fit(X_train, y_train)
joblib.dump(trained, "price_model.joblib")
print("MAE:", round(mean_absolute_error(y_test, trained.predict(X_test))))
```

<div dir="rtl">

</div>

```text
MAE: 1381886
```

<div dir="rtl">

</div>

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

model = joblib.load("price_model.joblib")
data = pd.read_csv("laptops_clean.csv")

BRANDS = sorted(data["brand"].unique())
CITIES = sorted(data["city"].unique())
# مرزهای اسلایدر از خودِ داده می‌آیند، نه از حدس — بیرونِ این بازه مدل چیزی ندیده
YEAR_MIN, YEAR_MAX = int(data["year"].min()), int(data["year"].max())


def estimate(year, ram_gb, brand, city):
    row = pd.DataFrame([{"year": year, "ram_gb": ram_gb, "brand": brand, "city": city}])
    price = float(model.predict(row)[0])
    return f"{round(price):,} سکه"


demo = gr.Interface(
    fn=estimate,
    inputs=[
        gr.Slider(YEAR_MIN, YEAR_MAX, value=YEAR_MAX - 2, step=1, label="سال ساخت"),
        gr.Dropdown([4, 8, 16, 32], value=16, label="حافظه (گیگابایت)"),
        gr.Dropdown(BRANDS, value=BRANDS[0], label="برند"),
        gr.Dropdown(CITIES, value=CITIES[0], label="شهر"),
    ],
    outputs=gr.Textbox(label="قیمت پیشنهادی"),
    title="برآورد قیمت لپ‌تاپ دست‌دوم",
    description="این عدد یک برآورد آماری است، نه قیمت قطعی. بخش «محدودیت‌ها» را بخوان.",
)
demo.launch()
```

<div dir="rtl">

</div>

```text-approx
Running on local URL:  http://127.0.0.1:7860
```

<div dir="rtl">

> ✅ **چک کن:** رابط باید در همان سلول یک آدرس چاپ کند و پایینش یک قابِ زنده نشان بدهد. اگر قاب خالی است یا چیزی نمی‌بینی، سلول را دوباره اجرا کن. با مقدارهای پیش‌فرض و برندِ «ایسوس»، دکمهٔ `Submit` باید `30,840,171 سکه` را بدهد، به شرطی که شهر «تهران» باشد. اگر رابط به‌جای نتیجه `Error` نشان داد، در Colab متنِ خطا خودبه‌خود چاپ نمی‌شود: **`demo.launch(debug=True)` بزن تا خطا در خروجیِ همین سلول بیاید.** با `debug=True` سلول در حالِ اجرا می‌ماند، و وقتی کارت تمام شد خودت متوقفش می‌کنی.

سه تصمیم در این کد، و هر سه از مدل مهم‌ترند:

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

> 📏 **اندازه بگیر:** به آن دو خطِ `YEAR_MIN` و `YEAR_MAX` دقت کن؛ **این تنها جای درستِ گرفتنِ بازه است.** اگر عددها را دستی بنویسی و اشتباه بزنی، هیچ خطایی نمی‌گیری: رابط بالا می‌آید، کاربر سالی خارج از دامنهٔ آموزش انتخاب می‌کند، و مدل با اطمینانِ کامل یک عددِ بی‌معنا می‌دهد. **همان شکستِ خاموشِ ترمِ ۴ فصلِ ۶، این بار در لباسِ یک فرمِ زیبا.** و در فصلِ ۷ می‌بینی که همین بازه باید عیناً در کارتِ مدل هم بیاید — اگر آنجا عددِ دیگری بنویسی، سندت با کدت نمی‌خواند.

## ۳. وقتی ورودی هنوز بد است

بعضی ورودی‌ها را نمی‌شود محدود کرد. آن‌وقت تابعت باید خودش مراقب باشد:

</div>

```python
# build-notebooks: no-run
def estimate_safe(year, ram_gb, brand, city):
    if brand not in BRANDS:
        return "این برند در دادهٔ آموزش نبوده؛ برآورد قابل اتکا نیست."
    if not YEAR_MIN <= year <= YEAR_MAX:
        return "سال خارج از بازه‌ای است که مدل دیده."

    row = pd.DataFrame([{"year": year, "ram_gb": ram_gb, "brand": brand, "city": city}])
    price = float(model.predict(row)[0])
    if price <= 0:
        return "برآورد بی‌معنا شد؛ ورودی‌ها را بازبینی کن."
    return f"{round(price):,} سکه"
```

<div dir="rtl">

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

آخری را جدی بگیر: یک مدلِ خطی می‌تواند برای ورودیِ غیرعادی عددِ منفی بدهد. **مدل نمی‌داند قیمت نمی‌تواند منفی باشد؛ تو می‌دانی. آن دانش را در کد بگذار.**

## ۴. لینکِ عمومیِ موقت

</div>

```python
# build-notebooks: no-run
demo.launch(share=True)
```

<div dir="rtl">

</div>

```text-approx
* Running on public URL: https://xxxxxxxxxxxx.gradio.live

This share link is temporary and will last for up to 1 week (best effort).
```

<div dir="rtl">

`share=True` یک آدرسِ عمومیِ **موقت** می‌سازد که هر کسی می‌تواند بازش کند. عمرش با نسخهٔ `Gradio` عوض شده، پس همان جمله‌ای را باور کن که برای خودت چاپ می‌شود. برای نشان دادنِ کار به یک نفر عالی است. روی ماشینِ خودت این پارامتر لازم است؛ در Colab همان `launch()` بخشِ ۱ هم همین کار را کرده بود، پس رابطت از همان لحظه عمومی بوده است.

</div>

| | `share=True` | Hugging Face Spaces (فصلِ ۶) |
|---|---|---|
| عمر | چند روز | دائمی |
| کجا اجرا می‌شود | روی همین جلسهٔ Colab | روی سرورِ خودشان |
| با بستنِ نوت‌بوک | می‌میرد | زنده می‌ماند |
| مناسبِ | نشان دادنِ سریع | انتشارِ واقعی |

<div dir="rtl">

> ⚠️ **مواظب باش:** با `share=True` هر کسی که لینک را داشته باشد **کدِ تو را روی ماشینِ تو اجرا می‌کند**. هیچ‌وقت رابطی را که فایل می‌خواند، فایل می‌نویسد، یا فرمانِ سیستمی اجرا می‌کند، عمومی نکن. و **هیچ‌وقت کلیدِ API را داخلِ تابعِ رابط نگذار** — همان قاعدهٔ ترمِ ۴ فصلِ ۳، این بار با درِ بازِ اینترنت.

## ۵. چه چیزی را در رابط نگذار

</div>

| نگذار | چرا | به‌جایش |
|---|---|---|
| ورودیِ متنیِ آزاد برای مقدارهای دسته‌ای | کاربر شکلِ ناشناخته می‌نویسد | `Dropdown` |
| عددِ خام بدونِ واحد | «۱۶» یعنی گیگابایت یا مگابایت؟ | برچسبِ با واحد |
| پیش‌بینی بدونِ هیچ زمینه‌ای | کاربر عدد را قطعی می‌گیرد | بازه یا هشدار |
| گزینه‌های تنظیمِ مدل | کاربر معنایشان را نمی‌داند | مقدارِ ثابتِ درست |
| `traceback` خام | ترسناک و بی‌فایده | پیامِ فارسیِ روشن |

<div dir="rtl">

آن ردیفِ سوم را جدی بگیر. **یک عددِ تنها روی صفحه، خودش را قطعی نشان می‌دهد.** «۳۰٬۸۴۰٬۱۷۱ سکه» دقیق به‌نظر می‌رسد در حالی که خطای متوسطِ مدل بیش از یک میلیون است. **صادقانه‌تر: «حدودِ ۲۹ تا ۳۲ میلیون» یا «۳۰٫۸ میلیون ± ۱٫۴ میلیون».** رقم‌های اضافی دقتی را نشان می‌دهند که وجود ندارد.

> 🔧 **اگر کار نکرد:** سه مشکلِ رایج. **آدرس عوض شد:** پورتِ ۷۸۶۰ اشغال است و `Gradio` خودش سراغِ پورتِ بعدی رفته، مثلاً ۷۸۶۱. این خطا نیست. فقط اگر پورت را خودت با `server_port` تعیین کرده باشی و اشغال باشد، با `OSError` می‌ایستد. **رابط بالا می‌آید ولی دکمه `Error` نشان می‌دهد:** تابعت خطا می‌دهد؛ با `demo.launch(debug=True)` متنِ خطا را در خروجیِ همان سلول ببین. **تغییرِ کد اثر ندارد:** نسخهٔ قبلی هنوز در حالِ اجراست — `demo.close()` بزن و دوباره `launch` کن.

> 🤖 **از دستیارت بپرس:** «چه اجزای ورودیِ دیگری در Gradio هست و هرکدام برای چه نوع داده‌ای مناسب است؟» بعد **برای مدلِ خودت انتخاب کن و دلیلش را بنویس**. و این را هم بپرس: «چطور یک نمودار را به‌عنوان خروجی نشان بدهم؟» — چون نشان دادنِ اینکه پیش‌بینی کجای توزیعِ داده می‌افتد، از خودِ عدد گویاتر است.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Gradio | گرِیدیو | کتابخانهٔ ساختِ رابط برای تابع‌های پایتون |
| Interface | اینترفیس | تعریفِ تابع + ورودی‌ها + خروجی‌ها |
| component | کامپوننت | یک جزءِ ورودی یا خروجی (`Slider`، `Dropdown`، …) |
| launch | لانچ | بالا آوردنِ سرورِ رابط |
| share link | شیر لینک | آدرسِ عمومیِ موقت |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `Dropdown` برای برند از ورودیِ متنی بهتر است؟

**تمرینِ اجباری:** رابطِ بخشِ ۲ را بساز و اجرا کن، بعد **عمداً سعی کن خرابش کنی**: ترکیب‌های عجیب بده و ببین کجا جوابِ بی‌معنا می‌دهد. هر موردی را که پیدا کردی با یک بررسی در `estimate_safe` ببند. **فهرستِ چیزهایی را که پیدا کردی نگه دار — همان فهرست، بخشِ «محدودیت‌ها»ی فصلِ ۷ می‌شود.**

**تمرینِ ستاره‌دار ⭐:** خروجی را از یک عدد به سه چیز تغییر بده: برآورد، **بازهٔ عدم‌قطعیت** بر اساسِ `MAE` مدل، و یک جملهٔ کوتاه که بگوید این ورودی چقدر شبیهِ دادهٔ آموزش است (مثلاً «۲۳ لپ‌تاپ مشابه در داده بوده» یا «هیچ نمونهٔ مشابهی نبوده — با احتیاط»). **این دومی از خودِ برآورد مفیدتر است** و تقریباً هیچ رابطی آن را نشان نمی‌دهد.

## در فصل بعد

رابطت کار می‌کند، ولی با بستنِ Colab می‌میرد. فصلِ بعد آن را جایی می‌برد که **همیشه زنده باشد**: Hugging Face Spaces — رایگان، با یک آدرسِ دائمی که می‌توانی به هر کسی بدهی.

</div>

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