サポートされているモデル
拡張思考は以下のモデルでサポートされています:- Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929) - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001) - Claude Opus 4.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514)
APIの動作はClaude Sonnet 3.7とClaude 4モデル間で異なりますが、APIの形状は完全に同じです。詳細については、モデルバージョン間での思考の違いを参照してください。
拡張思考の仕組み
拡張思考が有効になると、Claudeは内部推論を出力するthinkingコンテンツブロックを作成します。Claudeは最終的な回答を作成する前に、この推論からの洞察を組み込みます。
APIレスポンスにはthinkingコンテンツブロック、続いてtextコンテンツブロックが含まれます。
デフォルトのレスポンス形式の例は以下の通りです:
拡張思考の使用方法
Messages APIで拡張思考を使用する例は以下の通りです:thinkingオブジェクトを追加し、typeパラメータをenabledに設定し、budget_tokensを拡張思考用の指定されたトークン予算に設定します。
budget_tokensパラメータは、Claudeが内部推論プロセスに使用できるトークンの最大数を決定します。Claude 4モデルでは、この制限は完全な思考トークンに適用され、要約された出力には適用されません。より大きな予算により、複雑な問題に対してより徹底的な分析を可能にすることで、レスポンスの品質を向上させることができますが、特に32k以上の範囲では、Claudeが割り当てられた予算全体を使用しない場合があります。
budget_tokensはmax_tokens未満の値に設定する必要があります。ただし、インターリーブ思考とツールを使用する場合、トークン制限が全体のコンテキストウィンドウ(200kトークン)になるため、この制限を超えることができます。
要約された思考
拡張思考が有効になっている場合、Claude 4モデル用のMessages APIは、Claudeの完全な思考プロセスの要約を返します。要約された思考は、誤用を防ぎながら、拡張思考の完全な知能の利点を提供します。 要約された思考に関する重要な考慮事項は以下の通りです:- 元のリクエストによって生成された完全な思考トークンに対して課金され、要約トークンに対してではありません。
- 請求される出力トークン数は、レスポンスで表示されるトークン数と一致しません。
- 思考出力の最初の数行はより詳細で、プロンプトエンジニアリング目的に特に役立つ詳細な推論を提供します。
- Anthropicが拡張思考機能の改善を求める中で、要約動作は変更される可能性があります。
- 要約は、最小限の追加レイテンシでClaudeの思考プロセスの主要なアイデアを保持し、ストリーミング可能なユーザーエクスペリエンスとClaude Sonnet 3.7からClaude 4モデルへの簡単な移行を可能にします。
- 要約は、リクエストでターゲットとするモデルとは異なるモデルによって処理されます。思考モデルは要約された出力を見ません。
Claude Sonnet 3.7は完全な思考出力を返し続けます。Claude 4モデルの完全な思考出力へのアクセスが必要な稀なケースでは、営業チームにお問い合わせください。
思考のストリーミング
サーバー送信イベント(SSE)を使用して拡張思考レスポンスをストリーミングできます。 拡張思考でストリーミングが有効になっている場合、thinking_deltaイベントを介して思考コンテンツを受信します。
Messages APIを介したストリーミングの詳細なドキュメントについては、Streaming Messagesを参照してください。
思考でストリーミングを処理する方法は以下の通りです:
思考が有効になっているストリーミングを使用する場合、テキストが時々、より小さなトークンごとの配信と交互に、より大きなチャンクで到着することに気づくかもしれません。これは、特に思考コンテンツにとって期待される動作です。ストリーミングシステムは最適なパフォーマンスのためにコンテンツをバッチで処理する必要があり、これにより、ストリーミングイベント間で遅延が発生する可能性のある、この「チャンク状」の配信パターンが生じる可能性があります。私たちは継続的にこのエクスペリエンスの改善に取り組んでおり、将来のアップデートでは思考コンテンツがよりスムーズにストリーミングされることに焦点を当てています。
ツール使用での拡張思考
拡張思考はツール使用と併用でき、Claudeがツール選択と結果処理を通じて推論できるようになります。 拡張思考をツール使用と併用する場合、以下の制限事項に注意してください:-
ツール選択の制限: 思考を伴うツール使用は
tool_choice: {"type": "auto"}(デフォルト)またはtool_choice: {"type": "none"}のみをサポートします。tool_choice: {"type": "any"}またはtool_choice: {"type": "tool", "name": "..."}を使用すると、これらのオプションがツール使用を強制するため、拡張思考と互換性がないため、エラーが発生します。 -
思考ブロックの保持: ツール使用中は、最後のアシスタントメッセージのために
thinkingブロックをAPIに戻す必要があります。推論の継続性を維持するために、完全な未修正ブロックをAPIに含めてください。
例:ツール結果での思考ブロックの受け渡し
例:ツール結果での思考ブロックの受け渡し
ツール結果を提供する際に思考ブロックを保持する方法を示す実用的な例は以下の通りです:APIレスポンスには思考、テキスト、およびtool_useブロックが含まれます:次に会話を続けてツールを使用しましょうAPIレスポンスにはテキストのみが含まれるようになります
思考ブロックの保持
ツール使用中は、thinkingブロックをAPIに戻す必要があり、完全な未修正ブロックをAPIに含める必要があります。これは、モデルの推論フローと会話の整合性を維持するために重要です。
以前の
assistantロールターンからthinkingブロックを省略することはできますが、マルチターン会話では常にすべての思考ブロックをAPIに戻すことをお勧めします。APIは:- 提供された思考ブロックを自動的にフィルタリングします
- モデルの推論を保持するために必要な関連する思考ブロックを使用します
- Claudeに表示されるブロックの入力トークンのみを請求します
- 推論の継続性: 思考ブロックは、ツールリクエストにつながったClaudeの段階的推論をキャプチャします。ツール結果を投稿するとき、元の思考を含めることで、Claudeが中断したところから推論を続けることができます。
- コンテキストの維持: ツール結果はAPI構造ではユーザーメッセージとして表示されますが、継続的な推論フローの一部です。思考ブロックを保持することで、複数のAPI呼び出しにわたってこの概念的フローを維持します。コンテキスト管理の詳細については、コンテキストウィンドウに関するガイドを参照してください。
thinkingブロックを提供する場合、連続するthinkingブロックの全体のシーケンスは、元のリクエスト中にモデルによって生成された出力と一致する必要があります。これらのブロックのシーケンスを再配置または変更することはできません。
インターリーブ思考
Claude 4モデルでのツール使用を伴う拡張思考は、インターリーブ思考をサポートしており、Claudeがツール呼び出し間で思考し、ツール結果を受信した後により洗練された推論を行うことができます。 インターリーブ思考により、Claudeは以下のことができます:- 次に何をするかを決定する前に、ツール呼び出しの結果について推論する
- 間に推論ステップを挟んで複数のツール呼び出しを連鎖させる
- 中間結果に基づいてより微妙な決定を行う
interleaved-thinking-2025-05-14を追加します。
インターリーブ思考に関する重要な考慮事項は以下の通りです:
- インターリーブ思考では、
budget_tokensは1つのアシスタントターン内のすべての思考ブロック全体の総予算を表すため、max_tokensパラメータを超えることができます。 - インターリーブ思考はMessages APIを介して使用されるツールでのみサポートされています。
- インターリーブ思考は、ベータヘッダー
interleaved-thinking-2025-05-14を使用してClaude 4モデルでのみサポートされています。 - Claude APIへの直接呼び出しでは、任意のモデルへのリクエストで
interleaved-thinking-2025-05-14を渡すことができ、効果はありません。 - サードパーティプラットフォーム(例:Amazon BedrockおよびVertex AI)では、Claude Opus 4.1、Opus 4、またはSonnet 4以外のモデルに
interleaved-thinking-2025-05-14を渡すと、リクエストが失敗します。
インターリーブ思考なしのツール使用
インターリーブ思考なしのツール使用
- Claudeはタスクを理解するために最初に一度思考します
- すべてのツール使用決定を事前に行います
- ツール結果が返されると、Claudeは追加の思考なしに即座にレスポンスを提供します
インターリーブ思考を伴うツール使用
インターリーブ思考を伴うツール使用
- Claudeは最初にタスクについて思考します
- 計算機の結果を受信した後、Claudeはその結果が何を意味するかについて再び思考できます
- Claudeは最初の結果に基づいてデータベースをクエリする方法を決定します
- データベースの結果を受信した後、Claudeは最終的なレスポンスを策定する前に両方の結果についてもう一度思考します
- 思考予算はターン内のすべての思考ブロックに分散されます
プロンプトキャッシュを伴う拡張思考
思考を伴うプロンプトキャッシュにはいくつかの重要な考慮事項があります:拡張思考タスクは完了するのに5分以上かかることがよくあります。より長い思考セッションとマルチステップワークフローにわたってキャッシュヒットを維持するために、1時間のキャッシュ期間の使用を検討してください。
- 以前のターンからの思考ブロックはコンテキストから削除され、キャッシュブレークポイントに影響を与える可能性があります
- ツール使用で会話を続ける場合、思考ブロックはキャッシュされ、キャッシュから読み取られる際に入力トークンとしてカウントされます
- これによりトレードオフが生じます:思考ブロックは視覚的にはコンテキストウィンドウスペースを消費しませんが、キャッシュされた場合は入力トークン使用量にカウントされます
- 思考が無効になった場合、現在のツール使用ターンで思考コンテンツを渡すとリクエストが失敗します。他のコンテキストでは、APIに渡された思考コンテンツは単に無視されます
- 思考パラメータの変更(有効/無効または予算割り当て)により、メッセージキャッシュブレークポイントが無効になります
- インターリーブ思考は、複数のツール呼び出し間で思考ブロックが発生する可能性があるため、キャッシュ無効化を増幅します
- システムプロンプトとツールは、思考パラメータの変更やブロック削除にもかかわらずキャッシュされたままです
思考ブロックキャッシュ動作の理解
拡張思考をツール使用と併用する場合、思考ブロックはトークンカウントに影響する特定のキャッシュ動作を示します: 仕組み:- キャッシュは、ツール結果を含む後続のリクエストを行う場合にのみ発生します
- 後続のリクエストが行われると、以前の会話履歴(思考ブロックを含む)をキャッシュできます
- これらのキャッシュされた思考ブロックは、キャッシュから読み取られる際に使用量メトリクスで入力トークンとしてカウントされます
- ツール結果以外のユーザーブロックが含まれる場合、以前のすべての思考ブロックは無視され、コンテキストから削除されます
- このキャッシュ動作は、明示的な
cache_controlマーカーなしでも自動的に発生します - この動作は、通常の思考またはインターリーブ思考を使用するかどうかに関係なく一貫しています
システムプロンプトキャッシュ(思考変更時に保持される)
システムプロンプトキャッシュ(思考変更時に保持される)
メッセージキャッシュ(思考変更時に無効化される)
メッセージキャッシュ(思考変更時に無効化される)
cache_creation_input_tokens=1370とcache_read_input_tokens=0でキャッシュヒットがないことを示し、思考パラメータが変更されるとメッセージベースのキャッシュが無効になることを証明しています。拡張思考でのmax tokensとコンテキストウィンドウサイズ
古いClaudeモデル(Claude Sonnet 3.7以前)では、プロンプトトークンとmax_tokensの合計がモデルのコンテキストウィンドウを超えた場合、システムは自動的にmax_tokensをコンテキスト制限内に収まるように調整していました。これは、大きなmax_tokens値を設定でき、システムが必要に応じてそれを静かに削減することを意味していました。
Claude 3.7および4モデルでは、max_tokens(思考が有効な場合は思考予算を含む)は厳格な制限として強制されます。プロンプトトークン + max_tokensがコンテキストウィンドウサイズを超える場合、システムは検証エラーを返すようになりました。
より徹底的な詳細については、コンテキストウィンドウに関するガイドをお読みください。
拡張思考でのコンテキストウィンドウ
拡張思考が有効な場合のコンテキストウィンドウ使用量を計算する際に、注意すべき考慮事項があります:- 以前のターンからの思考ブロックは削除され、コンテキストウィンドウにカウントされません
- 現在のターンの思考は、そのターンの
max_tokens制限にカウントされます
ツール使用を伴う拡張思考でのコンテキストウィンドウ
拡張思考をツール使用と併用する場合、思考ブロックは明示的に保持され、ツール結果と一緒に返される必要があります。 ツール使用を伴う拡張思考の有効なコンテキストウィンドウ計算は以下のようになります:拡張思考でのトークン管理
拡張思考Claude 3.7および4モデルでのコンテキストウィンドウとmax_tokensの動作を考慮すると、以下が必要になる場合があります:
- トークン使用量をより積極的に監視および管理する
- プロンプト長が変化するにつれて
max_tokens値を調整する - トークンカウントエンドポイントをより頻繁に使用する可能性
- 以前の思考ブロックがコンテキストウィンドウに蓄積されないことを認識する
思考の暗号化
完全な思考コンテンツは暗号化され、signatureフィールドで返されます。このフィールドは、APIに戻される際に思考ブロックがClaudeによって生成されたことを検証するために使用されます。
拡張思考でツールを使用する場合にのみ、思考ブロックを戻すことが厳密に必要です。それ以外の場合は、以前のターンから思考ブロックを省略するか、戻す場合はAPIに削除させることができます。思考ブロックを戻す場合は、一貫性を保ち、潜在的な問題を回避するために、受け取ったものをすべて戻すことをお勧めします。
- レスポンスをストリーミングする場合、署名は
content_block_stopイベントの直前にcontent_block_delta内のsignature_deltaを介して追加されます。 signature値は、以前のモデルよりもClaude 4モデルで大幅に長くなります。signatureフィールドは不透明なフィールドであり、解釈や解析すべきではありません。検証目的のためだけに存在します。signature値はプラットフォーム間(Claude API、Amazon Bedrock、およびVertex AI)で互換性があります。1つのプラットフォームで生成された値は別のプラットフォームと互換性があります。
思考の編集
時々、Claudeの内部推論が安全システムによってフラグが立てられることがあります。これが発生すると、thinkingブロックの一部またはすべてを暗号化し、redacted_thinkingブロックとして返します。redacted_thinkingブロックは、APIに戻される際に復号化され、Claudeがコンテキストを失うことなくレスポンスを続けることができます。
拡張思考を使用する顧客向けアプリケーションを構築する場合:
- 編集された思考ブロックには、人間が読めない暗号化されたコンテンツが含まれていることを認識してください
- 「Claudeの内部推論の一部が安全上の理由で自動的に暗号化されました。これはレスポンスの品質には影響しません。」のような簡単な説明を提供することを検討してください
- 思考ブロックをユーザーに表示する場合、通常の思考ブロックを保持しながら編集されたブロックをフィルタリングできます
- 拡張思考機能を使用すると、時々一部の推論が暗号化される可能性があることを透明にしてください
- UIを壊すことなく編集された思考を適切に管理するための適切なエラーハンドリングを実装してください
出力で編集された思考ブロックを見ることは期待される動作です。モデルは安全ガードレールを維持しながら、この編集された推論を使用してレスポンスを知らせることができます。アプリケーションで編集された思考処理をテストする必要がある場合は、プロンプトとしてこの特別なテスト文字列を使用できます:
ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CBthinkingおよびredacted_thinkingブロックを戻す場合、最後のアシスタントターンのために完全な未修正ブロックをAPIに含める必要があります。これは、モデルの推論フローを維持するために重要です。すべての思考ブロックを常にAPIに戻すことをお勧めします。詳細については、上記の思考ブロックの保持セクションを参照してください。
例:編集された思考ブロックの操作
例:編集された思考ブロックの操作
この例は、Claudeの内部推論が安全システムによってフラグが立てられたコンテンツを含む場合にレスポンスに表示される可能性のある
redacted_thinkingブロックの処理方法を示しています:モデルバージョン間での思考の違い
Messages APIは、主に編集と要約動作において、Claude Sonnet 3.7とClaude 4モデル間で思考を異なって処理します。 簡潔な比較については、以下の表を参照してください:| 機能 | Claude Sonnet 3.7 | Claude 4モデル |
|---|---|---|
| 思考出力 | 完全な思考出力を返す | 要約された思考を返す |
| インターリーブ思考 | サポートされていない | interleaved-thinking-2025-05-14ベータヘッダーでサポート |
価格設定
拡張思考は標準のトークン価格設定スキームを使用します:| モデル | ベース入力トークン | キャッシュ書き込み | キャッシュヒット | 出力トークン |
|---|---|---|---|---|
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
- 思考中に使用されるトークン(出力トークン)
- 後続のリクエストに含まれる最後のアシスタントターンからの思考ブロック(入力トークン)
- 標準のテキスト出力トークン
拡張思考が有効な場合、この機能をサポートするために特殊なシステムプロンプトが自動的に含まれます。
- 入力トークン: 元のリクエストのトークン(以前のターンからの思考トークンを除く)
- 出力トークン(請求): Claudeが内部的に生成した元の思考トークン
- 出力トークン(表示): レスポンスで表示される要約された思考トークン
- 料金なし: 要約の生成に使用されるトークン
請求される出力トークン数は、レスポンスで表示されるトークン数と一致しません。表示される要約ではなく、完全な思考プロセスに対して請求されます。
拡張思考のベストプラクティスと考慮事項
思考予算の操作
- 予算の最適化: 最小予算は1,024トークンです。最小値から開始し、使用ケースに最適な範囲を見つけるために思考予算を段階的に増やすことをお勧めします。より高いトークン数により、タスクに応じて収穫逓減のトレードオフでより包括的な推論が可能になります。予算を増やすことで、レイテンシの増加のトレードオフでレスポンスの品質を向上させることができます。重要なタスクでは、最適なバランスを見つけるために異なる設定をテストしてください。思考予算は厳格な制限ではなく目標であることに注意してください。実際のトークン使用量はタスクに基づいて変動する場合があります。
- 開始点: 複雑なタスクには大きな思考予算(16k+トークン)から開始し、ニーズに基づいて調整してください。
- 大きな予算: 32kを超える思考予算については、ネットワークの問題を回避するためにバッチ処理の使用をお勧めします。32kトークンを超えて思考するようにモデルをプッシュするリクエストは、システムタイムアウトと開いている接続制限に対して実行される可能性のある長時間実行リクエストを引き起こします。
- トークン使用量の追跡: コストとパフォーマンスを最適化するために思考トークンの使用量を監視してください。
パフォーマンスの考慮事項
- レスポンス時間: 推論プロセスに必要な追加処理のため、レスポンス時間が長くなる可能性があることを準備してください。思考ブロックの生成により全体のレスポンス時間が増加する可能性があることを考慮してください。
- ストリーミング要件:
max_tokensが21,333を超える場合、ストリーミングが必要です。ストリーミング時は、到着する思考とテキストコンテンツブロックの両方を処理する準備をしてください。
機能の互換性
- 思考は
temperatureやtop_kの変更、および強制ツール使用と互換性がありません。 - 思考が有効な場合、
top_pを1から0.95の間の値に設定できます。 - 思考が有効な場合、レスポンスを事前入力することはできません。
- 思考予算の変更により、メッセージを含むキャッシュされたプロンプトプレフィックスが無効になります。ただし、キャッシュされたシステムプロンプトとツール定義は、思考パラメータが変更されても引き続き機能します。
使用ガイドライン
- タスクの選択: 数学、コーディング、分析など、段階的推論の恩恵を受ける特に複雑なタスクに拡張思考を使用してください。
- コンテキストの処理: 以前の思考ブロックを自分で削除する必要はありません。Claude APIは以前のターンからの思考ブロックを自動的に無視し、コンテキスト使用量を計算する際に含まれません。
- プロンプトエンジニアリング: Claudeの思考能力を最大化したい場合は、拡張思考プロンプティングのヒントをご確認ください。