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

فصل ۶ از ۸

پیشرفت ترم
۰٪

ترم ۵ · از نوت‌بوک تا چیزی که دیگران استفاده می‌کنند

انتشار روی Hugging Face Spaces

فصل ۶رایگان

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

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

یک تابلوی نصب‌شده بر دیوارِ عمومی که همان نقشهٔ کوچکِ روی میز را در معرضِ دید گذاشته

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

  • یک Space بسازی و پروژه‌ات را رویش منتشر کنی
  • سه فایلِ لازم را درست بنویسی
  • رازها را در محیطِ سرور نگه داری، نه در کد
  • بگویی چه چیزی را نباید عمومی کنی

قبل از شروع#

از فصل ۳: git، commit، push، و اینکه راز هرگز commit نمی‌شود.

از فصل ۵: رابطِ Gradio که ساختی.

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

💡 نکته: این فصل با حسابِ خودت انجام می‌شود، پس خروجی‌ها تقریبی‌اند. مسیرِ کار را بخوان، بعد قدم‌به‌قدم روی حسابِ خودت اجرا کن.

۱. Space چیست#

یک Space یک مخزنِ git است که Hugging Face به‌جای اینکه فقط نگهش دارد، اجرایش می‌کند. push می‌کنی، آن‌ها می‌سازند و بالا می‌آورند، و یک آدرسِ دائمی می‌گیری.

Colab با share=True Space
آدرس موقت دائمی
اجرا روی جلسهٔ تو روی سرورِ آن‌ها
بستنِ لپ‌تاپ همه‌چیز می‌میرد زنده می‌ماند
به‌روزرسانی اجرای دوبارهٔ سلول git push
هزینه رایگان ردهٔ پایه رایگان

۲. سه فایلِ لازم#

my-price-tool/
    app.py             ← رابط Gradio
    requirements.txt   ← وابستگی‌ها با نسخه
    README.md          ← با سرآیندِ ویژه‌ای که Space را پیکربندی می‌کند
    price_model.joblib ← مدلِ آموزش‌دیده

سکو از روی app_file در سرآیند می‌فهمد از کدام فایل شروع کند، و نامِ پیش‌فرض و رایج app.py است. README.md اینجا فقط توضیح نیست؛ سرآیندش پیکربندیِ Space است:

---
title: برآورد قیمت لپ‌تاپ
emoji: 💻
colorFrom: blue
colorTo: green
sdk: gradio
python_version: "3.12"
app_file: app.py
pinned: false
---

# برآورد قیمت لپ‌تاپ دست‌دوم

یک مدل رگرسیون خطی روی داده‌ای از آگهی‌های لپ‌تاپ دست‌دوم.
بخش «محدودیت‌ها» را قبل از اعتماد به عددها بخوان.

آن بخشِ بینِ دو خطِ --- را front matter می‌گویند. sdk: gradio می‌گوید چطور اجرایش کند و app_file می‌گوید از کجا شروع کند. python_version را با نسخه‌ای بگیر که مدلت را با آن ساخته‌ای، چون نسخه‌های تازهٔ pandas و numpy روی پایتونِ قدیمی نصب نمی‌شوند؛ پیش‌فرضِ سکو را «در زمانِ انتشار چک کن». اگر این سرآیند نباشد یا خراب باشد، Space بالا نمی‌آید و پیامِ خطایش هم چندان راهنما نیست.

۳. app.py#

import gradio as gr
import joblib
import pandas as pd

model = joblib.load("price_model.joblib")

# این پنج مقدار از دادهٔ آموزش استخراج شده‌اند، نه حدس زده — روی Space فایلِ داده نداریم،
# پس هر بار که داده عوض شود باید این خط‌ها هم با آن به‌روز شوند.
BRANDS = ["اپل", "اچ پی", "ایسوس", "دل", "لنوو"]
CITIES = ["اصفهان", "تبریز", "تهران", "شیراز", "مشهد"]
YEAR_MIN, YEAR_MAX = 2016, 2024
MAE = 1_381_886          # خطای متوسط مدل روی دادهٔ آزمون


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])
    if price <= 0:
        return "برآورد بی‌معنا شد؛ ورودی‌ها را بازبینی کن."
    low, high = round(price - MAE), round(price + MAE)
    return f"حدود {round(price):,} سکه\n(بازهٔ محتمل: {low:,} تا {high:,})"


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

demo.launch()

✅ چک کن: بعد از آپلود، تبِ Logs را باز کن و منتظرِ خطِ Running بمان. تا وقتی این خط نیامده، Space بالا نیست — حتی اگر صفحه‌اش باز شود. و اگر پیامِ Build failed دیدی، آخرین ده خطِ همان لاگ تقریباً همیشه دقیقاً می‌گوید کدام بسته یا کدام فایل کم است.

دو تفاوت با فصلِ ۵، و هر دو عمدی‌اند:

  • BRANDS و بازهٔ سال اینجا ثابت‌اند، نه از csv. روی Space فایلِ داده را نداریم و لازم هم نیست — رابط فقط به فهرستِ گزینه‌ها نیاز دارد، نه به کلِ داده. دادهٔ خام را بی‌جهت عمومی نکن. ولی این یک بده‌بستان است، نه یک بهبود: در فصلِ ۵ همین مقدارها خودشان را از داده می‌ساختند و همیشه درست بودند؛ اینجا اگر داده عوض شود و کسی این خط‌ها را به‌روز نکند، رابط بی‌سروصدا از داده عقب می‌افتد. برای همین کامنتشان اجباری است، و برای همین در کارتِ مدلِ فصلِ ۷ دوباره همین عددها را می‌نویسیم — تا اگر روزی نخواندند، معلوم شود.
  • خروجی بازه می‌دهد، نه یک عدد. همان درسِ فصلِ ۵: عددِ تنها خودش را قطعی نشان می‌دهد.

پوشه را بساز. requirements.txt هنوز جایی نوشته نشده و مدل هم باید به این پوشه بیاید. این کد هر دو را می‌سازد. نسخه‌ها را از همان محیطی می‌گیرد که مدل در آن آموزش دیده، پس فایل با مدل می‌خواند. gradio در این فهرست نیست، چون sdk: gradio آن را نصب می‌کند.

import shutil
from pathlib import Path

import joblib
import numpy
import pandas as pd
import sklearn
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)

folder = Path("my-price-tool")
shutil.rmtree(folder, ignore_errors=True)
folder.mkdir()
joblib.dump(trained, folder / "price_model.joblib")

needs = (f"pandas=={pd.__version__}\nscikit-learn=={sklearn.__version__}\n"
         f"numpy=={numpy.__version__}\njoblib=={joblib.__version__}\n")
(folder / "requirements.txt").write_text(needs, encoding="utf-8")

print(needs)
print("MAE:", round(mean_absolute_error(y_test, trained.predict(X_test))))
print(sorted(p.name for p in folder.iterdir()))
pandas==3.1.0
scikit-learn==1.9.1
numpy==2.5.4
joblib==1.6.0

MAE: 1381886
['price_model.joblib', 'requirements.txt']

عددهای نسخه مالِ ماشینِ ماست و برای تو فرق دارند. app.py و README.md بالا را هم در همین پوشه بگذار. فایل را با Path.write_text بنویس، یا در پنلِ فایل‌های Colab یک فایلِ تازه بساز و متن را در آن بچسبان.

⚠️ مواظب باش: ما اینجا خودِ Pipeline را ذخیره کردیم، نه PriceModel فصلِ ۲ را، و این عمدی است. روی Space پوشهٔ price_tool نیست، و گفتیم فایلِ مدل بدونِ کدش باز نمی‌شود. اگر شیءِ PriceModel را به پوشه‌ای ببری که price_tool ندارد، این را می‌گیری:

ModuleNotFoundError: No module named 'price_tool'

اگر با PriceModel کار می‌کنی، به‌جای خودش joblib.dump(model.pipeline, ...) را ذخیره کن.

قبل از push، پشتِ رابط را همین‌جا امتحان کن. تابع‌های app.py تابعِ معمولی‌اند. با مقدارهای پیش‌فرضِ فرم، estimate این را برمی‌گرداند:

حدود 30,840,171 سکه
(بازهٔ محتمل: 29,458,285 تا 32,222,057)

۴. push کردن#

pip install -q huggingface_hub
# build-notebooks: no-run
from google.colab import userdata
from huggingface_hub import HfApi

api = HfApi(token=userdata.get("HF_TOKEN"))
repo_id = "your-username/my-price-tool"

api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio", exist_ok=True)
api.upload_folder(folder_path="my-price-tool", repo_id=repo_id, repo_type="space")

print("منتشر شد:", f"https://huggingface.co/spaces/{repo_id}")
منتشر شد: https://huggingface.co/spaces/your-username/my-price-tool

توکن باز هم از Colab Secrets آمد، نه از داخلِ کد. توکن باید دسترسیِ write داشته باشد.

بعد از upload_folder، سکو خودش شروع به ساختن می‌کند: requirements.txt را نصب می‌کند، app.py را اجرا می‌کند، و چند دقیقه بعد آدرس زنده است. اگر خطا داد، در تبِ Logs همان Space دقیقاً می‌بینی کجا شکست — و تقریباً همیشه یا بستهٔ جامانده در requirements.txt است یا فایلی که آپلود نشده.

۵. رازها در محیط، نه در کد#

اگر رابطت به یک کلیدِ API نیاز دارد (مثلاً همان دستیارِ ترمِ ۴)، کلید نه در کد می‌رود و نه در مخزن. Space یک بخشِ Settings > Variables and secrets دارد؛ راز را آنجا می‌گذاری و کد این‌طور می‌خواندش:

import os

API_KEY = os.environ.get("GEMINI_API_KEY")
if not API_KEY:
    raise RuntimeError("کلید تنظیم نشده؛ در Settings > Secrets اضافه‌اش کن.")
کجا چطور خوانده می‌شود
Colab userdata.get("NAME")
Space os.environ.get("NAME")
ماشینِ خودت متغیرِ محیطی یا فایلِ .env که در .gitignore است

آن raise را حذف نکن. بدونِ آن، API_KEY برابرِ None می‌شود و برنامه با یک خطای عجیب در وسطِ کار می‌شکند. خطای صریح در ابتدای اجرا، از خطای مبهم در وسطِ کار خیلی بهتر است.

⚠️ مواظب باش: یک Space عمومی یعنی همهٔ فایل‌هایش عمومی است — کد، مدل، و هر فایلِ داده‌ای که آپلود کرده‌ای. قبل از upload_folder، پوشه را باز کن و تک‌تکِ فایل‌ها را نگاه کن. رایج‌ترین اشتباه، یک فایلِ csv جامانده از آزمایش است که دادهٔ واقعیِ کسی در آن هست. اگر مدلت روی دادهٔ شخصی آموزش دیده، خودِ مدل هم می‌تواند نشتی داشته باشد — و آن دیگر با پاک کردنِ فایل حل نمی‌شود.

۶. بعد از انتشار#

کار چطور
به‌روزرسانیِ کد فایل را عوض کن و دوباره upload_folder
دیدنِ خطا تبِ Logs در صفحهٔ Space
خصوصی کردن Settings > Change visibility
خواب رفتنِ Space ردهٔ رایگان بعد از بی‌کاری می‌خوابد و با اولین بازدید بیدار می‌شود

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

🔧 اگر کار نکرد: پنج خطای رایج. Build failed: بسته‌ای در requirements.txt نیست یا نسخه‌اش ناسازگار است — Logs را بخوان. FileNotFoundError برای price_model.joblib: فایل آپلود نشده یا در .gitignore بوده. ModuleNotFoundError: No module named 'price_tool': شیءِ PriceModel را ذخیره کرده‌ای، نه Pipeline را. Config error: سرآیندِ README.md خراب است. مدل باز نمی‌شود: نسخهٔ scikit-learn روی Space با نسخه‌ای که مدل را ساخته یکی نیست — دقیقاً همان چیزی که فصلِ ۱ هشدارش را داد؛ نسخه را در requirements.txt قفل کن.

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

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

کلمه تلفظ به حروف فارسی یعنی چه
Space اسپیس مخزنی که سکو اجرایش هم می‌کند
front matter فرانت متر سرآیندِ پیکربندی در ابتدای README.md
environment variable انوایرمنت وریبل مقداری که از محیطِ اجرا خوانده می‌شود، نه از کد
build بیلد مرحلهٔ نصبِ وابستگی‌ها و آماده‌سازی
logs لاگز گزارشِ اجرا، جایی که خطاها را می‌بینی

تمرین‌ها

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

در فصل بعد#

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

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

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