مثال‌های پیشرفته API

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

یکپارچه‌سازی پیشرفته API چیست؟

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

هر نمونه مستقل است تا بتوانید آن را جداگانه آزمایش و وارد پروژه کنید. پیش از ترکیب چند قابلیت، سازگاری Model ID انتخابی را با همان قابلیت بررسی کنید؛ پشتیبانی chat به‌تنهایی تضمین‌کننده tools، vision یا Responses نیست.

export CHABOKAN_AI_API_KEY="sk-chbk-کلید-واقعی-شما"
export CHABOKAN_AI_MODEL="openai/gpt-4o-mini"

۱. مکالمه چندمرحله‌ای با Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
)

messages = [
    {"role": "system", "content": "پاسخ را کوتاه و فارسی بنویس."},
    {"role": "user", "content": "سه نام برای یک فروشگاه کتاب پیشنهاد بده."},
]

first = client.chat.completions.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    messages=messages,
)
first_text = first.choices[0].message.content or ""
print(first_text)

messages.append({"role": "assistant", "content": first_text})
messages.append({"role": "user", "content": "فقط گزینه دوم را رسمی‌تر کن."})

second = client.chat.completions.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    messages=messages,
)
print(second.choices[0].message.content)

هر درخواست مستقل است؛ برای حفظ context باید history لازم را دوباره بفرستید. تاریخچه را بی‌نهایت رشد ندهید و محدودیت context_length مدل را در نظر بگیرید.

۲. Streaming با Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CHABOKAN_AI_API_KEY,
  baseURL: "https://ai.chabokan.net/v1",
});

const stream = await client.chat.completions.create({
  model: process.env.CHABOKAN_AI_MODEL,
  messages: [
    { role: "user", content: "در پنج مورد کوتاه HTTP را توضیح بده." },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

در streaming نباید فرض کنید هر chunk متن دارد؛ chunkهای metadata یا پایان جریان ممکن است content نداشته باشند.

۳. چند درخواست هم‌زمان با Python Async

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
    timeout=60,
    max_retries=2,
)

async def ask(question: str) -> str:
    response = await client.chat.completions.create(
        model=os.environ["CHABOKAN_AI_MODEL"],
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content or ""

async def main() -> None:
    questions = [
        "DNS را در یک جمله تعریف کن.",
        "TLS را در یک جمله تعریف کن.",
        "CDN را در یک جمله تعریف کن.",
    ]
    results = await asyncio.gather(*(ask(item) for item in questions))
    for result in results:
        print(result)

asyncio.run(main())

هم‌زمانی را محدود نگه دارید. ایجاد صدها coroutine بدون semaphore می‌تواند به 429 و افزایش ناگهانی هزینه منجر شود.

۴. Tool calling کامل با Python

این مثال یک تابع محلی بی‌خطر را به مدل معرفی می‌کند. مدل باید tools را در supported_parameters داشته باشد.

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
)
model = os.environ["CHABOKAN_AI_MODEL"]

def get_order_status(order_id: str) -> dict:
    # در برنامه واقعی از سرویس خودتان بخوانید.
    return {"order_id": order_id, "status": "processing"}

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "وضعیت یک سفارش را برمی‌گرداند.",
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"}
            },
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
}]

messages = [{"role": "user", "content": "وضعیت سفارش 123 را بررسی کن."}]
first = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    if call.function.name != "get_order_status":
        raise ValueError(f"Unexpected tool: {call.function.name}")

    arguments = json.loads(call.function.arguments)
    order_id = str(arguments["order_id"])
    result = get_order_status(order_id)

    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result, ensure_ascii=False),
    })

final = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
)
print(final.choices[0].message.content)

مدل فقط درخواست اجرای تابع را تولید می‌کند. برنامه شما باید نام تابع و آرگومان‌ها را allowlist و validate کند. هیچ آرگومان مدل را مستقیماً به SQL، shell یا عملیات مالی ندهید.

۵. ورودی تصویر با URL

این مثال فقط برای مدلی است که ورودی image را پشتیبانی می‌کند:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
)

response = client.chat.completions.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "این تصویر را در یک جمله توضیح بده."},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/sample.jpg"},
            },
        ],
    }],
)

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

URL نمونه را با تصویر HTTPS قابل‌دسترسی جایگزین کنید. برای تصاویر خصوصی از URL عمومی دائمی استفاده نکنید؛ سیاست دسترسی و زمان انقضای لینک را در نظر بگیرید.

۶. استفاده مستقیم از Responses API

چابکان مسیر /v1/responses را نیز ارائه می‌کند. برای هر مدل جداگانه سازگاری را آزمایش کنید:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
)

response = client.responses.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    input="فقط عبارت «Responses متصل است» را پاسخ بده.",
)

print(response.output_text)

Chat Completions و Responses شکل ورودی و خروجی متفاوت دارند:

مورد	Chat Completions	Responses
ورودی اصلی	messages	input
متن خروجی SDK	choices[0].message.content	output_text
مسیر	/v1/chat/completions	/v1/responses

۷. مدیریت خطا در Python

import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
    timeout=60,
    max_retries=2,
)

try:
    response = client.chat.completions.create(
        model=os.environ["CHABOKAN_AI_MODEL"],
        messages=[{"role": "user", "content": "سلام"}],
    )
    print(response.choices[0].message.content)
except openai.AuthenticationError:
    print("کلید نامعتبر، غیرفعال یا ارسال‌نشده است.")
except openai.RateLimitError:
    print("محدودیت نرخ یا ظرفیت مصرف بررسی شود.")
except openai.APITimeoutError:
    print("درخواست timeout شد.")
except openai.APIStatusError as error:
    print(f"API error: status={error.status_code} request_id={error.request_id}")

متن کامل prompt، پاسخ حساس یا Authorization header را داخل log ننویسید.

۸. آزمون قابلیت مدل پیش از اجرا

curl --silent --show-error --fail https://ai.chabokan.net/v1/models \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY" \
  | jq --arg id "$CHABOKAN_AI_MODEL" \
    '.data[] | select(.id == $id) | {
      id,
      context_length,
      max_completion_tokens,
      supported_parameters,
      architecture
    }'

اگر خروجی خالی است، Model ID در دسترس سرویس شما نیست یا مقدار environment اشتباه است.

منابع: Chat Completions، SDKهای رسمی OpenAI