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

آخر این فصل میتوانی:
- ردیابِ آزمایش را با
sqlite3از صفر بنویسی - ثبتِ دوبارهٔ یک اجرا را به یک خطای پایگاه داده تبدیل کنی، نه یک ردیفِ اضافه
- جدولِ مقایسه را با یک پرسمانِ
SQLبگیری - بگویی کدام بخشِ جدول قابلِ اتکاست و کدام بخشش نویز است
قبل از شروع#
از فصلِ ۱: پیکربندی بهعنوان داده، run(cfg)، run_id از اثرِ انگشتِ پیکربندی، و اثرِ انگشتِ کد و داده. همان run و DEFAULTS در سلولِ راهاندازی هستند و اینجا فقط صدایشان میزنیم.
از ترمِ ۲: sqlite3 و فهرستِ نسخهها — همانجا اولین جدولِ ثبت را ساختیم. اینجا همان ابزار روی آزمایش بهکار میرود.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوتبوک روی CPU | یک تا دو دقیقه |
| GPU | لازم نیست |
۱. دو جدول، و نه بیشتر#
تصمیمِ طراحی: پیکربندی در یک ستونِ متنی میرود، متریک در جدولی جدا.
چرا پیکربندی ستونبندی نمیشود؟ چون هر بار که یک کلیدِ تازه به DEFAULTS اضافه کنی، باید جدول را عوض کنی — و در تمرینِ فصلِ ۴ دقیقاً همین کار را میکنی. چرا متریک جدولِ جداست؟ چون تعدادِ متریکها هم عوض میشود، و چون میخواهیم بتوانیم یک متریک را برای همهٔ اجراها بگیریم بدونِ اینکه بدانیم چند متریک وجود دارد.
import sqlite3
DB = WORK / "tracker.db"
db = sqlite3.connect(DB)
db.executescript("""
CREATE TABLE runs (
run_id TEXT PRIMARY KEY,
config_json 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 REFERENCES runs(run_id),
name TEXT NOT NULL,
value REAL NOT NULL,
PRIMARY KEY (run_id, name)
);
""")
print("جدولها:", [r[0] for r in db.execute(
"SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")])
جدولها: ['metrics', 'runs']
run_id کلیدِ اصلی است و این یک تصمیمِ حسابشده است، نه یک عادت. بخشِ ۳ نشان میدهد چه چیزی را برایمان میگیرد.
دو جدول یعنی دو کلمهٔ تازهٔ SQL. ترمِ ۲ فصلِ ۴ جدول و INSERT و SELECT ... WHERE را ساخت؛ آنجا همیشه یک جدول در کار بود. حالا که دوتا شد، دو ابزار لازم میشود:
JOIN— دو جدول را از روی ستونِ مشترکشان کنارِ هم میگذارد.... FROM runs r JOIN metrics m ON m.run_id = r.run_idیعنی «هر ردیفِmetricsرا کنارِ آن ردیفِrunsبگذار کهrun_idشان یکی است». حرفِrوmفقط نامِ کوتاهِ همان جدولاند.GROUP BY— ردیفها را دسته میکند و از هر دسته یک ردیف میسازد. هر تابعی که در ستونها بیاید (count(*)،max(...)،avg(...)) روی همان دسته حساب میشود.
روی دو ردیفِ اسباببازی، هر سه حالت پشتِ سرِ هم:
demo = sqlite3.connect(":memory:")
demo.executescript("""
CREATE TABLE toy_runs (run_id TEXT PRIMARY KEY, note TEXT);
CREATE TABLE toy_metrics (run_id TEXT, name TEXT, value REAL);
INSERT INTO toy_runs VALUES ('r1', 'پایه'), ('r2', 'فرانمونه');
INSERT INTO toy_metrics VALUES ('r1', 'f1', 0.40), ('r1', 'recall', 0.31),
('r2', 'f1', 0.55), ('r2', 'recall', 0.59);
""")
QUERIES = [
("جدولِ metrics بهتنهایی",
"SELECT run_id, name, value FROM toy_metrics"),
("JOIN: هر متریک با ردیفِ اجرایش",
"SELECT r.note, m.name, m.value FROM toy_runs r"
" JOIN toy_metrics m ON m.run_id = r.run_id"),
("GROUP BY: یک ردیف بهازای هر نامِ متریک",
"SELECT m.name, count(*), max(m.value) FROM toy_metrics m"
" GROUP BY m.name ORDER BY m.name"),
]
for title, sql in QUERIES:
print(title)
for row in demo.execute(sql):
print(" ", " ".join(str(v) for v in row))
جدولِ metrics بهتنهایی
r1 f1 0.4
r1 recall 0.31
r2 f1 0.55
r2 recall 0.59
JOIN: هر متریک با ردیفِ اجرایش
پایه f1 0.4
پایه recall 0.31
فرانمونه f1 0.55
فرانمونه recall 0.59
GROUP BY: یک ردیف بهازای هر نامِ متریک
f1 2 0.55
recall 2 0.59
به تعدادِ ردیفها نگاه کن: چهار، چهار، دو. JOIN ردیف اضافه نکرد — فقط ستونِ note را کنارِ هر متریک آورد. GROUP BY چهار ردیف را به دو دسته کوچک کرد و در هر دسته count و max حساب شد.
و یک قاعده که بعداً به دردت میخورد: بیشتر از این SQL لازم نداریم. پرسمانهای این دوره همیشه دادهٔ خام را میآورند و شکل دادن به جدولِ نهایی در پایتون انجام میشود — چون پایتون را بلدی و در آن میشود تست نوشت.
۲. ثبت، قبل از اجرا#
ترتیبِ داخلِ log_run مهمتر از خودِ log_run است: اول ردیفِ اجرا نوشته میشود، بعد آزمایش اجرا میشود.
اگر برعکس بود، هر اجرایی که وسطش میشکست هیچ ردی از خودش باقی نمیگذاشت — و شکستها دقیقاً همان چیزهاییاند که فراموش میشوند و دوباره تکرار میشوند.
import hashlib
import inspect
import json
from datetime import datetime
CODE_FP = hashlib.sha256(inspect.getsource(run).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 canonical(cfg):
return json.dumps(DEFAULTS | cfg, sort_keys=True, ensure_ascii=False)
def run_id(cfg):
return hashlib.sha256(canonical(cfg).encode("utf-8")).hexdigest()[:12]
def log_run(cfg):
"""اجرا را قبل از شروع ثبت میکند، بعد اجرا میکند، بعد نتیجه را مینویسد."""
rid = run_id(cfg)
db.execute("INSERT INTO runs VALUES (?, ?, ?, ?, ?, ?)",
(rid, canonical(cfg), CODE_FP, DATA_FP,
datetime.now().isoformat(timespec="seconds"), "running"))
db.commit()
try:
metrics = run(cfg)
except Exception as exc: # اجرا شکست خورد
db.execute("UPDATE runs SET status = ? WHERE run_id = ?",
(f"failed:{type(exc).__name__}", rid))
db.commit()
raise
db.executemany("INSERT INTO metrics VALUES (?, ?, ?)",
[(rid, k, v) for k, v in metrics.items()])
db.execute("UPDATE runs SET status = 'done' WHERE run_id = ?", (rid,))
db.commit()
return rid
print("ثبت شد:", log_run({"balance": "oversample"}))
ثبت شد: a5856660bd1c
آن a5856660bd1c همان شناسهای است که فصلِ ۱ برای همین پیکربندی ساخت. شناسه از پیکربندی میآید، پس بینِ نشستها، ماشینها و آدمها یکسان است — چیزی که یک شمارندهٔ 1, 2, 3 هرگز نمیدهد.
⚠️ مواظب باش:
started_atرا باdatetime.now()پر کردیم، در حالی که ترمِ ۲ فصلِ ۴ گفت زمانِ واقعی بازتولیدپذیری را میشکند. تناقضی نیست، و مرزش دقیق است: آن ستون در هیچ شناسهای دخالت ندارد.run_idفقط از پیکربندی ساخته میشود، پس دو اجرای یک آزمایش در دو روز همان شناسه را میگیرند. قاعده همان است که آنجا نوشتیم: زمانِ واقعی را ثبت کن، ولی هرگز داخلِ چیزی که با آن یکسانی را میسنجی نبر.
۳. همان آزمایش را دو بار ثبت کن#
try:
log_run({"balance": "oversample"})
except sqlite3.IntegrityError as e:
print(f"{type(e).__name__}: {e}")
print("شمارِ اجراها هنوز:", db.execute("SELECT count(*) FROM runs").fetchone()[0])
IntegrityError: UNIQUE constraint failed: runs.run_id
شمارِ اجراها هنوز: 1
این خطا یک ویژگی است، نه یک دردسر. آزمایشی که پیکربندیاش عیناً قبلاً اجرا شده، آزمایشِ تازهای نیست — و اگر اجازه بدهی دوباره ثبت شود، جدولِ مقایسهات پر از ردیفهایی میشود که فقط تکرارِ همدیگرند و میانگینهایت را بهسمتِ پرتکرارها میکشند.
🔧 اگر کار نکرد:
sqlite3.IntegrityError: UNIQUE constraint failed: runs.run_idیعنی همین. اگر واقعاً میخواهی همان پیکربندی دوباره اجرا شود، راهِ درست عوض کردنِseedاست — که آزمایشِ واقعاً متفاوتی است. راهِ غلطINSERT OR REPLACEاست: آنوقت رکوردِ قبلی بیسروصدا پاک میشود و اگر کد بینِ دو اجرا عوض شده باشد، جدولت دوcode_fpمتفاوت را با یک شناسه نشان میدهد، بدونِ اینکه بدانی. و اگر پیامِ خطاno such table: runsبود، سلولِ بخشِ ۱ را دوباره اجرا کردهای و پایگاه داده از نو ساخته شده — کلِ نوتبوک را از بالا اجرا کن.
۴. دوازده آزمایش#
GRID = [
{},
{"balance": "oversample"},
{"balance": "weight"},
{"features": "meta"},
{"features": "meta", "balance": "oversample"},
{"features": "text+meta", "balance": "oversample"},
{"ngram": 2, "balance": "oversample"},
{"min_df": 3, "balance": "oversample"},
{"C": 0.1, "balance": "oversample"},
{"C": 10.0, "balance": "oversample"},
{"split": "group", "balance": "oversample"},
{"features": "text+meta", "split": "group", "balance": "oversample"},
]
new = skipped = 0
for cfg in GRID:
try:
log_run(cfg)
new += 1
except sqlite3.IntegrityError:
skipped += 1
print("تازه:", new, "· تکراری و رد شد:", skipped,
"· جمع:", db.execute("SELECT count(*) FROM runs").fetchone()[0])
تازه: 11 · تکراری و رد شد: 1 · جمع: 12
یکی از دوازدهتا قبلاً ثبت شده بود و خودش را رد کرد. این یعنی میتوانی همین سلول را هر روز اجرا کنی و فقط چیزهای تازه اجرا شوند — که پایهایترین شکلِ همتوانیِ ترمِ ۲ است، این بار روی آزمایش.
حالا یک اجرای شکستخورده:
try:
log_run({"min_df": 5000, "balance": "oversample"})
except ValueError as e:
print("اجرا شکست خورد:", type(e).__name__)
for status, n in db.execute(
"SELECT status, count(*) FROM runs GROUP BY status ORDER BY status"):
print(f" {status:<18}{n}")
اجرا شکست خورد: ValueError
done 12
failed:ValueError 1
سیزدهمین ردیف در پایگاه داده هست، با وضعیتِ failed. حالا هر وقت دوباره همان پیکربندی را امتحان کنی، ردیابْ همان IntegrityError را میدهد و جلوی تکرارِ یک شکستِ شناختهشده را میگیرد.
۵. جدولِ مقایسه#
QUERY = """
SELECT r.run_id, r.config_json, m.name, m.value
FROM runs r JOIN metrics m ON m.run_id = r.run_id
WHERE r.status = 'done'
ORDER BY r.run_id
"""
def label(config_json):
cfg = json.loads(config_json)
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 "پیشفرض"
scores = {}
for rid, cj, name, value in db.execute(QUERY): # هر متریک یک ردیف است
scores.setdefault((rid, cj), {})[name] = value
BOARD = sorted(scores.items(), key=lambda kv: -kv[1]["f1"]) # چرخاندن، در پایتون
print(f" {'#':<3}{'run_id':<14}{'F1':>7}{'prec':>8}{'rec':>8} پیکربندی")
for rank, ((rid, cj), m) in enumerate(BOARD, start=1):
print(f" {rank:<3}{rid:<14}{m['f1']:>7.4f}{m['precision']:>8.4f}"
f"{m['recall']:>8.4f} {label(cj)}")
# run_id F1 prec rec پیکربندی
1 4e3dcb39dccc 0.6875 0.6154 0.7788 balance=oversample features=text+meta
2 77c29a514207 0.6169 0.7045 0.5487 features=meta
3 dad0c2cf419b 0.5690 0.5546 0.5841 balance=oversample features=meta
4 cb61dc3fc3c0 0.5620 0.5271 0.6018 C=0.1 balance=oversample
5 a5856660bd1c 0.5469 0.5076 0.5929 balance=oversample
6 cda9e467e5a1 0.5469 0.5076 0.5929 balance=oversample min_df=3
7 c37de97c7e40 0.5397 0.4892 0.6018 balance=weight
8 3d5eb250e17f 0.5391 0.4825 0.6106 balance=oversample ngram=2
9 4a6c5ce361a4 0.5136 0.4583 0.5841 C=10.0 balance=oversample
10 b8645d28d266 0.5102 0.4360 0.6148 balance=oversample split=group
11 b27182263311 0.4679 0.5312 0.4180 balance=oversample features=text+meta split=group
12 8c3a11d3e62f 0.4023 0.5738 0.3097 پیشفرض
سه چیزِ خواندنی در این جدول هست، و هر سه از خودِ داده درآمدهاند.
۱) ردیفهای ۵ و ۶ عیناً یک عدد دارند. min_df=3 هیچ اثری نداشت. یعنی هیچ واژهای در این پیکره نیست که در یک یا دو تیکت دیده شود و روی تصمیم اثر بگذارد. یک نتیجهٔ منفی است و ارزشِ ثبتش دقیقاً بهاندازهٔ یک نتیجهٔ مثبت است — چون جلوی این را میگیرد که کسی دوباره امتحانش کند.
۲) ردیفهای ۱۰ و ۱۱ (split=group) پایینِ جدولاند. همان درسِ ترمِ ۲: تقسیمِ گروهی عددِ کوچکتری میدهد، و آن عددِ کوچکتر صادقتر است. پس این جدول را نمیشود از بالا به پایین خواند؛ ردیفهایی که تقسیمشان فرق دارد اصلاً همسنگ نیستند.
۳) ردیفِ ۲ بیشترین precision جدول را دارد، و recall آن از همهٔ ردیفهای فرانمونهدارِ تقسیمِ تصادفی کمتر است. این ردیف فرانمونه ندارد. یعنی ستونِ F1 بهتنهایی نمیگوید مدل چه رفتاری دارد.
۶. چقدر از این ترتیب واقعی است#
TOP = [{"features": "meta", "balance": "oversample"},
{"features": "text+meta", "balance": "oversample"},
{"balance": "oversample"}]
for cfg in TOP:
for s in range(5):
try:
log_run(cfg | {"seed": s})
except sqlite3.IntegrityError:
pass
print("جمعِ اجراها:", db.execute("SELECT count(*) FROM runs").fetchone()[0])
FAMILY = """
SELECT r.config_json, m.value
FROM runs r JOIN metrics m ON m.run_id = r.run_id
WHERE r.status = 'done' AND m.name = 'f1'
"""
by_family = {}
for cj, f1 in db.execute(FAMILY):
cfg = json.loads(cj)
cfg.pop("seed")
key = json.dumps(cfg, sort_keys=True, ensure_ascii=False)
by_family.setdefault(key, []).append(f1)
print()
print(f" {'پیکربندی':<40}{'n':>3}{'میانگین':>10}{'کمینه':>9}{'بیشینه':>9}")
rows = sorted(((label(k), v) for k, v in by_family.items() if len(v) > 1),
key=lambda kv: -sum(kv[1]) / len(kv[1]))
for name, vals in rows:
print(f" {name:<40}{len(vals):>3}{sum(vals) / len(vals):>10.4f}"
f"{min(vals):>9.4f}{max(vals):>9.4f}")
جمعِ اجراها: 25
پیکربندی n میانگین کمینه بیشینه
balance=oversample features=text+meta 5 0.6808 0.6391 0.7000
balance=oversample features=meta 5 0.5938 0.5690 0.6320
balance=oversample 5 0.5220 0.5101 0.5469
دقت کن که by_family چه کار میکند: seed را از پیکربندی برمیدارد و بقیه را کلید میگیرد. این سادهترین کاری است که یک ردیاب باید بلد باشد — گروه کردنِ اجراهایی که واقعاً یک آزمایشاند و فقط seed شان فرق دارد.
و حالا عددِ اصلیِ فصل:
middle = [m["f1"] for _, m in BOARD[3:8]]
key = DEFAULTS | {"balance": "oversample"}
key.pop("seed")
one_config = by_family[json.dumps(key, sort_keys=True, ensure_ascii=False)]
print(f"دامنهٔ رتبههای ۴ تا ۸ جدولِ اول : {max(middle) - min(middle):.4f}")
print(f"دامنهٔ یک پیکربندی روی پنج seed : {max(one_config) - min(one_config):.4f}")
دامنهٔ رتبههای ۴ تا ۸ جدولِ اول : 0.0229
دامنهٔ یک پیکربندی روی پنج seed : 0.0368
پنج ردیفِ وسطِ جدول در دامنهای باریکتر از نوسانِ یک پیکربندیِ تنها جمع شدهاند.
یعنی اگر seed را عوض میکردیم، ترتیبِ آن پنج ردیف میتوانست کاملاً بههم بریزد. هیچکدام از آنها «بهتر» از دیگری نیست؛ فقط در این یک قرعهکشی جلوتر افتادهاند.
ولی سه ردیفِ جدولِ خانوادهها با هم فرق دارند و این فرق واقعی بهنظر میرسد: بازههای ۰٫۶۳۹–۰٫۷۰۰ و ۰٫۵۶۹–۰٫۶۳۲ و ۰٫۵۱۰–۰٫۵۴۷ روی هم نمیافتند. پس این ادعا از داده درمیآید: text+meta از meta بهتر است و meta از text. فصلِ ۵ همین شکلِ استدلال را دقیق میکند و نشان میدهد «روی هم نیفتادن» چهقدر معیارِ سستکاری است.
📏 اندازه بگیر: با چه چیزی مقایسه شد؟ هر ردیف با ردیفهای دیگرِ همان جدول، و مهمتر با نوسانِ درونیِ خودش. روی کدام داده؟ همان تقسیمِ ۲۵ درصدی؛ ردیفهای
split=groupروی تقسیمِ دیگریاند و به همین دلیل همسنگ نیستند. با چندseed؟ جدولِ اول با یکتا — و همین کافی است که هشت ردیفش قابلِ اتکا نباشد. جدولِ دوم با پنجتا.
✅ چک کن: در سطرِ
BOARD، کلیدِ مرتبسازی را از"f1"به"precision"عوض کن. رتبهٔ اول عوض میشود؟ اگر بله، یعنی «بهترین» یک صفت نیست، یک انتخابِ متریک است — و باید قبل از دیدنِ جدول انتخابش کرده باشی، نه بعدش.
۷. و ابزارهای آماده#
MLflow و Weights & Biases و Neptune دقیقاً همین کار را میکنند، با رابطِ گرافیکی، ذخیرهٔ فایلِ مدل، و مقایسهٔ تصویری. وجود دارند و در تیمهای واقعی زیاد استفاده میشوند.
ولی حالا که همین را با ۳۰ خط نوشتهای، میدانی زیرِ آن رابطِ گرافیکی چه چیزی هست: یک جدولِ اجرا، یک جدولِ متریک، و یک کلیدِ یکتا. و مهمتر، میدانی چه چیزی نیست: هیچکدام از آنها بهجای تو تصمیم نمیگیرند که پنج ردیفِ وسطِ جدولت نویزند.
🤖 از دستیارت بپرس: «چه فیلدهای دیگری در جدولِ
runsیک ردیابِ آزمایش لازم است؟» بعد این را هم بپرس: «اگر دو نفر همزمان روی یک فایلِsqlite3بنویسند چه اتفاقی میافتد؟» — جوابِ دوم محدودیتِ واقعیِ این طراحی است و در ترمِ ۶ که کارِ تیمی را میبینیم دوباره سراغش میرویم.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| experiment tracker | اکسپریمنت ترکر | جایی که پیکربندی و نتیجهٔ هر اجرا ثبت میشود |
| leaderboard | لیدربورد | جدولِ اجراها مرتبشده بر اساسِ یک متریک |
| run status | ران استیتوس | وضعیتِ اجرا: در حالِ اجرا، تمامشده، شکستخورده |
| unique constraint | یونیک کانسترینت | قاعدهٔ پایگاه داده که از ثبتِ کلیدِ تکراری جلوگیری میکند |
| negative result | نگتیو ریزالت | نتیجهای که نشان میدهد یک ایده اثر نداشت |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
ردیابمان code_fp و data_fp را ثبت میکند و این خوب است. ولی هنوز یک چیزِ بزرگ را ثبت نمیکند: محیط. فصلِ بعد آن را اضافه میکند و بعد سؤالِ سخت را میپرسد: اگر همهچیز را ثبت کنیم و همهٔ seedها را ببندیم، آیا نتیجه واقعاً بازتولیدپذیر میشود؟ جواب «نه» است، و دقیقاً نشان میدهیم کجا و چرا — با یک منبعِ ناقطعیت که از داخلِ همان فرآیند اصلاً نمیشود خاموشش کرد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.