Kimi K3 vLLMエラー再現の最小手順

公式recipeは2026年8月6日更新時点で、Kimi K3用イメージをCUDA 13（cu130）専用とし、NVIDIAホストにはr580以上のドライバーを求めています。公式Kimi K3 recipe

この条件を満たさないまま、ドライバー、イメージ、並列数、推論パラメーターを同時に変更してはいけません。今週は、まず失敗状態を凍結し、「互換性確認→最小起動→単一リクエスト→機能を1つずつ追加」の順でKimi K3 vLLMエラー再現を行うのが最も安全です。公式の互換基線でも同じエラーを安定して再現できない場合は、既存クラスターを触り続けるのではなく、隔離した検証環境へ移します。

この手順を使うべき担当者

対象は、Kimi K3の起動後にCUDA、OOM、通信、キャッシュのエラーが次々に入れ替わっているインフラエンジニアです。Agent基盤チームへ再現条件を渡したい場合や、既存クラスターを止めて調査するか、別の算力環境を借りるか判断したい場合にも使えます。

反対に、まだ一度も起動を試していない場合は、先に公式recipeのイメージ、ドライバー、GPU構成を確認してください。最小再現の目的は、すぐにサービスを成功させることではなく、同じ条件で同じ失敗地点を再現することです。

最初に失敗現場を凍結する

「起動するたびに別のエラーが出る」状態では、変更履歴が診断情報になります。最初に以下を読み取り専用の記録として保存します。

• ホストOSとカーネルのバージョン
• nvidia-smi の出力
• コンテナイメージの完全なタグ
• vLLM、PyTorch、CUDAランタイムのバージョン
• GPUの見え方を確認する CUDA_VISIBLE_DEVICES
• 完全な起動コマンド
• 最初に出た異常スタック
• 使用したリクエスト本文
• 変更した時刻と変更内容

この段階では、ドライバー更新、別イメージへの変更、max-model-len の縮小、並列数の変更を同時に行いません。例えばCUDA初期化に失敗しているのに、先にGPUメモリー使用率を下げても、OOMの調査には進めません。

注意：OOMが出ても、それが根因とは限りません。CUDA初期化や通信初期化の失敗後に、残ったプロセスや不完全な割り当てが二次的なメモリーエラーを出している可能性があります。最初に発生した異常の位置を優先してください。

第一段階：公式互換基線と実環境を照合する

公式recipeでは、Kimi K3用DockerイメージはCUDA 13、つまりcu130ビルドのみと記載されています。cu129タグは提供されておらず、NVIDIAホストにはr580以上のドライバーが必要です。公式の前提条件

また、同じページではNVIDIA構成として最低8基のGB300が示されています。これは手元の環境で必ず再現できるという意味ではなく、公式recipeが想定するハードウェア境界です。コミュニティで語られる必要メモリー量や非公式イメージの互換性は、一般的な事実として扱わないようにします。

確認はパッケージ一覧ではなく、実際にロードされたランタイムで行います。

nvidia-smi
docker image inspect vllm/vllm-openai:kimi-k3
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi

ホスト側のnvidia-smiだけが新しく、コンテナ内で別のランタイムやライブラリーが読み込まれている場合、アップグレード後も旧環境を混用している状態になります。比較表のように、記録の対象を分けておくと見落としを減らせます。

vLLMのトラブルシューティングでは、PTXツールチェーン非互換や古いドライバーがCUDAエラーの原因として整理されています。公式トラブルシューティング

第二段階：最小起動で最初の失敗地点を固定する

次に、Agentツール、監視サイドカー、負荷試験スクリプト、構造化出力、投機的デコード、通信最適化などを外します。残すのは、モデル、GPU並列数、信頼設定、重み読み込みに必要な指定だけです。

公式ブログのQuick startでは、--tensor-parallel-size 8、--trust-remote-code、--load-format fastsafetensors などを使い、--enable-prefix-caching も明示しています。vLLM公式ブログの起動例

ただし、最小再現の最初から本番用オプションをすべて戻す必要はありません。ログは次の時間順に分類します。

1. コンテナ初期化
2. GPUデバイス認識
3. 重みの読み込み
4. エンジン初期化
5. APIの待受開始
6. リクエスト処理

CUDAやドライバーの段階で止まった場合、OOMやprefix cachingの確認へ進まないことが重要です。CUDAGraph付近で落ちる場合、公式資料は--enforce-eagerで最終的なCUDA操作を切り分ける方法を案内しています。CUDAGraph周辺の切り分け

第三段階：単一リクエストを固定する

サービスが起動したら、同じ入力、同じ出力上限、同じAPI形式で1件だけ送ります。長い会話履歴、画像、ツール定義、ランダムな負荷生成は後回しにします。

記録する項目は、入力トークン数、max_tokens、HTTP応答、終了理由、GPUメモリー使用量、ログの警告です。まず単一リクエストが複数回安定して通ることを確認し、その後に入力長、並列数、ツール呼び出しを1つずつ追加します。

オンライン推論では、スケジューリングによって結果が変わる場合があります。vLLMの再現性資料も、同じハードウェアと同じvLLMバージョンが必要であり、オンライン環境では完全な再現を保証しないと説明しています。公式の再現性資料

そのため、文章の完全一致ではなく、次のような運用上の再現を基準にします。

• 起動が成功するか
• APIが応答するか
• 同じ入力で同じ種類の異常が出るか
• メモリー割り当て失敗が発生するか
• 通信初期化が完了するか

第四段階：prefix caching、文脈長、並列数を1項目ずつ戻す

Kimi K3のprefix cachingは、最小再現から完全に外すのではなく、サービスが単一リクエストで安定した後に明示的に追加します。公式ブログの起動例でも--enable-prefix-cachingが明示されています。prefix cachingを含む公式起動例

最初は同じ長い接頭辞を含むリクエストを2回送り、キャッシュが有効になったかをログやメトリクスで確認します。キャッシュが効かない場合は、入力の違い、保持ポリシー、バージョン差を調べます。そこでOOMが出たからといって、すぐに並列数やGPUメモリー設定を変えません。

推奨する追加順序は次の通りです。

• --enable-prefix-caching
• 固定した長い入力
• max-model-len
• 同時実行数
• ノード間通信
• Agentツールと構造化出力

各段階で、成功、キャッシュヒット、OOM、通信異常のうち、観察対象を1つに限定します。

経験上、エラーの種類が変わった場合は「改善した」と判断せず、直前の安定基線へ戻します。新しいエラーが出た地点を、次の再現候補として保存する方が、複数の変更を積み上げるより調査費用を抑えられます。

変更を続けるか、隔離環境へ移すかを判定する

次のチェックリストをすべて埋められる状態なら、修正作業へ進めます。

• [ ] ホストドライバーの実表示を保存した
• [ ] コンテナ内のGPU認識結果を保存した
• [ ] イメージタグとvLLMバージョンを固定した
• [ ] 最小起動コマンドを1行で再実行できる
• [ ] 最初の異常スタックを保存した
• [ ] 単一リクエストの入力と出力上限を固定した
• [ ] prefix cachingを単独で追加した
• [ ] OOMが前序のCUDA異常ではないと確認した
• [ ] 変更ごとに直前の基線へ戻せる
• [ ] 同じ失敗を複数回確認した

逆に、共有クラスターの別ジョブでGPU状態が変わる、ドライバーを固定できない、イメージをロールバックできない、同じコマンドでも毎回異なる初期化段階で落ちる、といった場合は、原環境での調査を打ち切ります。

その時点で必要なのは、環境指紋、最小起動コマンド、固定リクエスト、最初のエラー、各変更の前後ログです。これを隔離ノードへ持ち込み、同じ失敗が再現するかを確認します。公式基線でも再現しないなら、上流へ報告する前に環境差を疑います。

今週の判断：既存クラスターを直すか、Mac環境を併用するか

Kimi K3の公式NVIDIA構成は、CUDA 13専用イメージ、r580以上のドライバー、複数GPU構成を前提にしています。公式recipeの互換境界 そのため、現在の環境でドライバーを固定できず、他ジョブの影響を受け、再現のたびに待ち時間とログ整理の費用が増えるなら、修正を続けること自体がコストになります。

JexMacのMac環境は、Kimi K3の公式CUDA実行環境を置き換えるものではありません。GPUドライバーやCUDA初期化とは別系統の検証、APIクライアント、Agent連携、ログ収集、前処理の確認を、既存クラスターから切り離して進めたい場合の補助環境として検討できます。まずはJexMacの環境一覧を確認し、必要な期間だけ料金と利用条件を比較してください。

長期にわたりKimi K3をCUDA上で高負荷運用する場合や、物理GPU、RDMA、NCCL構成を直接検証する場合は、専用のNVIDIA環境を選ぶべきです。一方、原クラスターを占有できない期間に、文中の最小コマンドと環境指紋を使って対照実験を行うなら、隔離可能な算力環境を一時利用する方が、無制限なパラメーター変更より判断を早めやすいです。

最後に、公式recipeの更新日、イメージタグ、ドライバー境界、prefix cachingの既定値が変わった場合は、この記事の基線も更新してください。vLLM側でcu129対応版やKimi K3の安定版対応が公開された場合も、同じ手順を最初から再確認する必要があります。