# فصل ۰۳ — بازتولیدپذیریِ واقعی

<div dir="rtl">

# فصل ۰۳ — بازتولیدپذیریِ واقعی

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

محیط را ثبت می‌کنیم، هر `seed` را می‌بندیم، و به چیزی می‌رسیم که می‌شود به آن تکیه کرد: **دو اجرای پشتِ سرِ هم، اثرِ انگشتِ کاملاً یکسان — و آن اثرِ انگشت با عوض شدنِ `seed` تکان می‌خورد، پس بی‌خاصیت هم نیست.**

بعد به دیوار می‌خوریم. **شش فرآیندِ تازهٔ پایتون، شش ترتیبِ متفاوت از یک `set` می‌دهند، و هیچ خطی از کدِ داخلِ نوت‌بوک نمی‌تواند جلویش را بگیرد** — چون تنها سوئیچی که خاموشش می‌کند باید **قبل** از روشن شدنِ مفسر تنظیم شده باشد. و همان اعداد با دو ترتیبِ متفاوت، دو جمعِ متفاوت می‌دهند.

**این فصل هر دو را نشان می‌دهد: تا کجا قطعیت به‌دست می‌آید، و از کجا به بعد فقط می‌شود صادق بود.**

![دو دستگاهِ یکسان که یکی مهرِ یکسان می‌زند و دیگری هر بار جای دیگری](/lesson-assets/t3-s03-reproducibility/prompt/01-image-two-presses.png)

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

- محیط را طوری ثبت کنی که ماه‌ها بعد بگوید دقیقاً چه چیزی عوض شده
- اثرِ انگشتِ اجرا بسازی و برابریِ دو اجرا را **ثابت** کنی، نه ادعا
- دو منبعِ ناقطعیتِ واقعی را با اندازه‌گیری نشان بدهی
- بگویی «بازتولیدپذیر است» یعنی دقیقاً چه ادعایی، و چه ادعایی نیست

## قبل از شروع

**از فصلِ ۲:** `log_run`، `code_fp`، `data_fp`. اینجا سومی را اضافه می‌کنیم: `env_fp`.

**از سرنخ ترمِ ۵:** `seed` و اینکه چرا نتیجه بدونش هر بار فرق می‌کند. **این فصل همان درس است، ولی از سمتِ دیگرش: `seed` را بستیم؛ حالا چه چیزی هنوز تکان می‌خورد؟**

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

</div>

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

<div dir="rtl">

## ۱. محیط را ثبت کن

</div>

```python
import hashlib
import json
import platform
from importlib.metadata import version

PACKAGES = ["scikit-learn", "numpy", "scipy"]


def environment():
    """هر چیزی که بیرونِ کدِ توست و می‌تواند نتیجه را عوض کند."""
    env = {"python": platform.python_version(),
           "implementation": platform.python_implementation(),
           "machine": platform.machine()}
    for name in PACKAGES:
        env[name] = version(name)
    return env


def env_fp(env):
    return hashlib.sha256(
        json.dumps(env, sort_keys=True).encode("utf-8")).hexdigest()[:12]


ENV = environment()
for k, v in ENV.items():
    print(f"  {k:<16}{v}")
print("env_fp:", env_fp(ENV))
```

```text-approx
  python          3.13.2
  implementation  CPython
  machine         AMD64
  scikit-learn    1.7.2
  numpy           2.4.6
  scipy           1.17.1
env_fp: 07aa03401abd
```

<div dir="rtl">

**عددهای بالا روی ماشینِ تو فرق دارند — و همین دلیلِ وجودِ این بخش است.** نسخهٔ کتابخانه‌ها یک متغیرِ پنهانِ آزمایشِ توست، و تنها راهِ دیده شدنش این است که ثبت شود. `machine` هم هست، چون معماریِ پردازنده می‌تواند ترتیبِ محاسبات را عوض کند (بخشِ ۵).

> 🔧 **اگر کار نکرد:** `PackageNotFoundError: No package metadata was found for sklearn` یعنی نامِ **بستهٔ نصبی** را با نامِ **ماژولِ ایمپورتی** اشتباه گرفته‌ای. `import sklearn` درست است، ولی بسته‌اش `scikit-learn` نام دارد. همین برای `PIL` (بسته‌اش `Pillow`) و `cv2` (بسته‌اش `opencv-python`) هم صادق است. **راهِ مطمئن: نامِ بسته را از `pip freeze` بردار، نه از خطِ `import`.**

## ۲. هر `seed` که از داخل بسته می‌شود

</div>

```python
import os
import random

import numpy as np


def set_all_seeds(seed):
    """هر منبعِ تصادفی که از داخلِ این فرآیند در دسترس است."""
    os.environ["PYTHONHASHSEED"] = str(seed)     # دیر است — بخشِ ۴ نشان می‌دهد چرا
    random.seed(seed)
    np.random.seed(seed)


set_all_seeds(0)
print("seedها بسته شدند")
```

```text
seedها بسته شدند
```

<div dir="rtl">

## ۳. اثرِ انگشتِ اجرا

**متریک برای بازتولیدپذیری کافی نیست.** دو مدلِ کاملاً متفاوت می‌توانند `F1` یکسان بدهند. چیزی که باید اثرِ انگشت بگیری، **پیش‌بینیِ مدل برای تک‌تکِ ردیف‌های آزمون** است.

</div>

```python
from sklearn.feature_extraction.text import CountVectorizer
from sklearn.linear_model import LogisticRegression


def predictions(cfg):
    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"])
    model.fit(vec.fit_transform([texts[i] for i in tr]), [Y[i] for i in tr])
    return model.predict(vec.transform([texts[i] for i in te]))


def pred_fp(cfg):
    """اثرِ انگشتِ پیش‌بینی‌ها — نه متریک، خودِ جوابِ مدل برای تک‌تکِ ردیف‌ها."""
    return hashlib.sha256(bytes(predictions(cfg).tolist())).hexdigest()[:16]


print("اثرِ انگشتِ اجرا:", pred_fp({"balance": "oversample"}))
```

```text-approx
اثرِ انگشتِ اجرا: bf4e08f40450ef6f
```

<div dir="rtl">

**این عدد روی ماشینِ تو ممکن است فرق کند و آن هم اشکالی ندارد.** چیزی که نباید فرق کند این است:

</div>

```python
base = pred_fp({"balance": "oversample"})
print("دو اجرای پشتِ سرِ هم یکسان‌اند؟", base == pred_fp({"balance": "oversample"}))
set_all_seeds(999)
print("بعد از set_all_seeds(999) هم؟  ", base == pred_fp({"balance": "oversample"}))
print("با seed دیگر یکسان است؟       ",
      base == pred_fp({"balance": "oversample", "seed": 1}))
```

```text
دو اجرای پشتِ سرِ هم یکسان‌اند؟ True
بعد از set_all_seeds(999) هم؟   True
با seed دیگر یکسان است؟        False
```

<div dir="rtl">

**سه خط، سه ادعای متفاوت.** خطِ اول همان چیزی است که می‌خواستیم. **خطِ دوم مهم‌تر است: `seed` سراسری را به ۹۹۹ عوض کردیم و هیچ اتفاقی نیفتاد** — چون `run` هیچ‌وقت به تصادفِ سراسری تکیه نمی‌کند و همه‌جا `random.Random(seed)` محلی می‌سازد. **این طراحی است، نه شانس.** و خطِ سوم می‌گوید اثرِ انگشت **کور نیست**: چیزی که باید عوضش کند، عوضش می‌کند.

> ✅ **چک کن:** `set_all_seeds` را کاملاً حذف کن و کلِ نوت‌بوک را دوباره اجرا کن. **هر سه خط باید همان جواب را بدهند.** اگر دادند، یعنی آزمایشت به تصادفِ سراسری وابسته نیست — که خودش یک آزمونِ سلامتِ ارزشمند است. **اگر ندادند، جایی در کدت `random.random()` یا `np.random.rand()` بی‌`seed` صدا زده می‌شود.**

## ۴. جایی که قطعیت ممکن نیست — یک

پایتون رشته‌ها را با یک عددِ تصادفیِ **هر بار متفاوت** hash می‌کند، پس ترتیبِ پیمایشِ یک `set` از رشته‌ها در هر اجرای تازهٔ مفسر فرق می‌کند. برای دیدنش، با `subprocess` شش مفسرِ تازه راه می‌اندازیم و خروجی‌شان را می‌شماریم — **یک سلولِ نوت‌بوک همیشه در یک فرآیندِ واحد است و این تفاوت را نشان نمی‌دهد.**

</div>

```python
import subprocess
import sys

CHILD = (
    "s = ['تشدید', 'پرداخت', 'ارسال', 'اپلیکیشن', 'حساب', 'متن',"
    " 'مشتری', 'زمان', 'برچسب', 'مدل', 'آزمایش', 'نتیجه']\n"
    "print('|'.join(set(s)))"
)


def child_orders(rounds, hash_seed):
    env = dict(os.environ)
    env["PYTHONIOENCODING"] = "utf-8"
    if hash_seed is None:
        env.pop("PYTHONHASHSEED", None)
    else:
        env["PYTHONHASHSEED"] = hash_seed
    return [subprocess.run([sys.executable, "-c", CHILD], capture_output=True,
                           text=True, encoding="utf-8", env=env).stdout.strip()
            for _ in range(rounds)]


free = child_orders(6, None)
fixed = child_orders(6, "0")
print("بدونِ PYTHONHASHSEED — هر ۶ اجرا یک ترتیب دادند؟", len(set(free)) == 1)
print("با PYTHONHASHSEED=0  — هر ۶ اجرا یک ترتیب دادند؟", len(set(fixed)) == 1)
```

```text
بدونِ PYTHONHASHSEED — هر ۶ اجرا یک ترتیب دادند؟ False
با PYTHONHASHSEED=0  — هر ۶ اجرا یک ترتیب دادند؟ True
```

<div dir="rtl">

**پس راهِ حلی هست.** ولی حالا کاری را بکن که هر کسی اول از همه امتحان می‌کند — همان متغیرِ محیطی را از داخلِ نوت‌بوک تنظیم کن:

</div>

```python
os.environ["PYTHONHASHSEED"] = "0"
child = subprocess.run([sys.executable, "-c", "print(hash('تشدید'))"],
                       capture_output=True, text=True, encoding="utf-8",
                       env=dict(os.environ, PYTHONIOENCODING="utf-8"))
print("این فرآیند با فرزندِ خودش هم‌نظر شد؟",
      hash("تشدید") == int(child.stdout.strip()))
```

```text
این فرآیند با فرزندِ خودش هم‌نظر شد؟ False
```

<div dir="rtl">

**فرزند از متغیرِ محیطی پیروی می‌کند؛ خودِ این فرآیند نه.** بذرِ hash در همان لحظهٔ روشن شدنِ مفسر خوانده می‌شود و بعدش قابلِ تغییر نیست. **پس آن خطی که در `set_all_seeds` نوشتیم، برای فرآیندِ جاری هیچ کاری نمی‌کند** — و عمداً همان‌جا گذاشتیمش تا اینجا رویش دست بگذاریم. راهِ درستش این است که مفسر را **از بیرون** با آن متغیر روشن کنی، **و رابطِ Colab این را به‌ت نمی‌دهد.**

**چرا مهم است؟** چون هر جا کدی روی یک `set` از رشته‌ها حلقه بزند — یک واژگان، یک مجموعهٔ برچسب، یک فهرستِ ویژگی — **ترتیبش در اجرای بعدی فرق می‌کند**، و ترتیب (بخشِ بعد) بی‌اثر نیست. **علاجِ عملی: هیچ‌وقت روی `set` حلقه نزن؛ `sorted(set(...))` بنویس.**

## ۵. جایی که قطعیت ممکن نیست — دو

</div>

```python
rng = random.Random(0)
vals = [rng.uniform(-1, 1) for _ in range(20000)]
shuffled = vals[:]
random.Random(1).shuffle(shuffled)
print("جمعِ پایتون با جمعِ numpy برابر است؟      ",
      sum(vals) == float(np.array(vals).sum()))
print("همان اعداد با دو ترتیب، در numpy برابرند؟",
      float(np.array(vals).sum()) == float(np.array(shuffled).sum()))
```

```text
جمعِ پایتون با جمعِ numpy برابر است؟       False
همان اعداد با دو ترتیب، در numpy برابرند؟ False
```

```python
print("جمعِ پایتون      :", repr(sum(vals)))
print("جمعِ numpy       :", repr(float(np.array(vals).sum())))
print("numpy، ترتیبِ دوم:", repr(float(np.array(shuffled).sum())))
print("اختلافِ دو ترتیب  :",
      abs(float(np.array(vals).sum()) - float(np.array(shuffled).sum())))
```

```text-approx
جمعِ پایتون      : 17.268048768837048
جمعِ numpy       : 17.26804876883704
numpy، ترتیبِ دوم: 17.268048768837048
اختلافِ دو ترتیب  : 7.105427357601002e-15
```

<div dir="rtl">

**دقیقاً همان بیست هزار عدد، فقط با ترتیبِ متفاوت، دو جمعِ متفاوت.** اختلاف در حدِ ۱۰ به توانِ منفیِ ۱۵ است و همین کوچکی گمراه‌کننده است: **در یک محاسبهٔ زنجیره‌ای بزرگ می‌شود**، و اگر جایی مقایسهٔ «بزرگ‌تر از» انجام شود، **یک بیتِ آخر می‌تواند یک تصمیم را برگرداند.**

جمعِ اعشاری شرکت‌پذیر نیست، و کتابخانه‌های عددی برای سرعت جمع را **تکه‌تکه و موازی** انجام می‌دهند. تعدادِ تکه‌ها به پردازنده، به تعدادِ نخ‌ها و به نسخهٔ کتابخانه بستگی دارد — **هیچ‌کدام از این‌ها زیرِ کنترلِ کدِ تو نیستند.** روی GPU وضعیت بدتر است.

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** یک محاسبه با خودش، فقط با ترتیبِ متفاوتِ همان اعداد. **روی کدام داده؟** بیست هزار عددِ تصادفیِ `seed`دار، پس خودِ داده کاملاً بازتولیدپذیر است — **و همین است که ناقطعیتِ باقی‌مانده را به گردنِ محاسبه می‌اندازد، نه به گردنِ داده.** **با چند `seed`؟** یکی کافی است، چون ادعا «همیشه فرق می‌کند» نیست؛ ادعا این است که **می‌تواند فرق کند و کردنش را دیدیم.**

## ۶. پس «بازتولیدپذیر» یعنی چه

</div>

```python
RECORD = WORK / "run_record.json"
cfg = {"balance": "oversample", "seed": 0}
record = {"config": DEFAULTS | cfg, "env": ENV, "env_fp": env_fp(ENV),
          "pred_fp": pred_fp(cfg), "metrics": run(cfg)}
RECORD.write_text(json.dumps(record, ensure_ascii=False, indent=1), encoding="utf-8")
print("ذخیره شد:", RECORD.name, "· کلیدها:", sorted(record))


def reproduce(path):
    """سه ماه بعد: همان پیکربندی را دوباره بزن و بگو دقیقاً چه چیزی فرق کرده."""
    old = json.loads(path.read_text(encoding="utf-8"))
    now = environment()
    drift = [k for k in sorted(set(old["env"]) | set(now))
             if old["env"].get(k) != now.get(k)]
    return {"env_same": drift == [], "env_drift": drift,
            "pred_same": pred_fp(old["config"]) == old["pred_fp"]}


print(reproduce(RECORD))
```

```text
ذخیره شد: run_record.json · کلیدها: ['config', 'env', 'env_fp', 'metrics', 'pred_fp']
{'env_same': True, 'env_drift': [], 'pred_same': True}
```

<div dir="rtl">

حالا وانمود کنیم این رکورد مالِ سه ماه پیش است و از آن موقع همه‌چیز عوض شده:

</div>

```python
faked = json.loads(RECORD.read_text(encoding="utf-8"))
faked["env"]["scikit-learn"] = "0.0.0"
faked["env"]["python"] = "3.0.0"
FAKED = WORK / "run_record_old.json"
FAKED.write_text(json.dumps(faked, ensure_ascii=False, indent=1), encoding="utf-8")
out = reproduce(FAKED)
print("محیط یکی است؟       ", out["env_same"])
print("چه چیزی فرق دارد؟   ", out["env_drift"])
print("پیش‌بینی‌ها یکی است؟", out["pred_same"])
```

```text
محیط یکی است؟        False
چه چیزی فرق دارد؟    ['python', 'scikit-learn']
پیش‌بینی‌ها یکی است؟ True
```

<div dir="rtl">

**رکورد دقیقاً نامِ دو چیزی را می‌دهد که عوض شده‌اند.** فرقِ این با «نتیجه بازتولید نشد» تمامِ ماجراست: **اولی یک سرنخ است، دومی یک بن‌بست.**

**پس تعریفِ صادقانه‌ای که از این فصل بیرون می‌آید:**

- **بازتولیدپذیریِ کامل** — همان بیت‌ها، همیشه، همه‌جا — **تقریباً هیچ‌وقت به‌دست نمی‌آید** و قول دادنش نادرست است.
- **چیزی که به‌دست می‌آید و کافی است:** در **همان محیط**، همان پیکربندی همان اثرِ انگشت را می‌دهد؛ و اگر محیط عوض شده باشد، **رکورد می‌گوید کدام قسمتش.**

> 🤖 **از دستیارت بپرس:** «چرا `PYTHONHASHSEED` را نمی‌شود بعد از شروعِ مفسر عوض کرد؟» بعد این را هم بپرس: **«اگر کدم روی GPU اجرا شود، چه منابعِ ناقطعیتِ تازه‌ای اضافه می‌شود و کدامشان را می‌شود خاموش کرد؟»** — جوابِ دوم به دو گزینه می‌رسد که هر دو **سرعت را کم می‌کنند**، و همین معامله را باید آگاهانه انجام بدهی.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| reproducibility | ریپروداسیبیلیتی | رسیدن به همان نتیجه با همان ورودی‌ها |
| environment capture | انوایرمنت کپچر | ثبتِ نسخهٔ پایتون و کتابخانه‌ها و ماشین |
| hash randomization | هش رندومیزیشن | تصادفی بودنِ `hash` رشته‌ها در هر اجرای مفسر |
| non-determinism | نان-دترمینیسم | رفتاری که با ورودیِ یکسان همیشه یکسان نیست |
| floating-point associativity | فلوتینگ-پوینت اسوسیتیویتی | اینکه جمعِ اعشاری به ترتیب حساس است |
| prediction fingerprint | پردیکشن فینگرپرینت | اثرِ انگشتِ خروجیِ مدل روی کلِ دادهٔ آزمون |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا اثرِ انگشت را از پیش‌بینی‌ها می‌گیریم و نه از `F1`؟

**تمرینِ اجباری:** `environment()` را کامل‌تر کن: نسخهٔ `sqlite3`، تعدادِ هسته‌های پردازنده، و مقدارِ متغیرِ محیطیِ `PYTHONHASHSEED` (اگر تنظیم شده باشد). حالا `env_fp` را دوباره بگیر و **با عددِ قبلی مقایسه کن.** بعد سؤالِ اصلی: **کدام‌یک از این فیلدها اگر عوض شود واقعاً می‌تواند نتیجه را عوض کند، و کدام فقط سروصداست؟** برای هرکدام یک جمله بنویس. فیلدی که سروصداست، **هر بار بی‌خود می‌گوید محیط فرق کرده** و بعد از دو هفته کسی به هشدارش نگاه نمی‌کند.

**تمرینِ ستاره‌دار ⭐:** یک تابعِ `vocabulary(texts)` بنویس که واژه‌ها را در یک `set` جمع کند و بعد **بدونِ `sorted`** رویش حلقه بزند و به هر واژه یک شمارهٔ ستون بدهد. حالا همان `predictions` را بنویس که به‌جای `CountVectorizer` از این شماره‌ها استفاده کند، و **در دو فرآیندِ جدا با `subprocess` اجرایش کن و `pred_fp` را مقایسه کن.** بعد `sorted` را اضافه کن و دوباره امتحان کن. **چند بار از ده بار فرق داشتند، قبل و بعد؟** این تنها راهِ فهمیدنِ این است که آن یک کلمه `sorted` واقعاً چه کار می‌کند.

## در فصل بعد

حالا هر اجرا ثبت می‌شود و می‌دانیم تا کجا قابلِ بازتولید است. **مسئلهٔ بعدی این است که اجراها مجانی نیستند.** فضای پیکربندیِ ما همین الان هزاران حالت دارد و هر حالت وقت می‌برد. فصلِ بعد **بودجه را به‌عنوان ورودیِ طراحی** وارد می‌کند: با ۲۴ اجرا، جست‌وجوی شبکه‌ای چه چیزی پیدا می‌کند و جست‌وجوی تصادفی چه چیزی — **و کدام‌شان با همان بودجه به عددِ بهتری می‌رسد.**

</div>

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