# فصل ۰۶ — انتشار روی Hugging Face Spaces

<div dir="rtl">

# فصل ۰۶ — انتشار روی Hugging Face Spaces

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

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

![یک تابلوی نصب‌شده بر دیوارِ عمومی که همان نقشهٔ کوچکِ روی میز را در معرضِ دید گذاشته](/lesson-assets/t5-s06-spaces/prompt/01-image-public-board.png)

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

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

## قبل از شروع

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

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

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

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

## ۱. Space چیست

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

</div>

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

<div dir="rtl">

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

</div>

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

<div dir="rtl">

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

</div>

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

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

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

<div dir="rtl">

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

## ۳. `app.py`

</div>

```text-file
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()
```

<div dir="rtl">

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

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

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

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

</div>

```python
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()))
```

<div dir="rtl">

</div>

```text-approx
pandas==3.1.0
scikit-learn==1.9.1
numpy==2.5.4
joblib==1.6.0

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

<div dir="rtl">

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

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


</div>

```text
ModuleNotFoundError: No module named 'price_tool'
```

<div dir="rtl">

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

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


</div>

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

<div dir="rtl">

## ۴. `push` کردن

</div>

```bash
pip install -q huggingface_hub
```

<div dir="rtl">

</div>

```python
# 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}")
```

<div dir="rtl">

</div>

```text-approx
منتشر شد: https://huggingface.co/spaces/your-username/my-price-tool
```

<div dir="rtl">

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

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

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

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

</div>

```text-file
import os

API_KEY = os.environ.get("GEMINI_API_KEY")
if not API_KEY:
    raise RuntimeError("کلید تنظیم نشده؛ در Settings > Secrets اضافه‌اش کن.")
```

<div dir="rtl">

</div>

| کجا | چطور خوانده می‌شود |
|---|---|
| Colab | `userdata.get("NAME")` |
| Space | `os.environ.get("NAME")` |
| ماشینِ خودت | متغیرِ محیطی یا فایلِ `.env` که در `.gitignore` است |

<div dir="rtl">

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

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

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

</div>

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

<div dir="rtl">

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

> 🔧 **اگر کار نکرد:** پنج خطای رایج. **`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` قفل کن.

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

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

</div>

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

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `BRANDS` در `app.py` ثابت شد به‌جای اینکه از `csv` خوانده شود؟

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

**تمرینِ ستاره‌دار ⭐:** یک `Space` دوم بساز که دستیارِ پرسش‌وپاسخِ ترمِ ۴ را منتشر کند، با کلید در `Secrets`. حالا این سؤال را جواب بده: **اگر هزار نفر از آن استفاده کنند، سهمیهٔ کلیدِ تو چه می‌شود؟** یک `cache` و یک سقفِ ساده برایش طراحی کن — و بگو با چه معیاری سقف را انتخاب کردی. (فصلِ ۷ ترمِ ۴ همهٔ ابزارش را داده.)

## در فصل بعد

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

</div>

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