رفتن به محتوا
میزان تلاش استدلال

میزان تلاش استدلال

جدید

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

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

message = response.choices[0].message
print("Reasoning:", getattr(message, "reasoning_content", None))
print("Answer:", message.content)
print("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens)

پاسخ متن استدلال را در reasoning_content، جواب را در content و توکن‌های استدلال را در usage دارد:

200 JSON
{
  "id": "chatcmpl-2a6c8e0b4d1f4a3c9e7b5d3f1a8c6e4b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

کدام مدل‌ها استدلال می‌کنند

مدل متن استدلال برمی‌گرداند فیلد میزان تلاش را اعمال می‌کند
shannon-1.6-lite — —
shannon-1.6-pro, shannon-2-lite, shannon-2-pro, shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro, shannon-coder-1 بله —
هر مدل open-weight میزبانی‌شده بله بله

این‌ها فلگ‌های capabilities.reasoning و capabilities.reasoning_effort هستند که GET /v1/models برای هر شناسه گزارش می‌کند. پاسخ فقط وقتی متن استدلال دارد که مدل مقداری تولید کرده باشد. مدل‌ها و قیمت‌ها

تنظیم میزان تلاش

هر endpoint شکل نوشتن خاص خودش را برای میزان تلاش دارد. همه آن‌ها یکی از همان چهار سطح را انتخاب می‌کنند.

فیلد نوع پیش‌فرض توضیحات اعمال‌شده توسط
reasoning_effort string high /v1/chat/completions. اینکه مدل پیش از پاسخ تا چه عمقی استدلال کند: off، low، medium یا high. مدل‌های open-weight میزبانی‌شده
reasoning object | string /v1/chat/completions. همان مقدار به شکل {"effort": "low"} یا یک رشته ساده. اگر هر دو فیلد فرستاده شوند، reasoning_effort ملاک است. مدل‌های open-weight میزبانی‌شده
reasoning.effort string high /v1/responses. به‌صورت شیء {"effort": "low"} نوشته می‌شود. مدل‌های open-weight میزبانی‌شده
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} یا {"type": "disabled"}. بودجه یکی از سطوح را انتخاب می‌کند؛ جدول پایین‌تر را ببینید. مدل‌های open-weight میزبانی‌شده
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
مقدار همچنین پذیرفته می‌شود اثر
off none, minimal بدون استدلال. پاسخ متن استدلال ندارد.
low استدلال مختصر.
medium default عمق متوسط.
high max عمیق‌ترین سطح. این سطح درخواستی است که هیچ مقداری نمی‌فرستد.
  • مقادیر بدون توجه به حروف بزرگ و کوچک خوانده می‌شوند.
  • مقدار default یعنی medium. نفرستادن فیلد یعنی high.
  • مدل‌های Shannon (shannon-*) عمق خود را در هر درخواست خودشان تعیین می‌کنند؛ GET /v1/models برای آن‌ها reasoning_effort: false گزارش می‌کند.

بودجه thinking روی /v1/messages

روی /v1/messages فیلد thinking سطح را انتخاب می‌کند. budget_tokens یکی از سطوح بالا را برمی‌گزیند؛ حد توکن مستقلی نیست. adaptive مانند enabled خوانده می‌شود.

آنچه می‌فرستید سطح
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} با n تا 2,048 low
n از 2,049 تا 8,192 medium
n بزرگ‌تر، یا enabled بدون budget_tokens high
بدون فیلد thinking high

متن استدلال کجا می‌رسد

متن استدلال همیشه از پاسخ جداست. هر فرمت جای خودش را برای آن دارد:

Endpoint بدون stream با stream
/v1/chat/completions choices[0].message.reasoning_content: یک رشته، یا وقتی مدل چیزی تولید نکرده null. chunkهایی با choices[0].delta.reasoning_content، پیش از chunkهای delta.content.
/v1/responses یک آیتم output به شکل {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} پیش از آیتم message. وقتی استدلالی نیست آیتمی وجود ندارد. response.output_item.added با یک آیتم reasoning، سپس رویدادهای response.reasoning_summary_text.delta و یک response.reasoning_summary_text.done.
/v1/messages اولین بلوک محتوا {"type": "thinking", "thinking": "…"} و سپس بلوک text. وقتی استدلالی نیست بلوک thinking وجود ندارد. یک بلوک محتوای thinking: content_block_start، رویدادهای content_block_delta با thinking_delta، content_block_stop. بلوک متن بعد از آن می‌آید.
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

کجا را نگاه کنید، برای هر مدل:

مدل‌ها متن کجا می‌رسد
مدل‌های open-weight میزبانی‌شده روی هر endpoint، با stream یا بدون آن. درخواست با میزان تلاش off یا با response_format / text.format بدون متن استدلال پاسخ داده می‌شود.
shannon-3، shannon-3-pro، shannon-3.1، shannon-3.1-pro روی هر endpoint، با stream یا بدون آن، هر زمان که مدل متن استدلال تولید کرده باشد.
shannon-2-lite، shannon-2-pro /v1/chat/completions، بدون stream: در message.reasoning_content. با stream، در درخواستی بدون tools یا response_format: stream تا وقتی مدل استدلال می‌کند خطوط توضیح : thinking را می‌آورد و سپس chunkهای پاسخ را. /v1/messages، با stream: یک بلوک thinking پیش از بلوک متن.
shannon-1.6-pro، shannon-coder-1 در پاسخ‌های stream و در پاسخ به درخواست‌هایی که tools دارند، هر زمان که مدل متن استدلال تولید کرده باشد.

روی /v1/responses، پاسخی که stream نمی‌شود برای خانواده Shannon 3 و مدل‌های open-weight میزبانی‌شده آیتم reasoning را دارد.

خواندن یک stream

در stream ابتدا متن استدلال، در deltaهای جداگانه، می‌آید و پاسخ بعد از آن. این دو را جدا چاپ یا ذخیره کنید:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

stream = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="medium",
    stream=True,
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)      # the reasoning text comes first
    if delta.content:
        print(delta.content, end="", flush=True)  # then the answer

اولین chunk مدل open-weight میزبانی‌شده، چه استدلال و چه پاسخ، delta.role: "assistant" را هم دارد. استریم

توکن‌های استدلال و صورت‌حساب

در مدل‌های open-weight میزبانی‌شده، توکن‌های استدلال توکن خروجی هستند: با قیمت خروجی مدل محاسبه می‌شوند و شمارش خروجی از قبل آن‌ها را در بر دارد. usage سهم استدلال را اینجا نشان می‌دهد:

Endpoint فیلد یادداشت
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens از قبل در completion_tokens گنجانده شده است.
/v1/responses usage.output_tokens_details.reasoning_tokens از قبل در output_tokens گنجانده شده است.
/v1/messages usage.output_tokens استدلال و پاسخ با هم. این فرمت شمارش جداگانه ندارد.
  • در مدل‌های open-weight میزبانی‌شده max_tokens متن پاسخ را محدود می‌کند. توکن‌های استدلال در آن شمرده نمی‌شوند.
  • چون استدلال به‌عنوان خروجی محاسبه می‌شود، میزان تلاش یک تنظیم هزینه هم هست: off هیچ توکن استدلالی تولید نمی‌کند.
  • مدل‌های Shannon prompt_tokens، completion_tokens و total_tokens (روی /v1/messages input_tokens و output_tokens) را بدون سهم استدلال گزارش می‌کنند و برای هر توکن یک قیمت ثابت محاسبه می‌کنند. مدل‌ها و قیمت‌ها

استدلال در درخواست بعدی

لازم نیست استدلال را پس بفرستید. بلوک thinking یا آیتم reasoning در گفتگویی که می‌فرستید به مدل منتقل نمی‌شود، پس نوبت assistant را می‌توان با آن یا بدون آن پس فرستاد. بلوک thinking دو فیلد type و thinking دارد؛ signature ندارد.

خطاها

وضعیت نوع پیام زمان
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high یک مدل open-weight میزبانی‌شده مقداری خارج از فهرست دریافت کرد، برای مثال xhigh. چیزی از موجودی شما کم نمی‌شود.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort رشته نیست.

خطاهای احراز هویت، موجودی و سرور مثل هر درخواست دیگر هستند. مدیریت خطا