拡張思考による構築

拡張思考は、Claude 3.7 Sonnetに複雑なタスクのための強化された推論能力を提供し、最終的な回答を提供する前の段階的な思考プロセスの透明性も確保します。

​

拡張思考の仕組み

拡張思考が有効になると、Claudeは内部の推論を出力するthinkingコンテンツブロックを作成します。Claudeは最終的な応答を作成する前に、この推論からの洞察を組み込みます。

APIレスポンスにはthinkingとtextの両方のコンテンツブロックが含まれます。

複数ターンの会話では、ツール使用セッションまたは最後のメッセージ位置にあるassistantターンに関連する思考ブロックのみがClaudeに表示され、入力トークンとして課金されます。以前のassistantメッセージに関連する思考ブロックはサンプリング中にClaudeには表示されず、入力トークンとして課金されません。

​

拡張思考の実装

APIリクエストにthinkingパラメータと、拡張思考に使用する指定されたトークン予算を追加します。

budget_tokensパラメータは、Claudeが内部推論プロセスに使用できる最大トークン数を決定します。より大きな予算を設定することで、複雑な問題に対してより徹底的な分析を可能にし、応答の品質を向上させることができます。ただし、32K以上の範囲では、Claudeが割り当てられた予算全体を使用しない場合があります。

budget_tokensは、常に指定されたmax_tokensより小さくなければなりません。

APIレスポンスには思考とテキストの両方のコンテンツブロックが含まれます：

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

​

思考ブロックについて

思考ブロックはClaudeの内部思考プロセスを表します。Claudeが最小限の内部制限で問題に取り組めるようにしながら、安全基準とステートレスAPIを維持するために、以下のように実装されています：

• 思考ブロックにはsignatureフィールドが含まれています。このフィールドには、思考ブロックがClaudeによって生成されたことを検証する暗号化トークンが含まれており、思考ブロックがAPIに戻されたときに検証されます。レスポンスをストリーミングする場合、署名はcontent_block_stopイベントの直前にcontent_block_deltaイベント内のsignature_deltaとして追加されます。拡張思考を使用したツール使用の場合にのみ、思考ブロックを送り返す必要があります。それ以外の場合は、以前のターンからの思考ブロックを省略するか、APIに送り返してもAPIが自動的に削除します。

• 時々、Claudeの内部推論が安全システムによってフラグが立てられることがあります。この場合、thinkingブロックの一部または全部が暗号化され、redacted_thinkingブロックとして返されます。これらの編集された思考ブロックはAPIに戻されたときに復号化され、Claudeはコンテキストを失うことなく応答を継続できます。

以下は、通常の思考ブロックと編集された思考ブロックの両方を示す例です：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpP..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

複数ターンの会話でthinkingおよびredacted_thinkingブロックをAPIに戻す場合、最後のアシスタントターンの完全な未変更ブロックを含める必要があります。

これはモデルの推論の流れを維持するために重要です。すべての思考ブロックを常にAPIに戻すことをお勧めします。詳細については、思考ブロックの保持セクションを参照してください。

​

本番環境での編集された思考の処理に関する提案

拡張思考を使用するカスタマー向けアプリケーションを構築する場合：

• 編集された思考ブロックには人間が読めない暗号化されたコンテンツが含まれていることを認識してください
• 「Claudeの内部推論の一部が安全上の理由で自動的に暗号化されています。これは応答の品質には影響しません。」のような簡単な説明を提供することを検討してください
• ユーザーに思考ブロックを表示する場合、編集されたブロックをフィルタリングしながら通常の思考ブロックを保持できます
• 拡張思考機能の使用により、推論の一部が暗号化される可能性があることを透明に伝えてください
• UIを壊さずに編集された思考を適切に処理するエラー処理を実装してください

​

拡張思考のストリーミング

ストリーミングが有効な場合、thinking_deltaイベントを通じて思考コンテンツを受信します。以下は、思考を含むストリーミングの処理方法です：

ストリーミング出力の例：

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// 追加の思考デルタ...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// 追加のテキストデルタ...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

event: message_start
data: {"type":"message_start","message":{"id":"msg_018J5iQyrGb5Xgy5CWx3iQFB","type":"message","role":"assistant","model":"claude-3-7-sonnet-20250219","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":92,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}       }

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"redacted_thinking","data":"EvEBCoYBGAIiQAqN5Z4LumxzafxD2yf2zW+hVm/G2/Am05ChRXkU1Xe2wQLPLo0wnmoaVJI1WTkLpRYJAIz2UjzHblLwkJ59xeAqQNr5EWqMZkOr8yNcpbCO5PssXiUvEjhoaC0IN3qyhE3vumOOS9Qd0Ku4AYTgu8VjP4C6IJHnkuIexa0VrU/cFbISDJjPWOWQlyAx4y5FCRoMk55jLUCR8KCZrKrzIjDR8S3F/pCWlz/JA5RN0uprpWAI75HjgcY2NJkPX3sEC0Ew6fl6YEISNk1XsmzWtj4qGArQlCfAW9l8SDiKbXm0UZ4hQhh2ruPbaw=="}  }

event: ping
data: {"type": "ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":0         }

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"redacted_thinking","data":"EvMBCoYBGAIiQKZ6LAz+dCNWxvz0dmjI0gfqEInA9MLVAtFJTpolzOaIbUs28xuKyXVzEQsPWPvP12gN+hxVJ4mYzWT8DCIAxXIqQHwQZcGASLMxWCfHrUlYfFq0vF8IGhRgQKxpj1zxouNLuKdhpZrcHF9vKODIPCPW8EWD13aI6t+exz/UboOs/ZMSDA8tVDp4vkOEUc7sGBoMbiRhGYMqcmAOhb3nIjC/lewBt2l9P+VpJkV78YQ3LhvNh/q3KfsbGuJ2U+lIMPGf9wnzrRC/6xqdsHPe1B0qGozBPKnbBifhyb7xYyWcEWoi/qW9OdoFl1/w"}            }

event: content_block_stop
data: {"type":"content_block_stop","index":1             }

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"redacted_thinking","data":"Eu8BCoYBGAIiQCXtUNB4QyT//Zww832Q+xjJ0oa7/PQZr74OvbS1+a7cRNywZfYMYGGte3RXXTMa6I0bFJOMmXXckcbLxR/L+msqQLhKGx9Bt2FnLpo7bp/PdMQBDDCo+jkbOctnxBQrHCuYbu33o30qPCh73AZ8O1xXXEZfzfLC0L6RoHzLxQSHN5gSDAxGSY7Ifg073BaUYBoMSWHLVrmZrydEfc7SIjAF1R+fYlyVPFwS4Sac/Dw9caskXNF/p+Yn7RNaW9+v/jL03qsqqvemuqRGltSBfZcqFrowQipxo/ftIkEC47Ua64RzSBIe27E="}   }

event: content_block_stop
data: {"type":"content_block_stop","index":2              }

event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"redacted_thinking","data":"Eu8BCoYBGAIiQEgE6WUvQO3d6fPpY3OaA95soqeWgZv/Nyi0X6iywTb5KqvUn9NxWySiZwSFZb+4S8ymtHRO4OBKA7eRWEXcBuQqQNudvV6YSFH5ErwaDME0HaEjtHcuy8SslL6RhLwhEJKGpYCzq7zWupcMBB1g57sR8vh/JwGjr7D9sfX9jmM7EsESDEatCbzVVczyZ0TERRoMenFOToj2qn0Xmh1LIjA1WgxaMqiHhb5T4k/++UCKNMH2SEseLzTlR7uIz20qZUXDWtoVck6wc+x7lSWRKXQqFiLoTO1oG0I/lbPz1n2FgC3MH7683FU="}     }

// 追加のイベント...

event: content_block_start
data: {"type":"content_block_start","index":58,"content_block":{"type":"redacted_thinking","data":"EuoBCoYBGAIiQJ/SxkPAgqxhKok29YrpJHRUJ0OT8ahCHKAwyhmRuUhtdmDX9+mn4gDzKNv3fVpQdB01zEPMzNY3QuTCd+1bdtEqQK6JuKHqdndbwpr81oVWb4wxd1GqF/7Jkw74IlQa27oobX+KuRkopr9Dllt/RDe7Se0sI1IkU7tJIAQCoP46OAwSDF51P09q67xhHlQ3ihoM2aOVlkghq/X0w8NlIjBMNvXYNbjhyrOcIg6kPFn2ed/KK7Cm5prYAtXCwkb4Wr5tUSoSHu9T5hKdJRbr6WsqEc7Lle7FULqMLZGkhqXyc3BA"}        }

event: content_block_stop
data: {"type":"content_block_stop","index":58            }

event: content_block_start
data: {"type":"content_block_start","index":59,"content_block":{"type":"text","text":""}              }

event: content_block_delta
data: {"type":"content_block_delta","index":59,"delta":{"type":"text_delta","text":"I'm"}        }

event: content_block_delta
data: {"type":"content_block_delta","index":59,"delta":{"type":"text_delta","text":" not"}     }

event: content_block_delta
data: {"type":"content_block_delta","index":59,"delta":{"type":"text_delta","text":" sure"}    }

// 追加のテキストデルタ...

event: content_block_delta
data: {"type":"content_block_delta","index":59,"delta":{"type":"text_delta","text":" me know what you'"}          }

event: content_block_delta
data: {"type":"content_block_delta","index":59,"delta":{"type":"text_delta","text":"d like assistance with."}   }

event: content_block_stop
data: {"type":"content_block_stop","index":59               }

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":184}  }

event: message_stop
data: {"type":"message_stop"          }

​

拡張思考を使用する際の重要な考慮事項

思考予算の扱い方： 最小予算は1,024トークンです。最小値から始めて、ユースケースに対してClaudeが良好なパフォーマンスを発揮する最適な範囲を見つけるために、思考予算を段階的に増やすことをお勧めします。より高いトークン数を設定することで、より包括的で微妙な推論を実現できる可能性がありますが、タスクによっては収穫逓減の可能性もあります。

• 思考予算は厳密な制限ではなく目標値です - 実際のトークン使用量はタスクに応じて異なる場合があります。
• 推論プロセスに必要な追加処理により、応答時間が長くなる可能性があることを考慮してください。
• max_tokensが21,333を超える場合、ストリーミングが必要です。

32Kを超える思考予算について： 思考予算を32K以上に設定するワークロードについては、ネットワークの問題を避けるためにバッチ処理を使用することをお勧めします。モデルに32Kトークンを超える思考を要求すると、システムのタイムアウトやオープン接続制限に抵触する可能性のある長時間実行リクエストが発生します。

他の機能との思考の互換性：

• 思考はtemperature、top_p、top_kの変更および強制ツール使用と互換性がありません。
• 思考が有効な場合、応答を事前に入力することはできません。
• 思考予算の変更により、メッセージを含むキャッシュされたプロンプトプレフィックスは無効になります。ただし、キャッシュされたシステムプロンプトとツール定義は、思考パラメータが変更されても引き続き機能します。

​

拡張思考の価格設定とトークン使用量

拡張思考トークンはコンテキストウィンドウにカウントされ、出力トークンとして課金されます。思考トークンは通常の出力トークンとして扱われるため、レート制限にもカウントされます。APIの使用を計画する際は、このトークン使用量の増加を考慮してください。

Claude 3.7 Sonnetの価格は以下の通りです：

拡張思考のバッチ処理はこれらの価格の50%オフで利用可能で、多くの場合1時間未満で完了します。

​

拡張出力機能（ベータ版）

Claude 3.7 Sonnetは、最大128K出力トークン（ベータ版）をサポートし、他のClaudeモデルの15倍以上の長さの応答を生成できます。この拡張機能は、複雑な推論、豊富なコード生成、包括的なコンテンツ作成を含む拡張思考のユースケースに特に効果的です。

この機能は、anthropic-betaヘッダーにoutput-128k-2025-02-19を渡すことで有効にできます。

より長い出力で拡張思考を使用する場合、より徹底的な推論をサポートするために大きな思考予算を割り当てながら、最終応答のために十分なトークンを確保できます。

この拡張出力機能では、ストリーミングまたはバッチモードの使用をお勧めします。詳細については、長時間のリクエストに関するネットワーク信頼性の考慮事項のガイダンスを参照してください。

​

プロンプトキャッシングと拡張思考の使用

思考を含むプロンプトキャッシングには、いくつかの重要な考慮事項があります：

キャッシュされたプロンプトへの思考ブロックの含め方

• 思考はアシスタントターンの生成時にのみ含まれ、キャッシュされることを意図していません。
• 以前のターンの思考ブロックは無視されます。
• 思考が無効になった場合、APIに渡された思考コンテンツは単に無視されます。

キャッシュ無効化のルール

• 思考パラメータの変更（有効化/無効化または予算の変更）により、メッセージで設定されたキャッシュブレークポイントは無効になります。
• システムプロンプトとツールは、思考パラメータが変更されてもキャッシュを維持します。

​

拡張思考を使用したプロンプトキャッシングの例

最初のリクエスト - キャッシュを確立
最初の応答の使用量：{ cache_creation_input_tokens: 1365, cache_read_input_tokens: 0, input_tokens: 44, output_tokens: 725 }

2番目のリクエスト - 同じ思考パラメータ（キャッシュヒットが予想される）
2番目の応答の使用量：{ cache_creation_input_tokens: 0, cache_read_input_tokens: 1365, input_tokens: 386, output_tokens: 765 }

3番目のリクエスト - 異なる思考予算（キャッシュヒットが予想される）
3番目の応答の使用量：{ cache_creation_input_tokens: 0, cache_read_input_tokens: 1365, input_tokens: 811, output_tokens: 542 }

最初のリクエスト - キャッシュを確立
最初の応答の使用量：{ cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

2番目のリクエスト - 同じ思考パラメータ（キャッシュヒットが予想される）

2番目の応答の使用量：{ cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

3番目のリクエスト - 異なる思考予算（キャッシュミスが予想される）
3番目の応答の使用量：{ cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

​

拡張思考を使用した最大トークンとコンテキストウィンドウサイズ

古いClaudeモデル（Claude 3.7 Sonnet以前）では、プロンプトトークンとmax_tokensの合計がモデルのコンテキストウィンドウを超えた場合、システムは自動的にmax_tokensを調整してコンテキスト制限内に収めていました。これは、大きなmax_tokens値を設定すると、システムが必要に応じて自動的に削減することを意味していました。

Claude 3.7 Sonnetでは、max_tokens（思考が有効な場合は思考予算を含む）は厳密な制限として適用されます。プロンプトトークン + max_tokensがコンテキストウィンドウサイズを超える場合、システムは検証エラーを返すようになりました。

​

拡張思考を使用したコンテキストウィンドウの計算方法

思考が有効な場合のコンテキストウィンドウの計算には、いくつかの考慮事項があります：

• 以前のターンからの思考ブロックは削除され、コンテキストウィンドウにはカウントされません
• 現在のターンの思考は、そのターンのmax_tokens制限にカウントされます

以下の図は、拡張思考が有効な場合の特殊なトークン管理を示しています：

有効なコンテキストウィンドウは以下のように計算されます：

コンテキストウィンドウ =
  (現在の入力トークン - 以前の思考トークン) +
  (思考トークン + 編集された思考トークン + テキスト出力トークン)

特に思考を含む複数ターンの会話を扱う場合は、トークンカウントAPIを使用して、特定のユースケースの正確なトークン数を取得することをお勧めします。

​

拡張思考を使用したトークンの管理

Claude 3.7 Sonnetのような拡張思考モデルでの新しいコンテキストウィンドウとmax_tokensの動作を考慮すると、以下が必要になる場合があります：

• トークン使用量をより積極的に監視および管理する
• プロンプトの長さが変更されたときにmax_tokensの値を調整する
• トークンカウントエンドポイントをより頻繁に使用する可能性がある
• 以前の思考ブロックがコンテキストウィンドウに蓄積されないことを認識する

この変更は、特に最大トークン制限が大幅に増加したことを考慮して、より予測可能で透明性のある動作を提供するために行われました。

​

ツール使用と拡張思考

ツール使用と拡張思考を組み合わせる場合、以下の動作パターンに注意してください：

1. 最初のアシスタントターン：最初のユーザーメッセージを送信すると、アシスタントの応答には思考ブロックとツール使用リクエストが含まれます。

2. ツール結果ターン：ツール結果ブロックを含むユーザーメッセージを渡すと、後続のアシスタントメッセージには追加の思考ブロックは含まれません。

ここで詳しく説明すると、思考を含むツール使用の会話の通常の順序は以下のステップに従います：

1. ユーザーが最初のメッセージを送信
2. アシスタントが思考ブロックとツールリクエストで応答
3. ユーザーがツール結果を含むメッセージを送信
4. アシスタントが追加のツール呼び出しまたはテキストのみで応答（この応答には思考ブロックは含まれない）
5. さらにツールが要求された場合、会話が完了するまでステップ3-4を繰り返す

この設計により、Claudeはツールリクエストを行う前に推論プロセスを表示できますが、ツール結果を受信した後は思考プロセスを繰り返しません。Claudeは、次の非tool_resultのuserターンの後まで、別の思考ブロックを出力しません。

以下の図は、拡張思考とツール使用を組み合わせた場合のコンテキストウィンドウトークン管理を示しています：

{
    "content": [
        {
            "type": "thinking",
            "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "I can help you get the current weather information for Paris. Let me check that for you"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

{
    "content": [
        {
            "type": "text",
            "text": "Currently in Paris, the temperature is 88°F (31°C)"
        }
    ]
}

​

思考ブロックの保持

ツール使用中は、thinkingおよびredacted_thinkingブロックをAPIに戻す必要があり、完全な未変更ブロックをAPIに含める必要があります。これはモデルの推論の流れと会話の整合性を維持するために重要です。

​

思考ブロックを保持する必要がある理由

Claudeがツールを呼び出すとき、外部情報を待つために応答の構築を一時停止します。ツール結果が返されると、Claudeはその既存の応答の構築を継続します。これにより、以下の理由でツール使用中に思考ブロックを保持する必要があります：

1. 推論の継続性：思考ブロックは、ツールリクエストにつながったClaudeの段階的な推論を捉えています。ツール結果を投稿するとき、元の思考を含めることで、Claudeは中断した場所から推論を継続できます。

2. コンテキストの維持：ツール結果はAPI構造ではユーザーメッセージとして表示されますが、これらは連続的な推論の流れの一部です。思考ブロックを保持することで、複数のAPI呼び出しにわたってこの概念的な流れを維持します。

重要：thinkingまたはredacted_thinkingブロックを提供する場合、連続するthinkingまたはredacted_thinkingブロックの全シーケンスは、元のリクエスト中にモデルが生成した出力と一致する必要があります。これらのブロックのシーケンスを並べ替えたり変更したりすることはできません。

​

拡張思考モードを最大限活用するためのヒント

拡張思考を最大限活用するために：

1. 適切な予算を設定する：複雑なタスクには大きな思考予算（16,000以上のトークン）から始めて、必要に応じて調整します。

2. 思考トークン予算を実験する：モデルは異なる最大思考予算設定で異なるパフォーマンスを示す可能性があります。最大思考予算を増やすと、レイテンシーが増加する代わりにモデルがより良く/より深く考えることができます。重要なタスクでは、品質とパフォーマンスの最適なバランスを見つけるために、異なる予算設定をテストすることを検討してください。

3. 以前の思考ブロックを自分で削除する必要はありません：Anthropic APIは以前のターンからの思考ブロックを自動的に無視し、コンテキスト使用量の計算に含めません。

4. トークン使用量を監視する：コストとパフォーマンスを最適化するために、思考トークンの使用量を追跡します。

5. 特に複雑なタスクに拡張思考を使用する：数学、コーディング、分析など、段階的な推論が有益なタスクに思考を有効にします。

6. 応答時間の延長を考慮する：思考ブロックの生成により全体の応答時間が増加する可能性があることを考慮します。

7. ストリーミングを適切に処理する：ストリーミング時は、思考とテキストの両方のコンテンツブロックを到着時に処理できるように準備します。

8. プロンプトエンジニアリング：Claudeの思考能力を最大限に活用したい場合は、拡張思考のプロンプトのヒントを確認してください。

​

次のステップ