در این فصل چه یاد میگیری#
یک مدلِ آموزشدیده در نوتبوک یک متغیر است و با بسته شدنِ نشست از بین میرود. این فصل آن را به یک محصولِ نسخهدار تبدیل میکند — با انبارِ محتوا-نشانی، جدولِ نسخه، مرحلهٔ چرخهٔ عمر، و پیوند به همان اجرایی که ساختش.
و آزمونِ نهاییاش یک عدد است: مدلی که از رجیستری بارگذاری میشود، دقیقاً همان F1 برابرِ ۰٫۷۰۴۵۴۵ را میدهد که موقعِ ثبت گزارش شده بود — اختلاف 0.0.
در راه دو چیزِ دیگر هم اندازه میگیریم: پنج بار ذخیره، سه فایل (انبارِ محتوا-نشانی تکراریها را خودش حذف میکند)، و یک قاعدهٔ پایگاه داده که دو نسخهٔ همزمان در تولید را غیرممکن میکند.

آخر این فصل میتوانی:
- انبارِ artifact محتوا-نشانی بسازی و تکراریها را خودکار حذف کنی
- مرحلهٔ چرخهٔ عمر را طوری پیاده کنی که پایگاه داده جلوی حالتِ غلط را بگیرد
- از مدلِ تولید به پیکربندی و داده و کدش برسی، با یک پرسمان
- ثابت کنی مدلِ ذخیرهشده همان عددی را میدهد که ادعا شده
قبل از شروع#
از فصلِ ۱ تا ۵: run(cfg)، اثرِ انگشتِ داده و کد، و برندهای که در فصلِ ۵ صادقانه انتخاب شد.
از ترمِ ۲: اثرِ انگشتِ محتوا برای فایل. اینجا همان ایده روی فایلِ مدل بهکار میرود.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوتبوک روی CPU | کمتر از یک دقیقه |
| GPU | لازم نیست |
۱. انبارِ محتوا-نشانی#
نامِ فایل را از محتوایش بساز، نه از تاریخ و نه از یک شمارنده. model_final_v2_REAL.pkl نامِ آشنایی است و دقیقاً همان مشکلی را دارد که بهنظر میرسد.
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, "بایت")
اثرِ انگشتِ artifact: 2d38e7cf014f913a · اندازه: 14404 بایت
دقت کن که چه چیزی ذخیره شد: (vec, model)، نه فقط model. یک LogisticRegression تنها بیفایده است، چون نمیداند ستونِ ۳۱۷ کدام کلمه بود. مدل و تبدیلی که ورودیاش را میسازد یک artifact واحدند — و جدا کردنشان یکی از رایجترین راههای شکستنِ یک استقرار است.
again, _ = fit_model(CFG)
sha2, _ = save_artifact(again)
print("آموزشِ دوباره همان بایتها را داد؟", sha1 == sha2)
print("ذخیرهها:", len(SAVES), "· فایلهای انبار:", len(list(STORE.glob("*.pkl"))))
آموزشِ دوباره همان بایتها را داد؟ True
ذخیرهها: 2 · فایلهای انبار: 1
دو ذخیره، یک فایل. و توجه کن که این خودش یک آزمونِ بازتولیدپذیریِ سطحِ بایت است — همان چیزی که فصلِ ۳ رویش کار کرد، این بار روی خودِ مدل و نه روی پیشبینیها.
۲. جدولِ نسخه، با یک قاعدهٔ سخت#
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("رجیستری ساخته شد")
رجیستری ساخته شد
آن CREATE UNIQUE INDEX ... WHERE stage = 'production' مهمترین خطِ کلِ فصل است.
یک شاخصِ یکتای شرطی است: میگوید برای هر name، حداکثر یک ردیف میتواند stage برابرِ production داشته باشد. قاعده در پایگاه داده است، نه در کد — و این تفاوتش با یک if در تابعِ ارتقاست: هیچ اسکریپتِ عجول، هیچ نوتبوکِ موازی و هیچ فراموشیِ سه ماه بعد نمیتواند دورش بزند.
۳. سه نسخه ثبت کن#
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"))))
نسخهٔ 1: F1 = 0.5469
نسخهٔ 2: F1 = 0.7126
نسخهٔ 3: F1 = 0.7045
ذخیرهها: 5 · فایلهای انبار: 3
پنج ذخیره، سه فایل. نسخهٔ ۲ همان پیکربندیِ بخشِ ۱ را داشت، پس بایتهایش قبلاً در انبار بودند و هیچ فایلِ تازهای ساخته نشد — ولی رکوردِ نسخهاش ساخته شد. این دو چیز عمداً از هم جدا شدهاند: انبار دربارهٔ بایتهاست، رجیستری دربارهٔ معنا.
و هر ردیف چهار چیز را به هم گره میزند: artifact_sha (کدام بایتها)، config_json (با چه تنظیمی)، data_fp (روی کدام داده)، code_fp (با کدام کد). بدونِ هر کدام از این چهارتا، شش ماه بعد یک سؤالِ بیجواب داری.
۴. مرحلهٔ چرخهٔ عمر#
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}")
IntegrityError: UNIQUE constraint failed: model_versions.name
نسخهٔ 1: staging
نسخهٔ 2: production
نسخهٔ 3: staging
🔧 اگر کار نکرد:
sqlite3.IntegrityError: UNIQUE constraint failed: model_versions.nameدقیقاً همان چیزی است که میخواستیم — پایگاه داده نگذاشت دو مدل همزمان در تولید باشند. ولی بهreg.rollback()داخلِexceptدقت کن: بدونِ آن، اتصال در یک تراکنشِ نیمهکاره میماند و دستورِ بعدیات یا شکست میخورد یا — بدتر — بعداً با یکcommitناخواسته اعمال میشود. هرIntegrityErrorباید یاrollbackشود یا اتصال بسته شود؛ نادیده گرفتنش بدترین کار است.
راهِ درستِ ارتقا، یک تراکنش است:
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}")
نسخهٔ 1: staging
نسخهٔ 2: archived
نسخهٔ 3: production
نسخهٔ ۲ بایگانی شد، پاک نشد. این تفاوت مهم است: برگشت به نسخهٔ قبلی باید یک UPDATE باشد، نه یک آموزشِ دوباره. و چون artifactش هنوز در انبار است، برگشت در کسری از ثانیه انجام میشود.
و دقت کن که نسخهٔ ۳ با F1 برابرِ ۰٫۷۰۴۵ به تولید رفت، در حالی که نسخهٔ ۲ عددِ ۰٫۷۱۲۶ داشت. این عمدی است و از فصلِ ۵ میآید: آن دو عدد با ده seed قابلِ تفکیک نبودند (p برابرِ ۰٫۲۳)، پس انتخاب بر اساسِ عددِ بزرگترِ یک اجرا اشتباه بود.
پس چرا نسخهٔ ۳؟ چون وقتی در بخشِ ۱ فصلِ ۵ همان دو پیکربندی را با ده seed سنجیدیم، میانگینشان ۰٫۶۹۵۳ و ۰٫۶۹۸۷ شد — یعنی min_df=3 اندکی جلوتر، درست برعکسِ چیزی که seed=0 نشان میداد. و همان p برابرِ ۰٫۲۳ میگوید این «جلوتر» هم دلیلِ محکمی نیست: انتخاب بین دو گزینهٔ عملاً همارز است، و کاری که رجیستری میکند این نیست که بگوید کدام بهتر است، این است که بگوید کدام انتخاب شد و با چه شواهدی. رجیستری جای تصمیم نیست؛ جای ثبتِ تصمیم است.
۵. از تولید تا داده و کد#
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))
نسخهٔ تولید : 3
artifact : e5c69a36dd9d8485
داده : 50c6fba97e38 · کد: 08688385e2fb
متریکِ ثبتشده: 0.7045
پیکربندی : {'C': 1.0, 'balance': 'weight', 'features': 'text+meta', 'min_df': 3, 'ngram': 1, 'seed': 0, 'split': 'random'}
یک پرسمان، یک ردیف، و جوابِ سؤالی که در هر جلسهای پرسیده میشود: «این مدلی که دارد جواب میدهد از کجا آمده؟»
۶. و حالا ثابتش کن#
ثبت کردنِ یک عدد ارزشی ندارد اگر نشود دوباره به آن رسید.
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)
متریکِ ثبتشده : 0.704545
متریکِ بازخوانده: 0.704545
اختلاف : 0.0
داده همان است؟ True
اختلاف دقیقاً صفر — و آن خطِ آخر است که این را از یک شعبده به یک ادعا تبدیل میکند.
اگر data_fp فرق میکرد، عددِ برابر هیچ چیزی ثابت نمیکرد، چون معلوم نبود روی چه چیزی سنجیده شده. بازتولیدِ یک متریک بدونِ تطبیقِ اثرِ انگشتِ داده، یک تصادف است، نه یک تأیید.
📏 اندازه بگیر: با چه چیزی مقایسه شد؟ عددِ بازخوانده با عددی که هنگامِ ثبت نوشته شده بود. روی کدام داده؟ روی همان
data_fp— که در همان خط بررسی شد. با چندseed؟ یکی، و اینجا درست است: این اندازهگیری دربارهٔ کیفیتِ مدل نیست، دربارهٔ سلامتِ انبار است. برای این ادعاseedباید ثابت بماند، وگرنه اصلاً همان آزمایش نیست.
✅ چک کن: یک بایت از فایلِ artifact را عوض کن (
path.write_bytes(blob[:-1] + b"\x00")) و دوباره بارگذاری کن. چه خطایی میگیری؟ بعد نامِ فایل را باsha256محتوایش دوباره حساب کن: دیگر نمیخواند. انبارِ محتوا-نشانی فقط تکراریها را حذف نمیکند؛ خرابیِ فایل را هم قابلِ تشخیص میکند.
🤖 از دستیارت بپرس: «چرا
pickleبرای مدلی که از منبعِ ناشناس میآید خطرناک است و جایگزینهایش چیست؟» بعد این را هم بپرس: «اگر نسخهٔ کتابخانه عوض شود، آیاpickleقدیمی هنوز بارگذاری میشود؟» — جوابِ دوم مستقیماً بهenv_fpفصلِ ۳ وصل است، و دلیلِ اینکه چرا رجیستریِ واقعی محیط را هم کنارِ نسخه ثبت میکند.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| model registry | مدل رجیستری | جایی که نسخههای مدل با فرادادهشان ثبت میشوند |
| artifact store | آرتیفکت استور | انبارِ فایلهای تولیدشده، با نامِ برآمده از محتوا |
| lifecycle stage | لایفسایکل استیج | مرحلهٔ نسخه: staging، production، archived |
| lineage | لینیج | زنجیرهٔ مدل تا اجرا تا کد تا داده |
| partial unique index | پارشال یونیک ایندکس | یکتاییِ مشروط، فقط روی ردیفهایی که شرط را دارند |
| rollback | رولبک | برگشت به نسخهٔ قبلی، بدونِ آموزشِ دوباره |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
مدلِ تولیدمان F1 برابرِ ۰٫۷۰۴۵ دارد، ثبت شده، قابلِ بازتولید است، و میشود در یک ثانیه به قبلیاش برگشت. همهچیز مرتب است — و همین جای نگرانی دارد.
فصلِ بعد نشان میدهد که این عدد روی دنیایی سنجیده شده که دیگر وجود ندارد. دو مدلِ تازه را، یکی با فراداده و یکی با متن، روی بُرشِ زمانیِ بعدیِ داده میسنجیم و ترتیبشان کاملاً برعکس میشود: مدلی که آفلاین با اختلافِ روشن جلو بود، در استقرار با اختلافِ روشن عقب میافتد. و هیچکدام از دامنههایشان با هم همپوشانی ندارد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.