در این فصل چه یاد میگیری#
هفت فصل، هفت تکه. اینجا همهشان یک چیز میشوند: بیست اجرای ثبتشده، یک جدولِ مقایسه، یک آزمونِ جفتشده، یک ارزیابیِ زمانی، و یک تصمیمِ مکتوب که خودش خودش را میسنجد.
و آن تصمیم «مستقر نشود» است.
منتخب آفلاین F1 برابرِ ۰٫۷۰۸۵ میدهد، روی برشِ زمانیِ بعدی ۰٫۴۲۸۰، و هزینهاش ۸۶٫۰ در برابرِ ۷۳٫۷ برای قاعدهای که هیچ مدلی لازم ندارد. و این بدشانسیِ یک نامزد نیست: هر ۴۳۲ پیکربندیِ فضا را روی همان برش سنجیدیم و ارزانترینشان ۷۷٫۴ بود — هیچکدام از خطِ پایه جلو نزدند.

آخر این فصل میتوانی:
- یک دفترِ آزمایش بسازی که پیکربندی و محیط و متریک را با هم ثبت کند
- از بیست اجرا به یک نامزد برسی، با آزمونِ جفتشده و نه با نگاه به جدول
- نامزد را روی برشِ زمانی و در برابرِ خطِ پایهٔ بیمدل بسنجی
- تصمیم را طوری بنویسی که کسی که آنجا نبوده بتواند بازبینیاش کند
قبل از شروع#
هیچ مفهومِ تازهای در این فصل نیست. ردیاب از فصلِ ۲، محیط از فصلِ ۳، بودجه و جستوجوی تصادفی از فصلِ ۴، آزمونِ جفتشده از فصلِ ۵، فراداده و پیوند از فصلِ ۶، و برشِ زمانی و هزینه از فصلِ ۷.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوتبوک روی CPU | یک تا دو دقیقه |
| GPU | لازم نیست |
۱. دفترچه#
import hashlib
import inspect
import json
import platform
import random
import sqlite3
import statistics
from datetime import datetime
from importlib.metadata import version
LAB = sqlite3.connect(WORK / "lab.db")
LAB.executescript("""
CREATE TABLE runs (
run_id TEXT PRIMARY KEY,
config_json TEXT NOT NULL,
env_fp TEXT NOT NULL,
code_fp TEXT NOT NULL,
data_fp TEXT NOT NULL,
started_at TEXT NOT NULL,
status TEXT NOT NULL
);
CREATE TABLE metrics (
run_id TEXT NOT NULL, name TEXT NOT NULL, value REAL NOT NULL,
PRIMARY KEY (run_id, name)
);
""")
ENV = {"python": platform.python_version(), "machine": platform.machine(),
**{p: version(p) for p in ("scikit-learn", "numpy", "scipy")}}
ENV_FP = hashlib.sha256(json.dumps(ENV, sort_keys=True).encode()).hexdigest()[:12]
CODE_FP = hashlib.sha256(inspect.getsource(run).encode()).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()
).hexdigest()[:12]
def canonical(cfg):
return json.dumps(DEFAULTS | cfg, sort_keys=True, ensure_ascii=False)
def log_run(cfg):
rid = hashlib.sha256(canonical(cfg).encode()).hexdigest()[:12]
LAB.execute("INSERT INTO runs VALUES (?, ?, ?, ?, ?, ?, ?)",
(rid, canonical(cfg), ENV_FP, CODE_FP, DATA_FP,
datetime.now().isoformat(timespec="seconds"), "running"))
metrics = run(cfg)
LAB.executemany("INSERT INTO metrics VALUES (?, ?, ?)",
[(rid, k, v) for k, v in metrics.items()])
LAB.execute("UPDATE runs SET status = 'done' WHERE run_id = ?", (rid,))
LAB.commit()
return rid
print("دفترچه آماده است · env_fp:", ENV_FP != "", "· data_fp:", DATA_FP)
دفترچه آماده است · env_fp: True · data_fp: 50c6fba97e38
سه اثرِ انگشت کنارِ هر اجرا: محیط، کد، داده. فصلِ ۲ دوتایش را داشت؛ سومی از فصلِ ۳ آمد.
۲. بیست اجرا، با بودجه#
SPACE = {"features": ["text", "meta", "text+meta"],
"balance": ["none", "oversample", "weight"],
"ngram": [1, 2], "min_df": [1, 2, 3, 5],
"C": [0.03, 0.1, 0.3, 1.0, 3.0, 10.0]}
rng = random.Random(0)
tried, drawn = [], 0
while len(tried) < 20:
drawn += 1
cfg = {k: rng.choice(v) for k, v in SPACE.items()}
try:
log_run(cfg)
tried.append(cfg)
except sqlite3.IntegrityError:
LAB.rollback()
print("قرعهها:", drawn, "· اجراهای تازه:", len(tried),
"· تکراری:", drawn - len(tried))
قرعهها: 20 · اجراهای تازه: 20 · تکراری: 0
جستوجوی تصادفی با بودجهٔ ۲۰ — همان چیزی که فصلِ ۴ نشان داد از شبکهٔ همبودجه بهتر است. و حلقهاش با IntegrityError کنار میآید، پس میشود همین سلول را دوباره اجرا کرد و فقط چیزهای تازه اضافه شوند.
BOARD = """
SELECT r.config_json, MAX(CASE WHEN m.name='f1' THEN m.value END) AS f1
FROM runs r JOIN metrics m ON m.run_id = r.run_id
WHERE r.status = 'done' GROUP BY r.run_id ORDER BY f1 DESC LIMIT 5
"""
def label(cfg):
diff = {k: v for k, v in cfg.items() if DEFAULTS[k] != v and k != "seed"}
return " ".join(f"{k}={v}" for k, v in sorted(diff.items())) or "پیشفرض"
top = [(json.loads(cj), f1) for cj, f1 in LAB.execute(BOARD)]
print(f" {'#':<3}{'F1':>8} پیکربندی")
for i, (cfg, f1) in enumerate(top, start=1):
print(f" {i:<3}{f1:>8.4f} {label(cfg)}")
# F1 پیکربندی
1 0.7085 balance=weight features=text+meta min_df=5
2 0.6868 C=0.3 balance=oversample features=text+meta min_df=5
3 0.6587 C=0.03 balance=oversample features=text+meta ngram=2
4 0.6559 C=0.3 balance=oversample features=text+meta min_df=2 ngram=2
5 0.6534 C=0.03 balance=weight features=text+meta min_df=5 ngram=2
هر پنج ردیف features=text+meta دارند. با بیست قرعه، مهمترین محور خودش را نشان میدهد — و این تنها چیزی است که یک جستوجوی کوچک واقعاً بهت میگوید.
۳. رتبهٔ ۱ در برابرِ رتبهٔ ۲#
import itertools
SEEDS = list(range(5))
def with_seeds(cfg):
return [run({k: v for k, v in cfg.items() if k != "seed"} | {"seed": s})["f1"]
for s in SEEDS]
first, second = with_seeds(top[0][0]), with_seeds(top[1][0])
d = [a - b for a, b in zip(first, second)]
observed = abs(statistics.mean(d))
p = sum(1 for signs in itertools.product((1, -1), repeat=len(d))
if abs(statistics.mean([s * v for s, v in zip(signs, d)])) >= observed) / 2 ** len(d)
print(f"رتبهٔ ۱ با پنج seed: {statistics.mean(first):.4f}"
f" [{min(first):.3f}–{max(first):.3f}]")
print(f"رتبهٔ ۲ با پنج seed: {statistics.mean(second):.4f}"
f" [{min(second):.3f}–{max(second):.3f}]")
print(f"اختلافِ جفتشده: {statistics.mean(d):+.4f} · p = {p:.4f}")
رتبهٔ ۱ با پنج seed: 0.6939 [0.660–0.711]
رتبهٔ ۲ با پنج seed: 0.6770 [0.638–0.715]
اختلافِ جفتشده: +0.0169 · p = 0.1250
p برابرِ ۰٫۱۲۵ است، و با پنج جفت کمترین p ممکن ۰٫۰۶۲۵ است. پس این آزمون در بهترین حالتش هم نمیتوانست به آستانهٔ ۰٫۰۵ برسد — محدودیت در داده نیست، در تعدادِ seed است.
گزارشِ صادقانه: رتبهٔ ۱ را برمیداریم چون میانگینش بالاتر است، ولی نمیتوانیم ادعا کنیم بهتر است. این دو جمله فرق دارند و هر دو در تصمیمنامه نوشته میشوند.
۴. آزمونِ واقعی#
from sklearn.feature_extraction.text import CountVectorizer
from sklearn.linear_model import LogisticRegression
MISS, ALARM = 5, 1
CUT = int(0.75 * len(Y))
TR, TE = list(range(CUT)), list(range(CUT, len(Y)))
def deploy_eval(cfg, seed=0):
cfg = DEFAULTS | cfg | {"seed": seed}
texts = texts_for(cfg)
tr = oversample(TR, seed) if cfg["balance"] == "oversample" else TR
vec = CountVectorizer(min_df=cfg["min_df"], ngram_range=(1, cfg["ngram"]))
model = LogisticRegression(
max_iter=2000, C=cfg["C"], random_state=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])
pred = model.predict(vec.transform([texts[i] for i in TE]))
gold = [Y[i] for i in TE]
tp = sum(1 for a, b in zip(pred, gold) if a == 1 and b == 1)
fp = sum(1 for a, b in zip(pred, gold) if a == 1 and b == 0)
fn = sum(1 for a, b in zip(pred, gold) if a == 0 and b == 1)
f1 = 2 * tp / (2 * tp + fp + fn) if tp else 0.0
return {"f1": f1, "fp": fp, "fn": fn,
"cost": 100 * (MISS * fn + ALARM * fp) / len(TE)}
FINAL = {k: v for k, v in top[0][0].items() if k != "seed"}
res = deploy_eval(FINAL)
always = 100 * ALARM * sum(1 for i in TE if Y[i] == 0) / len(TE)
never = 100 * MISS * sum(Y[i] for i in TE) / len(TE)
print(f"منتخب — F1 آفلاین : {top[0][1]:.4f}")
print(f"منتخب — F1 روی آینده: {res['f1']:.4f}")
print(f"هزینهٔ منتخب : {res['cost']:.1f}")
print(f"هزینهٔ «همیشه هشدار» : {always:.1f}")
print(f"هزینهٔ «هیچوقت هشدار»: {never:.1f}")
print("منتخب از خطِ پایه ارزانتر است؟", res["cost"] < min(always, never))
منتخب — F1 آفلاین : 0.7085
منتخب — F1 روی آینده: 0.4280
هزینهٔ منتخب : 86.0
هزینهٔ «همیشه هشدار» : 73.7
هزینهٔ «هیچوقت هشدار»: 131.6
منتخب از خطِ پایه ارزانتر است؟ False
۰٫۷۰۸۵ روی کاغذ، ۰٫۴۲۸۰ در عمل، و در آخر یک False.
حالا سؤالِ درست را بپرس: چه چیزی باید عوض شود تا این False به True تبدیل شود؟
breakeven = (always - res["fp"] * ALARM * 100 / len(TE)) / (res["fn"] * 100 / len(TE))
print(f"نسبتِ هزینهٔ فعلی (نادیده گرفتن به هشدارِ بیجا): {MISS}")
print(f"نسبتی که در آن منتخب و خطِ پایه برابر میشوند : {breakeven:.2f}")
print("پس منتخب فقط وقتی میارزد که این نسبت کمتر از آن باشد.")
نسبتِ هزینهٔ فعلی (نادیده گرفتن به هشدارِ بیجا): 5
نسبتی که در آن منتخب و خطِ پایه برابر میشوند : 3.96
پس منتخب فقط وقتی میارزد که این نسبت کمتر از آن باشد.
۳٫۹۶ عددِ قابلِ گفتگویی است و ۸۶٫۰ نیست.
جملهٔ «مدل خوب نیست» بحثناپذیر است. جملهٔ «اگر نادیده گرفتنِ یک تشدید حدودِ دو تا چهار هشدارِ بیجا برایتان هزینه دارد، این مدل میارزد؛ کمتر از آن «هیچوقت هشدار نده» ارزانتر است و بیشتر از آن «همیشه هشدار بده»» یک سؤالِ مشخص به کسی میدهد که جوابش را میداند و تو نمیدانی.
و برای اینکه معلوم شود این مالِ یک نامزدِ بدشانس نیست:
grid = [dict(zip(SPACE, v)) for v in itertools.product(*SPACE.values())]
costs = [deploy_eval(c)["cost"] for c in grid]
print("همهٔ پیکربندیهای فضا:", len(grid))
print(f"ارزانترینشان روی برشِ آینده: {min(costs):.1f}")
print(f"خطِ پایهٔ «همیشه هشدار بده» : {always:.1f}")
print("چند تا از خطِ پایه ارزانترند:", sum(1 for c in costs if c < always))
همهٔ پیکربندیهای فضا: 432
ارزانترینشان روی برشِ آینده: 77.4
خطِ پایهٔ «همیشه هشدار بده» : 73.7
چند تا از خطِ پایه ارزانترند: 0
صفر از ۴۳۲. این دیگر دربارهٔ انتخابِ ابرپارامتر نیست؛ دربارهٔ این است که این خانوادهٔ مدل، روی این داده، با این معیارِ هزینه، هنوز به دردِ استقرار نمیخورد.
📏 اندازه بگیر: با چه چیزی مقایسه شد؟ با دو خطِ پایهٔ بیمدل، و با کلِ فضای جستوجو. روی کدام داده؟ ۳۹۹ ردیفِ آخرِ زمانی که هیچکدام در آموزش نبودند. با چند
seed؟ جدولِ نامزدها با پنجتا؛ ارزیابیِ زمانی با یکی، چون تقسیمش ثابت است وseedفقط ترتیبِ فرانمونه را عوض میکند — و همین را باید در تصمیمنامه نوشت، نه پنهان کرد.
۵. تصمیمنامه#
DECISION = WORK / "decision.json"
record = {
"تاریخ": "ثبتشده در دفترچه",
"نامزدها": len(tried),
"منتخب": FINAL,
"f1_آفلاین": round(top[0][1], 4),
"f1_آینده": round(res["f1"], 4),
"شکاف": round(top[0][1] - res["f1"], 4),
"p_برابرِ_رتبهٔ_دوم": round(p, 4),
"هزینهٔ_منتخب": round(res["cost"], 1),
"هزینهٔ_خط_پایه": round(min(always, never), 1),
"نسبتِ_سربهسر": round(breakeven, 2),
"تصمیم": "مستقر نشود",
"دلیل": "روی برشِ زمانیِ بعدی از قاعدهٔ یکخطیِ «همیشه هشدار بده» گرانتر است",
"شرطِ_بازنگری": "اگر نسبتِ هزینه کمتر از نسبتِ سربهسر باشد، یا با پنجرهٔ لغزان بازآموزی شود",
"env_fp": ENV_FP, "code_fp": CODE_FP, "data_fp": DATA_FP,
}
DECISION.write_text(json.dumps(record, ensure_ascii=False, indent=1), encoding="utf-8")
for k, v in record.items():
print(f" {k:<20}{v}")
تاریخ ثبتشده در دفترچه
نامزدها 20
منتخب {'C': 1.0, 'balance': 'weight', 'features': 'text+meta', 'min_df': 5, 'ngram': 1, 'split': 'random'}
f1_آفلاین 0.7085
f1_آینده 0.428
شکاف 0.2805
p_برابرِ_رتبهٔ_دوم 0.125
هزینهٔ_منتخب 86.0
هزینهٔ_خط_پایه 73.7
نسبتِ_سربهسر 3.96
تصمیم مستقر نشود
دلیل روی برشِ زمانیِ بعدی از قاعدهٔ یکخطیِ «همیشه هشدار بده» گرانتر است
شرطِ_بازنگری اگر نسبتِ هزینه کمتر از نسبتِ سربهسر باشد، یا با پنجرهٔ لغزان بازآموزی شود
env_fp 645d3df95dd6
code_fp 021b7189d7d5
data_fp 50c6fba97e38
«شرطِ بازنگری» مهمترین سطرِ این تصمیمنامه است. یک تصمیمِ «نه» بدونِ شرطِ بازنگری، یک بنبست است؛ با شرطِ بازنگری، یک وظیفه برای آینده است.
۶. سیاههٔ تحویل#
def checklist():
n_runs = LAB.execute("SELECT count(*) FROM runs").fetchone()[0]
n_ids = LAB.execute("SELECT count(DISTINCT run_id) FROM runs").fetchone()[0]
envs = LAB.execute("SELECT count(DISTINCT env_fp) FROM runs").fetchone()[0]
saved = json.loads(DECISION.read_text(encoding="utf-8"))
checks = [
("هر اجرا پیکربندیِ کامل دارد",
all(set(json.loads(cj)) == set(DEFAULTS)
for (cj,) in LAB.execute("SELECT config_json FROM runs"))),
("هیچ اجرای تکراری ثبت نشده", n_runs == n_ids),
("همهٔ اجراها در یک محیط بودهاند", envs == 1),
("تصمیم روی چند seed گرفته شده", len(SEEDS) >= 5),
("اختلافِ دو نامزدِ اول با آزمونِ جفتشده سنجیده شده", "p_برابرِ_رتبهٔ_دوم" in saved),
("منتخب روی برشِ زمانی هم سنجیده شده", "f1_آینده" in saved),
("عددِ نهایی با خطِ پایهٔ بیمدل مقایسه شده", "هزینهٔ_خط_پایه" in saved),
("تصمیم و دلیلش مکتوب است", bool(saved["تصمیم"]) and bool(saved["دلیل"])),
]
for name, ok in checks:
print((" [درست] " if ok else " [غلط ] ") + name)
return all(ok for _n, ok in checks)
print("سیاههٔ تحویل کامل است:", checklist())
[درست] هر اجرا پیکربندیِ کامل دارد
[درست] هیچ اجرای تکراری ثبت نشده
[درست] همهٔ اجراها در یک محیط بودهاند
[درست] تصمیم روی چند seed گرفته شده
[درست] اختلافِ دو نامزدِ اول با آزمونِ جفتشده سنجیده شده
[درست] منتخب روی برشِ زمانی هم سنجیده شده
[درست] عددِ نهایی با خطِ پایهٔ بیمدل مقایسه شده
[درست] تصمیم و دلیلش مکتوب است
سیاههٔ تحویل کامل است: True
هشت ادعا، هشتتا اجراشدنی — و هیچکدامشان نمیگویند «مدل خوب است».
همهشان دربارهٔ فرآیندند، نه دربارهٔ نتیجه، و این عمدی است: یک سیاههٔ تحویل نمیتواند تضمین کند مدلت کار میکند؛ فقط میتواند تضمین کند اگر کار نکند، خودت اولین کسی هستی که میفهمد.
🔧 اگر کار نکرد: اگر بندِ «همهٔ اجراها در یک محیط بودهاند»
[غلط]شد، یعنی نوتبوک را در دو نشستِ متفاوت با نسخههای متفاوت اجرا کردهای و جدولت اجراهایی از دو دنیا دارد. علاجش پاک کردنِ آن اجراها نیست؛ افزودنِenv_fpبه گروهبندیِ جدولِ مقایسه است تا فقط چیزهای همسنگ با هم مقایسه شوند. و اگر بندِ «هیچ اجرای تکراری» غلط شد، جاییINSERT OR REPLACEنوشتهای — همان تلهٔ فصلِ ۲.
✅ چک کن: یک بندِ نهم اضافه کن: «منتخب از خطِ پایه ارزانتر است». حالا سیاهه
Falseمیدهد. همانجا بگذارش. یک سیاههٔ تحویلی که همیشه سبز است، هیچوقت چیزی بهت نگفته.
🤖 از دستیارت بپرس: «یک تصمیمنامهٔ مدل چه بخشهایی باید داشته باشد؟» بعد این را هم بپرس: «اگر شش ماه بعد داده عوض شده باشد، کدام بخشهای این تصمیمنامه دیگر معتبر نیستند؟» — جوابِ دوم دقیقاً همان چیزی است که ترمِ ۵ رویش ساخته میشود.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| lab notebook | لب نوتبوک | دفترِ ثبتِ همهٔ آزمایشها و تصمیمها |
| decision record | دسیژن رکورد | نوشتنِ تصمیم، دلیلش، و شرطِ بازنگریاش |
| break-even ratio | بریک-ایون ریشیو | نسبتی که در آن دو گزینه هزینهٔ برابر پیدا میکنند |
| delivery checklist | دلیوری چکلیست | فهرستِ ادعاهایی که خودشان اجرا و سنجیده میشوند |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
دفترِ آزمایشت کامل است، تصمیمت مکتوب، و مدلت — با شواهد — مستقر نشد. ترمِ بعد همان مدلی را برمیدارد که مستقر میشود و میپرسد: چطور به دستِ کاربر میرسد؟ بستهبندی، سرویس، صف، cache، انتشارِ تدریجی، و طرحِ برگشت. و اولین چیزی که آنجا لازم میشود، دقیقاً همان artifact_sha و همان تصمیمنامهای است که اینجا ساختیم — چون استقراری که نداند چه چیزی را مستقر میکند، برگشت هم ندارد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.