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

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

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

یکی از راهکارهای مناسب، استفاده از FastAPI است؛ فریم‌ورکی برای ساخت API با پایتون که امکان دریافت درخواست HTTP، اعتبارسنجی داده‌ها و ارسال پاسخ JSON را فراهم می‌کند.

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

اگر هنوز تجربه ساخت چت‌بات ندارید، بهتر است ابتدا مقاله «آموزش ساخت چت‌بات هوش مصنوعی با پایتون و API» را مطالعه کنید. این آموزش ادامه همان پروژه است، اما به‌جای رابط ترمینال، روی ساخت Backend تمرکز دارد.

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

FastAPI یک فریم‌ورک پایتون برای توسعه وب‌سرویس و REST API است. با استفاده از آن می‌توانید مسیرهای مختلفی تعریف کنید که درخواست‌های کاربران را دریافت کرده و پاسخ مناسب برگردانند.

برای مثال، می‌توانیم یک مسیر با آدرس /chat بسازیم که متن سؤال را دریافت کند و پاسخ مدل هوش مصنوعی را برگرداند.

FastAPI قابلیت‌هایی مانند اعتبارسنجی خودکار ورودی، تولید مستندات OpenAPI و پشتیبانی از برنامه‌نویسی ناهم‌زمان را ارائه می‌دهد.

تفاوت چت‌بات ترمینالی با API چت‌بات

ساخت API به‌تنهایی به معنی آماده بودن برنامه برای تعداد زیادی کاربر نیست. مدیریت هم‌زمانی، امنیت و منابع سرور همچنان اهمیت دارند.

پیش‌نیازهای ساخت API چت‌بات با پایتون

برای شروع به Python 3.10 یا جدیدتر، یک ویرایشگر کد و API Key معتبر نیاز داریم.

در این پروژه از سه ابزار اصلی استفاده می‌کنیم:

• FastAPI: دریافت درخواست و تولید پاسخ HTTP

• OpenAI SDK: اتصال به مدل هوش مصنوعی از طریق API سازگار

• Uvicorn: اجرای برنامه به‌عنوان وب‌سرور ASGI

برای آشنایی بیشتر با نحوه کار رابط‌های سازگار، مقاله «API سازگار با OpenAI چیست؟» را بخوانید.

ساخت پوشه پروژه و محیط مجازی

ابتدا یک پوشه با نام ai-chatbot-api بسازید و در ترمینال وارد آن شوید:

mkdir ai-chatbot-api
cd ai-chatbot-api
python -m venv .venv

در ویندوز، محیط مجازی را با PowerShell فعال کنید:

.\.venv\Scripts\Activate.ps1

در macOS و Linux:

source .venv/bin/activate

اگر در مک دستور python شناسایی نشد، از python3 استفاده کنید.

نصب FastAPI و کتابخانه‌های موردنیاز

پس از فعال‌سازی محیط مجازی، دستور زیر را اجرا کنید:

python -m pip install "fastapi[standard]" openai

این دستور FastAPI، وابستگی‌های استاندارد آن و کتابخانه OpenAI را نصب می‌کند.

دریافت API Key و تنظیم اتصال به Sinox API

برای اتصال Backend به مدل هوش مصنوعی، به کلید معتبر نیاز دارید.

از داشبورد Sinox API یک کلید متناسب با پکیج موردنظر بسازید و شناسه مدل فعال را دریافت کنید.

در این پروژه، آدرس پایه OpenAI-Compatible برابر است با:

https://sinoxapi.com/v1

کلید را داخل کد قرار نمی‌دهیم؛ بلکه از متغیر محیطی استفاده می‌کنیم.

در PowerShell:

$env:SINOX_API_KEY="YOUR_API_KEY"
$env:SINOX_MODEL="YOUR_MODEL_ID"

در macOS یا Linux:

export SINOX_API_KEY="YOUR_API_KEY"
export SINOX_MODEL="YOUR_MODEL_ID"

مقدار YOUR_MODEL_ID را با شناسه واقعی مدل از داشبورد جایگزین کنید. شناسه باید با نوع کلید توکنی یا ریکوستی سازگار باشد.

ساخت اولین API چت‌بات با FastAPI

در پوشه پروژه، یک فایل به نام main.py ایجاد کنید.

کد زیر یک Endpoint با متد POST می‌سازد که پیام کاربر را دریافت کرده و به مدل هوش مصنوعی ارسال می‌کند.

import os

from fastapi import FastAPI, HTTPException
from openai import (
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    OpenAI,
)
from pydantic import BaseModel, Field

app = FastAPI(title="AI Chatbot API")

client = OpenAI(
    api_key=os.environ["SINOX_API_KEY"],
    base_url="https://sinoxapi.com/v1",
    timeout=30.0,
    max_retries=1,
)

MODEL = os.environ["SINOX_MODEL"]


class ChatRequest(BaseModel):
    message: str = Field(min_length=1, max_length=4000)


class ChatResponse(BaseModel):
    reply: str


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


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    try:
        response = client.chat.completions.create(
            model=MODEL,
            messages=[
                {
                    "role": "system",
                    "content": "تو یک دستیار فارسی‌زبان مفید هستی.",
                },
                {
                    "role": "user",
                    "content": request.message,
                },
            ],
            max_tokens=500,
        )

        answer = response.choices[0].message.content or ""

        return ChatResponse(reply=answer)

    except (APIConnectionError, APITimeoutError):
        raise HTTPException(
            status_code=502,
            detail="ارتباط با سرویس هوش مصنوعی برقرار نشد.",
        )

    except APIStatusError:
        raise HTTPException(
            status_code=502,
            detail="سرویس هوش مصنوعی درخواست را نپذیرفت.",
        )

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

بررسی بخش‌های مهم کد

تعریف مسیر POST برای چت‌بات

با دستور زیر یک مسیر برای دریافت پیام تعریف کرده‌ایم:

@app.post("/chat", response_model=ChatResponse)

وقتی برنامه در حال اجرا باشد، نرم‌افزارهای دیگر می‌توانند یک درخواست POST به مسیر /chat ارسال کنند.

این درخواست باید دارای بدنه JSON باشد.

اعتبارسنجی ورودی با Pydantic

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

class ChatRequest(BaseModel):
    message: str = Field(min_length=1, max_length=4000)

در این مثال، متن خالی یا متنی طولانی‌تر از ۴۰۰۰ کاراکتر پذیرفته نمی‌شود.

اگر داده ورودی با ساختار موردانتظار مطابقت نداشته باشد، FastAPI به‌صورت خودکار خطای اعتبارسنجی برمی‌گرداند.

محدودیت کاراکتر، جایگزین کنترل تعداد توکن نیست؛ چون تعداد توکن‌ها به Tokenizer مدل بستگی دارد.

ارسال درخواست به مدل هوش مصنوعی

در تابع chat از متد client.chat.completions.create استفاده کرده‌ایم.

این متد پیام را به Sinox API ارسال می‌کند و پاسخ مدل را دریافت می‌کند.

در نهایت، مقدار reply به‌صورت JSON به درخواست‌کننده برمی‌گردد.

برای یادگیری جزئیات پایه ارسال درخواست، مقاله «آموزش OpenAI API با پایتون» را مطالعه کنید.

اجرای سرور FastAPI

در ترمینالی که متغیرهای محیطی تنظیم شده‌اند، دستور زیر را اجرا کنید:

uvicorn main:app --reload

در صورت اجرای موفق، سرور توسعه معمولاً روی آدرس زیر در دسترس قرار می‌گیرد:

http://127.0.0.1:8000

پارامتر --reload باعث می‌شود تغییرات فایل در محیط توسعه به‌صورت خودکار اعمال شوند.

این حالت مخصوص توسعه محلی است و نباید بدون تنظیمات مناسب برای محیط Production استفاده شود.

تست API با Swagger UI

یکی از امکانات FastAPI، تولید مستندات تعاملی است.

مرورگر را باز کنید و به آدرس زیر بروید:

http://127.0.0.1:8000/docs

در صفحه Swagger، مسیر POST /chat را پیدا کنید، روی Try it out بزنید و این JSON را وارد کنید:

{
  "message": "سه کاربرد مهم هوش مصنوعی را توضیح بده."
}

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

{
  "reply": "هوش مصنوعی در تولید محتوا، تحلیل داده و خودکارسازی فرایندها کاربرد دارد."
}

متن پاسخ صرفاً نمونه است و ممکن است مدل خروجی متفاوتی تولید کند.

ارسال درخواست به API با cURL

علاوه بر Swagger، می‌توانید Endpoint را با cURL آزمایش کنید.

در macOS، Linux یا محیطی که cURL نصب شده است:

curl -X POST "http://127.0.0.1:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"FastAPI چیست؟"}'

در PowerShell ویندوز نیز می‌توانید از دستور زیر استفاده کنید:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/chat" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body '{"message":"FastAPI چیست؟"}'

اگر اتصال به مدل درست باشد، پاسخ JSON نمایش داده می‌شود.

به این ترتیب، چت‌بات شما دیگر محدود به ترمینال نیست و می‌تواند از طریق درخواست HTTP استفاده شود.

آیا این API تاریخچه گفتگو را نگه می‌دارد؟

خیر. در نسخه فعلی، هر درخواست مستقل است.

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

برای افزودن حافظه گفتگو، می‌توانید یک شناسه مکالمه تعریف کنید و پیام‌ها را در پایگاه داده ذخیره کنید.

در هر درخواست، Backend باید تاریخچه مرتبط با همان کاربر را بازیابی کرده و همراه پیام جدید به مدل بفرستد.

این کار باید با جداسازی داده‌های کاربران، کنترل دسترسی و مدیریت حجم Context انجام شود.

امنیت API چت‌بات؛ قبل از انتشار عمومی چه کارهایی لازم است؟

یک API که بدون احراز هویت روی اینترنت منتشر شود، ممکن است توسط افراد ناشناس مورد استفاده قرار بگیرد و هزینه ایجاد کند.

برای آماده‌سازی یک سرویس واقعی، موارد زیر اهمیت دارند:

همچنین نباید API Key مربوط به Sinox را در JavaScript سمت مرورگر قرار دهید.

در معماری مناسب، مرورگر به Backend شما درخواست می‌فرستد و Backend با استفاده از کلید محرمانه به Sinox متصل می‌شود.

نکته: تنظیم CORS به‌تنهایی جایگزین احراز هویت یا Rate Limiting نیست.

مدیریت هزینه API چت‌بات

در هر بار فراخوانی /chat، برنامه یک درخواست به مدل هوش مصنوعی ارسال می‌کند.

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

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

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

برای آشنایی با روش محاسبه، مقاله «توکن هوش مصنوعی چیست؟ آموزش محاسبه هزینه API» را بخوانید.

خطاهای رایج هنگام ساخت API چت‌بات

خطای 422 در FastAPI

این خطا معمولاً به معنی نامعتبر بودن ساختار درخواست است.

بررسی کنید که بدنه درخواست JSON معتبر باشد و فیلد message را به‌صورت رشته متنی ارسال کرده باشید.

خطای 401 هنگام اتصال به مدل

این خطا معمولاً به مشکل احراز هویت در سرویس بالادستی مربوط است.

مقدار SINOX_API_KEY را بررسی کنید. در نمونه آموزشی ما، خطاهای HTTP سرویس بالادستی به خطای عمومی 502 تبدیل می‌شوند تا جزئیات داخلی مستقیماً افشا نشوند.

خطای 404 برای Endpoint

مطمئن شوید مسیر /chat را با متد POST فراخوانی می‌کنید. اگر از آدرس اشتباه استفاده کنید، ممکن است پاسخ 404 دریافت کنید.

خطای 502 هنگام دریافت پاسخ مدل

در کد این آموزش، مشکلات اتصال، Timeout و پاسخ خطادار سرویس هوش مصنوعی با وضعیت 502 به کاربر اعلام می‌شوند.

برای تشخیص علت اصلی، باید لاگ‌های امن سمت سرور را بررسی کنید؛ برای مثال، نامعتبر بودن مدل، مشکل سهمیه یا محدودیت نرخ درخواست.

در محیط عملیاتی، بهتر است خطاها به‌صورت دقیق‌تر دسته‌بندی و ثبت شوند، بدون اینکه کلید API یا اطلاعات محرمانه کاربران در لاگ ذخیره شود.

سؤالات متداول درباره ساخت API چت‌بات با FastAPI

آیا برای ساخت API هوش مصنوعی به سرور نیاز داریم؟

برای توسعه و آزمایش، اجرای برنامه روی کامپیوتر شخصی کافی است. اما برای دسترسی دائمی کاربران، معمولاً باید Backend را روی سرور یا سرویس میزبانی مناسب مستقر کنید.

آیا FastAPI رایگان است؟

بله. FastAPI یک فریم‌ورک متن‌باز است. بااین‌حال، هزینه میزبانی و مصرف API مدل هوش مصنوعی می‌تواند جداگانه محاسبه شود.

آیا می‌توان این API را به سایت وردپرسی متصل کرد؟

بله. وردپرس می‌تواند از طریق یک افزونه یا کد سمت سرور به Endpoint شما درخواست ارسال کند. برای استفاده عمومی باید احراز هویت و کنترل دسترسی را نیز پیاده‌سازی کنید.

آیا می‌توان به‌جای GPT از Claude استفاده کرد؟

بله، در صورتی که مدل موردنظر از طریق رابط سازگار با OpenAI در ارائه‌دهنده شما پشتیبانی شود، می‌توانید شناسه مدل را تغییر دهید.

آیا FastAPI برای پروژه‌های واقعی مناسب است؟

بله، اما کد آموزشی این مقاله یک نمونه اولیه است. برای محیط عملیاتی به تنظیمات امنیتی، مدیریت منابع، پایش و استقرار مناسب نیاز دارید.

جمع‌بندی

در این آموزش یاد گرفتیم چگونه با FastAPI و پایتون یک API چت‌بات هوش مصنوعی بسازیم.

ابتدا محیط پروژه را آماده کردیم، سپس با استفاده از OpenAI SDK به Sinox API متصل شدیم و یک Endpoint با مسیر /chat ایجاد کردیم.

در ادامه، نحوه ارسال درخواست JSON، آزمایش API با Swagger و cURL و مدیریت خطاهای رایج را بررسی کردیم.

این پروژه می‌تواند پایه توسعه یک چت‌بات تحت وب، دستیار پشتیبانی یا سرویس هوش مصنوعی اختصاصی باشد.

برای دریافت API Key و انتخاب مدل موردنظر، می‌توانید به Sinox API مراجعه کنید و اطلاعات اتصال را در مستندات API بررسی کنید.