استدلال و خلاصهٔ مدل

سطح فکر کردن

با reasoning.effort یا reasoning_effort شدت پردازش را انتخاب کنید؛ مثل low، high یا max. فهرست دقیق هر مدل در GET /v1/models و reasoning.supported_efforts آمده است. فقط مقادیر اعلام‌شدهٔ همان مدل پذیرفته می‌شوند؛ xhigh یا ultra را فقط وقتی بفرستید که در آن فهرست باشند. بدون این فیلد، رفتار خودکار حفظ می‌شود. پارامتر در Chat Completions، Responses و اجرای عامل گفتگویی قابل استفاده است. سطح نامعتبر یا دو مقدار متناقض با HTTP 400 و پیش از رزرو اعتبار رد می‌شود. سطح بالاتر می‌تواند زمان و مصرف توکن را بیشتر کند؛ سقف خروجی همچنان رعایت می‌شود.

نمایش اختیاری

در Responses و اجرای عامل گفتگویی، include_reasoning را true بفرستید. پیش‌فرض false است؛ در این حالت نه فیلد reasoning و نه رویداد استدلال در خروجی API نمایش داده می‌شود. این گزینه نمایش متن را کنترل می‌کند، نه انجام محاسبات مدل.

import json, os, urllib.request, urllib.error

payload = {
    "model": "z-ai/glm-5.3-flash",
    "input": "کدام گزینه منطقی‌تر است و چرا؟ خرید سالانه یا ماهانه برای یک آزمایش دوماهه؟",
    "include_reasoning": True,
    "max_output_tokens": 2048
}

request = urllib.request.Request(
    "https://api.sarovi.ir/v1/responses",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
        print(result)
except urllib.error.HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from error

سقف خروجی

در مسیر مستقیم مدل، max_output_tokens سقف انتخابی شماست؛ سقف ثابت ۴۰۰۰ وجود ندارد و مقدار تا ۳۲۷۶۸ در قرارداد API پذیرفته می‌شود، با رعایت محدودیت خود مدل. اگر مدل به سقف برسد، Responses پاسخ جزئی را با status="incomplete" و incomplete_details.reason="max_output_tokens" برمی‌گرداند؛ در SSE رویداد response.incomplete را هم مدیریت کنید. در Chat Completions مقدار finish_reason برابر length است. متن جزئی و usage را نگه دارید؛ مصرف انجام‌شده محاسبه می‌شود. برای پاسخ طولانی‌تر سقف مناسب‌تری بفرستید.

قرارداد خروجی

پاسخ نهایی همیشه در output_text می‌ماند. با درخواست استدلال، reasoning شامل status، text، format و source است. status برابر available یا unavailable است؛ source برابر provider است. format می‌تواند summary یا text باشد. متن ممکن است خلاصهٔ تولیدشده توسط ارائه‌دهنده باشد و لزوماً همهٔ پردازش داخلی مدل نیست. دادهٔ رمزگذاری‌شده و امضاهای داخلی ارائه‌دهنده بازگردانده نمی‌شوند.

استدلال زنده

برای دریافت تدریجی، stream:true را نیز بفرستید. رویداد response.reasoning.delta شامل delta، format و response_id است. آن را در بخشی جدا از response.output_text.delta جمع کنید. رویداد response.completed نسخهٔ کامل پاسخ و استدلال را برمی‌گرداند. رویداد response.tool فعالیت ابزار را نشان می‌دهد؛ آن را با استدلال یکی نکنید.

مدل‌های پشتیبانی‌نشده

برخی مدل‌ها و مسیرها هیچ متن قابل نمایشی برنمی‌گردانند. پاسخ موفق با reasoning.status="unavailable" و text خالی معتبر است. ساروی برای پرکردن این بخش متن ساختگی تولید نمی‌کند. تصویر، صوت، ویدیو و عامل‌های Work در این قرارداد استدلال متنی ندارند؛ برای Work رویدادها و وضعیت ابزارهای اجرای کار را دنبال کنید.

هزینه و حریم خصوصی

توکن‌های پردازش و استدلال طبق مصرف گزارش‌شدهٔ مدل در همان صورتحساب اعتبار محاسبه می‌شوند، حتی وقتی نمایش خاموش است. غیرفعال بودن نمایش به معنی کاهش هزینهٔ مدل نیست. در آزمایشگاه گزینهٔ «نمایش استدلال مدل» را انتخاب کنید و نتیجه را در بخش بازشدنی ببینید. ذخیرهٔ محتوای درخواست در گزارش‌ها همچنان تابع تنظیم log_content پروژه است.