اگر می‌خواهید مدل هوش مصنوعی‌تان را از یک اسکریپت پایتون به یک سرویس تحت وب قابل فراخوانی تبدیل کنید، FastAPI سریع‌ترین و تمیزترین مسیر است. با همین فریم‌ورک در چند دقیقه یک REST API تایپ‌دار می‌سازید، اعتبارسنجی را با Pydantic خودکار می‌کنید، داک تعاملی Swagger را رایگان می‌گیرید و سرویس را با Uvicorn کنار Whisper یا Qdrant اجرا می‌کنید. در این آموزش نصب، اولین روت، مدل‌های داده و اتصال مدل AI را گام‌به‌گام با کد قابل اجرا می‌بینید.

FastAPI چیست و چرا سریع‌ترین راه ساخت API پایتون برای هوش مصنوعی است؟

FastAPI فریم‌ورکی مدرن مبتنی بر تایپ‌هینت است که با Starlette و Pydantic ساخته شده؛ فقط با تعریف تابع و تایپ ورودی، هم اعتبارسنجی و هم داک Swagger و ReDoc را خودکار می‌گیرید. سرعت نزدیک به Node و Go، پشتیبانی async ذاتی و تجربه توسعه روانی دارد. در ادامه نصب تا اتصال مدل AI را می‌خوانید.

فهرست مطالب

پیش‌نیازها و نصب FastAPI و Uvicorn
اولین API در ۵ دقیقه؛ Hello World و داک خودکار
مسیریابی، پارامترهای مسیر و کوئری
بدنه درخواست و پاسخ با Pydantic
اتصال مدل هوش مصنوعی به FastAPI
مقایسه FastAPI با Flask و Django REST
کاربرد واقعی؛ Whisper و جستجوی برداری
نکات امنیتی، async و دیپلوی
اشتباهات رایج
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب FastAPI و Uvicorn

به پایتون ۳.۹+ نیاز دارید. FastAPI سرور ندارد؛ Uvicorn آن را اجرا می‌کند. محیط مجازی بسازید تا وابستگی‌ها تمیز بماند.

python -m venv .venv
source .venv/bin/activate  # ویندوز: .venv\Scripts\activate
pip install fastapi uvicorn[standard] pydantic python-dotenv
pip show fastapi  # 0.11x

fastapi: فریم‌ورک اصلی با Pydantic v2.
uvicorn[standard]: اجرای پرسرعت با uvloop.
ساختار: پوشه app/ با main.py بسازید.
ویرایشگر: VS Code با Pylance تایپ‌ها را چک می‌کند.

اولین API در ۵ دقیقه؛ Hello World و داک خودکار

ساده‌ترین API یک روت GET است؛ همین سه خط داک تعاملی هم می‌سازد.

# app/main.py
from fastapi import FastAPI

app = FastAPI(title="TooAI FastAPI Demo", version="1.0.0")

@app.get("/")
def root():
    return {"message": "سلام از FastAPI!"}

@app.get("/health")
def health():
    return {"status": "ok"}

uvicorn app.main:app --reload --port 8000
# http://127.0.0.1:8000/docs  -> Swagger
# http://127.0.0.1:8000/redoc -> ReDoc

app.main:app: فایل و شی اپلیکیشن.
--reload: فقط در توسعه؛ در تولید حذف کنید.
خروجی: GET / برمی‌گرداند {"message":"سلام از FastAPI!"}

مسیریابی، پارامترهای مسیر و کوئری

پارامترها از روی تایپ‌هینت فهمیده می‌شوند و در داک مستند هستند.

from fastapi import FastAPI, Query, Path

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int = Path(..., ge=1), q: str | None = Query(None, max_length=50)):
    return {"user_id": user_id, "q": q}

@app.get("/search")
def search(limit: int = Query(10, ge=1, le=100), offset: int = 0):
    return {"limit": limit, "offset": offset}

Path: پارامتر اجباری داخل URL؛ ge=1 مقدار منفی را 422 می‌کند.
Query: پارامتر اختیاری بعد از ?.
تست: از /docs یا HTTPX استفاده کنید. برای سرویس صوتی، آموزش Whisper را ببینید.

بدنه درخواست و پاسخ با Pydantic؛ اعتبارسنجی هوشمند

به‌جای if دستی، یک مدل Pydantic تعریف می‌کنید و تبدیل نوع و پیام خطا خودکار می‌شود.

from pydantic import BaseModel, Field
from fastapi import FastAPI

app = FastAPI()

class SummarizeIn(BaseModel):
    text: str = Field(..., min_length=20, max_length=5000)
    max_len: int = Field(150, ge=30, le=300)

class SummarizeOut(BaseModel):
    summary: str
    chars: int

@app.post("/summarize", response_model=SummarizeOut)
def summarize(payload: SummarizeIn):
    s = payload.text[:payload.max_len].strip() + " …"
    return {"summary": s, "chars": len(s)}

response_model: خروجی را فیلتر و در داک ثبت می‌کند.
422: اگر text کوتاه باشد جزئیات دقیق برمی‌گردد.

curl -X POST http://127.0.0.1:8000/summarize -H "Content-Type: application/json" -d "{\"text\": \"هوش مصنوعی در ۱۴۰۴ تحول بزرگی در زبان فارسی ایجاد کرده ...\", \"max_len\": 120}"

برای داده جدولی، ترکیب با Polars و برای جستجوی معنایی با Qdrant رایج است.

اتصال مدل هوش مصنوعی به FastAPI؛ مثال خلاصه‌ساز فارسی

پشت یک روت یکسان می‌توانید API ابری یا مدل محلی بگذارید.

گزینه ۱ — مدل ابری شبیه OpenAI

import os
from openai import OpenAI
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

class In(BaseModel):
    text: str = Field(..., min_length=20, max_length=5000)

@app.post("/ai/summarize")
def ai_summarize(body: In):
    try:
        resp = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "system", "content": "تو خلاصه‌ساز فارسی دقیق هستی."}, {"role": "user", "content": body.text}],
            temperature=0.3, max_tokens=250
        )
        return {"summary": resp.choices[0].message.content.strip()}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

گزینه ۲ — مدل محلی Hugging Face

from transformers import pipeline
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()
summarizer = pipeline("summarization", model="google/mt5-small")

class In(BaseModel):
    text: str

@app.post("/local/summarize")
def local_summarize(body: In):
    out = summarizer(body.text, max_length=120, min_length=30, do_sample=False)
    return {"summary": out[0]["summary_text"]}

لود یک‌باره: مدل را بیرون تابع بسازید.
قرارداد ثابت: کلاینت تفاوتی بین ابری و محلی حس نمی‌کند.

مقایسه FastAPI با Flask و Django REST

معیار	FastAPI	Flask	Django REST
سرعت	بسیار بالا — ASGI + async	متوسط — WSGI	متوسط — سنگین
اعتبارسنجی	ذاتی Pydantic	دستی/Marshmallow	Serializer پرکد
داک خودکار	Swagger/ReDoc بدون کد	Flasgger لازم	drf-spectacular لازم
async	بومی	محدود	جزئی
مناسب برای	سرویس AI و میکروسرویس	پروژه کوچک	پروژه سازمانی با ادمین

برای API هوش مصنوعی با ورودی تایپ‌دار، FastAPI کمترین کد را می‌خواهد.

کاربرد واقعی؛ سرویس Whisper و جستجوی برداری

Whisper: فایل صوتی را با UploadFile بگیرید و به متن فارسی تبدیل کنید؛ راهنمای کامل در آموزش Whisper.
Qdrant: متن را وکتور و با /search?q=... جستجوی معنایی بدهید؛ مرجع آموزش Qdrant.

from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/transcribe")
async def transcribe(file: UploadFile = File(...)):
    data = await file.read()
    text = "متن پیاده‌شده نمونه"
    return {"filename": file.filename, "text": text}

نکات امنیتی، async و دیپلوی تولید

CORS: فقط دامنه فرانت را در CORSMiddleware باز کنید.
کلید: از .env بخوانید و به .gitignore بگذارید.
rate limit: با slowapi روی روت گران سقف بگذارید.
async: بدون await از def معمولی استفاده کنید؛ برای HTTP از httpx.AsyncClient.
دیپلوی: uvicorn app.main:app --host 0.0.0.0 --workers 4 پشت Nginx یا Docker.

import asyncio, httpx
async def test():
    async with httpx.AsyncClient() as c:
        r = await c.post("http://127.0.0.1:8000/summarize", json={"text": "متن تستی ... "*20, "max_len": 120})
        print(r.json())
asyncio.run(test())

اشتباهات رایج هنگام کار با FastAPI

--reload در تولید: فقط برای توسعه است.
لود مدل داخل روت: رم را پر می‌کند؛ یک‌بار در سطح ماژول لود کنید.
فراموشی response_model: فیلد اضافی نشت می‌کند.
requests داخل async: حلقه رویداد را قفل می‌کند؛ httpx.AsyncClient بگذارید.
اعتبارسنجی فقط فرانت: حتما در Pydantic هم بگذارید.

سوالات متداول

FastAPI با Flask چه فرقی دارد؟

FastAPI تایپ‌محور و async با داک خودکار است؛ Flask مینیمال WSGI و بدون داک ذاتی. برای API تایپ‌دار و مدل AI، FastAPI سریع‌تر است.

آیا برای ترافیک بالا مناسب است؟

بله؛ با ۴ تا ۸ worker پشت Nginx یا Kubernetes پایدار است. --reload را حذف و برای روت سنگین کش و rate limit بگذارید.

خطای 422 را چطور دیباگ کنم؟

پاسخ 422 آرایه detail با loc دقیق دارد. همان JSON را در /docs → Try it out تست کنید.

فایل صوتی یا تصویر را چطور بگیرم؟

از UploadFile و File(...) با روت async استفاده کنید و بایت‌ها را به Whisper یا مدل تصویر بدهید.

اتصال به Qdrant یا دیتابیس چطور است؟

کلاینت را در startup باز و در shutdown ببندید و singleton نگه دارید؛ یک روت /search برای جستجوی معنایی بسازید.

بدون async عمیق می‌توانم شروع کنم؟

بله؛ با def معمولی شروع کنید و فقط برای I/O بلوکه‌کننده سراغ async و httpx بروید.

جمع‌بندی

pip install fastapi uvicorn[standard] pydantic و ساخت app/main.py
اجرای uvicorn app.main:app --reload و تست /docs
مدل Pydantic برای ورودی/خروجی و اعتبارسنجی خودکار
اتصال مدل AI ابری یا محلی با لود یک‌باره
CORS محدود، کلید در .env و تست با HTTPX
دیپلوی بدون --reload با چند worker

حالا یک روت /summarize بسازید و با /docs تست کنید — پیام detail در خطای 422 دقیقا می‌گوید کدام فیلد را درست کنید.

آموزش FastAPI در پایتون؛ ساخت API هوش مصنوعی سریع و مدرن