コンテンツへスキップ
推論 effort

推論 effort

新規

推論するモデルは、回答と並べて、専用のフィールドに推論テキストを返します。ホスト型オープンウェイトモデルでは、ひとつのリクエストフィールドで、モデルが回答する前にどれだけ深く推論するかを指定します。

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}
  }
}

推論するモデル

モデル 推論テキストを返す 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 はい —
すべてのホスト型オープンウェイトモデル はい はい

これらは、GET /v1/models が各 ID について報告するフラグ capabilities.reasoning と capabilities.reasoning_effort です。応答に推論テキストが含まれるのは、モデルが生成した場合のみです。 モデルと料金

effort の設定

エンドポイントごとに、effort の書き方が異なります。どれも、同じ四つのレベルのうちのひとつを選びます。

フィールド 型 デフォルト 説明 適用モデル
reasoning_effort string high /v1/chat/completions。モデルが回答する前にどれだけ深く推論するか：off、low、medium、high。 ホスト型オープンウェイトモデル
reasoning object | string /v1/chat/completions。{"effort": "low"} または単独の文字列としての同じ値。両方のフィールドを送信した場合は reasoning_effort が優先されます。 ホスト型オープンウェイトモデル
reasoning.effort string high /v1/responses。オブジェクト {"effort": "low"} として記述します。 ホスト型オープンウェイトモデル
thinking object /v1/messages。{"type": "enabled", "budget_tokens": n} または {"type": "disabled"}。バジェットがレベルのひとつを選びます。下の表を参照してください。 ホスト型オープンウェイトモデル 
{
  "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 を報告します。

/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、または budget_tokens のない enabled high
thinking フィールドなし high

推論テキストの届く場所

推論テキストは、常に回答とは別です。形式ごとに、専用の場所があります。

エンドポイント ストリームなし ストリーム
/v1/chat/completions choices[0].message.reasoning_content：文字列。モデルが生成しなかった場合は null。 choices[0].delta.reasoning_content を持つチャンク。delta.content を持つチャンクより前に届きます。
/v1/responses message アイテムの前に、output アイテム {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]}。推論がない場合、アイテムはありません。 reasoning アイテムを持つ response.output_item.added、続いて response.reasoning_summary_text.delta イベントと、ひとつの response.reasoning_summary_text.done。
/v1/messages 最初のコンテンツブロック {"type": "thinking", "thinking": "…"} の後に text ブロック。推論がない場合、thinking ブロックはありません。 thinking コンテンツブロック：content_block_start、thinking_delta を持つ content_block_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}
  }
}

モデルごとの確認場所：

モデル テキストの届く場所
ホスト型オープンウェイトモデル ストリームの有無にかかわらず、すべてのエンドポイントで。effort が off のリクエスト、または response_format / text.format を指定したリクエストには、推論テキストなしで応答します。
shannon-3、shannon-3-pro、shannon-3.1、shannon-3.1-pro ストリームの有無にかかわらず、すべてのエンドポイントで、モデルが推論テキストを生成した場合。
shannon-2-lite、shannon-2-pro /v1/chat/completions のストリームなし：message.reasoning_content に。tools や response_format のないリクエストのストリーム：モデルが推論している間、ストリームにコメント行 : thinking が届き、その後に回答のチャンクが続きます。/v1/messages のストリーム：テキストブロックの前の thinking ブロック。
shannon-1.6-pro、shannon-coder-1 ストリーム応答、および tools を含むリクエストへの応答で、モデルが推論テキストを生成した場合。

/v1/responses では、ストリームでない応答に、Shannon 3 ファミリーとホスト型オープンウェイトモデルの reasoning アイテムが含まれます。

ストリームの読み取り

ストリームでは、推論テキストが専用のデルタで先に届き、回答がその後に続きます。二つを別々に出力または保存してください。

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

ホスト型オープンウェイトモデルの最初のチャンクには、推論でも回答でも、delta.role: "assistant" も含まれます。 ストリーミング

推論トークンと課金

ホスト型オープンウェイトモデルでは、推論トークンは出力トークンです。モデルの出力価格で課金され、出力数にはすでに含まれています。usage には、ここで推論の内訳が示されます。

エンドポイント フィールド 備考
/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 推論と回答の合計。この形式には、個別のカウントはありません。
  • ホスト型オープンウェイトモデルでは、max_tokens は回答テキストを制限します。推論トークンはこれに含まれません。
  • 推論は出力として課金されるため、effort のレベルはコストの設定でもあります。off では推論トークンは生成されません。
  • Shannon モデルは、推論の内訳なしで prompt_tokens、completion_tokens、total_tokens（/v1/messages では input_tokens と output_tokens）を報告し、トークンごとに単一の定額で課金します。 モデルと料金

次のリクエストでの推論

推論を送り返す必要はありません。送信する会話内の thinking ブロックや reasoning アイテムは、モデルには渡されないため、アシスタントのターンは、それを付けても付けなくても送り返せます。thinking ブロックには type と thinking の二つのフィールドがあり、signature はありません。

エラー

ステータス タイプ メッセージ 発生条件
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high ホスト型オープンウェイトモデルが、一覧にない値（たとえば xhigh）を受け取りました。残高からは何も引かれません。
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort が文字列ではありません。

認証、残高、サーバーのエラーは、すべてのリクエストと同じです。 エラー処理