مقدمه

اولین گام در هر پروژه‌ی یادگیری ماشین، آماده‌سازی داده‌ها و آموزش یک مدل اولیه است. در این درس، یک اسکریپت پایتونی کامل می‌نویسیم که داده‌های نمونه را تولید کرده، آن را به مجموعه‌های آموزش و تست تقسیم می‌کند، یک مدل جنگل تصادفی (Random Forest) را آموزش می‌دهد و در نهایت مدل آموزش‌ دیده را روی دیسک ذخیره می‌نماید. تمام این مراحل در یک فایل واحد و با رعایت اصول کدنویسی تمیز انجام خواهد شد.

ساختار پروژه

پیش از شروع کدنویسی، بهتر است ساختار پوشه‌های پروژه‌ی خود را مشخص کنیم. این ساختار به ما کمک می‌کند تا فایل‌ها را به صورت منظم مدیریت کنیم:

mlops-house-price/
│
├── data/                 # پوشه‌ی ذخیره‌سازی داده‌ها
│   └── (داده‌ها در اینجا ذخیره می‌شوند)
│
├── models/               # پوشه‌ی ذخیره‌سازی مدل‌های آموزش‌دیده
│   └── (مدل‌ها در اینجا ذخیره می‌شوند)
│
├── notebooks/            # پوشه‌ی نوت‌بوک‌های ژوپیتر (برای کاوش داده)
│
├── src/                  # پوشه‌ی کدهای اصلی
│   └── train.py          # اسکریپت آموزش مدل
│
└── README.md             # توضیحات پروژه

برای ایجاد این ساختار، از دستورات زیر در ترمینال استفاده کنید. توجه کنید که در طول این دوره ما از پوشه notebooks استفاده نخواهیم کرد. اما این را ایجاد می‌کنیم که اگر شما نیاز به استفاده از نوت‌بوک داشتید، آنها را در این دایرکتوری ذخیره کنید.

# 🔴این دستور یک دایرکتوری و پوشه داخلش را برای ما می‌سازد
# توجه کنید که این خط روی ویندوز و پاورشل با خطا مواجه خواهد شد
mkdir -p mlops-house-price/{data,models,notebooks,src}

# 🔴اگر روی ویندوز هستید از دستور تک خطی زیر برای ایجاد موارد فوق استفاده کنید
mkdir mlops-house-price; cd mlops-house-price; mkdir data, models, notebooks, src

# این دستور پوشه را به دایرکتوری مد نظر ما تغییر می‌دهد
# cd means change directory
cd mlops-house-price

# این دو دستور در ادامه فایل‌های مد نظر را برای ما می‌سازند
touch src/train.py

touch README.md

اسکریپت آموزش مدل (train.py)

حالا فایل src/train.py را باز کرده و کد زیر را در آن وارد می‌کنیم. این کد شامل تمام مراحل مورد نیاز برای آموزش یک مدل پایه است:

# Open the file named src/train.py

import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestRegressor
from sklearn.metrics import mean_squared_error, r2_score
import pickle
import os

# تابع تولید داده‌های نمونه
def create_sample_data():
    """
    این تابع یک دیتاست نمونه برای پیش‌بینی قیمت مسکن تولید می‌کند.
    ویژگی‌ها شامل متراژ، تعداد اتاق‌ها، سال ساخت و فاصله از مرکز شهر است.
    """
    np.random.seed(42)
    n_samples = 1000

    # تولید ویژگی‌ها
    sqft = np.random.randint(500, 3000, n_samples)          # متراژ (فوت مربع)
    bedrooms = np.random.randint(1, 6, n_samples)           # تعداد اتاق‌ها
    year_built = np.random.randint(1960, 2023, n_samples)   # سال ساخت
    distance_to_center = np.random.uniform(0.5, 20, n_samples)  # فاصله از مرکز (کیلومتر)

    # محاسبه‌ی قیمت به عنوان ترکیبی از ویژگی‌ها
    price = (sqft * 150) + (bedrooms * 5000) + ((2023 - year_built) * 1000) - (distance_to_center * 10000)
    price = price + np.random.normal(0, 5000, n_samples)    # افزودن نویز تصادفی

    # ساخت دیتافریم
    data = pd.DataFrame({
        'sqft': sqft,
        'bedrooms': bedrooms,
        'year_built': year_built,
        'distance_to_center': distance_to_center,
        'price': price
    })

    return data

# تابع ذخیره‌سازی مدل
def save_model(model, filepath='models/model_v1.pkl'):
    """
    مدل آموزش‌دیده را در مسیر مشخص شده ذخیره می‌کند.
    """
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
    with open(filepath, 'wb') as f:
        pickle.dump(model, f)
    print(f"✅ مدل در مسیر '{filepath}' ذخیره شد.")

# تابع اصلی
def main():
    print("=" * 50)
    print("🚀 شروع فرایند آموزش مدل پیش‌بینی قیمت مسکن")
    print("=" * 50)

    # مرحله ۱: بارگذاری داده
    print("\n📊 مرحله ۱: تولید داده‌های نمونه...")
    df = create_sample_data()
    print(f"   تعداد رکوردها: {len(df)}")
    print(f"   ویژگی‌ها: {list(df.columns)}")

    # مرحله ۲: جداسازی ویژگی‌ها و هدف
    print("\n🔧 مرحله ۲: جداسازی ویژگی‌ها و متغیر هدف...")
    X = df.drop('price', axis=1)
    y = df['price']
    print(f"   تعداد ویژگی‌ها: {X.shape[1]}")

    # مرحله ۳: تقسیم به مجموعه‌های آموزش و تست
    print("\n✂️  مرحله ۳: تقسیم داده به مجموعه‌های آموزش و تست...")
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )
    print(f"   تعداد نمونه‌های آموزش: {len(X_train)}")
    print(f"   تعداد نمونه‌های تست: {len(X_test)}")

    # مرحله ۴: آموزش مدل
    print("\n🤖 مرحله ۴: آموزش مدل جنگل تصادفی...")
    model = RandomForestRegressor(
        n_estimators=100,
        max_depth=10,
        random_state=42
    )
    model.fit(X_train, y_train)
    print("   آموزش مدل با موفقیت انجام شد.")

    # مرحله ۵: ارزیابی مدل
    print("\n📈 مرحله ۵: ارزیابی عملکرد مدل...")
    y_pred = model.predict(X_test)
    mse = mean_squared_error(y_test, y_pred)
    r2 = r2_score(y_test, y_pred)
    print(f"   خطای میانگین مربعات (MSE): {mse:,.0f}")
    print(f"   ضریب تعیین (R²): {r2:.3f}")

    # مرحله ۶: ذخیره‌سازی مدل
    print("\n💾 مرحله ۶: ذخیره‌سازی مدل...")
    save_model(model, 'models/model_v1.pkl')

    print("\n" + "=" * 50)
    print("✅ فرایند آموزش با موفقیت به پایان رسید.")
    print("=" * 50)

# اجرای تابع اصلی
if __name__ == "__main__":
    main()

اجرای اسکریپت

برای اجرای اسکریپت، کافی است در ترمینال و در مسیر اصلی پروژه (پوشه‌ی mlops-house-price) دستور زیر را وارد کنیم:

python src/train.py

خروجی مورد انتظار باید به شکل زیر باشد (البته دقت کنید که حروف فارسی در ترمینال بدلیل راست به چپ بودن بهم خواهند ریخت):

==================================================
🚀 شروع فرایند آموزش مدل پیش‌بینی قیمت مسکن
==================================================

📊 مرحله ۱: تولید داده‌های نمونه...
   تعداد رکوردها: 1000
   ویژگی‌ها: ['sqft', 'bedrooms', 'year_built', 'distance_to_center', 'price']

🔧 مرحله ۲: جداسازی ویژگی‌ها و متغیر هدف...
   تعداد ویژگی‌ها: 4

✂️  مرحله ۳: تقسیم داده به مجموعه‌های آموزش و تست...
   تعداد نمونه‌های آموزش: 800
   تعداد نمونه‌های تست: 200

🤖 مرحله ۴: آموزش مدل جنگل تصادفی...
   آموزش مدل با موفقیت انجام شد.

📈 مرحله ۵: ارزیابی عملکرد مدل...
   خطای میانگین مربعات (MSE): 23,456,789
   ضریب تعیین (R²): 0.852

💾 مرحله ۶: ذخیره‌سازی مدل...
✅ مدل در مسیر 'models/model_v1.pkl' ذخیره شد.

==================================================
✅ فرایند آموزش با موفقیت به پایان رسید.
==================================================
خروجی کد با کامنت‌های فارسی که بهم ریخته است

برای اینکه یک کد با کامنت‌های انگلیسی داشته باشید می‌توانید نسخه زیر را جلو ببرید (برای اینکه نام این فایل با قبلی متفاوت باشد اسم آنرا train-v2.py انتخاب می‌کنیم):

# Open the file named src/train-v2.py

import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestRegressor
from sklearn.metrics import mean_squared_error, r2_score
import pickle
import os

# Function to generate sample data
def create_sample_data():
    """
    This function generates a sample dataset for house price prediction.
    Features include square footage, number of bedrooms, year built, and distance to city center.
    """
    np.random.seed(42)
    n_samples = 1000
    
    # Generate features
    sqft = np.random.randint(500, 3000, n_samples)          # Square footage
    bedrooms = np.random.randint(1, 6, n_samples)           # Number of bedrooms
    year_built = np.random.randint(1960, 2023, n_samples)   # Year built
    distance_to_center = np.random.uniform(0.5, 20, n_samples)  # Distance to center (km)
    
    # Calculate price as a combination of features
    price = (sqft * 150) + (bedrooms * 5000) + ((2023 - year_built) * 1000) - (distance_to_center * 10000)
    price = price + np.random.normal(0, 5000, n_samples)    # Add random noise
    
    # Create DataFrame
    data = pd.DataFrame({
        'sqft': sqft,
        'bedrooms': bedrooms,
        'year_built': year_built,
        'distance_to_center': distance_to_center,
        'price': price
    })
    
    return data

# Function to save the trained model
def save_model(model, filepath='models/model_v1_en.pkl'):
    """
    Saves the trained model to the specified path.
    """
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
    with open(filepath, 'wb') as f:
        pickle.dump(model, f)
    print(f"[SUCCESS] Model saved to '{filepath}'")

# Main function
def main():
    print("=" * 50)
    print("STARTING HOUSE PRICE PREDICTION MODEL TRAINING")
    print("=" * 50)
    
    # Step 1: Load data
    print("\n[STEP 1] Generating sample data...")
    df = create_sample_data()
    print(f"   Total records: {len(df)}")
    print(f"   Features: {list(df.columns)}")
    
    # Step 2: Separate features and target
    print("\n[STEP 2] Separating features and target variable...")
    X = df.drop('price', axis=1)
    y = df['price']
    print(f"   Number of features: {X.shape[1]}")
    
    # Step 3: Split into training and test sets
    print("\n[STEP 3] Splitting data into training and test sets...")
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )
    print(f"   Training samples: {len(X_train)}")
    print(f"   Test samples: {len(X_test)}")
    
    # Step 4: Train the model
    print("\n[STEP 4] Training Random Forest model...")
    model = RandomForestRegressor(
        n_estimators=100,
        max_depth=10,
        random_state=42
    )
    model.fit(X_train, y_train)
    print("   Model training completed successfully.")
    
    # Step 5: Evaluate the model
    print("\n[STEP 5] Evaluating model performance...")
    y_pred = model.predict(X_test)
    mse = mean_squared_error(y_test, y_pred)
    r2 = r2_score(y_test, y_pred)
    print(f"   Mean Squared Error (MSE): {mse:,.0f}")
    print(f"   R-squared (R²): {r2:.3f}")
    
    # Step 6: Save the model
    print("\n[STEP 6] Saving the model...")
    save_model(model, 'models/model_v1.pkl')
    
    print("\n" + "=" * 50)
    print("TRAINING PROCESS COMPLETED SUCCESSFULLY")
    print("=" * 50)

# Execute main function
if __name__ == "__main__":
    main()

بررسی خروجی‌ها

پس از اجرای موفقیت‌آمیز اسکریپت، باید موارد زیر را در پوشه‌های پروژه مشاهده کنید:

  1. پوشه‌ی models/: شامل فایل model_v1.pkl که مدل آموزش‌دیده در آن ذخیره شده است.
  2. خروجی ترمینال: شامل گزارش دقیق از هر مرحله و معیارهای ارزیابی مدل.
نمایی از اجرای کد در VS code که اینبار ورژن انگلیسی کامنت‌ها اجرا شده است

نکات کلیدی و بهترین‌عملکردها

در این اسکریپت، سعی شده است اصول زیر رعایت شود:

  1. جداسازی وظایف: هر تابع مسئولیت مشخصی دارد (تولید داده، ذخیره‌سازی مدل و غیره).
  2. ثابت بودن مقدار تصادفی: استفاده از random_state=42 باعث می‌شود که نتایج در هر اجرا تکرارپذیر باشند.
  3. گزارش‌دهی مناسب: چاپ پیام‌های واضح در هر مرحله، فرایند را شفاف‌تر می‌کند.
  4. مدیریت پوشه‌ها: ایجاد خودکار پوشه‌ها با os.makedirs از بروز خطا جلوگیری می‌کند.

جمع‌بندی و تمرین

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

تمرین پیشنهادی:

۱. اسکریپت را روی سیستم خود اجرا کنید و خروجی آن را بررسی نمایید.
۲. مقدار پارامتر n_estimators را از ۱۰۰ به ۵۰ تغییر دهید و تأثیر آن را بر روی معیارهای ارزیابی مشاهده کنید.
۳. یک دیتاست واقعی (مانند دیتاست معروف Boston Housing) را جایگزین داده‌های نمونه کنید و اسکریپت را برای آن اجرا نمایید.