داربست — خودآموز MLOps و مهندسی سامانه‌های هوش مصنوعی (پیشرفته)

فصل ۷ از ۷

پیشرفت ترم
۰٪

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

فصلِ آخرِ داربست، و هیچ مفهومِ تازه‌ای ندارد. هر چه لازم داری در شش ترمِ قبل ساخته‌ای.

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

بعد آن را روی دو پروژه اجرا می‌کنیم. پروژهٔ معمول — همان که همه‌جا هست — ۱ از ۱۸ می‌گیرد. پروژه‌ای که همهٔ قطعه‌های این ترم را دارد ۱۵ از ۱۸ می‌گیرد؛ سه بندِ قرمزش یک ریشه دارند و ریشه‌اش دقیقاً همان درسِ اولِ کلِ دوره است: مدل از خطِ پایه بهتر نیست — ۰٫۷۹۳۳ در برابرِ ۰٫۷۸۵۰.

آن یک ریشه را می‌بندیم و ۱۸ از ۱۸ می‌شود.

یک دستگاهِ کامل با کارتِ بازرسی که خودش پرش کرده

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

  • سیاههٔ تحویلی بنویسی که به‌جای پرسیدن، بررسی می‌کند
  • پروژه‌ات را با آن بسنجی و بدانی دقیقاً کجا ناتمام است
  • بگویی هر بندِ سیاهه به کدام قانونِ ثابتِ این دوره خدمت می‌کند
  • کاری تحویل بدهی که کسِ دیگری بتواند نگهش دارد

قبل از شروع#

هر شش فصلِ این ترم، و هر پنج ترمِ قبلش. هیچ چیزِ تازه‌ای اینجا نیست جز چیدنشان کنارِ هم.

و یک قاعده که کلِ فصل رویش ایستاده: سیاهه‌ای که اجرا نمی‌شود، یک آرزوست. همان تفاوتی که فصلِ ۳ بینِ «مستند» و «مستندِ اجراشدنی» گذاشت، اینجا بینِ «تعریفِ تمام‌شدن» و «تعریفِ تمام‌شدنی که خودش را می‌سنجد».

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

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

۱. دو پروژه#

پروژهٔ معمول سه فایل دارد: داده، یک ماژولِ مدل، و یک README که می‌گوید «نوت‌بوک را باز کن». این کاریکاتور نیست؛ اکثریتِ پروژه‌های واقعی دقیقاً همین‌اند و اغلب حتی همان ماژول را هم ندارند.

پروژهٔ کامل دوازده فایل دارد و هر فایلش از یکی از فصل‌های این ترم آمده: مجموعهٔ تست و دروازه از فصلِ ۲، READMEی که اجرا می‌شود و تصمیم‌نامه از فصلِ ۳، سیاههٔ ریسک و ردِ ممیزی از فصلِ ۴، و طرحِ انتشار و برگشت از ترمِ ۴.

import json
import re
import shlex
import sqlite3

TICKS = "`" * 3
COMMON = ('"""model.py — پاک‌سازی، قرارداد، تقسیم، ویژگی، مدل."""\n'
          'CATEGORIES = ("پرداخت", "ارسال", "حساب کاربری", "اپلیکیشن")\n'
          'REQUIRED = ("ticket_id", "week", "category", "text", "escalated")\n'
          "THRESHOLD = 0.5\n\n\n"
          "def normalise(text):\n"
          '    return " ".join(text.replace("ي", "ی").replace("ك", "ک").split())\n\n\n'
          "def features(rows):\n"
          '    return [normalise(r["text"]) for r in rows]\n\n\n'
          "def split(rows, upto=18):\n"
          '    return ([r for r in rows if r["week"] < upto],\n'
          '            [r for r in rows if r["week"] >= upto])\n\n\n')
MODEL_COUNT = COMMON + (
    "import json\n\n\n"
    "def fit(rows):\n"
    "    score = {}\n"
    "    for row, text in zip(rows, features(rows)):\n"
    "        for word in set(text.split()):\n"
    '            score[word] = score.get(word, 0) + (1 if row["escalated"] else -1)\n'
    "    return score\n\n\n"
    "def predict(fitted, text):\n"
    "    return int(sum(fitted.get(w, 0) for w in normalise(text).split()) > 0)\n\n\n"
    "def save(fitted, path):\n"
    '    json.dump(fitted, open(path, "w", encoding="utf-8"), ensure_ascii=False)\n\n\n'
    "def load(path):\n"
    '    return json.load(open(path, encoding="utf-8"))\n')
MODEL_REAL = COMMON + (
    "import pickle\n\n"
    "from sklearn.feature_extraction.text import CountVectorizer\n"
    "from sklearn.linear_model import LogisticRegression\n"
    "from sklearn.pipeline import make_pipeline\n\n\n"
    "def fit(rows):\n"
    "    pipe = make_pipeline(CountVectorizer(), LogisticRegression(max_iter=1000))\n"
    '    pipe.fit(features(rows), [r["escalated"] for r in rows])\n'
    "    return pipe\n\n\n"
    "def predict(fitted, text):\n"
    "    return int(fitted.predict_proba([normalise(text)])[0][1] >= THRESHOLD)\n\n\n"
    "def save(fitted, path):\n"
    '    pickle.dump(fitted, open(path, "wb"))\n\n\n'
    "def load(path):\n"
    '    return pickle.load(open(path, "rb"))\n')

FULL = {
    "data.json": json.dumps(TICKETS, ensure_ascii=False),
    "model.py": MODEL_COUNT,
    "tests.py": '"""tests.py — مجموعهٔ تستِ پروژه، با ردهٔ سرعت."""\n'
                "import json\n\nimport model\n\n"
                'ROWS = json.load(open("data.json", encoding="utf-8"))\n\n\n'
                "def test_normalise_arabic():\n"
                '    assert model.normalise("كارت") == "کارت", model.normalise("كارت")\n\n\n'
                "def test_schema_categories():\n"
                '    unknown = sorted({r["category"] for r in ROWS} - set(model.CATEGORIES))\n'
                '    assert not unknown, f"دستهٔ ناشناخته: {unknown}"\n\n\n'
                "def test_split_shares_no_row():\n"
                "    train, test = model.split(ROWS)\n"
                '    shared = {r["ticket_id"] for r in train} & {r["ticket_id"] for r in test}\n'
                '    assert not shared, f"{len(shared)} تیکت در هر دو طرف"\n\n\n'
                "def test_split_is_chronological():\n"
                "    train, test = model.split(ROWS)\n"
                '    assert max(r["week"] for r in train) < min(r["week"] for r in test)\n\n\n'
                "def test_features_ignore_the_label():\n"
                "    row = dict(ROWS[0])\n"
                "    before = model.features([row])\n"
                '    row["escalated"] = 1 - row["escalated"]\n'
                '    assert model.features([row]) == before, "ویژگی به برچسب نگاه می‌کند"\n\n\n'
                "def test_model_beats_baseline():\n"
                "    train, test = model.split(ROWS)\n"
                "    fitted = model.fit(train)\n"
                '    hit = sum(model.predict(fitted, r["text"]) == r["escalated"]'
                " for r in test) / len(test)\n"
                '    share = sum(r["escalated"] for r in test) / len(test)\n'
                "    base = max(share, 1 - share)\n"
                '    assert hit > base + 0.02, f"مدل {hit:.4f} · خطِ پایه {base:.4f}"\n\n\n'
                "SUITE = [\n"
                '    ("normalise_arabic", "fast", test_normalise_arabic),\n'
                '    ("schema_categories", "fast", test_schema_categories),\n'
                '    ("split_shares_no_row", "fast", test_split_shares_no_row),\n'
                '    ("split_is_chronological", "fast", test_split_is_chronological),\n'
                '    ("features_ignore_the_label", "fast", test_features_ignore_the_label),\n'
                '    ("model_beats_baseline", "slow", test_model_beats_baseline),\n'
                "]\n",
    "ci.py": '"""ci.py — دروازهٔ خودکار: سریع اول، بعد کند."""\n'
             "import sys\n\nimport tests\n\n"
             "failures = []\n"
             'for kind in ("fast", "slow"):\n'
             "    for name, group, check in tests.SUITE:\n"
             "        if group != kind:\n            continue\n"
             "        try:\n            check()\n"
             "        except Exception as error:\n"
             '            failures.append(f"{name} — {type(error).__name__}: {error}")\n'
             "            break\n"
             "    if failures:\n        break\n"
             'print("قرمز: " + failures[0] if failures else "سبز")\n'
             "sys.exit(1 if failures else 0)\n",
    "prepare.py": '"""prepare.py — پاک‌سازی و ذخیره."""\n'
                  "import json\n\nimport model\n\n"
                  'rows = json.load(open("data.json", encoding="utf-8"))\n'
                  "for row in rows:\n"
                  '    row["text"] = model.normalise(row["text"])\n'
                  'json.dump(rows, open("clean.json", "w", encoding="utf-8"),'
                  " ensure_ascii=False)\n"
                  'print("clean.json ساخته شد:", len(rows), "ردیف")\n',
    "train.py": '"""train.py — آموزش روی برشِ زمانی و ذخیرهٔ مدل."""\n'
                "import json\n\nimport model\n\n"
                'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                "train, _ = model.split(rows)\n"
                'model.save(model.fit(train), "model.bin")\n'
                'print("model.bin ساخته شد از", len(train), "ردیف")\n',
    "evaluate.py": '"""evaluate.py — دقت روی هفته‌های بعدی، کنارِ خطِ پایه."""\n'
                   "import json\n\nimport model\n\n"
                   'fitted = model.load("model.bin")\n'
                   'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                   "_, test = model.split(rows)\n"
                   'hit = sum(model.predict(fitted, r["text"]) == r["escalated"]'
                   " for r in test) / len(test)\n"
                   'share = sum(r["escalated"] for r in test) / len(test)\n'
                   'print(f"دقت {hit:.4f} · خطِ پایه {max(share, 1 - share):.4f}"\n'
                   '      f" · روی {len(test)} ردیفِ آینده")\n',
    "deploy.py": '"""deploy.py — انتشارِ تدریجی با طرحِ برگشت."""\n'
                 'STAGES = ["shadow", "canary", "full"]\n'
                 'ROLLBACK = "نسخهٔ قبلی از رجیستری، با یک فرمان"\n'
                 'print("مرحله‌ها:", STAGES, "· برگشت:", ROLLBACK)\n',
    "record.py": '"""record.py — ردِ ممیزی: نسخهٔ داده، نسخهٔ مدل، و هر پیش‌بینی."""\n'
                 "import hashlib\nimport json\nimport os\nimport sqlite3\n\nimport model\n\n"
                 'if os.path.exists("audit.db"):\n    os.remove("audit.db")\n'
                 'db = sqlite3.connect("audit.db")\n'
                 'db.execute("PRAGMA foreign_keys = ON")\n'
                 'db.executescript("""\n'
                 "CREATE TABLE data_versions (id TEXT PRIMARY KEY, rows INTEGER);\n"
                 "CREATE TABLE model_versions (id TEXT PRIMARY KEY,\n"
                 "    data_id TEXT NOT NULL REFERENCES data_versions(id));\n"
                 "CREATE TABLE predictions (id INTEGER PRIMARY KEY, ticket_id TEXT,\n"
                 "    answer INTEGER, model_id TEXT NOT NULL REFERENCES model_versions(id));\n"
                 '""")\n'
                 'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                 "train, test = model.split(rows)\n"
                 'data_id = hashlib.sha256(json.dumps([r["ticket_id"] for r in train])'
                 ".encode()).hexdigest()[:12]\n"
                 'model_id = "m-" + data_id\n'
                 'fitted = model.load("model.bin")\n'
                 'db.execute("INSERT INTO data_versions VALUES (?, ?)", (data_id, len(train)))\n'
                 'db.execute("INSERT INTO model_versions VALUES (?, ?)", (model_id, data_id))\n'
                 'db.executemany("INSERT INTO predictions (ticket_id, answer, model_id)'
                 ' VALUES (?, ?, ?)",\n'
                 '               [(r["ticket_id"], model.predict(fitted, r["text"]), model_id)\n'
                 "                for r in test])\n"
                 "db.commit()\n"
                 'print("ردِ ممیزی ثبت شد:",\n'
                 '      db.execute("SELECT COUNT(*) FROM predictions").fetchone()[0],'
                 ' "پیش‌بینی")\n',
    "README.md": "# خطِ تشدید\n\n## اجرا\n\n"
                 + "\n\n".join(f"{TICKS}bash\n{step}\n{TICKS}" for step in
                               ("python prepare.py", "python train.py",
                                "python evaluate.py", "python ci.py", "python record.py"))
                 + "\n",
    "docs/adr/0001-time-split.md": "# ۰۰۰۱ — تقسیمِ زمانی به‌جای تصادفی\n\n"
                                   "وضعیت: پذیرفته‌شده\n"
                                   "زمینه: با تقسیمِ تصادفی رتبه‌بندیِ مدل‌ها وارونه می‌شد.\n"
                                   "تصمیم: ارزیابی فقط روی برشِ زمانیِ بعدی.\n"
                                   "پیامد: عددها پایین‌تر و قابلِ اتکا شدند.\n"
                                   "بدیلِ ردشده: تقسیمِ تصادفی با چند seed.\n"
                                   "نگهبان: python ci.py\n",
    "risks.md": "# سیاههٔ ریسک\n\n"
                "| ریسک | احتمال | اثر | نگهبان |\n|---|---|---|---|\n"
                "| نشتیِ ردیفِ تکراری | ۴ | ۵ | split_shares_no_row |\n"
                "| ارزیابیِ آفلاین وارونه | ۴ | ۵ | split_is_chronological |\n"
                "| برچسب در ویژگی‌ها | ۲ | ۵ | features_ignore_the_label |\n"
                "| قراردادِ داده می‌شکند | ۴ | ۳ | schema_categories |\n"
                "| مدل از خطِ پایه بدتر شود | ۳ | ۴ | model_beats_baseline |\n"
                "| مستند از کد عقب بماند | ۵ | ۲ | README در دروازه |\n",
}
TYPICAL = {"data.json": FULL["data.json"], "model.py": FULL["model.py"],
           "README.md": "# خطِ تشدید\n\nنوت‌بوک را باز کن و سلول‌ها را به‌ترتیب بزن.\n"}


def make(name, files):
    root = WORK / name
    shutil.rmtree(root, ignore_errors=True)
    for path, text in files.items():
        write(root / path, text)
    return root


complete = make("project-complete", FULL)
typical = make("project-typical", TYPICAL)
print("پروژهٔ کامل:", len(FULL), "فایل · پروژهٔ معمول:", len(TYPICAL), "فایل")
پروژهٔ کامل: 12 فایل · پروژهٔ معمول: 3 فایل

۲. سیاهه‌ای که خودش را اجرا می‌کند#

هجده بند. هیچ‌کدام سؤال نیستند. هر بند یا به فایل نگاه می‌کند، یا برنامه‌ای را واقعاً اجرا می‌کند و کدِ خروجش را می‌خواند.

BASH_BLOCK = re.compile(TICKS + r"bash\n(.*?)" + TICKS, re.S)


def read(root, name):
    path = root / name
    return path.read_text(encoding="utf-8") if path.exists() else ""


def run_readme(root):
    """هر دستورِ مستندشده، در یک نسخهٔ تازه (فصلِ ۳)."""
    fresh = WORK / "fresh"
    shutil.rmtree(fresh, ignore_errors=True)
    shutil.copytree(root, fresh)
    steps = [line.strip() for block in BASH_BLOCK.findall(read(root, "README.md"))
             for line in block.split("\n") if line.strip().startswith("python ")]
    return fresh, [(step, run_py(*shlex.split(step)[1:], cwd=fresh)) for step in steps]


def reconstructable(fresh):
    """یک پیش‌بینی: می‌شود به نسخهٔ مدل و دادهٔ سازنده‌اش برگرداندش؟ (فصلِ ۴)"""
    if not (fresh / "audit.db").exists():
        return False
    db = sqlite3.connect(fresh / "audit.db")
    row = db.execute("SELECT p.ticket_id, m.id, d.rows FROM predictions p"
                     " JOIN model_versions m ON m.id = p.model_id"
                     " JOIN data_versions d ON d.id = m.data_id LIMIT 1").fetchone()
    db.close()
    return bool(row)


def audit(root):
    """سیاههٔ تحویل — هر بند یک بررسیِ اجراشدنی است، نه یک سؤال."""
    fresh, steps = run_readme(root)
    tests_src = read(root, "tests.py")
    risks = read(root, "risks.md")
    adr = read(root, "docs/adr/0001-time-split.md")
    guard = re.search(r"نگهبان: (.+)", adr)
    guard_ok = bool(guard) and run_py(*shlex.split(guard.group(1))[1:], cwd=fresh)[0] == 0
    rows = [ln for ln in risks.split("\n") if ln.startswith("| ") and "---" not in ln][1:]
    return [
        ("کدِ اصلی در فایل است، نه در نوت‌بوک", bool(read(root, "model.py"))),
        ("مجموعهٔ تست دارد", tests_src.count("def test_") >= 5),
        ("تستِ سریع و کند از هم جدا شده‌اند",
         '"fast"' in tests_src and '"slow"' in tests_src),
        ("دروازه با کدِ خروج جواب می‌دهد", (root / "ci.py").exists()),
        ("دروازه همین حالا سبز است",
         (root / "ci.py").exists() and run_py("ci.py", cwd=fresh)[0] == 0),
        ("تستِ نشتی دارد", "shares_no_row" in tests_src),
        ("تستِ ناوردایی روی برچسب دارد", "features_ignore_the_label" in tests_src),
        ("قراردادِ داده دارد", "schema" in tests_src),
        ("خطِ پایه داخلِ تست است", "beats_baseline" in tests_src),
        ("README دستورِ اجرا دارد", len(steps) > 0),
        ("همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند",
         bool(steps) and all(code == 0 for _, (code, _) in steps)),
        ("تصمیم‌نامه دارد", bool(adr)),
        ("تصمیم‌نامه نگهبانِ سبز دارد", guard_ok),
        ("سیاههٔ ریسک با حداقل پنج ردیف", len(rows) >= 5),
        ("هر ریسک ستونِ نگهبان دارد",
         bool(rows) and all(len(ln.split("|")) >= 6 and ln.split("|")[4].strip()
                            for ln in rows)),
        ("نسخهٔ داده و مدل ثبت می‌شود", "data_versions" in read(root, "record.py")),
        ("یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد", reconstructable(fresh)),
        ("طرحِ انتشار و برگشت دارد",
         "shadow" in read(root, "deploy.py") and "ROLLBACK" in read(root, "deploy.py")),
    ]


for label, root in (("پروژهٔ معمول", typical), ("پروژهٔ کامل", complete)):
    result = audit(root)
    print(f"— {label} —")
    for item, ok in result:
        print(f"  {'✓' if ok else '✗'} {item}")
    print(f"  {sum(ok for _, ok in result)} از {len(result)}")
— پروژهٔ معمول —
  ✓ کدِ اصلی در فایل است، نه در نوت‌بوک
  ✗ مجموعهٔ تست دارد
  ✗ تستِ سریع و کند از هم جدا شده‌اند
  ✗ دروازه با کدِ خروج جواب می‌دهد
  ✗ دروازه همین حالا سبز است
  ✗ تستِ نشتی دارد
  ✗ تستِ ناوردایی روی برچسب دارد
  ✗ قراردادِ داده دارد
  ✗ خطِ پایه داخلِ تست است
  ✗ README دستورِ اجرا دارد
  ✗ همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند
  ✗ تصمیم‌نامه دارد
  ✗ تصمیم‌نامه نگهبانِ سبز دارد
  ✗ سیاههٔ ریسک با حداقل پنج ردیف
  ✗ هر ریسک ستونِ نگهبان دارد
  ✗ نسخهٔ داده و مدل ثبت می‌شود
  ✗ یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد
  ✗ طرحِ انتشار و برگشت دارد
  1 از 18
— پروژهٔ کامل —
  ✓ کدِ اصلی در فایل است، نه در نوت‌بوک
  ✓ مجموعهٔ تست دارد
  ✓ تستِ سریع و کند از هم جدا شده‌اند
  ✓ دروازه با کدِ خروج جواب می‌دهد
  ✗ دروازه همین حالا سبز است
  ✓ تستِ نشتی دارد
  ✓ تستِ ناوردایی روی برچسب دارد
  ✓ قراردادِ داده دارد
  ✓ خطِ پایه داخلِ تست است
  ✓ README دستورِ اجرا دارد
  ✗ همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند
  ✓ تصمیم‌نامه دارد
  ✗ تصمیم‌نامه نگهبانِ سبز دارد
  ✓ سیاههٔ ریسک با حداقل پنج ردیف
  ✓ هر ریسک ستونِ نگهبان دارد
  ✓ نسخهٔ داده و مدل ثبت می‌شود
  ✓ یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد
  ✓ طرحِ انتشار و برگشت دارد
  15 از 18

۱ از ۱۸، و ۱۵ از ۱۸.

پروژهٔ معمول تنها بندی را می‌گیرد که رایگان است: کدش در یک فایل است. همهٔ هفده بندِ دیگر چیزی می‌خواهند که کسی وقتش را نگذاشته — و هیچ‌کدامشان از خودِ مدل سخت‌تر نبودند.

و سه بندِ قرمزِ پروژهٔ کامل، هدیهٔ این فصل‌اند. من این پروژه را ساختم تا کامل باشد، و سیاهه سه چیز پیدا کرد که ندیده بودم.

۳. سه قرمز، یک ریشه#

fresh, steps = run_readme(complete)
print("دروازه چه گفت؟", run_py("ci.py", cwd=fresh)[1].splitlines()[-1])
for step, (code, out) in steps:
    if code:
        print(f"{step} → {out.splitlines()[-1]}")
دروازه چه گفت؟ قرمز: model_beats_baseline — AssertionError: مدل 0.7933 · خطِ پایه 0.7850
python ci.py → قرمز: model_beats_baseline — AssertionError: مدل 0.7933 · خطِ پایه 0.7850

۰٫۷۹۳۳ در برابرِ ۰٫۷۸۵۰.

سه بندِ قرمز — «دروازه سبز است»، «دستورهای README اجرا می‌شوند»، «تصمیم‌نامه نگهبانِ سبز دارد» — هر سه یک چیز می‌گویند، چون هر سه در نهایت همان ci.py را اجرا می‌کنند. و آن یک چیز، درسِ اولِ کلِ این دوره است: مدل از خطِ پایه بهتر نیست.

هشت هزارمِ بهبود. مدلِ شمارشی به‌اندازهٔ «همیشه بگو تشدید نمی‌شود» خوب است، و اگر خطِ پایه داخلِ تست نبود، عددِ ۰٫۷۹ روی هر اسلایدی قابلِ قبول به نظر می‌رسید.

و به شکلِ گزارش دقت کن: سیاهه سه بند را قرمز کرد، ولی مشکل سه‌تا نبود. یک سیاههٔ اجراشدنی خیلی وقت‌ها یک خرابی را چند بار گزارش می‌کند؛ اول ریشه را پیدا کن، بعد بشمار.

۴. بستنِ ریشه#

اصلاح، عوض کردنِ یک فایل است: مدلِ شمارشی می‌رود و همان LogisticRegression ترمِ ۱ می‌آید. بقیهٔ پروژه یک بایت هم عوض نمی‌شود، چون train.py و evaluate.py و record.py همه از پشتِ model.fit و model.predict کار می‌کنند — همان مرزِ ماژولِ ترمِ ۱ فصلِ ۴.

write(complete / "model.py", MODEL_REAL)
after = audit(complete)
for item, ok in after:
    if not ok:
        print("✗", item)
print("پس از عوض کردنِ مدل:", sum(ok for _, ok in after), "از", len(after))
fresh, steps = run_readme(complete)
for step, (code, out) in steps:
    print(f"  {step:<22}{out.splitlines()[-1]}")
پس از عوض کردنِ مدل: 18 از 18
  python prepare.py     clean.json ساخته شد: 2400 ردیف
  python train.py       model.bin ساخته شد از 1800 ردیف
  python evaluate.py    دقت 0.8283 · خطِ پایه 0.7850 · روی 600 ردیفِ آینده
  python ci.py          سبز
  python record.py      ردِ ممیزی ثبت شد: 600 پیش‌بینی

۱۸ از ۱۸.

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

✅ چک کن: به سطرِ evaluate.py نگاه کن: دقت و خطِ پایه کنارِ هم چاپ می‌شوند. این یک تزئین نیست. اگر evaluate.py فقط 0.8283 را چاپ می‌کرد، همان مدلِ شمارشیِ ۰٫۷۹۳۳ هم قابلِ قبول به نظر می‌رسید. هر عددی که تنها چاپ شود، بی‌معناست؛ کنارش همیشه باید چیزی باشد که با آن مقایسه می‌شود.

۵. هجده بند، سه قانون#

هر بندِ این سیاهه از یکی از سه قانونِ ثابتِ داربست می‌آید.

RULE = {
    "اگر خودکار نیست، انجام نمی‌شود": (1, 2, 3, 4, 9, 10, 12, 13),
    "هر چیزی که عوض می‌شود نسخه دارد": (0, 11, 15, 16, 17),
    "سامانهٔ پایش‌نشده خراب است و تو نمی‌دانی": (5, 6, 7, 8, 14),
}
BEFORE = dict(audit(typical))
AFTER = dict(after)
ITEMS = [item for item, _ in after]
print(f"{'قانونِ ثابتِ دوره':<44}{'پروژهٔ معمول':>16}{'پروژهٔ کامل':>16}")
for rule, idx in RULE.items():
    a = sum(BEFORE[ITEMS[i]] for i in idx)
    b = sum(AFTER[ITEMS[i]] for i in idx)
    print(f"{rule:<44}{f'{a}/{len(idx)}':>16}{f'{b}/{len(idx)}':>16}")
قانونِ ثابتِ دوره                               پروژهٔ معمول     پروژهٔ کامل
اگر خودکار نیست، انجام نمی‌شود                           0/8             8/8
هر چیزی که عوض می‌شود نسخه دارد                          1/5             5/5
سامانهٔ پایش‌نشده خراب است و تو نمی‌دانی                 0/5             5/5

صفر از هشت. پروژهٔ معمول در قانونی صفر می‌گیرد که ارزان‌ترین است. نوشتنِ یک دروازهٔ خودکار چند ساعت کار دارد؛ نداشتنش سال‌ها هزینه می‌دهد — و ما هزینه‌اش را در همین ترم شمردیم: ۱ از ۶ دستورِ مستند، ۴۳۱ تیکت در هر دو طرفِ تقسیم، و مدلی که به‌اندازهٔ خطِ پایه خوب بود و کسی نفهمید.

۶. پروژهٔ خودت#

همین سیاهه را روی کارِ خودت ببر. نه به‌عنوان یک تمرین — به‌عنوان تعریفِ تمام شدن.

اگر این بند قرمز است اولین کاری که باید بکنی
کد در نوت‌بوک است یک ماژول بساز و نوت‌بوک را نازک کن (ترمِ ۱ فصلِ ۱)
تست ندارد با دو تست شروع کن: نشتی و خطِ پایه (ترمِ ۱ فصلِ ۳)
دروازه ندارد یک ci.py بیست‌خطی که کدِ خروج بدهد (فصلِ ۲)
دستورهای README اجرا نمی‌شوند همان‌ها را در نسخهٔ تازه بزن و بشمار (فصلِ ۳)
تصمیم‌نامه ندارد سه تصمیمِ بزرگت را بنویس، با نگهبان (فصلِ ۳)
ریسک نگهبان ندارد فقط برای دو ریسکِ اولِ فهرست بساز (فصلِ ۴)
پیش‌بینی به مدلش برنمی‌گردد چهار جدول و یک کلیدِ خارجی (فصلِ ۴)
طرحِ برگشت ندارد سایه، بعد قناری، بعد دکمهٔ برگشت (ترمِ ۴)

و یک قاعده که از همهٔ جدول مهم‌تر است: از بندی شروع کن که ارزان‌ترین است و بیشترین ریسک را می‌بندد. جدولِ ریسکِ فصلِ ۴ همین را می‌گوید، و برای اکثرِ پروژه‌ها جوابش یکی است: تستِ نشتی و خطِ پایه، در یک بعدازظهر.

📏 اندازه بگیر: با چه چیزی مقایسه شد؟ دو پروژه با یک سیاهه و یک تعریف از هر بند — و بندها همه اجراشدنی‌اند، پس هیچ‌کدام به قضاوتِ من وابسته نیستند. روی کدام داده؟ روی همان ۲۴۰۰ تیکتِ ترم، و هر بار در یک نسخهٔ تازه از پوشهٔ پروژه. با چند seed؟ اینجا تصادفی نیست؛ ولی همان صداقتِ فصلِ ۴ لازم است: هجده بند و وزنِ برابرشان، انتخابِ من است. اگر بندی را حذف یا اضافه کنی، نمره‌ها عوض می‌شوند. چیزی که عوض نمی‌شود، ۱ در برابرِ ۱۸ است — و آن فاصله آن‌قدر بزرگ است که به وزن‌ها حساس نباشد.

🔧 اگر کار نکرد: اگر سیاهه روی پروژهٔ خودت با FileNotFoundError ایستاد، run_readme را نگاه کن: دستورها با cwd برابرِ نسخهٔ تازه اجرا می‌شوند، پس هر مسیرِ مطلقی در README تو همان‌جا می‌شکند — و همان یک یافته است، نه یک باگ. اگر shutil.copytree با FileExistsError ایستاد، پوشهٔ fresh از اجرای قبلی مانده. و اگر بندِ «یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد» بی‌صدا False داد در حالی که audit.db وجود دارد، JOIN جوابِ خالی داده — یعنی جدول‌ها پر شده‌اند ولی به هم وصل نیستند، که دقیقاً همان چیزی است که این بند برای گرفتنش نوشته شده.

🤖 از دستیارت بپرس: «این هجده بند را ببین [فهرست را بده]. برای پروژهٔ من چه بندِ نوزدهمی لازم است که اینجا نیست؟» بعد این را بپرس: «برای همان بند، یک بررسیِ اجراشدنی بنویس که کدِ خروج بدهد.» — اگر نتوانست، آن بند هنوز به‌اندازهٔ کافی مشخص نشده.

۷. و آخر#

در ابتدای این دوره یک نوت‌بوک داشتی که کار می‌کرد.

حالا چیزی داری که کسِ دیگری می‌تواند اجرایش کند، و شش ماهِ دیگر هم کار می‌کند. فاصلهٔ این دو، همان درّه‌ای بود که این دوره دربارهٔ آن نوشته شد.

و بیشترِ آنچه در این شش ترم یاد گرفتی، ابزار نبود. ابزارها عوض می‌شوند؛ هر کدام از سازوکارهایی که ساختی امروز یک ابزارِ آماده هم دارد، و فردا ابزارِ دیگری خواهد داشت. چیزی که عوض نمی‌شود، سه جمله است:

  • اگر خودکار نیست، انجام نمی‌شود. نه چون آدم‌ها تنبل‌اند — چون کار زیاد است و آنچه یادآور ندارد، فراموش می‌شود.
  • هر چیزی که عوض می‌شود باید نسخه داشته باشد. داده، کد، مدل، پیکربندی، و تصمیم. چیزی که نسخه ندارد، روزی که لازمش داشته باشی وجود ندارد.
  • سامانه‌ای که پایش نمی‌شود، خراب است و تو نمی‌دانی. این بدبینی نیست؛ در پنج ترمِ گذشته هر بار که چیزی را برای اولین بار اندازه گرفتیم، چیزی پیدا شد.

و یک جملهٔ چهارم که از ژرفا آمد و اینجا هم برقرار است: وقتی کار کرد، اول شک کن. F1 که به ۰٫۸۴۰ پرید نشتی بود. مدلی که آفلاین برنده بود، روی آینده بازنده شد. مدلی که دقتش هشت واحد بالاتر بود، هفته‌ای چهار و نیم پروندهٔ واقعی را از دست می‌داد. هر بار، عددِ خوب علامتِ خطر بود.

چیزی که از اینجا به بعد می‌سازی، دیگر تمرین نیست — و کسی هم آن را برایت تصحیح نمی‌کند. تنها چیزی که داری، همان سیاهه‌ای است که خودت می‌نویسی و خودت اجرایش می‌کنی.

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

کلمه تلفظ به حروف فارسی یعنی چه
definition of done دفینیشن آف دان فهرستِ روشنِ اینکه «تمام شد» یعنی چه
delivery checklist دلیوری چک‌لیست سیاهه‌ای که پیش از تحویل، خودش پروژه را می‌سنجد
handover هندآور تحویل دادنِ کار به کسی که آنجا نبوده
root cause روت کاز خرابیِ واحدی که چند علامتِ متفاوت از آن می‌آید

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

فصلِ بعدی وجود ندارد. داربست اینجا تمام می‌شود، و با آن این مسیر.

سامانه‌ای که ساختی نسخه دارد، تست دارد، دروازه دارد، مستندش اجرا می‌شود، ریسک‌هایش نوشته و نگهبان‌دار است، هر پیش‌بینی‌اش قابلِ بازسازی است، و راهِ برگشت دارد.

و یک جملهٔ آخر که این دوره حق ندارد نگوید: هیچ‌کدام از این هجده بند سامانه‌ات را مستقر نکرده است. هر شش ترم داخلِ یک runtimeِ Colab اجرا شدند و با بستنِ صفحه پاک می‌شوند — ترمِ ۴ فصلِ ۹ بخشِ ۸ ستون‌به‌ستون گفت کدام قطعه شبیه‌سازی بود. چیزی که یاد گرفتی تصمیم‌های مهندسی است؛ چیزی که هنوز نکرده‌ای رساندنِ آن‌ها به ماشینی است که با بستنِ مرورگر خاموش نمی‌شود.

آن قدمِ آخر سه چیز می‌خواهد و هر سه بیرونِ این دوره‌اند: جایی که فرآیندت همیشه روشن بماند، یک نام و یک اتصالِ رمزنگاری‌شده تا کسی جز تو وسطِ راه ننشیند، و مرزِ سرویس — کلید، سهمیه و محدودیتِ نرخ — که ترمِ ۴ فصلِ ۳ ساختنش را نشان داد. ترتیبش هم همین است: اول artifact ترمِ ۴ را روی ماشینِ خودت اجرا کن و ببین چه چیزی می‌شکند، بعد ببرش روی ماشینی که همیشه روشن است، و تنها بعد از آن آدرسش را به کسی بده.

آن روز است که می‌فهمی کدام یکی از این هجده بند را واقعاً لازم داشتی.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.