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 | ارسال رویدادهای استریم |
درخواست ساده
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])"
}'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)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 قرار دارد که هر عضو آن یک آیتم (مثلاً پیام یا فراخوانی تابع) است.
نمونهی پاسخ خام
{
"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 | خطا در حین تولید |
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)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 تعریف میشوند (نام و پارامترها در سطح اول قرار دارند):
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 با توضیح فارسی برمیگردد. فهرست مدلها و قابلیتهایشان را در کاتالوگ مدلها ببینید.