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

آخر این فصل میتوانی:
- یک 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 | لاگز | گزارشِ اجرا، جایی که خطاها را میبینی |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
کارت عمومی است. حالا مسئولیتش هم عمومی است. فصلِ بعد دربارهٔ چیزی است که بیشترِ پروژهها هرگز نمینویسندش و بیشترین ارزش را دارد: نوشتنِ صادقانهٔ اینکه این مدل چه میکند، روی چه چیزی آموزش دیده، کجا خطا میکند، و کِی نباید به آن اعتماد کرد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.