سرنخ — خودآموز پایتون و برنامه‌نویسی برای هوش مصنوعی (مقدماتی)

فصل ۵ از ۸

پیشرفت ترم
۰٪

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

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

یک دستگاه با چند دکمهٔ بزرگ و شفاف که همان مکانیزمِ پیچیدهٔ پشتش را ساده کرده

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

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

قبل از شروع#

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

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

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

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

۱. Gradio در سه خط#

pip install -q gradio
# 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()
Running on local URL:  http://127.0.0.1:7860

این خط را روی ماشینِ خودت می‌بینی. در 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 تازه است، آن فایل دیگر روی دیسک نیست و باید همان مدلِ فصلِ ۱ را دوباره بسازی:

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))))
MAE: 1381886
# 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()
Running on local URL:  http://127.0.0.1:7860

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

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

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

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

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

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

# 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):,} سکه"

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

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

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

# build-notebooks: no-run
demo.launch(share=True)
* Running on public URL: https://xxxxxxxxxxxx.gradio.live

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

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

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

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

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

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

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

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

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

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

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

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

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

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.