דילוג לתוכן
רמת מאמץ ה-reasoning

רמת מאמץ ה-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)

התשובה נושאת את טקסט ה-reasoning ב-reasoning_content, את התשובה ב-content, ואת טוקני ה-reasoning ב-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}
  }
}

אילו מודלים מנמקים

מודל מחזיר טקסט 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?"}]
}
ערך מתקבל גם השפעה
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}
  }
}

איפה להסתכל, לפי מודל:

מודלים איפה הטקסט מגיע
מודלי 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

ה-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 אינו מחרוזת.

שגיאות אימות, יתרה ושרת זהות לאלה של כל בקשה. טיפול בשגיאות