مدل‌های استدلالی (Reasoning)

مدل‌های استدلالی قبل از نوشتن پاسخ، «فکر می‌کنند»: توکن‌هایی تولید می‌کنند که تو معمولاً نمی‌بینی ولی هزینه دارند و کیفیت پاسخ را در مسائل چندمرحله‌ای (ریاضی، کد، تحلیل سند) بالا می‌برند. openai/o3، openai/gpt-5، deepseek/deepseek-r1، anthropic/claude-sonnet-4.5 و google/gemini-2.5-pro نمونه‌های رایج‌اند. نشان reasoning در صفحهٔ مدل‌ها یا "reasoning" در supported_parameters مشخصشان می‌کند.

کنترل میزان استدلال

دو شکل پذیرفته می‌شود و هر دو عبور می‌کنند:

شکل OpenAI:

resp = client.chat.completions.create(
    model="openai/o3-mini",
    messages=[{"role": "user", "content": "این تابع بازگشتی چرا برای n=0 حلقهٔ بی‌نهایت می‌شود؟\n\n" + code}],
    reasoning_effort="low",   # low | medium | high
)

شکل عمومی (برای همهٔ providerها):

resp = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[...],
    extra_body={"reasoning": {"effort": "high"}},
)

بلوک reasoning گزینه‌های بیشتری دارد: max_tokens برای سقف مستقیم توکن‌های استدلال (Anthropic، Gemini)، exclude: true اگر متن استدلال را در پاسخ نمی‌خواهی، و enabled: false برای خاموش کردن روی مدل‌هایی که اجازه می‌دهند. providerهایی که فقط effort را می‌فهمند، max_tokens را تقریب می‌زنند.

برای کار روزمره low یا medium کافی است. high هزینه را چند برابر می‌کند و فقط برای مسائلی می‌ارزد که پاسخ اشتباه گران‌تر از توکن است.

خواندن استدلال در پاسخ

بلوک usage تعداد توکن‌های استدلال را جدا گزارش می‌کند:

"usage": {
  "prompt_tokens": 8,
  "completion_tokens": 24,
  "completion_tokens_details": {"reasoning_tokens": 50},
  "total_tokens": 32
}

بسته به provider، reasoning_tokens ممکن است داخل completion_tokens شمرده شود یا جدا باشد؛ برای هزینه به هدر X-Uttapen-Cost-Toman یا رویداد uttapen.meta تکیه کن نه به جمع دستی توکن‌ها. اگر provider متن استدلال را برمی‌گرداند (DeepSeek، Gemini، بعضی مدل‌های Anthropic)، آن را در message.reasoning می‌بینی. مدل‌های OpenAI خلاصه یا هیچ متنی نمی‌دهند.

msg = resp.choices[0].message
thinking = getattr(msg, "reasoning", None) or msg.model_extra.get("reasoning")
if thinking:
    print("[استدلال]", thinking[:300])
print(msg.content)

استریم

در استریم، متن استدلال قبل از content و در فیلد delta.reasoning می‌آید. برای نشان دادن «در حال فکر کردن» در UI مفید است:

stream = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[{"role": "user", "content": "۱۷ × ۲۳ را مرحله به مرحله حساب کن."}],
    stream=True,
    extra_body={"reasoning": {"effort": "medium"}},
)
phase = None
for chunk in stream:
    if not chunk.choices:
        continue
    d = chunk.choices[0].delta
    r = getattr(d, "reasoning", None) or (d.model_extra or {}).get("reasoning")
    if r:
        if phase != "reasoning":
            print("\n--- استدلال ---"); phase = "reasoning"
        print(r, end="", flush=True)
    if d.content:
        if phase != "answer":
            print("\n--- پاسخ ---"); phase = "answer"
        print(d.content, end="", flush=True)

استریم برای مدل‌های استدلالی توصیهٔ جدی است: فکر کردن طولانی ممکن است بیش از یک دقیقه طول بکشد و در حالت غیراستریم watchdog «۱۲۰ ثانیه بدون بایت» فعال می‌شود. با استریم، چانک‌های reasoning اتصال را زنده نگه می‌دارند.

رزرو و هزینه

توکن‌های استدلال با قیمت توکن خروجی همان مدل (یا قیمت جداگانهٔ استدلال اگر در صفحهٔ مدل آمده باشد) شارژ می‌شوند. شارژ نهایی از مصرفی است که خود provider برای همین درخواست گزارش می‌دهد، پس فرقی نمی‌کند توکن‌ها کجا شمرده شده باشند.

برای رزرو قبل از ارسال، وقتی درخواست reasoning یا reasoning_effort دارد، برآورد توکن خروجی سه برابر می‌شود. مثال: max_tokens: 2000 روی مدلی با قیمت خروجی ۶۰۰٬۰۰۰ تومان به‌ازای هر ۱M توکن، بدون استدلال حدود ۱٬۴۰۰ تومان و با استدلال حدود ۴٬۱۰۰ تومان رزرو می‌شود (با ضریب احتیاط). بعد از پاسخ، مبلغ واقعی تسویه و بقیه آزاد می‌شود. اگر 402 گرفتی در حالی که موجودی «به نظر» کافی بود، همین ضریب دلیلش است؛ max_tokens را واقعی‌تر بگذار.

انتخاب مدل

• سرعت و قیمت: openai/o3-mini، openai/gpt-5-mini با reasoning_effort: "low".
• کد و ریاضی سنگین: openai/o3، deepseek/deepseek-r1.
• استدلال همراه با ورودی بلند و سند: anthropic/claude-sonnet-4.5، google/gemini-2.5-pro.

برای بسیاری از کارها، مدل غیراستدلالی با prompt خوب (چند مثال و درخواست «قدم به قدم») ارزان‌تر و کافی است. اول با مدل معمولی تست کن و فقط اگر کیفیت نرسید به استدلال ارتقا بده.