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

فصل ۴ از ۸

پیشرفت ترم
۰٪

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

تا اینجا درستیِ کدت را با نگاه کردن به خروجی می‌سنجیدی. این روش تا وقتی جواب می‌دهد که پروژه کوچک باشد و تو تنها کسی باشی که تغییرش می‌دهد. در این فصل همان سنجش را خودکار می‌کنی: assert، pytest، و مهم‌تر از هر دو — چیزی که مخصوصِ پروژه‌های داده است و در آموزش‌های عمومیِ تست‌نویسی نمی‌بینی: تستِ خودِ داده، و تستِ مدل به شکلی که فردا هم معنا داشته باشد.

یک ابزارِ اندازه‌گیریِ چند-شکافه که قطعه‌ها را قبل از عبور می‌سنجد

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

  • با assert انتظارت از یک تابع را ثبت کنی
  • چند تست را با pytest سازمان بدهی و یک‌جا اجرا کنی
  • برای دادهٔ ورودی یک دروازهٔ اعتبارسنجی بنویسی
  • بگویی از یک مدل چه چیزی را باید تست کرد و چه چیزی را نباید

قبل از شروع#

از فصل ۲: پوشهٔ پروژه، ماژول، و import.

از ترمِ ۲ فصل ۵: پاک‌سازیِ قیمتِ متنی — همان کار را اینجا در یک تابع می‌بندیم و تستش می‌کنیم.

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

۱. assert: ثبت کردنِ انتظار#

from pathlib import Path

import pandas as pd

CLEAN_PY = '''import pandas as pd


def clean_price(series):
    """قیمتِ متنی را به عدد تبدیل می‌کند: جداکنندهٔ هزارگان و فاصله را برمی‌دارد."""
    return pd.to_numeric(
        series.astype(str).str.replace(",", "", regex=False).str.strip(),
        errors="coerce",
    )
'''
Path("clean.py").write_text(CLEAN_PY, encoding="utf-8")

import sys
if "" not in sys.path:
    sys.path.insert(0, "")
from clean import clean_price

sample = pd.Series(["12,500,000", " 9800000 ", "نامشخص", "7,000,000"])
result = clean_price(sample)

print(result.tolist())
assert result[0] == 12500000
assert pd.isna(result[2])
print("هر دو assert رد شد بدون خطا")
[12500000.0, 9800000.0, nan, 7000000.0]
هر دو assert رد شد بدون خطا

assert می‌گوید «این باید درست باشد». اگر باشد، هیچ اتفاقی نمی‌افتد و همان سکوت یعنی موفقیت. اگر نباشد، AssertionError:

try:
    assert clean_price(pd.Series(["1,000"]))[0] == 999, "قیمت باید ۹۹۹ باشد"
except AssertionError as error:
    print("AssertionError:", error)
AssertionError: قیمت باید ۹۹۹ باشد

آن متنِ بعد از ویرگول پیامِ خطاست و اختیاری نیست، لازم است. بدونِ آن، شش ماه بعد فقط می‌بینی «تستِ خطِ ۴۷ رد شد» و باید کد را بخوانی تا بفهمی چه انتظاری داشتی.

۲. pytest: وقتی تست‌ها چند تا می‌شوند#

سه assert در نوت‌بوک قابلِ تحمل است. سی‌تا نه. pytest تست‌ها را در فایلِ جدا نگه می‌دارد، همه را با یک دستور اجرا می‌کند، و مهم‌تر: با اولین خطا نمی‌ایستد — همه را اجرا می‌کند و گزارشِ کامل می‌دهد.

TEST_PY = '''import pandas as pd

from clean import clean_price


def test_removes_thousand_separator():
    assert clean_price(pd.Series(["12,500,000"]))[0] == 12500000


def test_strips_spaces():
    assert clean_price(pd.Series([" 9800000 "]))[0] == 9800000


def test_unparsable_becomes_nan():
    assert pd.isna(clean_price(pd.Series(["نامشخص"]))[0])


def test_keeps_length():
    values = pd.Series(["1,000", "bad", "2,000"])
    assert len(clean_price(values)) == len(values)
'''
Path("test_clean.py").write_text(TEST_PY, encoding="utf-8")
print("نوشته شد: test_clean.py")
نوشته شد: test_clean.py

دو قرارداد که pytest بر اساسشان تست‌ها را خودش پیدا می‌کند — و رعایت نکردنشان یعنی تستت اجرا نمی‌شود و تو فکر می‌کنی همه‌چیز سبز است:

  • نامِ فایل با test_ شروع شود.
  • نامِ تابع با test_ شروع شود.

و یک قاعدهٔ سوم: تابع هیچ ورودی‌ای نگیرد و چیزی برنگرداند. این یکی بی‌صدا نیست. تابعی که ورودی بگیرد با ERROR گزارش می‌شود، و تابعی که به‌جای assert مقداری برگرداند می‌گذرد و فقط یک هشدار می‌گیرد، پس چیزی را نسنجیده است.

و نامِ تست، توضیحِ آن است: test_unparsable_becomes_nan بدونِ خواندنِ بدنه‌اش می‌گوید چه چیزی را تضمین می‌کند.

import subprocess

run = subprocess.run(
    [sys.executable, "-m", "pytest", "-q", "test_clean.py"],
    capture_output=True, text=True,
)
print("کد خروج pytest:", run.returncode)
print("همه گذشتند:", "failed" not in run.stdout)
کد خروج pytest: 0
همه گذشتند: True

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

💡 نکته: در Colab معمولاً !pytest -q را می‌زنی و گزارشِ رنگی را می‌بینی. اینجا از subprocess استفاده کردیم تا همین سلول در یک فایلِ .py هم کار کند — همان اصلِ فصلِ ۲.

۳. تستِ داده: چیزی که مخصوصِ کارِ ماست#

در یک برنامهٔ معمولی، ورودی را برنامه‌نویس تعیین می‌کند. در پروژهٔ داده، ورودی از دنیای بیرون می‌آید و بی‌خبر عوض می‌شود: کسی ستونی را تغییرِ نام می‌دهد، یک سامانهٔ دیگر قیمت را به‌صورتِ متن می‌فرستد، یک ردیفِ خراب وارد می‌شود.

کدت هیچ خطایی نمی‌دهد. فقط نتیجه‌اش غلط می‌شود.

from pandas.api.types import is_numeric_dtype

REQUIRED = ["year", "ram_gb", "brand", "city", "price"]
NUMERIC = ["year", "ram_gb", "price"]


def check_data(frame):
    """فهرستِ مشکلاتِ داده. فهرستِ خالی یعنی سالم."""
    problems = [f"ستون {c} نیست" for c in REQUIRED if c not in frame.columns]
    if problems:
        return problems                      # بدونِ ستون، سنجشِ مقدارها بی‌معناست

    problems = [f"ستون {c} عددی نیست" for c in NUMERIC if not is_numeric_dtype(frame[c])]
    if problems:
        return problems                      # با نوعِ غلط، مقایسه‌ها خطا می‌دهند

    if frame["price"].min() <= 0:
        problems.append("قیمت غیرمثبت دارد")
    if not frame["year"].between(2015, 2026).all():
        problems.append("سال خارج از بازهٔ منطقی")
    if frame["price"].isna().any():
        problems.append("قیمت خالی دارد")
    if frame.duplicated().any():
        problems.append("ردیف تکراری دارد")
    return problems


clean = pd.read_csv("laptops_clean.csv")
raw = pd.read_csv("laptops.csv")
broken = clean.copy()
broken.loc[5, "price"] = -1
broken.loc[9, "year"] = 1999

print("دادهٔ پاک‌شده    :", check_data(clean))
print("دادهٔ خام        :", check_data(raw))
print("دادهٔ دستکاری‌شده:", check_data(broken))
دادهٔ پاک‌شده    : []
دادهٔ خام        : ['ستون price عددی نیست']
دادهٔ دستکاری‌شده: ['قیمت غیرمثبت دارد', 'سال خارج از بازهٔ منطقی']

آن دو return زودهنگام، طراحیِ عمدی‌اند و همان چیزی‌اند که این تابع را از یک تابعِ شکننده جدا می‌کند. بدونِ آن‌ها، frame["price"].min() <= 0 روی دادهٔ خام TypeError می‌داد — چون قیمت هنوز متن است. بررسی را از کلی به جزئی مرتب کن: ستون‌ها، بعد نوع‌ها، بعد مقدارها. هر لایه فرض می‌کند لایهٔ قبل درست بوده.

📏 اندازه بگیر: این دروازه را در ابتدای هر مسیرِ پردازشِ داده بگذار، نه در انتها. یک ردیفِ خراب که وارد آموزش شود، نه خطا می‌دهد و نه معلوم می‌شود — فقط عددت را کمی بدتر می‌کند و تو ماه‌ها دنبالِ مقصر می‌گردی. هزینهٔ این تابع پنج دقیقه است؛ هزینهٔ نداشتنش می‌تواند یک فصل باشد.

۴. تستِ مدل: چه چیزی را باید تست کرد#

اینجا رایج‌ترین اشتباه پیش می‌آید. وسوسه می‌شوی بنویسی:

def test_model_accuracy():
    assert model.score(X_test, y_test) == 1381886

این تستِ بدی است، به سه دلیل: با هر نسخهٔ تازهٔ scikit-learn می‌شکند، با هر تغییرِ داده می‌شکند، و مهم‌تر — حتی وقتی می‌شکند به تو نمی‌گوید چیزی خراب شده، فقط می‌گوید چیزی عوض شده.

تستِ خوب قرارداد را می‌سنجد، نه عددِ دقیق را:

from sklearn.compose import ColumnTransformer
from sklearn.dummy import DummyRegressor
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

# در پروژهٔ واقعی این همان PriceModel فصل ۲ است؛ اینجا مستقیم می‌سازیمش
# تا این نوت‌بوک بدونِ هیچ فایلِ بیرونی کار کند.
model = Pipeline([
    ("prepare", ColumnTransformer([
        ("num", Pipeline([("fill", SimpleImputer(strategy="median")),
                          ("scale", StandardScaler())]), ["year", "ram_gb"]),
        ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
    ])),
    ("model", Ridge(alpha=0.1)),
])

X = clean[["year", "ram_gb", "brand", "city"]]
y = clean["price"]
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)

model.fit(X_train, y_train)
baseline = DummyRegressor(strategy="median").fit(X_train, y_train)

model_mae = mean_absolute_error(y_test, model.predict(X_test))
baseline_mae = mean_absolute_error(y_test, baseline.predict(X_test))

print("MAE مدل    :", round(model_mae))
print("MAE خط پایه:", round(baseline_mae))
print("دستِ‌کم دو برابر بهتر از خط پایه:", bool(model_mae < baseline_mae / 2))
MAE مدل    : 1381886
MAE خط پایه: 7793750
دستِ‌کم دو برابر بهتر از خط پایه: True

«دستِ‌کم دو برابر بهتر از خطِ پایه» تستی است که فردا هم معنا دارد. عوض شدنِ نسخه یا داده آن را نمی‌شکند، ولی اگر کسی ستونِ brand را از Pipeline بیندازد، فوراً می‌شکند.

تست کن تست نکن
تابع‌های پاک‌سازیِ خودت خودِ scikit-learn
شکل و نوعِ خروجیِ مدل عددِ دقیقِ متریک
«بهتر از خطِ پایه» «دقیقاً برابرِ فلان عدد»
اینکه پیش‌بینی برای ورودیِ ناشناخته خطا ندهد کیفیتِ پیش‌بینی برای یک ردیفِ خاص
اینکه داده به قرارداد پایبند است اینکه داده «خوب» است (تعریف‌ناپذیر)

✅ چک کن: قبل از اینکه به یک تست اعتماد کنی، عمداً بشکنش. یکی از ستون‌ها را از فهرست‌های ColumnTransformer بردار، مدل را دوباره آموزش بده، و ببین تستِ «دو برابر بهتر» واقعاً قرمز می‌شود یا نه. برداشتنِ ستون فقط از X این آزمایش نیست، چون ColumnTransformer آن ستون را می‌خواهد و با ValueError می‌ایستد. تستی که هرگز شکسته نشده، ممکن است اصلاً چیزی را نسنجد — و این رایج‌تر از چیزی است که فکر می‌کنی.

🔧 اگر کار نکرد: خطای ModuleNotFoundError هنگامِ اجرای pytest تقریباً همیشه یک علت دارد: pytest از پوشه‌ای اجرا می‌شود که ماژولِ تو در مسیرش نیست. از ریشهٔ پروژه اجرایش کن، نه از داخلِ پوشهٔ تست‌ها. و اگر تستی به فایلِ داده نیاز دارد، مسیرش را نسبت به ریشهٔ پروژه بنویس، نه نسبت به فایلِ تست.

🤖 از دستیارت بپرس: تابعِ check_data را به دستیارت بده و بپرس: «چه بررسی‌های دیگری برای این داده منطقی است؟» بعد هر پیشنهاد را با یک سؤال بسنج: اگر این بررسی قرمز شود، من دقیقاً چه کاری می‌کنم؟ اگر جوابی نداری، آن بررسی فقط سروصداست و باید حذفش کنی. تستی که به آن اهمیت نمی‌دهی، بدتر از نداشتنِ تست است — چون به قرمزها عادت می‌کنی.

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

کلمه تلفظ به حروف فارسی یعنی چه
assert اَسِرت «این باید درست باشد»، وگرنه خطا
pytest پای‌تست ابزارِ پیدا کردن و اجرای خودکارِ تست‌ها
test suite تست سوییت مجموعهٔ تست‌های یک پروژه
data validation ولیدیشن داده سنجشِ داده در برابرِ قرارداد، قبل از استفاده
regression test ری‌گرشن تست تستی که جلوی برگشتِ یک خطای رفع‌شده را می‌گیرد

تمرین‌ها

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

در فصل بعد#

کدت تست دارد و داده‌ات دروازه دارد. ولی هنوز فقط تو می‌توانی به‌کارش ببری. فصلِ بعد این را عوض می‌کند: یک رابطِ گرافیکی که هر کسی بتواند بدونِ دیدنِ یک خط کد ازش استفاده کند — با Gradio و در چند خط.

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

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