مرجع API تصمیم‌گیری (Decisions)

API تصمیم‌گیری شواهد ورودی را ارزیابی می‌کند و پاسخی با نوع مشخص برمی‌گرداند: احتمال درست‌بودن یک گزاره، انتخاب از میان دسته‌های تعیین‌شده یا امتیاز بر اساس سطوح مرتب یک معیار. از آن برای طبقه‌بندی، هدایت درخواست‌ها، بررسی ارتباط محتوا و اولویت‌بندی استفاده کنید. این API پاسخ گفت‌وگویی یا شیء JSON دلخواه تولید نمی‌کند.

AvalAI قالب درخواست OpenAI Decisions را در مسیر /v1/decisions برای مدل‌های Jev از TYPESAFE AI ارائه می‌دهد. قالب بومی این ارائه‌دهنده در نقطه پایانی SystemOne در دسترس است. نام فیلدها و قالب پاسخ این دو نقطه پایانی متفاوت است.

بررسی زنده، ۱۴۰۵-۰۸-۰۱ / (2026-10-23): درخواست طبقه‌بندی سه‌گزینه‌ای پایین و یک درخواست با متن مشترک و پرسش‌های predicate، choice و score برای هر دو مدل jev-latest و jev-preview پاسخ HTTP 200 با جواب‌های دارای نوع مشخص دادند. این بررسی درخواست‌های متنی کوچک مستندشده را تأیید می‌کند؛ انواع ورودی گسترده‌تر، محدودیت درخواست‌های بزرگ، گزینه‌های بولی، رفتار حافظه نهان و خودداری از پاسخ با این بررسی‌ها ثابت نشدند.

نقطه پایانی و احراز هویت

POST https://api.avalai.ir/v1/decisions

کلید API مربوط به AvalAI را در هدر Authorization: Bearer … قرار دهید و بدنه JSON را با هدر Content-Type: application/json بفرستید. کلید را از متغیر AVALAI_API_KEY در محیط سرور بخوانید؛ آن را در کد مرورگر یا فایل‌های عمومی قرار ندهید. راهنمای احراز هویت را ببینید.

مدل‌ها و قیمت‌گذاری

شناسه مدل در AvalAI	نسخه فعلی مقصد
jev-preview	jev-1.13.0
jev-latest	jev-1.14.0

قیمت هر دو نام مستعار در AvalAI یکسان است: ۰٫۰۴۲ دلار آمریکا به‌ازای یک میلیون توکن ورودی، ۰٫۰۰ دلار به‌ازای یک میلیون توکن ورودی ذخیره‌شده در حافظه نهان و ۰٫۰۰ دلار به‌ازای یک میلیون توکن خروجی. این نام‌های مستعار به نسخه‌های جدول بالا اشاره می‌کنند. نام مستعار و تنظیمات درخواست را در سوابق ارزیابی نگه دارید تا پس از تغییر نسخه بتوانید رفتار مدل را مقایسه کنید. صفحه ارائه‌دهنده و قیمت‌گذاری را ببینید.

مدل‌ها و قیمت‌های OpenAI به سرویس خود OpenAI مربوط‌اند و مسیرهای Jev یا شرایط تجاری AvalAI را تعیین نمی‌کنند. microsoft-decision-1 از گزینه‌های احتمالی آینده است و در این انتشار در دسترس نیست.

بدنه درخواست

بررسی زنده: درخواست اصلاح‌شده با choices در ۱ آبان ۱۴۰۵ (2026-10-23) با هر دو نام مستعار پاسخ HTTP 200 گرفت. تعریف‌های Predicate، Choice و Score در ادامه نیز در بررسی زنده پوشش داده شدند. درخواست قبلی با فیلد نادرست options پاسخ HTTP 400 گرفته بود؛ اصلاح این فیلد، خطا را برطرف کرد. System One بومی جداگانه بررسی شده است و قالب پاسخ متفاوتی دارد.

فیلد	نوع	الزامی	کاربرد
model	string	بله	شناسه مدل تصمیم‌گیری در AvalAI، مانند jev-latest یا jev-preview.
input	string or array	بله	شواهد مشترکی که همه پرسش‌ها ارزیابی می‌کنند. مثال‌های این صفحه از رشته متنی استفاده می‌کنند.
questions	array of question objects	بله	پرسش‌های مستقلی که باید درباره شواهد پاسخ داده شوند.

در قالب مرجع OpenAI، فیلد input آرایه‌ای مرتب از پیام‌ها، فراخوانی تابع و خروجی آن یا فراخوانی ابزار سفارشی و خروجی آن را نیز می‌پذیرد. خروجی هر ابزار باید با call_id به فراخوانی متناظر اشاره کند. در همان قالب، پیام کاربر می‌تواند متن، تصویر و JSON داشته باشد؛ پیام‌های سیستم و توسعه‌دهنده متن ورودی دارند و پیام دستیار شامل متن خروجی یا اعلام خودداری از پاسخ است.

گستردگی قالب مرجع OpenAI به‌معنای پشتیبانی از همه این ورودی‌ها برای Jev در AvalAI نیست. ابتدا از متن مشترک استفاده کنید و هر نوع ورودی دیگر را در مسیر مدل انتخابی خود بیازمایید. به‌ویژه، صرف سازگاری قالب نقطه پایانی با OpenAI، پشتیبانی از تصویر، input_json، تاریخچه ابزار، پاسخ جریانی، تنظیمات حافظه نهان ورودی یا محدودیت‌های عددی OpenAI را ثابت نمی‌کند. برای زمینه بومی متنی یا JSON، SystemOne را ببینید.

فیلدهای پرسش

فیلد	نوع	کاربرد	توضیح
type	string	همه پرسش‌ها	یکی از predicate، choice یا score.
instructions	string	همه پرسش‌ها	شرط، قاعده انتخاب دسته یا دستور امتیازدهی. از همین نام دقیق استفاده کنید.
name	string	همه پرسش‌ها، اختیاری	شناسه پرسش در پاسخ. برای هر پرسش نامی متمایز انتخاب کنید.
choices	array	choice	گزینه‌های مجاز؛ هر گزینه یک value و یک description اختیاری دارد.
levels	array	score	سطوح مرتب معیار؛ هر سطح یک label و یک description اختیاری دارد.

در /v1/decisions از choices استفاده کنید، نه options. برای هر پرسش از instructions استفاده کنید. نقطه پایانی بومی /v1/systemone از criteria و قالب درخواست متفاوتی استفاده می‌کند. ترکیب این دو قالب ممکن است پاسخ 400 برای درخواست نامعتبر ایجاد کند.

مرجع OpenAI از ۱ تا ۴۰۰ پرسش، ۲ تا ۲۵۵ گزینه یکتا و ۲ تا ۱۰ سطح امتیازدهی را مجاز می‌داند. این اعداد محدودیت‌های OpenAI هستند و برای Jev در AvalAI تأیید نشده‌اند. اندازه درخواست‌ها را محدود نگه دارید و اندازه‌های موردنیاز برنامه خود را بیازمایید.

گزاره (predicate)

گزاره یک شرط را بررسی می‌کند. پاسخ آن فیلد probability دارد که احتمال درست‌بودن شرط را برآورد می‌کند. پرسش را بر یک ویژگی قابل مشاهده متمرکز کنید و مشخص کنید چه چیزی شاهد آن محسوب می‌شود.

{
  "type": "predicate",
  "name": "duplicate_charge",
  "instructions": "Does the customer report being charged more than once for the same order?"
}

انتخاب (choice)

پرسش انتخابی یکی از دسته‌های داده‌شده را برمی‌گزیند. قالب مرجع OpenAI برای value رشته یا مقدار بولی می‌پذیرد؛ رشته و مقدار بولی، حتی اگر ظاهر مشابهی داشته باشند، متفاوت‌اند. مثال‌های متنی از رشته استفاده می‌کنند. برای دسته‌های هم‌پوشان توضیح متمایز بنویسید و اگر دسته‌ها همه ورودی‌ها را پوشش نمی‌دهند، گزینه‌ای صریح برای موارد دیگر قرار دهید.

{
  "type": "choice",
  "name": "department",
  "instructions": "Which department should handle this complaint?",
  "choices": [
    {
      "value": "billing",
      "description": "Payments, invoices, and refunds."
    },
    {
      "value": "technical",
      "description": "Problems using the product."
    },
    {
      "value": "shipping",
      "description": "Delivery and tracking."
    },
    {
      "value": "other",
      "description": "Requests outside these categories."
    }
  ]
}

امتیاز (score)

پرسش امتیازی شواهد را بر اساس سطوح مرتب ارزیابی می‌کند. سطوح را از پایین به بالا مرتب کنید و برای سطوح مجاور معیارهای متمایز بنویسید. شماره سطوح از 0 آغاز می‌شود. مقدار score در مرجع OpenAI میانگین وزن‌دار این شماره‌ها بر اساس احتمال هر سطح است و می‌تواند بین دو سطح قرار گیرد. این مقدار بازه عددی دلخواهی نیست که با minimum یا maximum تعیین کنید.

{
  "type": "score",
  "name": "severity",
  "instructions": "How severe is this issue?",
  "levels": [
    {
      "label": "Cosmetic",
      "description": "Appearance only; no lost functionality."
    },
    {
      "label": "Workaround available",
      "description": "A task fails, but another way works."
    },
    {
      "label": "Fully blocked",
      "description": "A task fails with no workaround."
    }
  ]
}

مثال طبقه‌بندی متن

برنامه‌های زیر درخواست یکسانی را به AvalAI می‌فرستند. مثال Python فقط از کتابخانه استاندارد استفاده می‌کند. مثال JavaScript به Node.js نسخه ۱۸ یا بالاتر نیاز دارد و روی سرور اجرا می‌شود. هر مثال یک تلاش با زمان محدود انجام می‌دهد تا درخواست نامعتبر مشخص شود؛ برای ترافیک عملیاتی، سیاست تلاش مجدد را به کار ببرید.

Bash

curl --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  https://api.avalai.ir/v1/decisions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "jev-latest",
    "input": "I was charged twice. Please help.",
    "questions": [{
      "type": "choice",
      "name": "route",
      "instructions": "Which team should handle this message?",
      "choices": [
        {"value": "billing", "description": "Payments or invoices"},
        {"value": "technical", "description": "Software or API problems"},
        {"value": "other", "description": "Anything else"}
      ]
    }]
  }'

Python

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

payload = {
    "model": "jev-latest",
    "input": "I was charged twice. Please help.",
    "questions": [
        {
            "type": "choice",
            "name": "route",
            "instructions": "Which team should handle this message?",
            "choices": [
                {"value": "billing", "description": "Payments or invoices"},
                {"value": "technical", "description": "Software or API problems"},
                {"value": "other", "description": "Anything else"},
            ],
        }
    ],
}
request = Request(
    "https://api.avalai.ir/v1/decisions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=30) as response:
        decision = json.load(response)
except HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise

print(json.dumps(decision, indent=2, ensure_ascii=False))

JavaScript

const apiKey = process.env.AVALAI_API_KEY;
if (!apiKey) throw new Error("AVALAI_API_KEY is required");

const payload = {
  model: "jev-latest",
  input: "I was charged twice. Please help.",
  questions: [{
    type: "choice",
    name: "route",
    instructions: "Which team should handle this message?",
    choices: [
      { value: "billing", description: "Payments or invoices" },
      { value: "technical", description: "Software or API problems" },
      { value: "other", description: "Anything else" },
    ],
  }],
};
const response = await fetch("https://api.avalai.ir/v1/decisions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(30_000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
console.log(JSON.stringify(JSON.parse(text), null, 2));

برای مقایسه مسیر پیش‌نمایش، فقط model را به jev-preview تغییر دهید. برای پرسش گزاره‌ای یا امتیازی، شیء پرسش را با مثال مربوط در بالا جایگزین کنید و شواهد متناسب را در input قرار دهید.

SDKهای رسمی فعلی OpenAI متد client.decisions.create(...) را مستند کرده‌اند، اما وجود آن به نسخه نصب‌شده و تعریف نوع‌های آن بستگی دارد. وقتی SDK شما بخش Decisions ندارد یا شناسه مدل را محدود می‌کند، درخواست مستقیم HTTP مبنای مناسبی برای بررسی است. این بدنه را با chat.completions.create نفرستید: مسیر /v1/decisions از input و questions استفاده می‌کند و قالب messages در Chat Completions را ندارد.

قالب پاسخ و تفسیر آن

پاسخ‌های متنی تأییدشده AvalAI شامل model، answers، usage و فیلد افزوده‌شده estimated_cost هستند. پاسخ‌های بررسی‌شده به‌ترتیب پرسش‌ها قرار می‌گیرند و name را بازمی‌گردانند. قالب مرجع همچنین پرسش بدون نام با مقدار null در پاسخ را مجاز می‌داند؛ این حالت آزمایش نشده است. پیش از خواندن فیلدهای هر پاسخ، type آن را بررسی کنید.

نوع پاسخ	فیلدهای مرجع OpenAI	تفسیر
predicate	name, probability, type	برآورد احتمال درست‌بودن شرط.
choice	name, choice, probabilities, confidence, type	مقدار انتخاب‌شده از گزینه‌ها، احتمال هر گزینه و مقدار جداگانه اطمینان.
score	name, score, probabilities, confidence, type	میانگین وزن‌دار شماره سطح، احتمال هر سطح و مقدار جداگانه اطمینان.
refusal	name, type	در قالب مرجع، مدل از پاسخ به یک پرسش خودداری کرده است؛ سایر پرسش‌ها همچنان می‌توانند پاسخ بگیرند.

پاسخ کامل ثبت‌شده AvalAI برای درخواست سه‌گزینه‌ای بالا با مدل jev-latest در زمان 2026-10-23 16:11:38 UTC دریافت شد؛ برابر با ساعت ۱۲:۱۱:۳۸ در منطقه زمانی America/New_York. وضعیت پاسخ HTTP 200 و شناسه آن avalai-request-id: 01a16988-37e0-7360-b61b-5d703e489cb4 بود. همین درخواست با مدل jev-preview در ساعت 16:11:48 UTC پاسخ HTTP 200 با شناسه 01a16988-5fcb-7101-b32e-5eebaed63b9b داد. پاسخ‌های عددی، تعداد توکن و مقدار تبدیل ارز در درخواست‌های بعدی می‌توانند متفاوت باشند:

{
  "model": "jev-latest",
  "answers": [
    {
      "type": "choice",
      "name": "route",
      "choice": "billing",
      "probabilities": [
        {
          "value": "billing",
          "probability": 1.0
        },
        {
          "value": "technical",
          "probability": 0.0
        },
        {
          "value": "other",
          "probability": 0.0
        }
      ],
      "confidence": 1.0
    }
  ],
  "usage": {
    "input_tokens": 333,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 38,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 371
  },
  "estimated_cost": {
    "unit": "0.0000139860",
    "irt": 3.78,
    "exchange_rate": 270000
  }
}

اعضای احتمال در پاسخ انتخابی از value و probability استفاده می‌کنند. در پاسخ امتیازی، label نیز وجود دارد و value شماره سطح از صفر است. مقدار confidence از احتمال گزینه انتخاب‌شده جداست؛ آن‌ها را جایگزین یکدیگر نکنید و از احتمال‌ها فرمولی حدسی برای اطمینان نسازید. فرض نکنید که فهرست احتمال‌های هر ارائه‌دهنده همیشه همه گزینه‌ها را در بر می‌گیرد.

در پاسخ ثبت‌شده، usage تعداد 333 توکن ورودی و 38 توکن خروجی را گزارش می‌کند که جمع آن‌ها 371 است. شمار توکن‌های خوانده‌شده از حافظه نهان، نوشته‌شده در آن و توکن‌های استدلال در این پاسخ 0 است. قیمت صفر خروجی به‌معنای گزارش صفر توکن خروجی نیست.

برآورد دلاری برابر است با 333 × 0.042 / 1,000,000 = 0.0000139860 و با estimated_cost.unit مطابقت دارد؛ مبنای هزینه در این نمونه توکن‌های ورودی قیمت‌گذاری‌شده است، نه total_tokens. مقدار estimated_cost.irt برابر 3.78 و مقدار ثبت‌شده exchange_rate برابر 270000 است. این مقادیر برآوردهای همان درخواست‌اند و نرخ تبدیل ثابت یا شمارش یکسان توکن برای سایر ورودی‌ها را تضمین نمی‌کنند. وجود فیلدهای حافظه نهان با مقدار صفر، عملکرد خواندن از حافظه نهان یا نوشتن در آن را ثابت نمی‌کند.

پاسخ غایب، نامعتبر، ناشناخته یا همراه با خودداری را تصمیم حل‌نشده در نظر بگیرید. خودداری از پاسخ معادل گزاره منفی یا دسته مربوط به سایر موارد نیست. رفتار خودداری و حالت‌های آزمایش‌نشده قالب پاسخ مرجع به بررسی بیشتر در مسیر انتخابی AvalAI نیاز دارند.

آستانه‌ها را با نمونه‌های برچسب‌خورده برنامه و هزینه هدایت اشتباه تعیین کنید. احتمال بالا درستی تصمیم را ثابت نمی‌کند. موارد نامطمئن را به صف بازبینی بفرستید و اجرای عمل برنامه را از پاسخ مدل جدا نگه دارید. راهنمای مدل‌های تصمیم‌گیری و دستورکار Jev را ببینید.

چند پرسش و مرزهای گردش کار

پرسش‌های مستقل می‌توانند input مشترک داشته باشند؛ برای مثال، یک پرسش پیام پشتیبانی را هدایت کند و پرسش دیگر اشاره به پرداخت تکراری را بررسی کند. یک پرسش نمی‌تواند در همان درخواست از پاسخ پرسش دیگر استفاده کند. برای گردش کار وابسته، ابتدا پاسخ اول را بخوانید و سپس درخواست جداگانه‌ای بسازید.

Decisions شواهد ارائه‌شده را ارزیابی می‌کند؛ برنامه شما مسیر، پالایش یا بازبینی حاصل را اجرا می‌کند. اگر به استخراج فیلدها، توضیح نوشتاری یا شیء خروجی سفارشی نیاز دارید، از مدل مناسب در Responses API همراه با قابلیت خروجی ساختاریافته استفاده کنید.

خطاها و تلاش مجدد

نشانه	موارد بررسی	سیاست تلاش مجدد
400 یا درخواست نامعتبر	ساختار JSON و فیلدهای model، input، questions، instructions و choices/levels. فیلد choices را با options جایگزین نکنید و فیلد بومی criteria را در این مسیر نفرستید.	ابتدا درخواست را اصلاح کنید. تکرار همان بدنه نامعتبر مشکل را حل نمی‌کند.
401	اعتبار کلید AvalAI و هدر Bearer.	ابتدا احراز هویت را اصلاح کنید.
403	دسترسی حساب یا کلید به مسیر مدل انتخابی.	پیش از تلاش مجدد، دسترسی را برقرار کنید.
404	نشانی دقیق /v1/decisions و شناسه مدل.	ابتدا مسیر یا مدل را اصلاح کنید.
429	تفاوت محدودیت نرخ با اتمام اعتبار یا سهمیه در بدنه خطا.	برای محدودیت موقت نرخ، با تأخیر تلاش کنید؛ خطاهای اعتبار یا سهمیه به رسیدگی حساب نیاز دارند.
500، 502، 503 یا 504	خطای موقت در درگاه یا ارائه‌دهنده.	از سیاست محدود تلاش مجدد استفاده کنید و در صورت وجود، تأخیر معتبر Retry-After را رعایت کنید.
قطع شبکه یا پایان مهلت	اتصال، مهلت هر تلاش و احتمال پردازش درخواست در سرور.	فقط در محدوده مهلت کل و تعداد تلاش مجاز دوباره درخواست بفرستید.

تأخیر معتبر Retry-After را حداقل زمان انتظار در نظر بگیرید. اگر این هدر غایب یا نامعتبر است، از افزایش نمایی فاصله تلاش‌ها همراه با تأخیر تصادفی کوتاه استفاده کنید. هم تعداد تلاش‌ها و هم زمان کل را محدود کنید؛ اگر سرور تأخیری فراتر از مهلت شما خواست، کار را به بعد موکول کنید و زودتر تلاش نکنید. هنگام افزودن حلقه تلاش مجدد، تلاش‌های خودکار SDK را نیز حساب کنید. درخواست‌های تکراری ممکن است بیش از یک بار پردازش شوند و هر بار هزینه ایجاد کنند؛ عمل بعدی برنامه را با شناسه کار داخلی فقط یک بار اجرا کنید.

برای اشکال‌زدایی، نقطه پایانی، نام مستعار مدل، وضعیت HTTP، بدنه خطا پس از حذف اطلاعات حساس و شناسه‌های درخواست در هدرهای پاسخ را نگه دارید. کلید API و ورودی حساس را در گزارش مشترک قرار ندهید. مدیریت خطا و محدودیت نرخ را ببینید.

منابع و راهنماهای مرتبط

• راهنمای رسمی OpenAI Decisions: انواع پرسش، مثال‌ها، تفسیر و مرز قابلیت‌های مرجع.
• مرجع رسمی ایجاد تصمیم در OpenAI: فیلدهای دقیق درخواست و پاسخ.
• راهنمای رسمی تلاش مجدد OpenAI: تأخیر سرور، افزایش محدود فاصله تلاش‌ها و تعامل با تلاش مجدد SDK.
• TYPESAFE AI در AvalAI، مرجع بومی SystemOne، راهنمای مدل‌های تصمیم‌گیری و دستورکار Jev.