Reasoning

複雑なタスクの推論量を設定し、結果、サマリー、Usageを正しく読み取ります。

Reasoningは、多段階の分析、複雑な制約、数学的導出、コード設計、ツール連携が必要なタスクに適しています。推論モデルでは通常、アプリケーションが推論量を制御でき、推論サマリー、Thinking Block、関連するUsageが返される場合があります。具体的な形式はモデルとプロトコルによって異なります。

単純な分類、形式変換、短い質問では、推論量を増やしても業務上の結果が改善するとは限らず、応答時間とToken使用量が増える場合があります。

推論機能はプロトコル間で統一された1つのフィールドではありません

Chat、Responses、Anthropic Messages、Geminiでは、推論設定、公開される結果、複数ターンの状態の表現が異なります。あるプロトコルのフィールドを別のプロトコルへ直接コピーしないでください。

使用する場面

タスク	推奨事項
複数制約の計画、複雑な分析	推論対応モデルを選び、低い設定またはデフォルトから評価を始める
数学、コード、論理問題	最終回答も検証し、推論量を結果の正しさと同一視しない
ツール呼び出しワークフロー	プロトコルが必要とする呼び出し、結果、状態構造を保持し、最大ループ回数を設定する
短い書き換え、抽出、分類	通常モデルまたは低い推論量を優先して試し、不要なコストを避ける

まずモデルマーケットプレイスで、現在のアカウントで利用できるモデル、プロトコル、機能タグを確認します。例のMODEL_IDは、現在のアカウントで対応する推論設定を利用できるモデルに置き換えてください。

Responsesで推論量を設定する

Responsesは推論設定をreasoningオブジェクトに配置します。

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "input": "2つのデータベース移行方式を比較し、選択理由を示してください。",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

effortは推論量を制御し、summaryはプロトコルが公開可能な推論サマリーを要求します。使用できる値と有効性はモデルによって異なります。完全な定義はResponses Referenceを参照してください。

プロトコルごとの推論表現

Chatではreasoning_effortによって推論量を要求できます。推論Tokenは、レスポンスで提供される場合、通常はUsageの完了詳細に記録されます。最終回答は引き続きAssistant Messageから読み取ります。

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "user", "content": "このデプロイ方式の主なリスクを分析してください。"}
  ],
  "reasoning_effort": "medium"
}

例の値はフィールド位置の説明用であり、すべてのモデルが同じ設定や予算を受け付けることを示すものではありません。Chat Completions、Anthropic Messages、Gemini Generate Contentの各Referenceを確認してください。

最終回答と公開推論情報を読み取る

アプリケーションでは通常、次の内容を分けて処理します。

最終回答：ユーザーに表示する、または後続処理へ渡す内容。
推論サマリーまたはThinking Block：プロトコルとモデルが明示的に返した場合にのみ読み取り、モデルの完全な内部思考と同一視しない。
Usage：入力、最終出力、推論Tokenを記録する。フィールド位置はプロトコルによって異なる。
停止または不完全状態：出力予算、コンテンツポリシー、キャンセル、エラーによって回答が未完了か判断する。

業務で最終結論だけが必要な場合、公開推論内容を永続化する必要はありません。保存前にプライバシー、ログ範囲、データ保持方針も評価してください。

Streamingとツール呼び出し

ストリーミングレスポンスでは、推論差分と最終テキスト差分が別々に返る場合があるため、独立したバッファーを使用します。
ツール呼び出しの前後にプロトコル状態やThinking Blockが含まれる場合があるため、最終テキストだけを保持しないでください。
ツール実行では、引き続きTool Callingのパラメータ検証、権限、冪等性要件に従います。
続行時は対象プロトコルが必要とする履歴構造だけを返送し、署名、呼び出しID、不透明な状態を独自に書き換えないでください。

完全なストリーミング処理はStreamingを参照してください。

出力予算を設計する

推論Tokenと可視回答が同じ出力予算を使用する場合があります。予算が小さすぎると、モデルが分析を終えても完全な最終回答を出す余地が不足する可能性があります。

本番アプリケーションでは、次の内容を併せて確認してください。

最終回答が完全か。
停止理由または不完全な理由。
推論と可視出力のUsage。
推論量ごとの品質、遅延、コスト。
ツールループが許可された回数と合計時間内に終了したか。

公開前の確認

現在のアカウントで対象モデルを利用でき、対応する推論インターフェースとリクエストフィールドを確認済みである。
アプリケーションは対象プロトコルが受け付ける推論フィールドだけを送信する。
最終回答、公開推論情報、Usageを分けて処理する。
Streaming、複数ターン、ツール呼び出しで必要なプロトコル状態を保持する。
出力予算不足、拒否、タイムアウト、不完全なレスポンスに明確な分岐がある。
推論強度、サマリー、公開Thinkingを正しさの保証として説明しない。

リクエスト失敗時はエラーとトラブルシューティングを、モデルまたはプロトコルの切り替え前はプロトコルの選択を参照してください。