مقدمه
در درس پیشین، با داکر آشنا شدیم و یاد گرفتیم چگونه مدل خود را در یک کانتینر بستهبندی کنیم. اما یک کانتینر به تنهایی برای استفادهی دیگران کافی نیست. ما نیاز داریم مدل خود را به صورت یک وب–سرویس درآوریم تا سایر برنامهها و کاربران بتوانند از طریق اینترنت با آن ارتباط برقرار کنند.
ایپیآی یا رابط برنامهنویسی (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 میتوانید:
- همهی مسیرهای API را مشاهده کنید.
- هر مسیر را با دادههای نمونه تست کنید.
- نتایج را به صورت لحظهای ببینید.
بخش پنجم: تست با 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

جمعبندی و تمرین
در این درس، یک API کامل برای مدل پیشبینی قیمت مسکن با FastAPI ساختیم. این API قابلیتهای زیر را دارد:
- پیشبینی تک: دریافت مشخصات یک خانه و بازگرداندن قیمت پیشبینیشده
- پیشبینی دستهای: دریافت چندین خانه و بازگرداندن قیمتهای پیشبینیشده برای همه
- مستندسازی خودکار: با Swagger UI و ReDoc
- بررسی سلامت: برای پایش وضعیت مدل و سرور
تمرین پیشنهادی:
- سرور را با
uvicornاجرا کنید و از طریقhttp://localhost:8000/docsآن را تست کنید. - یک درخواست با دادههای مختلف به مسیر
/predictارسال کنید. - مسیر جدیدی به API اضافه کنید که میانگین قیمتهای پیشبینیشده را برای یک دسته خانه محاسبه کند.
- داکر ایمیج را بسازید و کانتینر را اجرا کنید.
