مقدمه

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

ای‌پی‌آی یا رابط برنامه‌نویسی (Application Programming Interface=API) دقیقن همین کار را انجام می‌دهد. با ساخت یک API، مدل ما به یک سرویس تبدیل می‌شود که درخواست‌ها را دریافت کرده، پیش‌بینی را انجام داده و نتیجه را بازمی‌گرداند.

در این درس، با استفاده از FastAPI یک API ساده برای مدل پیش‌بینی قیمت مسکن خود می‌سازیم. فست‌ای‌پی‌آی یکی از سریع‌ترین و محبوب‌ترین فریم‌ورک‌های ساخت API در پایتون است که به صورت خودکار، مستندسازی تعاملی (Swagger UI) تولید می‌کند.

بخش اول: FastAPI چیست؟

فست‌ای‌پی‌آی یک فریم‌ورک مدرن و پرسرعت برای ساخت API با پایتون است. در جدول ذیل می‌توانید ویژگی‌های کلیدی این فریم‌ورک محبوب را مشاهده نمائید:

ویژگیتوضیح
سرعت بالایکی از سریع‌ترین فریم‌ورک‌های پایتون (همرده‌ی NodeJS و Go)
مستندسازی خودکارتولید خودکار مستندات Swagger UI و ReDoc
اعتبارسنجی دادهبا استفاده از Pydantic، داده‌های ورودی به صورت خودکار اعتبارسنجی می‌شوند
پشتیبانی از نوع‌دهی (Type Hints)کدنویسی تمیزتر و قابل‌درک‌تر
غیرهمزمان (Async)پشتیبانی از برنامه‌نویسی غیرهمزمان برای عملکرد بهتر

بخش دوم: نوشتن اولین برنامه با FastAPI

تا اینجا، مدل ما به صورت یک فایل pkl در پوشه‌ی models/ ذخیره شده است. اما این مدل به تنهایی برای کاربران یا برنامه‌های دیگر قابل استفاده نیست. برای اینکه بتوانیم از مدل خود به عنوان یک وب-سرویس استفاده کنیم، باید آن را درون یک برنامه‌ی وب قرار دهیم که از طریق اینترنت درخواست دریافت کند و پاسخ بدهد.

فایل src/app.py که در ادامه می‌بینیم، دقیقن همین کار را انجام می‌دهد. این فایل یک API است که با استفاده از فریم‌ورک FastAPI نوشته شده و کارهای زیر را انجام می‌دهد:

۱. مدل را از فایل pkl بارگذاری می‌کند (تا نیازی به آموزش مجدد نباشد).
۲. درخواست‌های ورودی را می‌گیرد (مشخصات یک خانه مانند متراژ، تعداد اتاق و …).
۳. داده را به فرمت مناسب برای مدل تبدیل می‌کند (مثلن به دیتافریم پانداس).
۴. پیش‌بینی را انجام می‌دهد و قیمت را محاسبه می‌کند.
۵. نتیجه را به صورت پاسخ برمی‌گرداند (معمولن به صورت JSON).

محتویات فایل src/app.py بشکل زیر است:

# src/app.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import pandas as pd
import pickle
import os
from typing import List, Optional

# ایجاد نمونه‌ی برنامه
app = FastAPI(
    title="House Price Prediction API",
    description="An API for predicting house prices based on features like square footage, bedrooms, etc.",
    version="1.0.0"
)

# تعیین مدل داده‌ی ورودی
class HouseFeatures(BaseModel):
    """
    مدل داده‌ی ورودی برای پیش‌بینی قیمت مسکن
    """
    sqft: float          # متراژ (فوت مربع)
    bedrooms: int        # تعداد اتاق‌ها
    year_built: int      # سال ساخت
    distance_to_center: float  # فاصله از مرکز شهر (کیلومتر)

    class Config:
        json_schema_extra = {
            "example": {
                "sqft": 1500,
                "bedrooms": 3,
                "year_built": 2005,
                "distance_to_center": 5.5
            }
        }

# تعیین مدل داده‌ی ورودی برای پیش‌بینی چندگانه
class HousesFeatures(BaseModel):
    houses: List[HouseFeatures]

# بارگذاری مدل
def load_model():
    """
    مدل آموزش‌دیده را از فایل بارگذاری می‌کند.
    """
    model_path = os.path.join(os.path.dirname(__file__), '..', 'models', 'model_v1.pkl')

    if not os.path.exists(model_path):
        raise FileNotFoundError(f"Model file not found at {model_path}")

    with open(model_path, 'rb') as f:
        model = pickle.load(f)
    return model

# بارگذاری مدل هنگام راه‌اندازی سرور
try:
    model = load_model()
    print("[SUCCESS] Model loaded successfully")
except Exception as e:
    print(f"[ERROR] Failed to load model: {e}")
    model = None

# تعریف مسیرهای ای‌پی‌آی

@app.get("/")
def read_root():
    """
    مسیر اصلی برای بررسی سلامتی ای‌پی‌آی
    """
    return {
        "message": "House Price Prediction API",
        "status": "running",
        "model_loaded": model is not None
    }

@app.get("/health")
def health_check():
    """
    بررسی وضعیت سلامت ای‌پی‌آی و مدل
    """
    return {
        "status": "healthy",
        "model_loaded": model is not None,
        "model_path": "models/model_v1.pkl"
    }

@app.post("/predict")
def predict_price(house: HouseFeatures):
    """
    پیش‌بینی قیمت برای یک خانه‌ی واحد
    """
    if model is None:
        raise HTTPException(status_code=503, detail="Model is not loaded")

    try:
        # تبدیل داده‌های ورودی به دیتافریم
        input_data = pd.DataFrame([{
            'sqft': house.sqft,
            'bedrooms': house.bedrooms,
            'year_built': house.year_built,
            'distance_to_center': house.distance_to_center
        }])

        # انجام پیش‌بینی
        prediction = model.predict(input_data)

        return {
            "predicted_price": round(prediction[0], 2),
            "features": house.dict()
        }
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Prediction error: {str(e)}")

@app.post("/predict_batch")
def predict_prices_batch(houses: HousesFeatures):
    """
    پیش‌بینی قیمت برای چند خانه به صورت دسته‌ای
    """
    if model is None:
        raise HTTPException(status_code=503, detail="Model is not loaded")

    try:
        # تبدیل داده‌های ورودی به دیتافریم
        input_data = pd.DataFrame([{
            'sqft': h.sqft,
            'bedrooms': h.bedrooms,
            'year_built': h.year_built,
            'distance_to_center': h.distance_to_center
        } for h in houses.houses])

        # انجام پیش‌بینی
        predictions = model.predict(input_data)

        # ساخت لیست نتایج
        results = []
        for i, house in enumerate(houses.houses):
            results.append({
                "house": i + 1,
                "predicted_price": round(predictions[i], 2),
                "features": house.dict()
            })

        return {
            "total": len(results),
            "predictions": results
        }
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Batch prediction error: {str(e)}")

@app.get("/info")
def model_info():
    """
    نمایش اطلاعات مدل
    """
    if model is None:
        raise HTTPException(status_code=503, detail="Model is not loaded")

    return {
        "model_type": "RandomForestRegressor",
        "model_loaded": True,
        "features": ["sqft", "bedrooms", "year_built", "distance_to_center"],
        "version": "1.0.0"
    }

این API چه مسیرهایی دارد؟

این فایل (src/app.py) شامل چندین مسیر (Endpoint) خواهد بود که هر کدام کار مشخصی انجام می‌دهند:

  • / : بررسی وضعیت اجرای API.
  • health/ : بررسی سلامت مدل و سرور.
  • predict/ : دریافت مشخصات یک خانه و برگرداندن قیمت پیش‌بینی‌شده.
  • predict_batch/ : دریافت مشخصات چند خانه و برگرداندن قیمت همه‌ی آنها.
  • info/ : نمایش اطلاعاتی درباره‌ی مدل (نوع مدل، ویژگی‌های ورودی و …).

بخش سوم: اجرای سرور

برای اجرای سرور، از دستور زیر در ترمینال (در مسیر پروژه) استفاده کنید:

uvicorn src.app:app --reload --host 0.0.0.0 --port 8000
پارامترتوضیح
src.app:appمسیر فایل و نام برنامه (app در فایل app.py)
--reloadراه‌اندازی مجدد خودکار هنگام تغییر کد (فقط برای توسعه)
--host 0.0.0.0گوش‌دادن به همه‌ی آدرس‌های IP (قابل دسترس از شبکه)
--port 8000پورت اجرای سرور

خروجی مورد انتظار:

INFO:     Will watch for changes in these directories: ['E:\\Previous-Courses\\Simple-MLOps-Text-Course\\mlops-house-price']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [13492] using StatReload
[SUCCESS] Model loaded successfully
INFO:     Started server process [13908]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1:1434 - "GET / HTTP/1.1" 200 OK
INFO:     127.0.0.1:1434 - "GET /favicon.ico HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:1434 - "GET /docs HTTP/1.1" 200 OK
INFO:     127.0.0.1:1434 - "GET /openapi.json HTTP/1.1" 200 OK

بخش چهارم: تست API با Swagger UI

یکی از ویژگی‌های عالی FastAPI، تولید خودکار مستندات تعاملی است. پس از اجرای سرور، آدرس‌های زیر را در مرورگر باز کنید:

مستندات Swagger UI:

http://localhost:8000/docs

مستندات ReDoc:

http://localhost:8000/redoc

در Swagger UI می‌توانید:

  1. همه‌ی مسیرهای API را مشاهده کنید.
  2. هر مسیر را با داده‌های نمونه تست کنید.
  3. نتایج را به صورت لحظه‌ای ببینید.

بخش پنجم: تست با curl یا Postman

تست مسیر سلامت (Health Check):

curl http://localhost:8000/health

پیش‌بینی یک خانه (از طریق پاورشل):

curl -X POST "http://localhost:8000/predict" `
     -H "Content-Type: application/json" `
     -d '{
           "sqft": 1500,
           "bedrooms": 3,
           "year_built": 2005,
           "distance_to_center": 5.5
         }'

نمونه خروجی دستور بالا بشکل زیر است:

{"predicted_price":201528.22,"features":{"sqft":1500.0,"bedrooms":3,"year_built":2005,"distance_to_center":5.5}}

پیش‌بینی چند خانه به صورت دسته‌ای:

curl -X POST "http://localhost:8000/predict_batch" `
     -H "Content-Type: application/json" `
     -d '{
           "houses": [
             {"sqft": 1500, "bedrooms": 3, "year_built": 2005, "distance_to_center": 5.5},
             {"sqft": 2200, "bedrooms": 4, "year_built": 2010, "distance_to_center": 3.2},
             {"sqft": 800, "bedrooms": 1, "year_built": 1995, "distance_to_center": 12.0}
           ]
         }'

و در حالت ارسال درخواست بصورت دسته‌ای، پیش‌بینی بشکل زیر می‌باشد:

{"total":3,"predictions":[{"house":1,"predicted_price":201528.22,"features":{"sqft":1500.0,"bedrooms":3,"year_built":2005,"distance_to_center":5.5}},{"house":2,"predicted_price":338662.59,"features":{"sqft":2200.0,"bedrooms":4,"year_built":2010,"distance_to_center":3.2}},{"house":3,"predicted_price":34335.56,"features":{"sqft":800.0,"bedrooms":1,"year_built":1995,"distance_to_center":12.0}}]}

بخش ششم: ساخت Dockerfile برای API

حالا که API خود را نوشته‌ایم، آن را با داکر بسته‌بندی می‌کنیم. فایل Dockerfile را به‌روز می‌کنیم:

# Dockerfile

FROM python:3.13-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY src/ ./src/
COPY models/ ./models/

EXPOSE 8000

CMD ["uvicorn", "src.app:app", "--host", "0.0.0.0", "--port", "8000"]

ساخت و اجرا با داکر:

قبل از اجرای دستور زیر ابتدا داکر خود را استارت بزنید. یعنی داکر باید بطور کامل در حالت اجرا یا running باشد. در غیر اینصورت با خطا ماجه خواهید شد.

# ساخت تصویر
docker build -t house-price-api .

# اجرای کانتینر
docker run -p 8000:8000 house-price-api
در نهایت پس از اجرای دستور فوق باید بتوانیم در مرورگر بعد از رفتن به آدرس localhost:8000/docs چنین تصویری را ببینیم. این یعنی کار را بدرستی انجام داده‌ایم

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

در این درس، یک API کامل برای مدل پیش‌بینی قیمت مسکن با FastAPI ساختیم. این API قابلیت‌های زیر را دارد:

  1. پیش‌بینی تک: دریافت مشخصات یک خانه و بازگرداندن قیمت پیش‌بینی‌شده
  2. پیش‌بینی دسته‌ای: دریافت چندین خانه و بازگرداندن قیمت‌های پیش‌بینی‌شده برای همه
  3. مستندسازی خودکار: با Swagger UI و ReDoc
  4. بررسی سلامت: برای پایش وضعیت مدل و سرور

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

  1. سرور را با uvicorn اجرا کنید و از طریق http://localhost:8000/docs آن را تست کنید.
  2. یک درخواست با داده‌های مختلف به مسیر /predict ارسال کنید.
  3. مسیر جدیدی به API اضافه کنید که میانگین قیمت‌های پیش‌بینی‌شده را برای یک دسته خانه محاسبه کند.
  4. داکر ایمیج را بسازید و کانتینر را اجرا کنید.