Kimi K3 reasoning_effortの選び方｜Agent設定

Kimi K3 reasoning_effortは、短い指示ならlow、複数ファイルの編集や通常のツール呼び出しならhigh、長時間の計画や失敗コストの高い処理だけmaxを選ぶのが基本です。すべてのリクエストをmaxに固定せず、タスクごとに振り分けてください。

今週の進め方

• 今日：代表タスクを3種類に分け、各段階のログ項目を決めます。
• 今週前半：同じ入力でlow、high、maxを比較します。
• 今週後半：成功率、応答時間、再試行回数を見て、Agentごとの既定値を決めます。

最終更新：2026年8月2日。Kimi K3 Quickstart、Reasoning Effortの公式仕様、公式GitHubリポジトリを確認しています。

この記事は、Kimi K3 APIでAgentを開発している方、コード生成や研究ワークフローを運用するチーム、API料金と成功率を管理する技術責任者向けです。単純なチャット利用や、Kimi K3の一般的な接続手順だけを知りたい場合は対象外です。

最終回答の品質は、reasoning_contentの長さだけでは判断できません。ツールを最後まで呼べたか、生成物が検証を通ったか、手直しが何回必要だったかまで確認してください。

Kimi K3 reasoning_effortの違いを先に整理する

公式仕様で確認できるのは、Kimi K3が常時推論型であること、設定項目がトップレベルのreasoning_effortであること、許可値がlow、high、maxの3段階であることです。指定しない場合の既定値はmaxです。詳細はKimi K3の公式Quickstartと公式GitHubリポジトリで確認できます。

一方、各段階で「何倍速い」「何％正確」といった性能差は、公式仕様だけでは判断できません。実際の違いは、入力の長さ、ツール数、外部サービスの待ち時間、コンテキストの保持方法によって変わります。

Kimi K3 APIの設定を考えるときは、単発のToken数だけでなく、「1つの仕事を完了するまでに何回呼び出したか」を見ます。高い推論強度で一度に終わる場合もあれば、低い段階で失敗して再実行することで、結果的にTokenコストが増える場合もあります。

lowとhighを使い分ける：短い処理と通常のコードAgent

短い指示は、まずlowで検証する

補完、JSONやCSVの形式変換、既存文章の短い要約、1つの関数だけの小規模修正は、最初からmaxに固定する必要がありません。出力を機械的に検証できるなら、lowを入口にして、失敗したときだけhighへ上げます。

ここで重要なのは、回答が長いかどうかではなく、検証条件を満たしたかです。例えば、JSONの構文検査、型検査、単体テスト、必須キーの有無を自動判定します。

lowから始める条件

• 入力と出力の形式が明確です。
• 正解を機械的に判定できます。
• 失敗しても再実行の影響が小さいです。
• 外部ツールを呼ばない、または呼び出しが少数です。

この条件を満たさない場合は、highへ回します。Kimi K3の既定値はmaxですが、既定値を全リクエストへ適用することが、最も安い運用や最も速い運用を意味するわけではありません。

複数ファイルの編集はhighを起点にする

コードAgentがリポジトリを読み、複数のファイルを変更し、テストや検索ツールを数回呼ぶ場合は、highから始めるのが扱いやすいです。lowでは、変更対象の見落とし、ツール引数の不整合、修正後のテスト漏れが起きる可能性があります。ただし、これは一般的な性能保証ではなく、あなたのリポジトリで検証するための初期ルールです。

判定は次の3項目で行います。

1. 指定したファイル以外を不用意に変更していないか。
2. ツール呼び出しが途中で止まっていないか。
3. 人が修正し直した行数や回数が許容範囲か。

highで複数回連続して検証を通過し、手直しも少ないなら、そのタスク群はhighを維持します。テスト失敗やツール停止が続くなら、maxへ上げる前に、プロンプト、コンテキスト、ツールスキーマを確認してください。

どの場面でmaxへ上げるべきか

maxは、常に使う「高品質モード」ではなく、失敗の影響が大きい処理に割り当てる段階です。長期計画、複数回の調査、依存関係の多いコード変更、復旧手順を含む自動化などが該当します。

特に、次の条件が複数重なる場合はmaxを候補にします。

• 正解を1回のテストだけでは判定できません。
• 多段階のツール連鎖が発生します。
• 途中で前提条件を更新する必要があります。
• 失敗するとデータ処理や納期に大きな影響があります。
• 人が全工程を監視できません。

Kimi K3は多ターン会話とツール呼び出しで、APIが返したassistant message全体を次のmessagesへ戻す必要があります。contentだけでなく、reasoning_contentとtool_callsも保持することが公式に求められています。実装時は公式のKimi K3ツール呼び出し仕様を確認してください。

reasoning_contentを削って送る実装は、短く見えても安全とは限りません。後続ターンが前の判断を参照できず、同じ調査を繰り返したり、ツール呼び出しが不完全になったりする可能性があります。

リアルタイム処理とバッチ処理では、選ぶ基準が違います

ユーザーが画面の前で待つAgentでは、答えの品質だけでなく、最初の文字が出るまでの時間と全体の応答時間を測ります。lowで十分な回答が返る処理をmaxへ送ると、待ち時間が伸びる可能性があります。反対に、highやmaxで一度に完了できる処理をlowで何度も再実行すると、ユーザーの待ち時間もTokenコストも増えます。

ストリーミングを使うか、タイムアウトをどう設定するかも、段階と同じくらい重要です。長い出力を扱う場合は、公式のストリーミングとベンチマーク指針を確認し、各段階の実際のリクエスト経路で測定してください。速度は環境依存のため、一般的な数値をそのまま本番判断に使わないでください。

バッチ処理や定時実行のAgentでは、1回の応答時間より「成功した仕事1件あたりのコスト」を見ます。計算には次を含めます。

• 初回リクエストのToken使用量。
• 失敗後の再試行回数。
• ツール呼び出しを含む総リクエスト数。
• タイムアウト後の復旧処理。
• キャッシュが使えず再送したコンテキスト量。

Kimi API側では、同時実行数、RPM、TPM、TPDという複数の制限概念が案内されています。大量処理では、推論強度だけでなく、同時実行数を上げすぎないことも安定性に直結します。制限値は公式のレート制限資料で確認してください。

第一歩：3種類の代表タスクを固定する

まず、実際の本番処理から次の3種類を選びます。

• 短いコード修正または形式変換。
• 複数ファイルを変更する通常のコードAgent。
• 長時間の調査、計画、または多段階の自動化。

各タスクを同じ入力、同じツール、同じ検証条件でlow、high、maxに通します。モデルの更新、プロンプト変更、ツール定義変更が入った場合は、比較結果を別の実験として保存します。

第二歩：ログを「回答」ではなく「完了」で残す

最低限、次の項目を1リクエスト単位で記録します。

• reasoning_effortの値。
• 開始時刻、最初の出力時刻、完了時刻。
• 入力Tokenと出力Token。
• ツール呼び出し数と失敗数。
• HTTPエラー、タイムアウト、再試行回数。
• テスト結果と人による修正内容。

Kimi K3 APIの仕様確認には、Kimi K3のReasoning Effort公式資料と公式リポジトリを使います。既定値、パラメータ位置、多ターンメッセージの要件を変更前後で比較してください。

第三歩：条件分岐でAgentを自動ルーティングする

次のルールを初期版にできます。

• もし入力が短く、出力形式を自動検証でき、失敗時に再実行できるなら、lowを選びます。
• もし複数ファイルの編集、検索、テストなどの通常のツール連鎖があるなら、highを選びます。
• もし長期計画、多段階調査、復旧が難しい処理、監視なしの実行なら、maxを選びます。
• もしlowで形式検証に失敗したら、同じ入力をhighへ再送します。
• もしhighでツール完了またはテスト通過に失敗したら、maxへ上げる前にコンテキスト欠落とツール引数を確認します。
• もしユーザーが待機中で、処理を非同期へ移せるなら、段階を上げる前にバックグラウンド実行へ切り替えます。
• もし成功率が維持できても、成功1件あたりのTokenコストが上限を超えるなら、プロンプト短縮、キャッシュ、タスク分割を先に検討します。

自動切り替えには、必ず人による上書きと即時降格の入口を残します。管理者がmaxを指定した場合は自動ルーターより優先し、レート制限や待ち時間が閾値を超えた場合はlowまたはhighへ戻せるようにします。

第四歩：本番投入は小さく始める

いきなり全トラフィックをルーティングしないでください。まず少量の実リクエストで、次の順に確認します。

1. lowを短い検証可能タスクへ投入します。
2. highを通常のコードAgentへ投入します。
3. maxを失敗コストの高い処理へ限定します。
4. 各段階の成功率、総応答時間、Tokenコストを比較します。
5. 再試行とタイムアウトを含めた成功1件あたりのコストを計算します。
6. 失敗ログを確認してから、対象タスクを段階的に広げます。

Kimi K3 APIの費用を考えるときは、単価表だけでなく、再試行と人手の修正時間も含めてください。Kimi K3 APIのコスト見積もりを作る場合も、段階別の成功タスク数で比較すると、Tokenコストだけを見た判断を避けられます。

本番前に確認するチェックリスト

• [ ] すべてのリクエストをmaxへ固定していません。
• [ ] lowへ送る処理に自動検証があります。
• [ ] 複数ファイルの変更はhighから評価しています。
• [ ] maxの対象に失敗コストの根拠があります。
• [ ] 最初の出力時刻と完了時刻を分けて記録しています。
• [ ] reasoning_contentとtool_callsを次のターンへ保持しています。
• [ ] ストリーミング、タイムアウト、再試行を実装しています。
• [ ] 1回の呼び出しではなく、成功1件あたりのコストを見ています。
• [ ] 管理者によるmax指定と、緊急時の降格経路があります。
• [ ] 仕様変更時に公式資料を再確認する担当者がいます。

ローカルのMacだけで長時間Agentを動かすと、電源管理、スリープ、ネットワーク切断、開発環境の占有が別の負担になります。自宅のMacを常時稼働させる方法は初期費用を抑えやすい一方、外出中の復旧、複数人の同時利用、長時間バッチの監視が弱くなりがちです。

必要な期間だけHashvpsのMac環境を借りれば、隔離した開発環境で3種類の代表タスクを再実行し、ログを保存してから本番の既定値を決めやすくなります。まずは遠隔のMacでAIコーディング環境を動かす方法を確認し、短期の検証環境として使えるかを判断してください。

長期の固定負荷や物理ポートへの接続が必要なら、自前のMacが適しています。ただし、設定比較、チーム検証、一時的なAgent運用では、専用環境をレンタルしてから購入判断をする方が、条件を変えながら検証しやすくなります。