پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

تولید متن و پرامپت‌نویسی

یاد بگیرید چگونه با استفاده از API AvalAI، مدلی را برای تولید متن پرامپت کنید. AvalAI دسترسی به مدل‌های زبان بزرگ مختلفی را فراهم می‌کند که قادر به تولید پاسخ‌های متنی متنوعی هستند - مانند کد، معادلات ریاضی، داده‌های ساختاریافته JSON یا نثر شبیه به انسان.

این راهنما عمدتا از مثال‌هایی استفاده می‌کند که با ساختار API Responses OpenAI سازگار هستند، که AvalAI از آن پشتیبانی می‌کند.

تولید متن پایه

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

python

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are a helpful assistant.",
    input="یک داستان یک جمله‌ای قبل از خواب درباره یک تک‌شاخ بنویس.",
)

print(response.output_text)

javascript

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "You are a helpful assistant.",
  input: "یک داستان یک جمله‌ای قبل از خواب درباره یک تک‌شاخ بنویس.",
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a helpful assistant.",
    "input": "یک داستان یک جمله‌ای قبل از خواب درباره یک تک‌شاخ بنویس."
  }'

go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"model":        "gpt-5.5",
		"instructions": "You are a helpful assistant.",
		"input":        "یک داستان یک جمله‌ای قبل از خواب درباره یک تک‌شاخ بنویس.",
	}

	body, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", "https://api.avalai.ir/v1/responses", bytes.NewBuffer(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVALAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(responseBody))
}

php

<?php

$apiKey = getenv('AVALAI_API_KEY');

$payload = [
    'model' => 'gpt-5.5',
    'instructions' => 'You are a helpful assistant.',
    'input' => 'یک داستان یک جمله‌ای قبل از خواب درباره یک تک‌شاخ بنویس.',
];

$ch = curl_init('https://api.avalai.ir/v1/responses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

شی پاسخ حاوی یک آرایه output با محتوای تولید شده توسط مدل است. یک پاسخ متنی ساده ممکن است به این شکل باشد:

json

{
  "id": "resp_...",
  "object": "response",
  // ... فیلدهای دیگر

  "output": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "زیر نور ملایم ماه، لونا تک‌شاخ در میان مزارع غبار ستاره‌ای درخشان می‌رقصید و ردپایی از رویاها را برای هر کودکی که خوابیده بود به جا می‌گذاشت.",
          "annotations": [
          ]
        }
      ]
    }
  ],
  "usage": { ... }
}

نکته مهم: آرایه output می‌تواند شامل چندین آیتم باشد، از جمله فراخوانی ابزار یا داده‌های استدلال، به خصوص در مدل‌های جدیدتر. فرض نکنید که خروجی متن اصلی همیشه در output[0].content[0].text قرار دارد. در صورت وجود، از helperهای SDK مانند output_text استفاده کنید یا آرایه output را با دقت تجزیه کنید.

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

گردش‌کار Responses-first

برای featureهای جدید تولید متن، وقتی مدل هدف و route حساب AvalAI شما پشتیبانی می‌کند، /v1/responses را ترجیح دهید. /v1/chat/completions را برای یکپارچه‌سازی‌های legacy پایدار یا routeهایی نگه دارید که هنوز فقط schema چت را ارائه می‌دهند.

هنگام مهاجرت یک flow چت موجود از این نقشه استفاده کنید:

Chat Completions	Responses API
`messages`	رشته `input` یا آرایه پیام‌های `input`
پیام `system`	`instructions` یا پیام `developer`
`choices[0].message.content`	helper SDK به نام `output_text` یا parse کردن آیتم‌های `output`
ارسال دوباره کل تاریخچه `messages`	`previous_response_id` در صورت پشتیبانی، یا تاریخچه خلاصه‌شده و مدیریت‌شده در برنامه
chunkهای `stream: true`	رویدادهای SSE معنایی با `stream: true`

چک‌لیست مهاجرت برای برنامه‌های AvalAI:

قواعد پایدار برنامه را در هر نوبت دوباره به‌صورت instructions یا محتوای developer ارسال کنید؛ وقتی نوبت‌ها را با previous_response_id زنجیره می‌کنید، instructions قبلی به‌صورت خودکار حفظ نمی‌شود.
با previous_response_id مثل ابزار مدیریت state رفتار کنید، نه context window رایگان. context زنجیره قبلی همچنان می‌تواند به‌عنوان input token محاسبه شود؛ برای مکالمات طولانی، نوبت‌های قدیمی‌تر را خلاصه کنید.
output را defensive parse کنید، چون Responses می‌تواند متن، reasoning، فراخوانی ابزار یا آیتم‌های دیگر را در یک پاسخ برگرداند.
اگر یک ابزار hosted OpenAI روی route مدل AvalAI شما فعال نیست، از جایگزین‌های پشتیبانی‌شده مثل function calling، لایه retrieval خودتان، /v1/search یا Files API در صورت فعال بودن استفاده کنید.

کنترل‌های API فراتر از پرامپت

راهنمای جدید OpenAI برای مدل‌های reasoning، متن prompt و تنظیمات API را یک سیستم واحد می‌بیند. وقتی مدل و route انتخابی در AvalAI این fieldها را پشتیبانی می‌کند، پیش از طولانی‌تر کردن prompt این کنترل‌ها را تنظیم کنید:

کنترل	چه زمانی استفاده شود	پیش‌فرض عملی
`reasoning.effort`	task به برنامه‌ریزی، code review، synthesis چندمرحله‌ای یا tradeoff دقیق نیاز دارد.	با `low` یا `medium` شروع کنید؛ `high`/`xhigh` را فقط وقتی eval نشان می‌دهد کیفیت ارزش latency و هزینه token را دارد استفاده کنید.
`text.verbosity`	متن UI فشرده، توضیح کامل‌تر یا اندازه خروجی ثابت می‌خواهید.	بودجه صریح بدهید؛ مثل «۳ bullet»، «زیر ۱۲۰ کلمه» یا «فقط JSON».
`text.format` / schemaها	کد پایین‌دست به fieldهای قابل اعتماد نیاز دارد.	به‌جای توضیح prose برای شکل JSON، از خروجی‌های ساختاریافته استفاده کنید.
`prompt_cache_key`	درخواست‌های زیاد، instructions، policy، مثال یا schema بلند مشترک دارند.	محتوای پایدار را ابتدای request و context مخصوص کاربر را نزدیک انتها نگه دارید؛ cached tokenها را در usage پایش کنید.
`previous_response_id` یا آیتم‌های خروجی برگشتی	به state چندمرحله‌ای نیاز دارید.	وقتی retention قابل قبول است از `previous_response_id` استفاده کنید؛ برای جریان‌های stateless یا retention سخت‌گیرانه‌تر، آیتم‌های خروجی برگشتی را replay کنید.

برای workflowهای ابزارمحور، راهنمای عملیاتی را در توضیح ابزار بگذارید: ابزار چه کاری می‌کند، چه زمانی فراخوانی شود، ورودی لازم، side effectها، ایمنی retry و خطاهای رایج. تاریخ امروز را به همه promptها اضافه نکنید؛ فقط وقتی قانون کسب‌وکار به تاریخ محلی کاربر، تاریخ اجرای policy یا مرجع غیر UTC وابسته است، تاریخ یا timezone را صریح کنید.

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

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

پارامتر instructions: راهنمایی سطح بالا (لحن، اهداف، مثال‌ها) را ارائه می‌دهد که برای درخواست فعلی بر پرامپت‌های input اولویت دارد. این پارامتر در طول مکالمه‌ای که با previous_response_id مدیریت می‌شود، پایدار نمی‌ماند.

python

# مثال استفاده از پارامتر instructions با AvalAI
import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    instructions="مثل دزدان دریایی صحبت کن.",
    input="آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
)
# print(response.output_text) # دسترسی به خروجی همانطور که قبلا نشان داده شد

javascript

// مثال استفاده از پارامتر instructions با AvalAI
const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,

  baseURL: "https://api.avalai.ir/v1",
});

async function main() {
  const response = await client.responses.create({
    model: "gpt-5.5",
    instructions: "مثل دزدان دریایی صحبت کن.",
    input: "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
  });

  // console.log(response.output_text); // دسترسی به خروجی همانطور که قبلا نشان داده شد
}
main();

bash

# مثال استفاده از پارامتر instructions با AvalAI
curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-5.5",
  "instructions": "مثل دزدان دریایی صحبت کن.",
  "input": "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟"
}'

go

// مثال استفاده از پارامتر instructions با AvalAI
config := openai.DefaultConfig(os.Getenv("AVALAI_API_KEY"))
config.BaseURL = "https://api.avalai.ir/v1"
client := openai.NewClientWithConfig(config)

resp, err := client.CreateResponse(
	context.Background(),
	openai.ResponseRequest{
		Model:        "gpt-5.5",
		Instructions: "مثل دزدان دریایی صحبت کن.",
		Input:        "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
	},
)

// استخراج متن از پاسخ همانطور که قبلا نشان داده شد

php

// مثال استفاده از پارامتر instructions با AvalAI
$apiKey = getenv('AVALAI_API_KEY');

$client = OpenAI::client($apiKey, [
'base_url' => 'https://api.avalai.ir/v1',
]);

$response = $client->responses()->create([
'model' => 'gpt-5.5',
'instructions' => 'مثل دزدان دریایی صحبت کن.',
'input' => 'آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟'
]);

// استخراج متن از پاسخ همانطور که قبلا نشان داده شد

نقش‌های پیام:
developer: دستورالعمل‌های توسعه‌دهنده برنامه که در همان درخواست جلوتر از پیام‌های کاربر اولویت می‌گیرند. اگر این قواعد باید در نوبت‌های بعدی هم فعال بمانند، دوباره آن‌ها را ارسال کنید.
user: ورودی کاربر نهایی، با وزن کمتر از developer.
assistant: پیام‌های تولید شده توسط خود مدل.

به developer مثل تعریف تابع برای سیاست‌های برنامه نگاه کنید و به user مثل آرگومان‌هایی که کاربر نهایی می‌فرستد. این جداسازی، قواعد کسب‌وکار را از متن قابل‌کنترل توسط کاربر جدا نگه می‌دارد و نوشتن تست برای پرامپت را ساده‌تر می‌کند.

python

# مثال استفاده از نقش‌های developer و user با AvalAI
import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {"role": "developer", "content": "مثل دزدان دریایی صحبت کن."},
        {
            "role": "user",
            "content": "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
        },
    ],
)
# print(response.output_text) # دسترسی به خروجی همانطور که قبلا نشان داده شد

javascript

// مثال استفاده از نقش‌های developer و user با AvalAI
const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,

  baseURL: "https://api.avalai.ir/v1",
});

async function main() {
  const response = await client.responses.create({
    model: "gpt-5.5",
    input: [
      {
        role: "developer",
        content: "مثل دزدان دریایی صحبت کن.",
      },
      {
        role: "user",
        content: "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
      },
    ],
  });

  // console.log(response.output_text); // دسترسی به خروجی همانطور که قبلا نشان داده شد
}
main();

bash

# مثال استفاده از نقش‌های developer و user با AvalAI
curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-5.5",
  "input": [
  {
    "role": "developer",
    "content": "مثل دزدان دریایی صحبت کن."
  },
  {
    "role": "user",
    "content": "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟"
  }
  ]
}'

go

// مثال استفاده از نقش‌های developer و user با AvalAI
config := openai.DefaultConfig(os.Getenv("AVALAI_API_KEY"))
config.BaseURL = "https://api.avalai.ir/v1"
client := openai.NewClientWithConfig(config)

resp, err := client.CreateResponse(
	context.Background(),
	openai.ResponseRequest{
		Model: "gpt-5.5",
		Input: []openai.ResponseMessage{
			{
				Role:    "developer",
				Content: "مثل دزدان دریایی صحبت کن.",
			},
			{
				Role:    "user",
				Content: "آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟",
			},
		},
	},
)

// استخراج متن از پاسخ همانطور که قبلا نشان داده شد

php

// مثال استفاده از نقش‌های developer و user با AvalAI
$apiKey = getenv('AVALAI_API_KEY');

$client = OpenAI::client($apiKey, [
'base_url' => 'https://api.avalai.ir/v1',
]);

$response = $client->responses()->create([
'model' => 'gpt-5.5',
'input' => [
[
'role' => 'developer',
'content' => 'مثل دزدان دریایی صحبت کن.'
],
[
'role' => 'user',
'content' => 'آیا نقطه‌ویرگول در جاوااسکریپت اختیاری است؟'
]
]
]);

// استخراج متن از پاسخ همانطور که قبلا نشان داده شد

برای مکالمات چند نوبتی، به راهنمای وضعیت مکالمه مراجعه کنید.

طول خروجی، Truncation و Sampling

در درخواست‌های Responses برای production، رفتار token و truncation را صریح کنید:

از max_output_tokens به‌عنوان سقف خروجی تولیدشده استفاده کنید. در مدل‌های reasoning، این پارامتر بودجه مشترک خروجی قابل مشاهده و reasoning پنهان است؛ اگر reasoning آن را تمام کند، پاسخ ممکن است با incomplete_details.reason: "max_output_tokens" و بدون متن قابل مشاهده برگردد. حاشیه امن بگذارید، مصرف reasoning tokenها را بررسی کنید و بخش بودجه توکن reasoning را ببینید.
context window را بودجه مشترک ورودی، نتیجه ابزارها، خروجی و reasoning بدانید. historyهای بلند را پیش از نزدیک شدن به limit مدل compact کنید.
وقتی حذف context قدیمی ناامن است، truncation را disabled نگه دارید؛ بهتر است درخواست با خطای واضح fail شود تا instruction یا evidence ابتدایی بی‌صدا حذف شود.
فقط برای historyهای کم‌ریسک که حذف itemهای قدیمی قابل‌قبول است از truncation: "auto" استفاده کنید. برای support، حقوقی، مالی یا workflowهای عاملی، summary مدیریت‌شده در برنامه یا فشرده‌سازی context را ترجیح دهید.
temperature یا top_p را تنظیم کنید، نه هر دو را همزمان. برای evalها و regression testها تنظیمات deterministic نگه دارید.

PythonJavaScript

python

response = client.responses.create(
    model="gpt-5.5",
    instructions="Answer in at most three concise bullets.",
    input="Summarize the release notes for a product manager.",
    max_output_tokens=300,
    truncation="disabled",
    temperature=0.2,
)

print(response.output_text)

javascript

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: "Answer in at most three concise bullets.",
  input: "Summarize the release notes for a product manager.",
  max_output_tokens: 300,
  truncation: "disabled",
  temperature: 0.2,
});

console.log(response.output_text);

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

برای برنامه‌های production روی AvalAI، prompt builderها را در کد برنامه نگه دارید و به prompt objectهای میزبانی‌شده وابسته نشوید. پرامپت‌های مدیریت‌شده در کد با code review، ورودی‌های typed، تست‌ها و فرایند deployment معمول شما بهتر هماهنگ می‌شوند.

طبق timeline فعلی deprecation در OpenAI، ایجاد prompt از ۳ ژوئن ۲۰۲۶ کم‌رنگ شده و v1/prompts / prompt objectهای قابل استفاده مجدد برای خاموشی در ۳۰ نوامبر ۲۰۲۶ برنامه‌ریزی شده‌اند. این یک دلیل دیگر است که templateهای prompt در AvalAI را در کد نگه دارید و instructions و input تولیدشده را مستقیم به /v1/responses بفرستید.

سازنده‌های پایدار instructions را نزدیک همان feature نگه دارید.
برای مقدارهای پویا مثل داده مشتری، فایل‌ها یا گزینه‌های task از آرگومان تابع یا schema استفاده کنید.
instructions و input تولیدشده را مستقیم به /v1/responses بفرستید.
قبل از تغییر پرامپت production، fixture و eval check اضافه کنید.
تغییرات پرامپت را با release process یا feature flag معمول خود rollout کنید.

انتخاب مدل

AvalAI دسترسی به مدل‌هایی از ارائه‌دهندگان مختلف (OpenAI، Anthropic، Google و غیره) را فراهم می‌کند. هنگام انتخاب مدل (که در پارامتر model مشخص می‌شود) این عوامل را در نظر بگیرید:

قابلیت‌ها: مدل‌های مختلف در وظایف مختلف (استدلال، سرعت، مقرون به صرفه بودن) برتری دارند.
ارائه دهنده: AvalAI به شما امکان می‌دهد مدل‌هایی مانند gpt-5.5, claude-opus-4-8, gemini-3.5-flash و غیره را انتخاب کنید.
هزینه در مقابل عملکرد: مدل‌های بزرگتر ممکن است تواناتر اما کندتر و گران‌تر باشند. مدل‌های کوچکتر می‌توانند سریع‌تر و ارزان‌تر باشند و به طور بالقوه برای وظایف خاص تنظیم دقیق شوند.

برای جزئیات در مورد مدل‌های موجود و ارائه‌دهندگان آن‌ها به بررسی اجمالی مدل‌ها مراجعه کنید. gpt-5.5 از طریق AvalAI معمولا نقطه شروع خوبی برای گردش‌کارهای OpenAI-family روی Responses است؛ وقتی latency یا قیمت مهم‌تر است، از مدل‌های کوچک‌تر یا مدل‌های provider-specific استفاده کنید.

مهندسی پرامپت

ساخت پرامپت‌های مؤثر برای دریافت خروجی‌های مورد نظر بسیار مهم است. اصول کلیدی عبارتند از:

مشخص بودن: وظیفه و فرمت خروجی مورد انتظار را به وضوح تعریف کنید.
ارائه مثال‌ها (یادگیری کم‌شات): مثال‌هایی از ورودی/خروجی را به مدل نشان دهید.
تعیین اهداف (مدل‌های استدلالی): نتیجه مطلوب را به جای دستورالعمل‌های گام به گام توصیف کنید.
ارزیابی: از داده‌های آزمایشی (راهنمای ارزیابی) برای اندازه‌گیری عملکرد پرامپت استفاده کنید.

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

مراحل بعدی

داده‌های ساختاریافته: درباره خروجی‌های ساختاریافته بیاموزید .
مرجع API: برای همه پارامترها به مرجع API تکمیل چت یا پاسخ‌ها مراجعه کنید.

تولید متن و پرامپت‌نویسی ​

تولید متن پایه ​

گردش‌کار Responses-first ​

کنترل‌های API فراتر از پرامپت ​

نقش‌های پیام و دستورالعمل‌ها ​

طول خروجی، Truncation و Sampling ​

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

انتخاب مدل ​

مهندسی پرامپت ​

مراحل بعدی ​

تولید متن و پرامپت‌نویسی

تولید متن پایه

گردش‌کار Responses-first

کنترل‌های API فراتر از پرامپت

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

طول خروجی، Truncation و Sampling

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

انتخاب مدل

مهندسی پرامپت

مراحل بعدی