רמת מאמץ ה-reasoning
חדשמודל שמנמק מחזיר את טקסט ה-reasoning שלו לצד התשובה, בשדה משלו. במודלי ה-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 ב-reasoning_content, את התשובה ב-content, ואת טוקני ה-reasoning ב-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}
}
} אילו מודלים מנמקים
| מודל | מחזיר טקסט reasoning | מיישם את שדה ה-effort |
|---|---|---|
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 מדווח לכל מזהה. תשובה נושאת טקסט reasoning רק כשהמודל הפיק כזה. מודלים ותמחור
קביעת ה-effort
לכל endpoint יש איות משלו ל-effort. כולם בוחרים אחת מאותן ארבע רמות.
| שדה | סוג | ברירת מחדל | תיאור | מופעל על ידי |
|---|---|---|---|---|
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 | בלי reasoning. התשובה אינה נושאת טקסט reasoning. |
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 |
איפה טקסט ה-reasoning מגיע
טקסט ה-reasoning תמיד נפרד מהתשובה. לכל פורמט יש מקום משלו עבורו:
| Endpoint | בלי streaming | עם streaming |
|---|---|---|
/v1/chat/completions | choices[0].message.reasoning_content: מחרוזת, או null כשהמודל לא הפיק. | Chunks עם choices[0].delta.reasoning_content, לפני ה-chunks עם delta.content. |
/v1/responses | פריט output בצורה {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} לפני פריט ה-message. אין פריט כשאין reasoning. | response.output_item.added עם פריט reasoning, ואחריו אירועי response.reasoning_summary_text.delta ו-response.reasoning_summary_text.done אחד. |
/v1/messages | בלוק תוכן ראשון {"type": "thinking", "thinking": "…"}, ואחריו בלוק ה-text. אין בלוק thinking כשאין reasoning. | בלוק תוכן 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, עם streaming או בלעדיו. בקשה עם effort off, או עם response_format / text.format, נענית בלי טקסט reasoning. |
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | בכל endpoint, עם streaming או בלעדיו, בכל פעם שהמודל הפיק טקסט reasoning. |
shannon-2-lite, shannon-2-pro | /v1/chat/completions, בלי streaming: ב-message.reasoning_content. עם streaming, בבקשה בלי tools או response_format: ה-stream נושא שורות הערה : thinking בזמן שהמודל מנמק, ואחר כך את chunks התשובה. /v1/messages, עם streaming: בלוק thinking לפני בלוק הטקסט. |
shannon-1.6-pro, shannon-coder-1 | בתשובות עם streaming ובתשובות לבקשות שנושאות tools, בכל פעם שהמודל הפיק טקסט reasoning. |
ב-/v1/responses, תשובה בלי streaming נושאת את הפריט reasoning עבור משפחת Shannon 3 ומודלי ה-open-weight המתארחים.
קריאת stream
ב-stream טקסט ה-reasoning בא ראשון, ב-deltas משלו, והתשובה אחריו. הדפיסו או שמרו את השניים בנפרד:
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 מתארח, reasoning או תשובה, נושא גם delta.role: "assistant". הזרמה
טוקני reasoning וחיוב
במודלי ה-open-weight המתארחים, טוקני reasoning הם טוקני פלט: הם מחויבים במחיר הפלט של המודל, וספירת הפלט כבר כוללת אותם. usage מראה כאן את חלק ה-reasoning:
| 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 | Reasoning ותשובה יחד. לפורמט הזה אין ספירה נפרדת. |
- במודלי ה-open-weight המתארחים
max_tokensמגביל את טקסט התשובה. טוקני reasoning אינם נספרים בו. - מכיוון ש-reasoning מחויב כפלט, רמת ה-effort היא גם הגדרת עלות:
offאינו מפיק טוקני reasoning. - מודלי Shannon מדווחים
prompt_tokens,completion_tokensו-total_tokens(input_tokensו-output_tokensב-/v1/messages) בלי חלק reasoning, ומחייבים מחיר אחיד אחד לטוקן. מודלים ותמחור
Reasoning בבקשה הבאה
אין צורך לשלוח reasoning בחזרה. בלוק 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 אינו מחרוזת. |
שגיאות אימות, יתרה ושרת זהות לאלה של כל בקשה. טיפול בשגיאות