AvalAI Docs
داشبورد توسعه‌دهنده
پرسش از هوش مصنوعی
پرسش از AvalAIپرسش از Claudeپرسش از ChatGPT
پرسش از هوش مصنوعی
پرسش از AvalAIپرسش از Claudeپرسش از ChatGPT

خروجی‌های پیش‌بینی‌شده ​

خروجی‌های پیش‌بینی‌شده زمانی latency را کم می‌کنند که بخش بزرگی از پاسخ متنی از قبل مشخص باشد. رایج‌ترین حالت، بازتولید یک فایل متنی یا کد پس از یک تغییر کوچک است: متن فعلی فایل را به‌عنوان prediction.content می‌فرستید و مدل می‌تواند tokenهای منطبق را سریع‌تر استفاده کند.

راهنمای رسمی OpenAI این قابلیت را برای Chat Completions و از طریق پارامتر prediction مستند می‌کند. در AvalAI، در دسترس بودن به ارائه‌دهنده بالادستی و مدل بستگی دارد. برای ترافیک خانواده OpenAI، وقتی در حساب AvalAI شما فعال هستند، مدل‌هایی مانند gpt-4.1، gpt-4.1-mini، gpt-4.1-nano، gpt-4o و gpt-4o-mini را ترجیح دهید.

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

از Predicted Outputs زمانی استفاده کنید که:

  • یک فایل کد، سند Markdown، فایل تنظیمات یا template را دوباره تولید می‌کنید؛
  • بیشتر پاسخ نهایی باید شبیه محتوای اصلی باشد؛
  • می‌توانید متن کامل مورد انتظار را به‌عنوان prediction بدهید؛
  • کاهش latency از ریسک هزینه tokenهای prediction ردشده مهم‌تر است.

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

تفاوت Prediction با Prompt Caching ​

Predicted Outputs و prompt caching دو مسئله متفاوت latency را حل می‌کنند:

تکنیکچه چیزی را سریع‌تر می‌کندبهترین کاربرد
Predicted Outputsتولید خروجی وقتی بیشتر completion tokenها از قبل مشخص‌اندبازتولید کد، Markdown، فایل config، template یا فایل‌های متنی پس از یک تغییر کوچک
Prompt cachingprefixهای ورودی تکراریassistantهایی با instruction ثابت، JSON schema، متن policy یا setup تکراری RAG

برای workflowهای ویرایش، اگر route و مدل پشتیبانی می‌کنند، هر دو را ترکیب کنید: instruction و schema پایدار را ابتدای prompt بگذارید تا cache شود، سپس فایل فعلی را به‌عنوان prediction.content بفرستید تا بخش‌های بدون تغییر خروجی سریع‌تر accepted شوند.

مثال Chat Completions ​

این مثال از مدل می‌خواهد در یک کلاس TypeScript مقدار username را با email جایگزین کند. فایل فعلی هم به‌عنوان ورودی و هم به‌عنوان خروجی پیش‌بینی‌شده ارسال می‌شود.

bash
CODE_CONTENT=$(
  cat <<'EOF'
class User {
  firstName: string = "";
  lastName: string = "";
  username: string = "";
}

export default User;
EOF
)

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d "$(jq -n --arg code "$CODE_CONTENT" '{
    model: "gpt-4.1",
    messages: [
      {
        role: "user",
        content: "Replace the username property with an email property. Respond only with code, with no markdown formatting."
      },
      {
        role: "user",
        content: $code
      }
    ],
    prediction: {
      type: "content",
      content: $code
    }
  }')"
python
import os
from openai import OpenAI

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

code = """
class User {
  firstName: string = "";
  lastName: string = "";
  username: string = "";
}

export default User;
""".strip()

completion = client.chat.completions.create(
    model=os.getenv("AVALAI_MODEL", "gpt-4.1"),
    messages=[
        {
            "role": "user",
            "content": "Replace the username property with an email property. Respond only with code, with no markdown formatting.",
        },
        {"role": "user", "content": code},
    ],
    prediction={"type": "content", "content": code},
)

print(completion.choices[0].message.content)
print(completion.usage.completion_tokens_details)
javascript
import OpenAI from "openai";

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

const code = `
class User {
  firstName: string = "";
  lastName: string = "";
  username: string = "";
}

export default User;
`.trim();

const completion = await client.chat.completions.create({
  model: process.env.AVALAI_MODEL ?? "gpt-4.1",
  messages: [
    {
      role: "user",
      content:
        "Replace the username property with an email property. Respond only with code, with no markdown formatting.",
    },
    { role: "user", content: code },
  ],
  prediction: {
    type: "content",
    content: code,
  },
});

console.log(completion.choices[0].message.content);
console.log(completion.usage?.completion_tokens_details);
نسخه Responses API بدون prediction

OpenAI پارامتر prediction را برای Chat Completions مستند کرده است، نه به‌عنوان پارامتر Responses API. هنگام مهاجرت این workflow غیرجریانی به /v1/responses، prediction را حذف کنید و از شکل Responses یعنی instructions، input و response.output_text استفاده کنید. اگر شمارش tokenهای accepted/rejected prediction برای شما ضروری است، Chat Completions را نگه دارید.

python
response = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    instructions="Return only the complete updated TypeScript file. Do not use markdown.",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Replace the username property with an email property in this file.",
                },
                {"type": "input_text", "text": code},
            ],
        }
    ],
    store=False,
)

print(response.output_text)
javascript
const response = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  instructions: "Return only the complete updated TypeScript file. Do not use markdown.",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Replace the username property with an email property in this file.",
        },
        { type: "input_text", text: code },
      ],
    },
  ],
  store: false,
});

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 "$(jq -n --arg code "$CODE_CONTENT" '{
    model: "gpt-5.5",
    instructions: "Return only the complete updated TypeScript file. Do not use markdown.",
    input: [
      {
        role: "user",
        content: [
          { type: "input_text", text: "Replace the username property with an email property in this file." },
          { type: "input_text", text: $code }
        ]
      }
    ],
    store: false
  }')"

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

  • messages → input
  • prompt سیستمی/توسعه‌دهنده → instructions
  • choices[0].message.content → response.output_text
  • prediction → معادل مستقیم در Responses ندارد؛ اگر prediction ضروری است، Chat Completions را نگه دارید
  • accepted_prediction_tokens / rejected_prediction_tokens → معادل usage در Responses ندارد

خواندن جزئیات Usage ​

اگر ارائه‌دهنده جزئیات usage را برگرداند، این فیلدها را بررسی کنید:

  • accepted_prediction_tokens: tokenهای prediction که با خروجی نهایی منطبق بوده‌اند و به کاهش latency کمک کرده‌اند؛
  • rejected_prediction_tokens: tokenهای prediction که با خروجی نهایی منطبق نبوده‌اند.

توکن‌های prediction ردشده ممکن است همچنان مانند completion tokenها هزینه داشته باشند. اگر rejected_prediction_tokens برای یک workload همیشه زیاد است، prediction را حذف کنید یا prediction را به خروجی مورد انتظار نزدیک‌تر کنید.

محل قرارگیری متن Prediction در پاسخ ​

متن prediction لازم نیست یک بلوک پیوسته در ابتدای پاسخ باشد. این متن می‌تواند قبل و بعد از متن جدیدی که مدل اضافه می‌کند match شود. برای مثال، هنگام افزودن یک route به فایل سرور، importهای بدون تغییر، routeهای موجود و کد startup می‌توانند همگی به‌عنوان accepted prediction token حساب شوند، حتی اگر route جدید در وسط فایل اضافه شود.

برای taskهای patch-style این الگو را به‌کار ببرید:

  • کل فایل فعلی را به‌عنوان prediction.content بفرستید؛
  • از مدل بخواهید فایل کامل به‌روزشده را برگرداند، نه diff؛
  • تا حد امکان formatting، commentها و متن اطراف را پایدار نگه دارید؛
  • rejected tokenها را بررسی کنید تا promptهایی که باعث rewrite غیرضروری می‌شوند شناسایی شوند.

Streaming همراه با Prediction ​

Predicted Outputs همراه با streaming هم می‌تواند مفید باشد، چون بخش‌های منطبق پاسخ ممکن است سریع‌تر برسند.

python
stream = client.chat.completions.create(
    model=os.getenv("AVALAI_MODEL", "gpt-4.1"),
    messages=[
        {
            "role": "user",
            "content": "Replace the username property with an email property. Respond only with code.",
        },
        {"role": "user", "content": code},
    ],
    prediction={"type": "content", "content": code},
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")
javascript
const stream = await client.chat.completions.create({
  model: process.env.AVALAI_MODEL ?? "gpt-4.1",
  messages: [
    {
      role: "user",
      content: "Replace the username property with an email property. Respond only with code.",
    },
    { role: "user", content: code },
  ],
  prediction: { type: "content", content: code },
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
نسخه streaming در Responses API بدون prediction

برای مثال streaming، transport را با stream: true / stream=True به /v1/responses منتقل کنید. این مسیر شتاب tokenهای prediction را بازتولید نمی‌کند، اما برای مدل‌ها و routeهایی که Responses را پشتیبانی می‌کنند، مسیر streaming توسعه‌دهنده‌پسندتری می‌دهد.

python
stream = client.responses.create(
    model=os.getenv("AVALAI_MODEL", "gpt-5.5"),
    instructions="Return only the complete updated TypeScript file. Do not use markdown.",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Replace the username property with an email property in this file.",
                },
                {"type": "input_text", "text": code},
            ],
        }
    ],
    store=False,
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
javascript
const stream = await client.responses.create({
  model: process.env.AVALAI_MODEL ?? "gpt-5.5",
  instructions: "Return only the complete updated TypeScript file. Do not use markdown.",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Replace the username property with an email property in this file.",
        },
        { type: "input_text", text: code },
      ],
    },
  ],
  store: false,
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
bash
curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d "$(jq -n --arg code "$CODE_CONTENT" '{
    model: "gpt-5.5",
    instructions: "Return only the complete updated TypeScript file. Do not use markdown.",
    input: [
      {
        role: "user",
        content: [
          { type: "input_text", text: "Replace the username property with an email property in this file." },
          { type: "input_text", text: $code }
        ]
      }
    ],
    store: false,
    stream: true
  }')"

چک‌لیست مهاجرت streaming:

  • messages → input
  • prompt سیستمی/توسعه‌دهنده → instructions
  • chunkهای stream در Chat → eventهای stream در Responses مانند response.output_text.delta
  • prediction → معادل مستقیم در Responses ندارد؛ اگر prediction ضروری است، Chat Completions را نگه دارید
  • فیلدهای usage مربوط به prediction token → معادل مستقیم در Responses ندارند

محدودیت‌ها ​

Predicted Outputs به ارائه‌دهنده و مدل وابسته است. OpenAI برای پیاده‌سازی Chat Completions خود این محدودیت‌ها را مستند کرده است:

  • فقط خروجی متنی پشتیبانی می‌شود؛
  • مقدار n بزرگ‌تر از 1 پشتیبانی نمی‌شود؛
  • logprobs پشتیبانی نمی‌شود؛
  • مقدار مثبت برای presence_penalty و frequency_penalty پشتیبانی نمی‌شود؛
  • ورودی/خروجی صوتی و modalities سازگار نیستند؛
  • max_completion_tokens همراه prediction پشتیبانی نمی‌شود؛
  • فراخوانی ابزار/تابع در حال حاضر همراه prediction پشتیبانی نمی‌شود.

راهنماهای مرتبط ​

حریم خصوصی

تنظیمات حریم خصوصی

ذخیره‌سازی ضروری مرورگر تنظیمات شما را نگه می‌دارد. با اجازه شما، می‌توانیم عملکرد مستندات را اندازه‌گیری کنیم یا داده زنده مدل‌ها را از سرویس ثالث نمایش دهیم.

یک سطح حریم خصوصی انتخاب کنید

ذخیره‌سازی تبلیغاتی، داده کاربر تبلیغاتی یا شخصی‌سازی تبلیغات را فعال نمی‌کنیم. هر زمان می‌توانید این انتخاب را تغییر دهید.

سیاست حریم خصوصی