現場でローカルLLMを回していると、「起動コマンドを一発で通すこと」より「壊さないこと」の方が先に効いてきます。私（クムビーバー）が社内検証基盤で最初に固定したのも、派手な最適化ではなく dry-run を既定にする ことでした。
ローカルLLMの検証基盤では、モデル起動が Docker Compose などの生成物に落ちることが多いです。便利な一方で、誤ったプロファイルをそのまま実行すると、ポート衝突、メモリ圧迫、キャッシュ汚染が起きます。GPU マシンは共有されやすく、復旧コストも高い。だから実害のある操作は、明示的に許可したときだけ実行する設計にします。
ポイント
実起動の前に、生成される Compose / CLI を目視確認するのを既定にします。
builder と executor を分ける
設計の要点は単純です。
- builder: 設定から起動定義（Compose やコマンド列）を生成する。副作用が少ない
- executor: 生成物を使って実際に起動・停止する。副作用がある
人間の確認ポイントは builder の出力です。ポート、GPU メモリ枠、モデル参照、環境変数の渡し方が意図どおりかを見てから executor に進みます。
この分離には副次効果もあります。比較対象の vLLM / TensorRT-LLM / SGLang / Atlas を、同じ「生成 → 確認 → 実行 → 計測」の型に載せられることです。ランタイムが違っても、評価軸と運用モデルを揃えやすくなります。実装者ごとに「自分のシェル履歴が正」になると、チームの再現性が一気に崩れます。
| 役割 | やること | やってはいけないこと |
|---|---|---|
| builder | YAML/プロファイルから起動定義を生成 | GPU 上でプロセスを起動する |
| レビュー | 生成物の差分を読む | 「たぶん大丈夫」で up する |
| executor | 明示許可後に起動・停止 | 未確認の生成物を常駐させる |
dry-run で見るチェックリスト
実起動前に、少なくとも次を確認します。
- 使っているプロファイル名は正しいか
- 公開ポートが既存サービスと被っていないか
- GPU メモリ利用率や KV キャッシュ設定が想定内か
- コンテキスト長が用途（コーディング、長文、ツール呼び出し）に合っているか
- モデル ID / 量子化方式が意図した候補か
- healthcheck の開始待ち時間は十分か（初回起動は長い）
- 失敗時に戻れるか（前の安定プロファイルが残っているか）
- volume マウント先が共有キャッシュを壊さないか
- restart ポリシーが検証意図（常駐 / 使い捨て）と一致するか
- 生成コマンド列に秘密情報やホスト固有パスが混入していないか
この確認がないまま「とりあえず up」すると、検証そのものより環境復旧に時間を取られます。dry-run は面倒な儀式ではなく、復旧コストの前払いです。
よくある落とし穴
現場で繰り返し見る失敗を、予防策とセットで残します。
| 落とし穴 | 症状 | 予防 |
|---|---|---|
| プロファイル取り違え | 意図しないモデルが起動 | dry-run 出力の先頭に profile 名を出す |
| ポート衝突 | bind 失敗 / 古いサービスに到達 | プロファイルごとにポートを明示 |
| healthcheck 過短 | ずっと unhealthy | start_period を初回ロード前提で延ばす |
| メモリ枠の見積もり甘い | OOM や他用途の圧迫 | gpu_memory_utilization を用途別に固定 |
| キャッシュ汚染 | 再現不能な速度差 | volume 方針を先に決める |
「起動できた」は成功条件の半分です。誰の検証を壊していないか、まで含めて成功とします。
小さなチームほど効く理由
少人数では、インフラ専任が常に張り付いているとは限りません。dry-run は個人の注意力に依存しすぎないための手順です。
- レビューしやすい（生成 YAML を見て議論できる）
- 再現しやすい（同じプロファイルから同じ定義が生まれる）
- 教育しやすい（新メンバーが「何が起動されるか」を先に読める）
- テストしやすい（GPU が無い開発機でも生成物の忠実性を検証できる）
- 切り分けやすい（生成ミスと実行時障害を分離できる）
特に最後が重要です。Compose 生成が間違っているのにモデル性能を疑い始めると、スパイラルが空転します。
実務への落とし込み
社内検証では、起動・ビルドの既定を dry-run にし、実行は明示フラグで許可する運用にしています。ワンコマンドで「確認 → 起動 → 計測 → 評価 → レポート」まで回す場合も、途中で定義を目視できる余白を残します。
また、生成物には restart ポリシーと healthcheck を必ず含める方針です。常駐サービスとして複数人同時利用に晒される前提なら、単発プロセス感覚の起動は危険です。健康確認が無い常駐は、障害検知が人間の体感依存になります。
PR やレビューでは、次の3点だけでも見てください。
- dry-run 出力が意図したプロファイルか
- 変更軸が1つか（複数変更の同時投入になっていないか）
- 失敗時の戻し先（直前の stable プロファイル）が残っているか
つまずいたこと
本番相当の起動コマンドを、確認なしに流して GPU を占有し切ったことがあります。意図は「すぐ試したい」だけでした。結果、他チームの検証枠を潰し、ロールバック手順も残っていませんでした。
dry-run を義務化したあとも、見た目が正しそうなコマンドが実は古いプロファイルを指している事故が続きました。苦労の本体はツール不足ではなく、「確認したつもり」を仕組みで無効化することでした。
この回の要点
- 本番相当コマンドの前に dry-run を挟む
- 正しそうな見た目より、指しているプロファイルを確認する
- 確認したつもりを、仕組みで無効化する
いま公開しているのは評価の型です。実機ベンチの数字は、再計測と匿名化が済んだものから順に足します。合格ラインや用途別プロファイルの未確定は残っています。
次は「vLLM起動プロファイルを読む：Gemma4を例に」へ進みます。いまのメモを1行残してから読むと、連載の筋がつながりやすくなります。
