آموزش هوش مصنوعی با پایتون؛ از نصب Python تا ساخت پروژه واقعی با API

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

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

در این آموزش، مسیر دوم را به‌صورت عملی دنبال می‌کنیم. ابتدا محیط پایتون را آماده می‌کنیم، سپس به API هوش مصنوعی درواره متصل می‌شویم و مرحله‌به‌مرحله پروژه‌های زیر را می‌سازیم:

• اولین درخواست هوش مصنوعی با پایتون
• دستیار هوشمند خط فرمان با حافظه مکالمه
• نمایش تدریجی پاسخ با Streaming
• دریافت و اعتبارسنجی خروجی JSON
• دسته‌بندی خودکار تیکت‌های پشتیبانی
• ساخت API اختصاصی با FastAPI
• مدیریت خطا، هزینه، توکن و امنیت کلید API

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

هوش مصنوعی با پایتون دقیقاً یعنی چه؟

عبارت «هوش مصنوعی با پایتون» می‌تواند به چند مسیر متفاوت اشاره کند:

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

آیا برای این آموزش باید پایتون را حرفه‌ای بلد باشیم؟

خیر. برای اجرای مثال‌های این مقاله آشنایی مقدماتی با موارد زیر کافی است:

• متغیرها و انواع داده
• رشته و فهرست
• شرط و حلقه
• تابع
• دیکشنری
• نصب Package با pip
• اجرای فایل پایتون در ترمینال

اگر هنوز تمام این مفاهیم را بلد نیستید، باز هم می‌توانید کدها را اجرا کنید؛ اما برای توسعه پروژه بهتر است مبانی پایتون را نیز هم‌زمان یاد بگیرید.

پیش‌نیازهای پروژه

برای ادامه آموزش به این موارد نیاز داریم:

• نصب Python
• یک ویرایشگر مانند Visual Studio Code
• دسترسی به ترمینال
• حساب کاربری در درواره
• کلید API درواره
• شناسه یکی از مدل‌های موجود در درواره

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

در تمام مثال‌ها از مقادیر زیر استفاده می‌کنیم:

YOUR_DARVAREH_API_KEY
YOUR_MODEL_ID

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

مرحله اول: نصب Python

پایتون را از وب‌سایت رسمی آن دانلود و نصب کنید. در ویندوز، هنگام نصب گزینه مربوط به اضافه‌کردن Python به PATH را فعال کنید.

پس از نصب، ترمینال را باز کرده و یکی از دستورات زیر را اجرا کنید:

python --version

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

python3 --version

در ویندوز نیز این دستور ممکن است در دسترس باشد:

py --version

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

مرحله دوم: ایجاد پوشه پروژه

یک پوشه برای پروژه بسازید و وارد آن شوید:

mkdir python-ai-project
cd python-ai-project

سپس پوشه را در VS Code باز کنید:

code .

اگر دستور code روی سیستم شما فعال نیست، می‌توانید VS Code را باز کرده و پوشه را به‌صورت دستی انتخاب کنید.

مرحله سوم: ساخت محیط مجازی

محیط مجازی یا Virtual Environment وابستگی‌های هر پروژه را از سایر پروژه‌های پایتون جدا می‌کند. ماژول استاندارد venv برای ساخت چنین محیطی طراحی شده است و بسته‌های نصب‌شده در آن به همان پروژه محدود می‌شوند. مستندات رسمی Python درباره venv

در ویندوز اجرا کنید:

py -m venv .venv

فعال‌سازی در PowerShell:

.venv\Scripts\Activate.ps1

فعال‌سازی در Command Prompt:

.venv\Scripts\activate.bat

در لینوکس و macOS اجرا کنید:

python3 -m venv .venv
source .venv/bin/activate

پس از فعال‌شدن محیط، معمولاً نام .venv در ابتدای خط ترمینال نمایش داده می‌شود.

مرحله چهارم: نصب کتابخانه‌های موردنیاز

دستور زیر را اجرا کنید:

pip install openai python-dotenv pydantic fastapi uvicorn

کاربرد بسته‌ها:

کتابخانه رسمی OpenAI امکان ساخت Client هم‌زمان و غیرهم‌زمان را فراهم می‌کند و نصب آن از طریق pip install openai انجام می‌شود. مخزن رسمی OpenAI Python SDK

برای ثبت دقیق وابستگی‌های پروژه نیز می‌توانید اجرا کنید:

pip freeze > requirements.txt

مرحله پنجم: نگهداری امن کلید API

در ریشه پروژه یک فایل با نام .env بسازید:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL=YOUR_MODEL_ID
DARVAREH_BASE_URL=https://api.darvareh.ir/v1

سپس فایل .gitignore را ایجاد کنید:

.venv/
.env
__pycache__/
*.pyc

کلید API را مستقیماً داخل کد، مخزن Git، برنامه فرانت‌اند یا فایل قابل دانلود قرار ندهید. کلید باید فقط در سمت سرور یا محیط اجرای مطمئن نگهداری شود.

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

فایلی به نام first_request.py بسازید:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

api_key = os.getenv("DARVAREH_API_KEY")
model_id = os.getenv("DARVAREH_MODEL")
base_url = os.getenv(
    "DARVAREH_BASE_URL",
    "https://api.darvareh.ir/v1",
)

if not api_key:
    raise RuntimeError("متغیر DARVAREH_API_KEY تنظیم نشده است.")

if not model_id:
    raise RuntimeError("متغیر DARVAREH_MODEL تنظیم نشده است.")

client = OpenAI(
    api_key=api_key,
    base_url=base_url,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[
        {
            "role": "system",
            "content": (
                "تو یک دستیار فارسی دقیق هستی. "
                "پاسخ‌ها را روشن، مختصر و کاربردی بنویس."
            ),
        },
        {
            "role": "user",
            "content": "پایتون را در سه بند برای یک برنامه‌نویس تازه‌کار معرفی کن.",
        },
    ],
    temperature=0.4,
    max_tokens=500,
)

answer = response.choices[0].message.content
print(answer)

برنامه را اجرا کنید:

python first_request.py

یا در برخی سیستم‌ها:

python3 first_request.py

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

اجزای اصلی درخواست چه هستند؟

در کد قبلی چهار بخش اهمیت بیشتری دارند.

آدرس پایه یا Base URL

درواره یک API سازگار با OpenAI ارائه می‌کند. آدرس پایه آن در مثال‌های این مقاله به‌صورت زیر است:

https://api.darvareh.ir/v1

این آدرس هنگام ساخت Client تنظیم می‌شود:

client = OpenAI(
    api_key=api_key,
    base_url="https://api.darvareh.ir/v1",
)

شناسه مدل

مدل از طریق پارامتر model انتخاب می‌شود:

model="YOUR_MODEL_ID"

شناسه مدل موردنظر را از صفحه مدل‌های درواره دریافت کنید.

پیام‌های مکالمه

پیام‌ها در یک فهرست قرار می‌گیرند:

messages=[
    {
        "role": "system",
        "content": "تو یک دستیار فارسی دقیق هستی.",
    },
    {
        "role": "user",
        "content": "سلام! پایتون چیست؟",
    },
]

نقش‌های متداول عبارت‌اند از:

پارامتر Temperature

پارامتر temperature میزان تنوع پاسخ را کنترل می‌کند:

temperature=0.3

به‌صورت کلی:

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

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

پروژه اول: ساخت چت‌بات خط فرمان با پایتون

در مثال اول فقط یک درخواست ارسال کردیم. اکنون یک دستیار تعاملی می‌سازیم که پیام‌های قبلی را نیز در تاریخچه نگه دارد.

فایل chatbot.py را بسازید:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

API_KEY = os.getenv("DARVAREH_API_KEY")
MODEL_ID = os.getenv("DARVAREH_MODEL")
BASE_URL = os.getenv(
    "DARVAREH_BASE_URL",
    "https://api.darvareh.ir/v1",
)

if not API_KEY or not MODEL_ID:
    raise RuntimeError(
        "متغیرهای DARVAREH_API_KEY و DARVAREH_MODEL را در فایل .env تنظیم کنید."
    )

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL,
)

messages = [
    {
        "role": "system",
        "content": (
            "تو یک دستیار فارسی برای آموزش برنامه‌نویسی هستی. "
            "پاسخ‌ها باید دقیق، مرحله‌به‌مرحله و همراه با مثال باشند. "
            "اگر از پاسخ مطمئن نیستی، عدم قطعیت را اعلام کن."
        ),
    }
]


def trim_history(history: list[dict], max_messages: int = 12) -> list[dict]:
    system_message = history[0]
    recent_messages = history[1:][-max_messages:]
    return [system_message, *recent_messages]


print("دستیار آماده است.")
print("برای خروج، /exit و برای پاک‌کردن تاریخچه، /clear را وارد کنید.")

while True:
    user_input = input("\nشما: ").strip()

    if not user_input:
        continue

    if user_input.lower() == "/exit":
        print("خدانگهدار!")
        break

    if user_input.lower() == "/clear":
        messages = [messages[0]]
        print("تاریخچه مکالمه پاک شد.")
        continue

    messages.append(
        {
            "role": "user",
            "content": user_input,
        }
    )

    messages = trim_history(messages)

    try:
        response = client.chat.completions.create(
            model=MODEL_ID,
            messages=messages,
            temperature=0.3,
            max_tokens=1000,
        )

        answer = response.choices[0].message.content or ""
        print(f"\nدستیار: {answer}")

        messages.append(
            {
                "role": "assistant",
                "content": answer,
            }
        )

    except Exception as error:
        print(f"\nخطا در دریافت پاسخ: {error}")

برنامه را اجرا کنید:

python chatbot.py

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

آیا مدل واقعاً حافظه دارد؟

مدل در این مثال حافظه دائمی ندارد. متغیر messages تاریخچه را در حافظه برنامه نگه می‌دارد و ما در هر درخواست آن را دوباره ارسال می‌کنیم.

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

• SQLite
• PostgreSQL
• Redis
• MongoDB
• فایل محلی برای نمونه‌های ساده

همچنین نباید تاریخچه را بدون محدودیت بزرگ کنید؛ زیرا پیام‌های بیشتر معمولاً به معنای مصرف توکن و هزینه بیشتر هستند. تابع trim_history در مثال ما فقط چند پیام آخر را نگه می‌دارد.

در پروژه‌های جدی‌تر می‌توانید پیام‌های قدیمی را خلاصه کنید و خلاصه را به‌جای کل تاریخچه برای مدل بفرستید.

پروژه دوم: نمایش تدریجی پاسخ با Streaming

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

فایل stream_chat.py را ایجاد کنید:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url=os.getenv(
        "DARVAREH_BASE_URL",
        "https://api.darvareh.ir/v1",
    ),
)

model_id = os.environ["DARVAREH_MODEL"]

stream = client.chat.completions.create(
    model=model_id,
    messages=[
        {
            "role": "system",
            "content": "پاسخ را به زبان فارسی و مرحله‌به‌مرحله بنویس.",
        },
        {
            "role": "user",
            "content": "مراحل ساخت یک REST API ساده با پایتون را توضیح بده.",
        },
    ],
    temperature=0.3,
    max_tokens=1000,
    stream=True,
)

print("پاسخ: ", end="", flush=True)

for chunk in stream:
    delta = chunk.choices[0].delta.content

    if delta:
        print(delta, end="", flush=True)

print()

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

پروژه سوم: دریافت خروجی JSON از هوش مصنوعی

خروجی متنی برای نمایش به کاربر مناسب است؛ اما نرم‌افزارها معمولاً به داده ساختاریافته نیاز دارند.

فرض کنید می‌خواهیم متن یک درخواست پشتیبانی را تحلیل کنیم و این موارد را استخراج کنیم:

• دسته‌بندی
• اولویت
• خلاصه
• نیاز یا عدم نیاز به بررسی انسانی

ابتدا فایل ticket_classifier.py را ایجاد کنید:

import json
import os
from typing import Literal

from dotenv import load_dotenv
from openai import OpenAI
from pydantic import BaseModel, ValidationError

load_dotenv()


class TicketResult(BaseModel):
    category: Literal["billing", "technical", "account", "other"]
    priority: Literal["low", "medium", "high", "urgent"]
    summary: str
    requires_human: bool


client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url=os.getenv(
        "DARVAREH_BASE_URL",
        "https://api.darvareh.ir/v1",
    ),
)

model_id = os.environ["DARVAREH_MODEL"]


def clean_json_text(text: str) -> str:
    cleaned = text.strip()

    if cleaned.startswith("```json"):
        cleaned = cleaned[7:]
    elif cleaned.startswith("```"):
        cleaned = cleaned[3:]

    if cleaned.endswith("```"):
        cleaned = cleaned[:-3]

    return cleaned.strip()


def classify_ticket(ticket_text: str) -> TicketResult:
    response = client.chat.completions.create(
        model=model_id,
        messages=[
            {
                "role": "system",
                "content": (
                    "یک سیستم دسته‌بندی تیکت هستی. "
                    "فقط یک JSON معتبر و بدون Markdown برگردان. "
                    "ساختار خروجی باید دقیقاً شامل category، priority، "
                    "summary و requires_human باشد. "
                    "category یکی از billing، technical، account یا other باشد. "
                    "priority یکی از low، medium، high یا urgent باشد. "
                    "summary به زبان فارسی نوشته شود. "
                    "requires_human مقدار true یا false باشد."
                ),
            },
            {
                "role": "user",
                "content": ticket_text,
            },
        ],
        temperature=0,
        max_tokens=300,
    )

    content = response.choices[0].message.content or "{}"
    data = json.loads(clean_json_text(content))

    return TicketResult.model_validate(data)


ticket = """
از دیروز وارد حسابم نمی‌شوم. بازیابی رمز عبور را هم انجام دادم،
اما کد تأیید برای من ارسال نمی‌شود و برای ارائه پروژه عجله دارم.
"""

try:
    result = classify_ticket(ticket)
    print(result.model_dump_json(indent=2))

except json.JSONDecodeError:
    print("خروجی مدل JSON معتبر نبود.")

except ValidationError as error:
    print("ساختار خروجی با مدل داده مورد انتظار سازگار نبود.")
    print(error)

اجرا:

python ticket_classifier.py

نمونه خروجی احتمالی:

{
  "category": "account",
  "priority": "high",
  "summary": "کاربر امکان ورود ندارد و کد تأیید بازیابی رمز را دریافت نمی‌کند.",
  "requires_human": true
}

چرا باید خروجی مدل را اعتبارسنجی کنیم؟

حتی اگر در پرامپت (Prompt) از مدل بخواهیم فقط JSON برگرداند، برنامه نباید بدون بررسی به پاسخ اعتماد کند.

مشکلات احتمالی عبارت‌اند از:

• JSON ناقص
• کلید حذف‌شده
• نوع داده اشتباه
• مقدار خارج از گزینه‌های مجاز
• توضیح اضافی قبل یا بعد از JSON
• پاسخ خالی
• اطلاعات از نظر ساختاری درست اما از نظر معنایی نادرست

در مثال بالا، Pydantic تضمین می‌کند که خروجی با ساختار تعریف‌شده سازگار باشد. برای محیط عملیاتی بهتر است در صورت پشتیبانی مدل انتخابی، از Structured Outputs یا JSON Schema نیز استفاده کنید؛ اما اعتبارسنجی سمت برنامه همچنان ضروری است.

پروژه چهارم: تبدیل برنامه پایتون به API با FastAPI

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

فایل main.py را بسازید:

import os

from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException
from openai import (
    APIConnectionError,
    APIStatusError,
    AuthenticationError,
    OpenAI,
    RateLimitError,
)
from pydantic import BaseModel, Field

load_dotenv()

api_key = os.getenv("DARVAREH_API_KEY")
model_id = os.getenv("DARVAREH_MODEL")
base_url = os.getenv(
    "DARVAREH_BASE_URL",
    "https://api.darvareh.ir/v1",
)

if not api_key:
    raise RuntimeError("DARVAREH_API_KEY تنظیم نشده است.")

if not model_id:
    raise RuntimeError("DARVAREH_MODEL تنظیم نشده است.")

client = OpenAI(
    api_key=api_key,
    base_url=base_url,
    timeout=30.0,
    max_retries=2,
)

app = FastAPI(
    title="Persian AI Assistant API",
    version="1.0.0",
)


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


class ChatResponse(BaseModel):
    answer: str
    model: str


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


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    try:
        response = client.chat.completions.create(
            model=model_id,
            messages=[
                {
                    "role": "system",
                    "content": (
                        "تو دستیار فارسی یک وب‌سایت آموزشی هستی. "
                        "پاسخ‌ها را دقیق، شفاف و کاربردی ارائه کن."
                    ),
                },
                {
                    "role": "user",
                    "content": request.message,
                },
            ],
            temperature=0.3,
            max_tokens=800,
        )

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

        if not answer:
            raise HTTPException(
                status_code=502,
                detail="مدل پاسخ قابل استفاده‌ای برنگرداند.",
            )

        return ChatResponse(
            answer=answer,
            model=model_id,
        )

    except AuthenticationError:
        raise HTTPException(
            status_code=500,
            detail="احراز هویت سرویس هوش مصنوعی ناموفق بود.",
        )

    except RateLimitError:
        raise HTTPException(
            status_code=429,
            detail="تعداد درخواست‌ها بیش از حد مجاز است؛ کمی بعد دوباره تلاش کنید.",
        )

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

    except APIStatusError as error:
        raise HTTPException(
            status_code=502,
            detail=f"سرویس بالادستی با کد {error.status_code} پاسخ داد.",
        )

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

برای اجرای برنامه:

uvicorn main:app --reload

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

http://127.0.0.1:8000/docs

FastAPI یک صفحه مستندات تعاملی نمایش می‌دهد. مسیر POST /chat را باز کرده و درخواست زیر را آزمایش کنید:

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

نمونه پاسخ:

{
  "answer": "پایتون در تحلیل داده، ساخت مدل‌های یادگیری ماشین و توسعه اپلیکیشن‌های مبتنی بر مدل‌های زبانی کاربرد دارد.",
  "model": "YOUR_MODEL_ID"
}

آزمایش API با cURL

پس از اجرای FastAPI، می‌توانید درخواست را از ترمینال نیز ارسال کنید:

curl -X POST "http://127.0.0.1:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"یک مسیر یادگیری پایتون برای هوش مصنوعی پیشنهاد بده."}'

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

$body = @{
    message = "یک مسیر یادگیری پایتون برای هوش مصنوعی پیشنهاد بده."
} | ConvertTo-Json

Invoke-RestMethod `
    -Method Post `
    -Uri "http://127.0.0.1:8000/chat" `
    -ContentType "application/json" `
    -Body $body

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

کلید API نباید در مرورگر کاربر قرار بگیرد. معماری پیشنهادی به این شکل است:

1. کاربر پیام را در رابط وب یا موبایل وارد می‌کند.
2. فرانت‌اند پیام را به Backend شما می‌فرستد.
3. Backend ورودی را اعتبارسنجی می‌کند.
4. Backend با کلید محرمانه به API درواره درخواست می‌فرستد.
5. پاسخ مدل به Backend برمی‌گردد.
6. Backend پاسخ نهایی را به کاربر تحویل می‌دهد.

یعنی فرانت‌اند نباید مستقیماً کلید درواره را در اختیار داشته باشد. پروژه FastAPI بخش Backend این معماری را پیاده‌سازی می‌کند.

نسخه غیرهم‌زمان برای درخواست‌های پرتعداد

در برنامه‌ای که هم‌زمان به چند کاربر پاسخ می‌دهد، استفاده از Client غیرهم‌زمان می‌تواند مناسب‌تر باشد.

نمونه ساده:

import os

from dotenv import load_dotenv
from openai import AsyncOpenAI

load_dotenv()

client = AsyncOpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url=os.getenv(
        "DARVAREH_BASE_URL",
        "https://api.darvareh.ir/v1",
    ),
)

model_id = os.environ["DARVAREH_MODEL"]


async def generate_answer(message: str) -> str:
    response = await client.chat.completions.create(
        model=model_id,
        messages=[
            {
                "role": "system",
                "content": "به زبان فارسی و دقیق پاسخ بده.",
            },
            {
                "role": "user",
                "content": message,
            },
        ],
        temperature=0.3,
        max_tokens=800,
    )

    return response.choices[0].message.content or ""

در FastAPI نیز می‌توانید مسیر را async تعریف کنید:

@app.post("/chat")
async def chat(request: ChatRequest):
    answer = await generate_answer(request.message)

    return {
        "answer": answer,
        "model": model_id,
    }

غیرهم‌زمان‌بودن به‌تنهایی ظرفیت نامحدود ایجاد نمی‌کند. همچنان باید محدودیت درخواست، Timeout، صف، ظرفیت سرور و محدودیت مدل را مدیریت کنید.

مدیریت خطاها در API هوش مصنوعی

یک برنامه واقعی باید برای خطاهای احتمالی آماده باشد.

خطای احراز هویت

دلایل رایج:

• کلید API اشتباه است.
• کلید ناقص کپی شده است.
• فایل .env خوانده نمی‌شود.
• متغیر محیطی روی سرور تنظیم نشده است.

بررسی کنید:

import os

print(bool(os.getenv("DARVAREH_API_KEY")))

مقدار واقعی کلید را در Log چاپ نکنید.

خطای مدل نامعتبر

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

خطای Rate Limit

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

• محدودکردن تعداد درخواست هر کاربر
• Retry با فاصله افزایشی
• استفاده از صف برای وظایف غیرضروری
• Cache کردن پاسخ‌های تکراری
• جلوگیری از ارسال چندباره درخواست با دکمه

خطای Timeout

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

client = OpenAI(
    api_key=api_key,
    base_url=base_url,
    timeout=30.0,
)

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

خطای پاسخ خالی

همیشه وجود پاسخ را بررسی کنید:

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

if not answer:
    raise ValueError("پاسخ مدل خالی است.")

خطای JSON

برای خروجی ساختاریافته از try استفاده کنید:

try:
    data = json.loads(content)
except json.JSONDecodeError:
    data = None

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

Retry با تأخیر افزایشی

Retry باید فقط برای خطاهای موقت انجام شود. برای مثال، تکرار درخواست با کلید اشتباه فایده‌ای ندارد.

نمونه ساده:

import time

from openai import APIConnectionError, RateLimitError


def run_with_retry(operation, attempts: int = 3):
    for attempt in range(attempts):
        try:
            return operation()

        except (RateLimitError, APIConnectionError):
            if attempt == attempts - 1:
                raise

            delay = 2 ** attempt
            time.sleep(delay)

استفاده:

response = run_with_retry(
    lambda: client.chat.completions.create(
        model=model_id,
        messages=[
            {
                "role": "user",
                "content": "پایتون چیست؟",
            }
        ],
    )
)

در پروژه‌های بزرگ‌تر بهتر است Retry همراه با سقف تأخیر، مقدار تصادفی کوچک و شناسه درخواست پیاده‌سازی شود.

توکن چیست و چرا اهمیت دارد؟

مدل‌های زبانی متن را به واحدهایی به نام توکن (Token) تقسیم می‌کنند. هم ورودی و هم خروجی می‌توانند در محاسبه مصرف و هزینه اثر داشته باشند.

موارد زیر باعث افزایش مصرف توکن می‌شوند:

• System Prompt طولانی
• تاریخچه مکالمه بزرگ
• ارسال متن یا سند کامل
• تولید پاسخ بسیار بلند
• تکرار اطلاعات ثابت در تمام درخواست‌ها
• نگهداری پیام‌های غیرضروری در Context

برای کاهش مصرف:

• دستورها را روشن و فشرده بنویسید.
• تاریخچه غیرضروری را حذف یا خلاصه کنید.
• طول خروجی را محدود کنید.
• برای کارهای ساده، مدل متناسب انتخاب کنید.
• پاسخ‌های تکراری را Cache کنید.
• ورودی‌های بزرگ را به بخش‌های منطقی تقسیم کنید.
• مصرف را به تفکیک قابلیت و کاربر ثبت کنید.

مشاهده میزان مصرف یک درخواست

اگر پاسخ مدل اطلاعات Usage را ارائه کند، می‌توانید آن را بررسی کنید:

response = client.chat.completions.create(
    model=model_id,
    messages=[
        {
            "role": "user",
            "content": "پایتون را در یک جمله معرفی کن.",
        }
    ],
)

if response.usage:
    print("Prompt tokens:", response.usage.prompt_tokens)
    print("Completion tokens:", response.usage.completion_tokens)
    print("Total tokens:", response.usage.total_tokens)

وجود و شکل جزئیات Usage می‌تواند به مدل و Endpoint وابسته باشد.

انتخاب مدل مناسب برای پروژه پایتون

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

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

چگونه یک پرامپت مناسب در پایتون بنویسیم؟

پرامپت خوب باید تا حد ممکن این عناصر را مشخص کند:

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

نمونه ضعیف:

این متن را بررسی کن.

نمونه بهتر:

نقش: تحلیل‌گر بازخورد مشتری

وظیفه:
متن مشتری را تحلیل کن و موضوع اصلی، احساس و اقدام پیشنهادی را مشخص کن.

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

ساختار:
{
  "topic": "string",
  "sentiment": "positive | neutral | negative",
  "suggested_action": "string"
}

متن مشتری:
{{CUSTOMER_TEXT}}

در پایتون می‌توانید ورودی را به‌صورت جداگانه در پیام کاربر قرار دهید:

messages = [
    {
        "role": "system",
        "content": SYSTEM_PROMPT,
    },
    {
        "role": "user",
        "content": customer_text,
    },
]

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

چند پروژه کاربردی هوش مصنوعی با پایتون

پس از اجرای مثال‌های این مقاله می‌توانید یکی از پروژه‌های زیر را توسعه دهید.

خلاصه‌ساز متن

ورودی:

• مقاله
• گزارش
• صورت‌جلسه
• متن آموزشی

خروجی:

• خلاصه کوتاه
• نکات کلیدی
• تصمیم‌ها
• اقدام‌های بعدی

دسته‌بندی پیام‌های مشتری

دسته‌ها:

• فروش
• پشتیبانی
• مالی
• پیشنهاد
• شکایت
• سایر

این پروژه می‌تواند پیام‌ها را پیش از ارجاع به اپراتور دسته‌بندی کند.

تولید توضیحات محصول

ورودی:

• نام محصول
• ویژگی‌ها
• مخاطب
• لحن برند

خروجی:

• عنوان
• توضیح کوتاه
• توضیح کامل
• مزایا
• پرسش‌های متداول

دستیار تولید کد

قابلیت‌ها:

• توضیح کد
• ساخت تست
• پیدا کردن خطای احتمالی
• بازنویسی تابع
• تولید مستندات
• تبدیل زبان برنامه‌نویسی

کد تولیدشده باید پیش از اجرا توسط توسعه‌دهنده بررسی و آزمایش شود.

استخراج داده از متن

می‌توانید متن آزاد را به داده ساختاریافته تبدیل کنید:

{
  "name": "شرکت نمونه",
  "phone": "02100000000",
  "city": "تهران",
  "request_type": "demo"
}

سپس داده اعتبارسنجی‌شده را در CRM یا دیتابیس ذخیره کنید.

دستیار پرسش‌وپاسخ داخلی

برای ساخت سیستم پاسخ‌گویی براساس اسناد سازمانی می‌توانید در مراحل بعدی از معماری RAG استفاده کنید:

1. اسناد را استخراج و پاک‌سازی کنید.
2. متن را به قطعه‌های مناسب تقسیم کنید.
3. برای قطعه‌ها Embedding بسازید.
4. قطعه‌های مرتبط با پرسش را بازیابی کنید.
5. فقط اطلاعات مرتبط را در اختیار مدل بگذارید.
6. پاسخ را همراه با منبع نمایش دهید.

تفاوت استفاده از API و اجرای مدل محلی

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

بهینه‌سازی هزینه پروژه

برای مدیریت هزینه، ابتدا باید بدانید هر قابلیت چه مقدار ورودی و خروجی تولید می‌کند.

راهکارهای عملی:

محدودکردن طول ورودی

در FastAPI طول پیام را مشخص کردیم:

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

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

محدودکردن طول پاسخ

max_tokens=800

مقدار مناسب را براساس کاربرد تعیین کنید. پاسخ یک دسته‌بندی نباید صدها توکن مصرف کند.

استفاده از مدل متناسب

برای تشخیص موضوع یا احساس، معمولاً مدل سبک و سریع کافی است. برای تحلیل پیچیده یا تولید کد دشوار می‌توان مدل قدرتمندتری انتخاب کرد.

Cache کردن پاسخ‌ها

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

نسخه‌بندی پرامپت

برای هر پرامپت شناسه نسخه داشته باشید:

PROMPT_VERSION = "ticket-classifier-v1"

این کار مقایسه کیفیت و هزینه نسخه‌های مختلف را ساده‌تر می‌کند.

ثبت Usage

برای هر درخواست این اطلاعات را ثبت کنید:

• نام قابلیت
• مدل
• تعداد توکن ورودی
• تعداد توکن خروجی
• زمان پاسخ
• موفق یا ناموفق‌بودن
• نسخه پرامپت

کلید API و متن‌های حساس کاربران نباید بدون ضرورت در Log ذخیره شوند.

ساختار پیشنهادی یک پروژه واقعی

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

python-ai-project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── schemas.py
│   ├── ai_client.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── chat_service.py
│   └── routes/
│       ├── __init__.py
│       └── chat.py
├── tests/
│   └── test_chat.py
├── .env
├── .gitignore
├── requirements.txt
└── README.md

مسئولیت فایل‌ها:

اشتباهات رایج در برنامه‌نویسی هوش مصنوعی با پایتون

قراردادن کلید API داخل کد

اشتباه:

api_key = "کلید واقعی"

روش مناسب:

api_key = os.environ["DARVAREH_API_KEY"]

قراردادن کلید در JavaScript مرورگر

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

استفاده از یک مدل قدرتمند برای تمام وظایف

وظایف ساده را به مدل سریع‌تر و اقتصادی‌تر بسپارید و مدل قدرتمند را فقط برای کارهای پیچیده استفاده کنید.

اعتماد کامل به خروجی مدل

پاسخ مدل ممکن است نادرست باشد. خروجی‌های مهم را اعتبارسنجی کنید و عملیات حساس را بدون کنترل برنامه انجام ندهید.

ارسال تاریخچه نامحدود

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

نداشتن Timeout

بدون Timeout، درخواست ممکن است منابع برنامه را برای مدت طولانی درگیر کند.

Retry نامحدود

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

ترکیب منطق API و رابط کاربری

منطق هوش مصنوعی را در یک Service مستقل قرار دهید تا بعداً بتوانید همان قابلیت را در وب، موبایل، بات یا پنل سازمانی استفاده کنید.

آزمایش فقط با چند ورودی ساده

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

چگونه کیفیت پاسخ‌ها را ارزیابی کنیم؟

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

[
  {
    "input": "رمز عبورم را فراموش کرده‌ام",
    "expected_category": "account"
  },
  {
    "input": "مبلغ صورتحساب اشتباه محاسبه شده",
    "expected_category": "billing"
  },
  {
    "input": "برنامه بعد از ورود بسته می‌شود",
    "expected_category": "technical"
  }
]

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

• چند پاسخ درست بوده است؟
• چند خروجی JSON نامعتبر بوده است؟
• زمان متوسط پاسخ چقدر است؟
• هزینه متوسط هر درخواست چقدر است؟
• کدام ورودی‌ها باعث خطا می‌شوند؟
• مدل در چه شرایطی اطلاعات را حدس می‌زند؟

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

مسیر پیشنهادی یادگیری هوش مصنوعی با پایتون

مرحله اول: مبانی Python

موضوعات ضروری:

• متغیرها
• شرط و حلقه
• تابع
• List و Dictionary
• مدیریت خطا
• ماژول و Package
• کار با فایل
• JSON
• HTTP

مرحله دوم: کار با API

یاد بگیرید:

• درخواست HTTP چیست؟
• Header و Body چه هستند؟
• JSON چگونه Parse می‌شود؟
• متغیر محیطی چیست؟
• Timeout و Retry چگونه کار می‌کنند؟
• وضعیت‌های HTTP چه معنایی دارند؟

مرحله سوم: مدل‌های زبانی

مفاهیم مهم:

• پرامپت
• پیام‌های System و User
• توکن
• Context Window
• Temperature
• Streaming
• Structured Output
• Tool Calling

مرحله چهارم: ساخت Backend

یکی از این ابزارها را یاد بگیرید:

• FastAPI
• Django
• Flask

برای پروژه‌های APIمحور، FastAPI انتخابی ساده و کاربردی است.

مرحله پنجم: دیتابیس

از SQLite شروع کنید و سپس PostgreSQL را یاد بگیرید:

• ذخیره کاربران
• تاریخچه مکالمه
• تنظیمات
• وضعیت درخواست
• گزارش مصرف

مرحله ششم: ارزیابی و انتشار

موضوعات مهم:

• تست خودکار
• ثبت خطا
• مانیتورینگ
• مدیریت هزینه
• Container و Docker
• استقرار Backend
• محدودیت نرخ
• کنترل نسخه پرامپت

برنامه تمرینی چهار هفته‌ای

در پایان چهار هفته باید بتوانید یک قابلیت هوش مصنوعی را از مرحله ایده تا API قابل استفاده پیاده‌سازی کنید.

پرسش‌های متداول

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

پایتون به‌دلیل سادگی، کتابخانه‌های گسترده و جامعه کاربری بزرگ یکی از بهترین انتخاب‌ها برای هوش مصنوعی است. بااین‌حال، برای اتصال به API مدل‌ها می‌توان از JavaScript، PHP، Java، Go و زبان‌های دیگر نیز استفاده کرد.

برای شروع هوش مصنوعی با پایتون به کارت گرافیک نیاز دارم؟

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

آیا برای استفاده از API باید یادگیری ماشین بلد باشم؟

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

چگونه پایتون را به API هوش مصنوعی درواره متصل کنیم؟

با ساخت یک Client و تنظیم کلید و آدرس پایه:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DARVAREH_API_KEY",
    base_url="https://api.darvareh.ir/v1",
)

سپس شناسه مدل را در درخواست قرار دهید:

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[
        {
            "role": "user",
            "content": "سلام",
        }
    ],
)

شناسه مدل را از کجا پیدا کنیم؟

فهرست مدل‌ها و شناسه قابل استفاده آن‌ها در صفحه مدل‌های درواره قرار دارد.

چرا باید از فایل .env استفاده کنیم؟

فایل .env تنظیمات محرمانه و وابسته به محیط را از کد جدا می‌کند. این فایل نباید وارد مخزن Git شود.

آیا می‌توان با پایتون چت‌بات فارسی ساخت؟

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

Streaming چیست؟

Streaming یعنی پاسخ مدل به‌جای انتظار برای تکمیل کامل، به‌صورت تدریجی دریافت و نمایش داده شود. این روش برای چت‌بات‌ها و پاسخ‌های طولانی تجربه کاربری بهتری ایجاد می‌کند.

آیا خروجی JSON مدل همیشه معتبر است؟

خیر. درخواست JSON در پرامپت به‌تنهایی تضمین کافی ایجاد نمی‌کند. خروجی باید Parse و با ابزاری مانند Pydantic اعتبارسنجی شود. در صورت پشتیبانی مدل، Structured Outputs نیز انتخاب مناسب‌تری است.

چگونه هزینه API هوش مصنوعی را کاهش دهیم؟

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

آیا می‌توان API ساخته‌شده با FastAPI را به React یا Next.js متصل کرد؟

بله. فرانت‌اند درخواست را به Backend مبتنی بر FastAPI می‌فرستد و Backend با API درواره ارتباط برقرار می‌کند. کلید درواره باید فقط روی Backend نگهداری شود.

آیا می‌توان از این روش برای اپلیکیشن تجاری استفاده کرد؟

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

جمع‌بندی

برای شروع برنامه‌نویسی هوش مصنوعی با پایتون لازم نیست از همان روز اول مدل عصبی آموزش دهید یا وارد مباحث پیچیده شوید. می‌توانید با استفاده از مدل‌های آماده و API، یک قابلیت واقعی را در چند مرحله بسازید.

در این مقاله یاد گرفتیم چگونه:

• Python و محیط مجازی را آماده کنیم.
• کتابخانه‌های موردنیاز را نصب کنیم.
• کلید API را با متغیر محیطی مدیریت کنیم.
• به API هوش مصنوعی درواره متصل شویم.
• یک دستیار خط فرمان بسازیم.
• پاسخ را به‌صورت Streaming نمایش دهیم.
• خروجی JSON را با Pydantic اعتبارسنجی کنیم.
• یک دسته‌بند تیکت پیاده‌سازی کنیم.
• قابلیت هوش مصنوعی را به API مبتنی بر FastAPI تبدیل کنیم.
• خطا، توکن، هزینه و تاریخچه مکالمه را مدیریت کنیم.

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

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

مقالات مرتبط

• API هوش مصنوعی چیست؟ راهنمای کامل اتصال هوش مصنوعی به نرم‌افزار
• دریافت API هوش مصنوعی؛ آموزش ساخت API Key و اتصال
• OpenAI-Compatible API چیست و چگونه کار می‌کند؟
• آموزش استفاده از API درواره با cURL
• ساخت AI Agent با Python و FastAPI
• Structured Outputs چیست؟ آموزش دریافت خروجی JSON
• Streaming API چیست؟ آموزش دریافت تدریجی پاسخ مدل
• Token چیست و چگونه هزینه API هوش مصنوعی محاسبه می‌شود؟
• چگونه API هوش مصنوعی را به اپلیکیشن خود متصل کنیم؟
• چگونه با API درواره یک چت‌بات هوش مصنوعی بسازیم؟

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.