رفتن به محتوای اصلی
هوشوانا

Responses API

استفاده از Responses API در هوشوانا: ساختار درخواست با input و instructions، رویدادهای استریم، تفاوت با Chat Completions و تنظیم Codex CLI.

آخرین به‌روزرسانی:

Responses API نسل جدیدتر API متنی OpenAI است و هوشوانا آن را با همان قالب پشتیبانی می‌کند. ابزارهایی مثل Codex CLI از این endpoint استفاده می‌کنند. اگر کد یا ابزاری دارید که با client.responses.create کار می‌کند، فقط آدرس پایه و کلید را به هوشوانا تغییر دهید.

POST https://hooshvana.ir/api/v1/responses

چه زمانی از Responses استفاده کنیم؟

  • ابزارتان آن را لازم دارد. Codex CLI و برخی SDKهای جدید عامل‌ها (agent) فقط با Responses کار می‌کنند.
  • کد جدید با SDK رسمی OpenAI می‌نویسید و ساختار ساده‌تر input و instructions را ترجیح می‌دهید.
  • رویدادهای استریم تایپ‌شده می‌خواهید که هر نوع رویداد (متن، فراخوانی ابزار، پایان) نام مشخص دارد.

اگر کد موجودتان با Chat Completions کار می‌کند، دلیلی برای مهاجرت نیست. Chat Completions گسترده‌ترین پشتیبانی را بین کتابخانه‌ها و مدل‌ها دارد و افزونه‌ی پایگاه دانش هوشوانا هم روی آن تعریف شده است.

پارامترهای اصلی

پارامترتوضیح
modelشناسه‌ی مدل، مثل openai/gpt-4.1
inputیک رشته‌ی ساده، یا آرایه‌ای از پیام‌ها با نقش و محتوا
instructionsدستورالعمل سیستمی (معادل پیام system)
max_output_tokensحداکثر توکن خروجی
temperatureمیزان تصادفی بودن خروجی
toolsتعریف ابزارها (function)
streamارسال رویدادهای استریم

درخواست ساده

Shell
curl https://hooshvana.ir/api/v1/responses \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "instructions": "You are a senior Python reviewer. Answer in Persian.",
    "input": "این کد چه مشکلی دارد؟ for i in range(len(items)): print(items[i])"
  }'
Python
import os
from openai import OpenAI

client = OpenAI(base_url="https://hooshvana.ir/api/v1", api_key=os.environ["HOOSHVANA_API_KEY"])

response = client.responses.create(
    model="openai/gpt-4.1",
    instructions="You are a senior Python reviewer. Answer in Persian.",
    input="این کد چه مشکلی دارد؟ for i in range(len(items)): print(items[i])",
)

print(response.output_text)
print(response.usage)
JavaScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hooshvana.ir/api/v1",
  apiKey: process.env.HOOSHVANA_API_KEY,
});

const response = await client.responses.create({
  model: "openai/gpt-4.1",
  input: [
    { role: "developer", content: "Answer in Persian." },
    { role: "user", content: "یک نام کوتاه برای یک کافه‌ی کتاب پیشنهاد بده." },
  ],
});

console.log(response.output_text);

output_text یک ویژگی کمکی در SDKهاست که همه‌ی متن‌های خروجی را کنار هم می‌گذارد. در پاسخ خام، خروجی در آرایه‌ی output قرار دارد که هر عضو آن یک آیتم (مثلاً پیام یا فراخوانی تابع) است.

نمونه‌ی پاسخ خام

JSON
{
  "id": "resp_abc123",
  "object": "response",
  "model": "openai/gpt-4.1",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "مشکل اصلی خوانایی است..." }]
    }
  ],
  "usage": { "input_tokens": 41, "output_tokens": 96, "total_tokens": 137 }
}

توجه کنید نام فیلدهای usage در Responses با Chat Completions فرق دارد: input_tokens و output_tokens.

استریم

با "stream": true پاسخ به صورت رویدادهای SSE نام‌دار می‌آید. مهم‌ترین رویدادها:

رویدادمعنی
response.createdپاسخ ساخته شد
response.output_text.deltaیک تکه‌ی جدید از متن خروجی در فیلد delta
response.output_text.doneمتن یک بخش کامل شد
response.function_call_arguments.deltaتکه‌ای از آرگومان‌های فراخوانی ابزار
response.completedپاسخ تمام شد و شیء کامل با usage در آن است
errorخطا در حین تولید
Python
stream = client.responses.create(
    model="openai/gpt-4.1",
    input="سه نکته برای نوشتن پیام commit خوب بگو.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print()
        print("tokens:", event.response.usage.total_tokens)
JavaScript
const stream = await client.responses.create({
  model: "openai/gpt-4.1",
  input: "سه نکته برای نوشتن پیام commit خوب بگو.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "response.completed") console.log("\ndone");
}

ابزارها

ابزارهای نوع function در Responses کمی ساده‌تر از Chat Completions تعریف می‌شوند (نام و پارامترها در سطح اول قرار دارند):

Python
tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather for a city.",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

response = client.responses.create(
    model="openai/gpt-4.1",
    input="هوای شیراز چطور است؟",
    tools=tools,
)

for item in response.output:
    if item.type == "function_call":
        print(item.name, item.arguments, item.call_id)

برای برگرداندن نتیجه، در درخواست بعدی آیتم‌های خروجی قبلی را به input اضافه کنید و بعد یک آیتم {"type": "function_call_output", "call_id": "...", "output": "..."} بفرستید.

ابزارهای داخلی خاص OpenAI (مثل جستجوی وب یا جستجوی فایل در سرورهای OpenAI) به معنای کامل در هوشوانا در دسترس نیستند. برای جستجو در اسناد خودتان از پایگاه دانش استفاده کنید.

نکته درباره‌ی Codex CLI

Codex CLI برای ارتباط با مدل از Responses API استفاده می‌کند. کافی است در پیکربندی آن یک ارائه‌دهنده با آدرس https://hooshvana.ir/api/v1 و کلید هوشوانا تعریف کنید. راهنمای گام‌به‌گام در بخش یکپارچه‌سازی‌ها آمده است. در این حالت پیشنهاد می‌شود برای Codex یک کلید جدا با سقف هزینه‌ی روزانه بسازید، چون عامل‌های کدنویسی در یک جلسه‌ی طولانی ممکن است توکن زیادی مصرف کنند.

سازگاری مدل‌ها

Responses بیشترین سازگاری را با مدل‌های OpenAI دارد. هوشوانا درخواست‌ها را برای مدل‌های دیگر هم ترجمه می‌کند، ولی برخی ویژگی‌ها ممکن است برای همه‌ی مدل‌ها در دسترس نباشد. اگر قابلیتی پشتیبانی نشود، خطای invalid_request با توضیح فارسی برمی‌گردد. فهرست مدل‌ها و قابلیت‌هایشان را در کاتالوگ مدل‌ها ببینید.