میزان تلاش استدلال
جدیدمدلی که استدلال میکند متن استدلالش را در کنار پاسخ، در فیلد جداگانهای، برمیگرداند. در مدلهای 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) import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const response = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "low",
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
const message = response.choices[0].message;
console.log("Reasoning:", message.reasoning_content);
console.log("Answer:", message.content);
console.log("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "low",
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' پاسخ متن استدلال را در reasoning_content، جواب را در content و توکنهای استدلال را در usage دارد:
{
"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?"}]
} {
"model": "Kimi-K3-3BIT-REAP",
"reasoning": {"effort": "low"},
"input": "Is 221 a prime number?"
} {
"model": "Kimi-K3-3BIT-REAP",
"max_tokens": 1024,
"thinking": {"type": "enabled", "budget_tokens": 2048},
"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}
}
} {
"output": [
{
"id": "rs_6f0a2c4e8b1d4f3a9c7e5b3d1f8a6c4e",
"type": "reasoning",
"summary": [
{
"type": "summary_text",
"text": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
}
]
},
{
"id": "msg_1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f1a",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "No. 221 = 13 x 17, so it is not prime.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 14,
"input_tokens_details": {"cached_tokens": 0},
"output_tokens": 43,
"output_tokens_details": {"reasoning_tokens": 27},
"total_tokens": 57
}
} {
"content": [
{
"type": "thinking",
"thinking": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
},
{"type": "text", "text": "No. 221 = 13 x 17, so it is not prime."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 14,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 43
}
} کجا را نگاه کنید، برای هر مدل:
| مدلها | متن کجا میرسد |
|---|---|
| مدلهای 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 import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const stream = await client.chat.completions.create({
model: "Kimi-K3-3BIT-REAP",
reasoning_effort: "medium",
stream: true,
messages: [{ role: "user", content: "Is 221 a prime number?" }],
});
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta ?? {};
if (delta.reasoning_content) process.stdout.write(delta.reasoning_content); // the reasoning text comes first
if (delta.content) process.stdout.write(delta.content); // then the answer
} curl -N https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Kimi-K3-3BIT-REAP",
"reasoning_effort": "medium",
"stream": true,
"messages": [
{"role": "user", "content": "Is 221 a prime number?"}
]
}' اولین 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/messagesinput_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 رشته نیست. |
خطاهای احراز هویت، موجودی و سرور مثل هر درخواست دیگر هستند. مدیریت خطا