# فصل ۰۶ — مدل به‌عنوان محصول: رجیستری

<div dir="rtl">

# فصل ۰۶ — مدل به‌عنوان محصول: رجیستری

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

یک مدلِ آموزش‌دیده در نوت‌بوک یک متغیر است و با بسته شدنِ نشست از بین می‌رود. **این فصل آن را به یک محصولِ نسخه‌دار تبدیل می‌کند** — با انبارِ محتوا-نشانی، جدولِ نسخه، مرحلهٔ چرخهٔ عمر، و پیوند به همان اجرایی که ساختش.

و آزمونِ نهایی‌اش یک عدد است: **مدلی که از رجیستری بارگذاری می‌شود، دقیقاً همان `F1` برابرِ ۰٫۷۰۴۵۴۵ را می‌دهد که موقعِ ثبت گزارش شده بود — اختلاف `0.0`.**

در راه دو چیزِ دیگر هم اندازه می‌گیریم: **پنج بار ذخیره، سه فایل** (انبارِ محتوا-نشانی تکراری‌ها را خودش حذف می‌کند)، و یک قاعدهٔ پایگاه داده که **دو نسخهٔ هم‌زمان در تولید را غیرممکن می‌کند.**

![یک قفسهٔ انبار که هر جعبه مهرِ محتوایش را دارد و فقط یک شکاف «فعال» است](/lesson-assets/t3-s06-model-registry/prompt/01-image-registry-shelf.png)

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

- انبارِ artifact محتوا-نشانی بسازی و تکراری‌ها را خودکار حذف کنی
- مرحلهٔ چرخهٔ عمر را طوری پیاده کنی که پایگاه داده جلوی حالتِ غلط را بگیرد
- از مدلِ تولید به پیکربندی و داده و کدش برسی، با یک پرسمان
- **ثابت کنی** مدلِ ذخیره‌شده همان عددی را می‌دهد که ادعا شده

## قبل از شروع

**از فصلِ ۱ تا ۵:** `run(cfg)`، اثرِ انگشتِ داده و کد، و برنده‌ای که در فصلِ ۵ صادقانه انتخاب شد.

**از ترمِ ۲:** اثرِ انگشتِ محتوا برای فایل. **اینجا همان ایده روی فایلِ مدل به‌کار می‌رود.**

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

</div>

| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوت‌بوک روی CPU | کمتر از یک دقیقه |
| GPU | لازم نیست |

<div dir="rtl">

## ۱. انبارِ محتوا-نشانی

**نامِ فایل را از محتوایش بساز، نه از تاریخ و نه از یک شمارنده.** `model_final_v2_REAL.pkl` نامِ آشنایی است و دقیقاً همان مشکلی را دارد که به‌نظر می‌رسد.

</div>

```python
import hashlib
import pickle

from sklearn.feature_extraction.text import CountVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import f1_score

STORE = WORK / "artifacts"
STORE.mkdir(exist_ok=True)


def fit_model(cfg):
    """همان آموزشِ run، ولی این بار خودِ مدل را برمی‌گرداند نه متریک را."""
    cfg = DEFAULTS | cfg
    texts = texts_for(cfg)
    tr, te = random_split(len(Y), cfg["seed"])
    if cfg["balance"] == "oversample":
        tr = oversample(tr, cfg["seed"])
    vec = CountVectorizer(min_df=cfg["min_df"], ngram_range=(1, cfg["ngram"]))
    model = LogisticRegression(
        max_iter=2000, C=cfg["C"], random_state=cfg["seed"],
        class_weight="balanced" if cfg["balance"] == "weight" else None)
    model.fit(vec.fit_transform([texts[i] for i in tr]), [Y[i] for i in tr])
    return (vec, model), te


SAVES = []


def save_artifact(obj):
    """ذخیرهٔ محتوا-نشانی: نامِ فایل، اثرِ انگشتِ خودِ بایت‌هاست."""
    blob = pickle.dumps(obj, protocol=4)
    SAVES.append(None)
    sha = hashlib.sha256(blob).hexdigest()
    path = STORE / f"{sha}.pkl"
    if not path.exists():
        path.write_bytes(blob)
    return sha, len(blob)


CFG = {"features": "text+meta", "balance": "weight", "min_df": 1, "seed": 0}
bundle, test_idx = fit_model(CFG)
sha1, size1 = save_artifact(bundle)
print("اثرِ انگشتِ artifact:", sha1[:16], "· اندازه:", size1, "بایت")
```

```text-approx
اثرِ انگشتِ artifact: 2d38e7cf014f913a · اندازه: 14404 بایت
```

<div dir="rtl">

**دقت کن که چه چیزی ذخیره شد: `(vec, model)`، نه فقط `model`.** یک `LogisticRegression` تنها بی‌فایده است، چون نمی‌داند ستونِ ۳۱۷ کدام کلمه بود. **مدل و تبدیلی که ورودی‌اش را می‌سازد یک artifact واحدند** — و جدا کردنشان یکی از رایج‌ترین راه‌های شکستنِ یک استقرار است.

</div>

```python
again, _ = fit_model(CFG)
sha2, _ = save_artifact(again)
print("آموزشِ دوباره همان بایت‌ها را داد؟", sha1 == sha2)
print("ذخیره‌ها:", len(SAVES), "· فایل‌های انبار:", len(list(STORE.glob("*.pkl"))))
```

```text
آموزشِ دوباره همان بایت‌ها را داد؟ True
ذخیره‌ها: 2 · فایل‌های انبار: 1
```

<div dir="rtl">

**دو ذخیره، یک فایل.** و توجه کن که این خودش یک آزمونِ بازتولیدپذیریِ سطحِ بایت است — **همان چیزی که فصلِ ۳ رویش کار کرد، این بار روی خودِ مدل و نه روی پیش‌بینی‌ها.**

## ۲. جدولِ نسخه، با یک قاعدهٔ سخت

</div>

```python
import json
import sqlite3

reg = sqlite3.connect(WORK / "registry.db")
reg.executescript("""
CREATE TABLE model_versions (
    name         TEXT    NOT NULL,
    version      INTEGER NOT NULL,
    artifact_sha TEXT    NOT NULL,
    config_json  TEXT    NOT NULL,
    data_fp      TEXT    NOT NULL,
    code_fp      TEXT    NOT NULL,
    metric_f1    REAL    NOT NULL,
    stage        TEXT    NOT NULL,
    PRIMARY KEY (name, version)
);
CREATE UNIQUE INDEX one_production
    ON model_versions(name) WHERE stage = 'production';
""")
print("رجیستری ساخته شد")
```

```text
رجیستری ساخته شد
```

<div dir="rtl">

**آن `CREATE UNIQUE INDEX ... WHERE stage = 'production'` مهم‌ترین خطِ کلِ فصل است.**

یک شاخصِ یکتای **شرطی** است: می‌گوید برای هر `name`، حداکثر یک ردیف می‌تواند `stage` برابرِ `production` داشته باشد. **قاعده در پایگاه داده است، نه در کد** — و این تفاوتش با یک `if` در تابعِ ارتقاست: هیچ اسکریپتِ عجول، هیچ نوت‌بوکِ موازی و هیچ فراموشیِ سه ماه بعد نمی‌تواند دورش بزند.

## ۳. سه نسخه ثبت کن

</div>

```python
import inspect

CODE_FP = hashlib.sha256(inspect.getsource(fit_model).encode("utf-8")).hexdigest()[:12]
DATA_FP = hashlib.sha256(
    "\n".join(f"{t}|{g}|{y}|{x}" for t, g, y, x in zip(T, G, Y, X)).encode("utf-8")
).hexdigest()[:12]


def register(name, cfg):
    bundle, te = fit_model(cfg)
    sha, _size = save_artifact(bundle)
    vec, model = bundle
    texts = texts_for(DEFAULTS | cfg)
    pred = model.predict(vec.transform([texts[i] for i in te]))
    f1 = f1_score([Y[i] for i in te], pred, zero_division=0)
    row = reg.execute("SELECT max(version) FROM model_versions WHERE name = ?",
                      (name,)).fetchone()[0]
    version = (row or 0) + 1
    reg.execute("INSERT INTO model_versions VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
                (name, version, sha,
                 json.dumps(DEFAULTS | cfg, sort_keys=True, ensure_ascii=False),
                 DATA_FP, CODE_FP, f1, "staging"))
    reg.commit()
    return version, round(f1, 4)


NAME = "escalation"
for cfg in ({"features": "text", "balance": "oversample"},
            {"features": "text+meta", "balance": "weight", "min_df": 1},
            {"features": "text+meta", "balance": "weight", "min_df": 3}):
    v, f1 = register(NAME, cfg)
    print(f"  نسخهٔ {v}: F1 = {f1}")
print("ذخیره‌ها:", len(SAVES), "· فایل‌های انبار:",
      len(list(STORE.glob("*.pkl"))))
```

```text
  نسخهٔ 1: F1 = 0.5469
  نسخهٔ 2: F1 = 0.7126
  نسخهٔ 3: F1 = 0.7045
ذخیره‌ها: 5 · فایل‌های انبار: 3
```

<div dir="rtl">

**پنج ذخیره، سه فایل.** نسخهٔ ۲ همان پیکربندیِ بخشِ ۱ را داشت، پس بایت‌هایش قبلاً در انبار بودند و **هیچ فایلِ تازه‌ای ساخته نشد** — ولی رکوردِ نسخه‌اش ساخته شد. **این دو چیز عمداً از هم جدا شده‌اند: انبار دربارهٔ بایت‌هاست، رجیستری دربارهٔ معنا.**

**و هر ردیف چهار چیز را به هم گره می‌زند:** `artifact_sha` (کدام بایت‌ها)، `config_json` (با چه تنظیمی)، `data_fp` (روی کدام داده)، `code_fp` (با کدام کد). **بدونِ هر کدام از این چهارتا، شش ماه بعد یک سؤالِ بی‌جواب داری.**

## ۴. مرحلهٔ چرخهٔ عمر

</div>

```python
reg.execute("UPDATE model_versions SET stage = 'production'"
            " WHERE name = ? AND version = ?", (NAME, 2))
reg.commit()
try:
    reg.execute("UPDATE model_versions SET stage = 'production'"
                " WHERE name = ? AND version = ?", (NAME, 3))
except sqlite3.IntegrityError as e:
    reg.rollback()
    print(f"{type(e).__name__}: {e}")
for v, stage in reg.execute("SELECT version, stage FROM model_versions"
                            " WHERE name = ? ORDER BY version", (NAME,)):
    print(f"  نسخهٔ {v}: {stage}")
```

```text
IntegrityError: UNIQUE constraint failed: model_versions.name
  نسخهٔ 1: staging
  نسخهٔ 2: production
  نسخهٔ 3: staging
```

<div dir="rtl">

> 🔧 **اگر کار نکرد:** `sqlite3.IntegrityError: UNIQUE constraint failed: model_versions.name` دقیقاً همان چیزی است که می‌خواستیم — **پایگاه داده نگذاشت دو مدل هم‌زمان در تولید باشند.** ولی به `reg.rollback()` داخلِ `except` دقت کن: **بدونِ آن، اتصال در یک تراکنشِ نیمه‌کاره می‌ماند** و دستورِ بعدی‌ات یا شکست می‌خورد یا — بدتر — بعداً با یک `commit` ناخواسته اعمال می‌شود. **هر `IntegrityError` باید یا `rollback` شود یا اتصال بسته شود؛ نادیده گرفتنش بدترین کار است.**

**راهِ درستِ ارتقا، یک تراکنش است:**

</div>

```python
def promote(name, version):
    """ارتقا و تنزل باید یک تراکنش باشند، وگرنه لحظه‌ای دو تولید داری."""
    with reg:
        reg.execute("UPDATE model_versions SET stage = 'archived'"
                    " WHERE name = ? AND stage = 'production'", (name,))
        reg.execute("UPDATE model_versions SET stage = 'production'"
                    " WHERE name = ? AND version = ?", (name, version))


promote(NAME, 3)
for v, stage in reg.execute("SELECT version, stage FROM model_versions"
                            " WHERE name = ? ORDER BY version", (NAME,)):
    print(f"  نسخهٔ {v}: {stage}")
```

```text
  نسخهٔ 1: staging
  نسخهٔ 2: archived
  نسخهٔ 3: production
```

<div dir="rtl">

**نسخهٔ ۲ بایگانی شد، پاک نشد.** این تفاوت مهم است: **برگشت به نسخهٔ قبلی باید یک `UPDATE` باشد، نه یک آموزشِ دوباره.** و چون artifactش هنوز در انبار است، برگشت در کسری از ثانیه انجام می‌شود.

**و دقت کن که نسخهٔ ۳ با `F1` برابرِ ۰٫۷۰۴۵ به تولید رفت، در حالی که نسخهٔ ۲ عددِ ۰٫۷۱۲۶ داشت.** این عمدی است و از فصلِ ۵ می‌آید: **آن دو عدد با ده `seed` قابلِ تفکیک نبودند** (`p` برابرِ ۰٫۲۳)، پس انتخاب بر اساسِ عددِ بزرگ‌ترِ **یک** اجرا اشتباه بود.

**پس چرا نسخهٔ ۳؟** چون وقتی در بخشِ ۱ فصلِ ۵ همان دو پیکربندی را با ده `seed` سنجیدیم، میانگینشان ۰٫۶۹۵۳ و ۰٫۶۹۸۷ شد — یعنی `min_df=3` **اندکی جلوتر**، درست برعکسِ چیزی که `seed=0` نشان می‌داد. **و همان `p` برابرِ ۰٫۲۳ می‌گوید این «جلوتر» هم دلیلِ محکمی نیست:** انتخاب بین دو گزینهٔ عملاً هم‌ارز است، و کاری که رجیستری می‌کند این نیست که بگوید کدام بهتر است، این است که **بگوید کدام انتخاب شد و با چه شواهدی.** **رجیستری جای تصمیم نیست؛ جای ثبتِ تصمیم است.**

## ۵. از تولید تا داده و کد

</div>

```python
LINEAGE = """
SELECT version, artifact_sha, config_json, data_fp, code_fp, metric_f1
FROM model_versions WHERE name = ? AND stage = 'production'
"""
version, sha, cfg_json, data_fp, code_fp, metric = reg.execute(
    LINEAGE, (NAME,)).fetchone()
print("نسخهٔ تولید :", version)
print("artifact   :", sha[:16])
print("داده       :", data_fp, "· کد:", code_fp)
print("متریکِ ثبت‌شده:", round(metric, 4))
print("پیکربندی   :", json.loads(cfg_json))
```

```text-approx
نسخهٔ تولید : 3
artifact   : e5c69a36dd9d8485
داده       : 50c6fba97e38 · کد: 08688385e2fb
متریکِ ثبت‌شده: 0.7045
پیکربندی   : {'C': 1.0, 'balance': 'weight', 'features': 'text+meta', 'min_df': 3, 'ngram': 1, 'seed': 0, 'split': 'random'}
```

<div dir="rtl">

**یک پرسمان، یک ردیف، و جوابِ سؤالی که در هر جلسه‌ای پرسیده می‌شود: «این مدلی که دارد جواب می‌دهد از کجا آمده؟»**

## ۶. و حالا ثابتش کن

**ثبت کردنِ یک عدد ارزشی ندارد اگر نشود دوباره به آن رسید.**

</div>

```python
vec, model = pickle.loads((STORE / f"{sha}.pkl").read_bytes())
cfg = json.loads(cfg_json)
texts = texts_for(cfg)
_tr, te = random_split(len(Y), cfg["seed"])
pred = model.predict(vec.transform([texts[i] for i in te]))
reloaded = f1_score([Y[i] for i in te], pred, zero_division=0)
print("متریکِ ثبت‌شده  :", round(metric, 6))
print("متریکِ بازخوانده:", round(reloaded, 6))
print("اختلاف          :", abs(metric - reloaded))
print("داده همان است؟  ", data_fp == DATA_FP)
```

```text
متریکِ ثبت‌شده  : 0.704545
متریکِ بازخوانده: 0.704545
اختلاف          : 0.0
داده همان است؟   True
```

<div dir="rtl">

**اختلاف دقیقاً صفر — و آن خطِ آخر است که این را از یک شعبده به یک ادعا تبدیل می‌کند.**

اگر `data_fp` فرق می‌کرد، عددِ برابر **هیچ چیزی ثابت نمی‌کرد**، چون معلوم نبود روی چه چیزی سنجیده شده. **بازتولیدِ یک متریک بدونِ تطبیقِ اثرِ انگشتِ داده، یک تصادف است، نه یک تأیید.**

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** عددِ بازخوانده با عددی که هنگامِ ثبت نوشته شده بود. **روی کدام داده؟** روی همان `data_fp` — که در همان خط بررسی شد. **با چند `seed`؟** یکی، **و اینجا درست است**: این اندازه‌گیری دربارهٔ کیفیتِ مدل نیست، دربارهٔ **سلامتِ انبار** است. برای این ادعا `seed` باید ثابت بماند، وگرنه اصلاً همان آزمایش نیست.

> ✅ **چک کن:** یک بایت از فایلِ artifact را عوض کن (`path.write_bytes(blob[:-1] + b"\x00")`) و دوباره بارگذاری کن. **چه خطایی می‌گیری؟** بعد نامِ فایل را با `sha256` محتوایش دوباره حساب کن: **دیگر نمی‌خواند.** انبارِ محتوا-نشانی فقط تکراری‌ها را حذف نمی‌کند؛ **خرابیِ فایل را هم قابلِ تشخیص می‌کند.**

> 🤖 **از دستیارت بپرس:** «چرا `pickle` برای مدلی که از منبعِ ناشناس می‌آید خطرناک است و جایگزین‌هایش چیست؟» بعد این را هم بپرس: **«اگر نسخهٔ کتابخانه عوض شود، آیا `pickle` قدیمی هنوز بارگذاری می‌شود؟»** — جوابِ دوم مستقیماً به `env_fp` فصلِ ۳ وصل است، و دلیلِ اینکه چرا رجیستریِ واقعی محیط را هم کنارِ نسخه ثبت می‌کند.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| model registry | مدل رجیستری | جایی که نسخه‌های مدل با فراداده‌شان ثبت می‌شوند |
| artifact store | آرتیفکت استور | انبارِ فایل‌های تولیدشده، با نامِ برآمده از محتوا |
| lifecycle stage | لایف‌سایکل استیج | مرحلهٔ نسخه: staging، production، archived |
| lineage | لینیج | زنجیرهٔ مدل تا اجرا تا کد تا داده |
| partial unique index | پارشال یونیک ایندکس | یکتاییِ مشروط، فقط روی ردیف‌هایی که شرط را دارند |
| rollback | رول‌بک | برگشت به نسخهٔ قبلی، بدونِ آموزشِ دوباره |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `vec` و `model` باید در یک artifact باشند؟

**تمرینِ اجباری:** یک ستونِ `env_fp` به `model_versions` اضافه کن و در `register` پُرش کن (تابعِ `environment()` فصلِ ۳). حالا یک تابعِ `health(name)` بنویس که برای نسخهٔ تولید سه چیز را بررسی کند و یک `dict` از سه `bool` برگرداند: **فایلِ artifact وجود دارد؟ اثرِ انگشتِ داده هنوز می‌خواند؟ محیط عوض نشده؟** بعد عمداً فایلِ artifact را پاک کن و ببین کدام بند قرمز می‌شود. **این سه بند، در ترمِ ۴ و ۵، به یک بررسیِ خودکارِ قبل از هر استقرار تبدیل می‌شوند.**

**تمرینِ ستاره‌دار ⭐:** رجیستری را طوری کامل کن که **برگشت** را هم ثبت کند: یک جدولِ `stage_history` با ستون‌های `name`، `version`، `from_stage`، `to_stage`، `reason`، `changed_at`. `promote` را طوری بنویس که هر تغییرِ مرحله را آنجا هم بنویسد، و برگشت به نسخهٔ ۲ را با دلیل ثبت کن. بعد یک پرسمان بنویس که بگوید **هر نسخه چند ساعت در تولید بوده.** سؤالِ سخت: **اگر مدلی فقط دو ساعت در تولید بوده، این چه چیزی به‌ت می‌گوید؟** جوابش یکی از مفیدترین متریک‌های یک تیمِ یادگیری ماشین است.

## در فصل بعد

مدلِ تولیدمان `F1` برابرِ ۰٫۷۰۴۵ دارد، ثبت شده، قابلِ بازتولید است، و می‌شود در یک ثانیه به قبلی‌اش برگشت. **همه‌چیز مرتب است — و همین جای نگرانی دارد.**

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

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t3/s06-model-registry (یادستان, Yaadestan)
