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

فصل ۲ از ۸

پیشرفت ترم
۰٪

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

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

چند برگهٔ پراکنده که در یک زونکنِ مرتب با جداکننده‌های برچسب‌خورده جا می‌گیرند

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

  • بگویی نوت‌بوک کجا کم می‌آورد و پوشهٔ پروژه چه چیزی حل می‌کند
  • کدت را به ماژول‌های مستقل تقسیم کنی و import کنی
  • یک class بنویسی و بگویی چه فرقی با چند تابعِ جدا دارد
  • if __name__ == "__main__" را درست به‌کار ببری

قبل از شروع#

از فصل ۱: random_state، joblib، اثرِ انگشتِ داده.

از ترمِ ۱: تابع، dict، و import.

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

۱. نوت‌بوک کجا کم می‌آورد#

کار در نوت‌بوک در فایلِ .py
کشف و آزمایشِ سریع عالی کند
نمایشِ نتیجه با نمودار عالی جداگانه لازم دارد
استفادهٔ دوباره از یک تابع در جای دیگر copy-paste import
اجرا از خطِ فرمان یا سرور نمی‌شود طبیعی
تست خودکار نمی‌شود طبیعی
دیدنِ تغییرات در git آشفته تمیز
ترتیبِ اجرا دستِ کاربر همیشه از بالا

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

۲. ساختنِ پوشهٔ پروژه#

import shutil
from pathlib import Path

PROJECT = Path("price_tool")
shutil.rmtree(PROJECT, ignore_errors=True)   # تا اجرای دوباره همیشه از صفر شروع کند
PROJECT.mkdir()
(PROJECT / "__init__.py").write_text("", encoding="utf-8")

print("پوشه ساخته شد:", PROJECT.name)
print("فایل‌های پایتون:", sorted(p.name for p in PROJECT.glob("*.py")))
پوشه ساخته شد: price_tool
فایل‌های پایتون: ['__init__.py']

دو چیزِ تازه در همین چند خط:

Path از کتابخانهٔ pathlib راهِ امروزیِ کار با مسیرِ فایل در پایتون است. به‌جای چسباندنِ رشته‌ها — که روی ویندوز و لینوکس فرق می‌کند — یک شیءِ مسیر می‌سازی و با .mkdir() و .write_text() رویش کار می‌کنی.

و آن / بینِ دو مسیر ضرب و تقسیم نیست. PROJECT / "__init__.py" یعنی «فایلِ __init__.py داخلِ پوشهٔ PROJECT». pathlib عمداً همین علامت را انتخاب کرده چون شکلش دقیقاً شبیهِ جداکنندهٔ مسیر است، و خودش می‌داند روی هر سیستم‌عاملی چه جداکننده‌ای بگذارد.

__init__.py — حتی خالی — به پایتون می‌گوید این پوشه یک بستهٔ قابلِ import است.

آن rmtree هم عمدی است: سلولی که بارِ دوم نتیجهٔ متفاوتی بدهد، همان دامِ حالتِ پنهانِ ترمِ ۱ فصلِ ۱۰ است. با پاک کردنِ پوشه در ابتدا، اجرای دوباره همیشه همان چیزی را می‌سازد که اجرای اول ساخت. و glob("*.py") هم فقط فایل‌های پایتون را می‌شمارد، تا پوشهٔ __pycache__ که خودِ پایتون می‌سازد، خروجی را عوض نکند.

💡 نکته: در Colab دستورِ %%writefile هم هست که محتوای یک سلول را در فایل می‌ریزد. اینجا عمداً از Path.write_text استفاده می‌کنیم، چون کدِ معمولیِ پایتون است و همان‌طور که در نوت‌بوک کار می‌کند، در یک فایلِ .py هم کار می‌کند — و همین موضوعِ کلِ فصل است. encoding="utf-8" را هم همیشه بنویس: بدونِ آن، روی بعضی سیستم‌ها متنِ فارسیِ داخلِ فایل خراب ذخیره می‌شود.

۳. اولین ماژول: داده#

DATA_PY = '''"""خواندن و شناسنامهٔ داده."""
import hashlib

import pandas as pd

FEATURES = ["year", "ram_gb", "brand", "city"]
TARGET = "price"


def load_data(path="laptops_clean.csv"):
    frame = pd.read_csv(path)
    return frame[FEATURES], frame[TARGET]


def fingerprint(frame):
    digest = hashlib.sha256(pd.util.hash_pandas_object(frame, index=True).values.tobytes())
    return digest.hexdigest()[:16]
'''

(PROJECT / "data.py").write_text(DATA_PY, encoding="utf-8")
print("نوشته شد:", sorted(p.name for p in PROJECT.glob("*.py")))
نوشته شد: ['__init__.py', 'data.py']

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

  • یک فایل، یک مسئولیت. data.py فقط با داده کار دارد. مدل جای دیگری است.
  • مقدارهای ثابت بالای فایل و با نامِ بزرگ. FEATURES یک بار تعریف می‌شود و همه‌جا از همان استفاده می‌شود — نه اینکه در پنج سلولِ مختلف دوباره تایپ شود.
  • مسیرها parameterاند، نه ثابتِ داخلِ کد. load_data(path=...) یعنی همین تابع فردا روی فایلِ دیگری هم کار می‌کند.

۴. class: داده و رفتارش، در یک جا#

در ترمِ ۴ فصلِ ۸ یک dict ساختی که وضعیتِ دستیار را نگه می‌داشت، و چند تابع نوشتی که هر کدام آن dict را به‌عنوان اولین ورودی می‌گرفتند. کار می‌کرد، ولی سه ایراد داشت:

  • هیچ‌چیز جلوی این را نمی‌گرفت که کسی یک کلیدِ لازم را جا بیندازد و خطا موقعِ استفاده ظاهر شود، نه موقعِ ساختن.
  • تابع‌ها از dict جدا بودند؛ هیچ‌جا نوشته نبود که این چهار تابع فقط با این شکل از dict کار می‌کنند.
  • برای هر تابع باید bot را دستی پاس می‌دادی.

class دقیقاً این را حل می‌کند: داده و تابع‌هایی را که رویش کار می‌کنند در یک چیزِ واحد می‌بندد.

MODEL_PY = '''"""مدلِ قیمت: داده و رفتارش، در یک جا."""
import joblib
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler


class PriceModel:
    """یک مدلِ قیمت با هر چیزی که برای به‌کار بردنش لازم است."""

    def __init__(self, alpha=0.1, seed=0):
        self.alpha = alpha
        self.seed = seed
        self.pipeline = Pipeline([
            ("prepare", ColumnTransformer([
                ("num", Pipeline([
                    ("fill", SimpleImputer(strategy="median")),
                    ("scale", StandardScaler()),
                ]), ["year", "ram_gb"]),
                ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
            ])),
            ("model", Ridge(alpha=alpha)),
        ])

    def fit(self, X, y):
        self.pipeline.fit(X, y)
        return self

    def predict(self, X):
        return self.pipeline.predict(X)

    def score(self, X, y):
        return mean_absolute_error(y, self.predict(X))

    def save(self, path="price_model.joblib"):
        joblib.dump(self, path)
        return path


def load_model(path="price_model.joblib"):
    """بارگذاری بیرونِ کلاس است، چون هنوز شیئی وجود ندارد که متدش را صدا بزنی."""
    return joblib.load(path)
'''

(PROJECT / "model.py").write_text(MODEL_PY, encoding="utf-8")
print("نوشته شد:", sorted(p.name for p in PROJECT.glob("*.py")))
نوشته شد: ['__init__.py', 'data.py', 'model.py']

سه کلمهٔ تازه، و هر سه ساده‌اند:

  • class PriceModel: یک نوعِ تازه تعریف می‌کند. مثلِ نقشهٔ ساختمان — خودش ساختمان نیست، ولی می‌شود از رویش ساخت.
  • __init__ وقتی صدا زده می‌شود که یکی از روی نقشه چیزی می‌سازد. کارش پر کردنِ وضعیتِ اولیه است.
  • self یعنی «همین شیءِ مشخص». self.alpha = alpha یعنی این عدد را در خودِ این شیء نگه دار، نه در یک متغیرِ محلی که با تمام شدنِ تابع از بین می‌رود.

توجه کن که fit در آخر return self می‌کند. این یک عادتِ عمدی است و همان چیزی است که به scikit-learn اجازه می‌دهد بنویسی PriceModel().fit(X, y) در یک خط — همان الگویی که چهار ترم دیده‌ای، حالا از داخل.

۵. import کردنِ چیزی که ساختی#

import sys

if "" not in sys.path:
    sys.path.insert(0, "")   # پوشهٔ فعلی را جزو مسیرهای جست‌وجوی پایتون کن

from sklearn.model_selection import train_test_split

from price_tool.data import load_data
from price_tool.model import PriceModel

X, y = load_data()
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)
model = PriceModel(alpha=0.1, seed=0).fit(X_train, y_train)

print("نوع شیء:", type(model).__name__)
print("alpha:", model.alpha, "| seed:", model.seed)
print("MAE:", round(model.score(X_test, y_test)))
نوع شیء: PriceModel
alpha: 0.1 | seed: 0
MAE: 1381886

همان 1381886 فصلِ ۱ — که خوب است: بازچینیِ کد نباید نتیجه را عوض کند. اگر عوض شد، بازچینی نکرده‌ای، برنامهٔ دیگری نوشته‌ای.

✅ چک کن: اگر ModuleNotFoundError: No module named 'price_tool' گرفتی، سه چیز را به‌ترتیب چک کن: پوشه واقعاً کنارِ نوت‌بوکِ توست، __init__.py داخلش هست، و سلولِ بخشِ ۲ اجرا شده. و اگر فایلی را عوض کردی ولی رفتار عوض نشد، پایتون نسخهٔ قبلی را در حافظه دارد — در Colab Runtime > Restart session بزن؛ این یکی از رایج‌ترین سردرگمی‌های همین فصل است.

۶. نقطهٔ ورود#

MAIN_PY = '''"""نقطهٔ ورودِ برنامه."""
from sklearn.model_selection import train_test_split

from price_tool.data import fingerprint, load_data
from price_tool.model import PriceModel

SEED = 0


def main():
    X, y = load_data()
    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=SEED)
    model = PriceModel(seed=SEED).fit(X_train, y_train)
    path = model.save()
    print("اثر انگشت داده:", fingerprint(X))
    print("MAE روی آزمون :", round(model.score(X_test, y_test)))
    print("مدل ذخیره شد در:", path)


if __name__ == "__main__":
    main()
'''

(PROJECT / "main.py").write_text(MAIN_PY, encoding="utf-8")

from price_tool.main import main
main()
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib

if __name__ == "__main__": مهم‌ترین دو خطِ این فصل است. معنایش این است: «این‌ها را فقط وقتی اجرا کن که این فایل مستقیم اجرا شده، نه وقتی که کسی importش کرده.»

بدونِ آن، همین حالا که from price_tool.main import main را نوشتیم، کلِ آموزشِ مدل خودش اجرا می‌شد — و در یک برنامهٔ بزرگ‌تر یعنی هر import ساده ممکن است ساعت‌ها محاسبه راه بیندازد.

از خطِ فرمان (یا با ! در Colab) همین فایل از پوشهٔ بالاتر، با -m، این‌طور اجرا می‌شود. -m یعنی «این را به‌عنوانِ ماژولی از یک بسته اجرا کن»، و price_tool.main همان نامی است که در import نوشتی، با نقطه، نه با /:

python -m price_tool.main
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib

۷. class سرِ جایش می‌ماند#

import pandas as pd

from price_tool.model import load_model

loaded = load_model()
new_laptop = pd.DataFrame([{"year": 2022, "ram_gb": 16, "brand": "ایسوس", "city": "تهران"}])

print("نوع شیء بعد از بارگذاری:", type(loaded).__name__)
print("alpha حفظ شد:", loaded.alpha)
print("قیمت پیشنهادی:", round(float(loaded.predict(new_laptop)[0])))
نوع شیء بعد از بارگذاری: PriceModel
alpha حفظ شد: 0.1
قیمت پیشنهادی: 30840171

کلِ شیء ذخیره و بازخوانی شد — نه فقط Pipeline، بلکه alpha و seed هم که خودت گذاشته بودی. مدلی که از فایل درآمد، دقیقاً همان چیزی است که ذخیره شده بود، با همان شناسنامه.

⚠️ مواظب باش: همین قابلیت یک قیدِ سفت هم دارد: برای باز کردنِ این فایل، پایتون باید کلاسِ PriceModel را پیدا کند. اگر فایلِ model.py را جابه‌جا کنی یا نامِ کلاس را عوض کنی، فایلِ ذخیره‌شده باز نمی‌شود. فایلِ مدل بدونِ کدش بی‌فایده است — پس هر دو را با هم و با نسخهٔ یکسان نگه دار.

۸. requirements.txt و شکلِ نهایی#

price_tool/
    __init__.py        ← این پوشه یک بستهٔ قابلِ import است
    data.py            ← خواندن داده و اثر انگشت
    model.py           ← class PriceModel
    main.py            ← نقطهٔ ورود
requirements.txt       ← وابستگی‌ها با نسخه
README.md              ← این پروژه چیست و چطور اجرا می‌شود

🔧 اگر کار نکرد: خطای ModuleNotFoundError: No module named 'price_tool' موقعِ اجرا یعنی فایل را با مسیرش اجرا کرده‌ای. وقتی می‌نویسی python price_tool/main.py یا داخلِ پوشه می‌روی و python main.py می‌زنی، پایتون پوشهٔ خودِ فایل را جست‌وجو می‌کند، نه پوشهٔ بالاتر را، پس بستهٔ price_tool را نمی‌بیند. همیشه از پوشهٔ بالاتر و با python -m price_tool.main اجرا کن.

🤖 از دستیارت بپرس: کلِ model.py را به دستیارت بده و بپرس: «این کلاس چه متدهای دیگری بهتر است داشته باشد؟» جوابش را با معیارِ خودت بسنج، نه با تعدادش: هر متدی که اضافه می‌کنی باید یا وضعیتِ داخلیِ کلاس را لازم داشته باشد یا رویش اثر بگذارد. اگر تابعی به self کاری ندارد، جایش داخلِ کلاس نیست — این ساده‌ترین و مفیدترین معیارِ تصمیم است.

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

کلمه تلفظ به حروف فارسی یعنی چه
pathlib / Path پث‌لیب / پث کار با مسیرِ فایل به‌صورتِ شیء؛ / یعنی «داخلِ این پوشه»
module ماژول یک فایلِ .py که می‌شود importش کرد
package پکیج پوشه‌ای با __init__.py که چند ماژول دارد
class کلاس نوعی تازه: داده + رفتارهایش، با هم
instance اینستنس یک شیءِ ساخته‌شده از روی یک کلاس
method متد تابعی که داخلِ کلاس تعریف شده
entry point انتری پوینت جایی که اجرای برنامه از آن شروع می‌شود

تمرین‌ها

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

در فصل بعد#

پروژه‌ات حالا چند فایل است. فصلِ بعد سؤالی را جواب می‌دهد که همین‌جا ساخته شد: وقتی فردا فایل را عوض کردی و خراب شد، چطور به دیروز برمی‌گردی؟ جوابش git است — و آن را از داخلِ همین Colab به‌کار می‌بریم.

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

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