起動設定ファイルの読み方：Gemma4を例に

検証ラボの メトリフクロウ です。前回までで、「なぜ測るか」「run_id で残す」「dry-run で壊さない」を揃えました。次に必要になるのが、実際に何を起動しようとしているかを YAML として読めることです。

この回の答え

主題はモデル解説ではなく、起動設定の読み方です。モデル名・用途・メモリ枠・文脈長・並列・パーサを一文で固定してから数字を読みます。

この回だけの用語

※ 公開可能な設定項目の説明です。社内の実パスや秘密情報は含みません。数値例は読み方の補助であり、特定機種の実測値ではありません。

ポイント
読む対象は「Gemma4」という固有名より、vLLM 起動プロファイルに書かれた制約です。Gemma4 はその具体例です。

連載のどこにいるか

dry-run は「生成された Compose / CLI を見る」安全弁でした。その生成元が起動プロファイルです。プロファイルが読めないと、dry-run 結果を見ても良し悪しが判断できません。

題材：Gemma4 とは（最低限）

Gemma は Google が公開しているオープン寄りの大規模言語モデル（LLM）ファミリーです。この連載の「Gemma4」は、社内検証で使っている Gemma 4 系の具体モデル（例: コーディング／ツール呼び出し向けの命令チューニング済み・NVFP4 量子化版）を指す呼び方です。

持ってほしい前提は3つです。

1. 比較の主役は「モデル名」ではなく 起動の束ね方（プロファイル）
2. 例として Gemma4 × vLLM × coding-agent を開く
3. 同じ読み方は、別モデル／別用途の vLLM プロファイルにも転用できる

Gemma4 のベンチ数値や「最強か」は扱いません。扱うのは、YAML を見て意図を復元する手順です。

vLLM起動プロファイルとは何か

起動プロファイルは、次を1枚に束ねた YAML です。

• どのモデルを
• どのランタイム（ここでは vLLM）で
• どの資源枠で
• どの用途向けオプション付きで起動するか

社内では用途別にディレクトリを分けています（例: coding-agent / long-context）。プロファイル名に用途が入っていないと、後から「何の試合だったか」が消えます。

例：Gemma4 coding-agent プロファイル（要約）

公開用に抽象化した項目だけ抜粋します。

profile_name: gemma4-nvfp4
model_key: gemma4-26b-a4b-nvfp4
runtime: vllm
served_model_name: Gemma-4-...-NVFP4
port: 8001

dtype: bfloat16
kv_cache_dtype: fp8
gpu_memory_utilization: 0.40
max_model_len: 131072
max_num_seqs: 2
max_num_batched_tokens: 8192

extra_args:
  - --enable-prefix-caching
  - --enable-chunked-prefill
  - --reasoning-parser
  - gemma4
  - --tool-call-parser
  - gemma4
  - --enable-auto-tool-choice
  - --limit-mm-per-prompt
  - '{"image":3,"video":0}'

Gemma4 固有なのは主に パーサ名（gemma4）と用途仮説 です。gpu_memory_utilization や max_model_len の読み方自体は、他の vLLM プロファイルでも同じです。

読むべき代表項目

1. モデル識別

• model_key / 公開名 / 量子化方式（例: NVFP4）
• ランタイム（この例では vLLM）
• 想定用途（coding、tool calling、reasoning など）

「Gemma4 だから長いコンテキスト」ではなく、「このプロファイルは何の業務仮説を検証するか」から読みます。例の仮説は「コーディングエージェント用途で、量子化済み Gemma4 を vLLM で常駐させられるか」です。

2. ネットワークとプロセス

• 待ち受けポート
• コンテナ名
• healthcheck の path / リトライ / start_period

検証機では「いつも同じポート」より、「プロファイルごとに明示」が事故を減らします。初回起動はモデルロードで時間がかかるため、healthcheck の開始待ちを短くしすぎないことも重要です。到達不能なのに品質ゼロと記録すると、モデル不合格と誤読されます。

3. メモリとコンテキスト（型付き項目）

数字は Gemma4 coding-agent 例の値で、読み方の補助です。

gpu_memory_utilization（例: 0.40）

GPU 全体メモリのうち、vLLM が自分のプロセス用に使ってよい割合です。0.40 なら「この起動は GPU の約4割まで」。

coding-agent 例の 0.40 は、速さ最大化より 一台を占有しすぎない 側の設計です。

max_model_len（例: 131072）

モデルが扱える 文脈長の上限（トークン数） です。入力＋出力を合わせた天井、と粗く理解して構いません。131072 は約 128K トークンです。

max_num_seqs（例: 2）と max_num_batched_tokens（例: 8192）

• seqs: 同時に何本まで抱えるか
• batched_tokens: 一度に噛む合計トークン上限

coding-agent 例の 2 は、同時実行より 1本の安定 を優先した読み方ができます。

dtype と kv_cache_dtype（別レイヤ）

「dtype: bfloat16 なのに NVFP4」は矛盾ではありません。役割が分かれているだけです。

加えて、GPU が FP4 演算をネイティブに持たない環境では、NVFP4 は重み圧縮として効いても生成加速には直結しないことがあります。「NVFP4 だから速い」とプロファイルを読まないでください。速さの根拠は、同じ試合規則の計測結果に置きます。

ひとことで言うと: NVFP4 は倉庫の圧縮、bf16 は計算の物差し、fp8 はメモの置き方——別物です。

4. 生成・ツールまわり（extra_args）

用途固有フラグは、型付き項目以外を extra_args で素通しする設計が扱いやすいです。便利な分、dry-run で最終コマンドを見ないと「入れたつもり」が起きやすいです。

Gemma4 例で効いてくるのは、とくに パーサ名が gemma4 であること です。

例のマルチモーダル制限は画像最大3・動画0です。テキストだけの評価なのに画像上限が緩い、あるいはその逆、がないかを用途と照合します。

詳細が必要な人向けの補足は次です。

• prefix caching: エージェントの固定指示や共通ツール定義が長いときに効きやすい
• chunked prefill: 長文と短文が同居する常駐で、長大な読み込みが他リクエストを塞がないようにする
• reasoning / tool-call parser: 系列名 gemma4 が紐づく。用途に不要なら「なぜ入れたか」を一文で言えない項目は忘れ物候補
• auto tool choice: 「いつでもツールを呼ぶ」わけではない。呼ばない判断も許す

品質スイートの tool_call が落ちたら、モデル能力の前にパーサと auto tool choice を疑う、が現場の定石です。

5. トレードオフを一文で書く

プロファイルを読むときは、数字単体より 意図したトレードオフ を先に書き出してください。

Gemma4（NVFP4）を vLLM で coding-agent 用途に載せる。GPU は約4割まで、文脈は最大 128K、同時シーケンスは薄め。KV は fp8 で節約しつつ、prefix cache / chunked prefill と Gemma4 向けパーサでエージェント用途を優先する。画像は最大3枚、動画は受けない。

この文が書けないプロファイルは、まだレビュー通過ではありません。

読むときの質問テンプレート

未知の vLLM プロファイルを開いたら、次を埋めてみてください（Gemma4 以外でも同じです）。

1. モデル系列と量子化は何か（例: Gemma4 / NVFP4）
2. このプロファイルの主用途は何か
3. 失敗したとき、何が壊れやすいか（メモリ、長文、ツール）
4. 比較対象のプロファイルと、変えたい軸は1つか
5. dry-run した生成物と、YAML の意図は一致しているか
6. 常駐共有か、検証用の使い捨て起動か
7. stable に進めるなら、制約（メモリ枠・用途）をどう書くか

埋めた答えは、レポートの冒頭にそのまま転記できます。

実務チェックリスト

• [ ] 「何のモデルを、何の用途で、どのランタイムで」が一文で言える
• [ ] 用途タグとディレクトリ名／プロファイル名が一致している
• [ ] ポートとコンテナ名が他プロファイルと衝突しない
• [ ] メモリ枠と max_model_len の意図が一文で説明できる
• [ ] max_num_seqs と max_num_batched_tokens をセットで説明できる
• [ ] 重みの量子化（例: NVFP4）と kv_cache_dtype が混同されていない
• [ ] prefix caching / chunked prefill を入れた／外した理由がある
• [ ] tool / reasoning パーサ名がモデル系列と一致している（例: gemma4）
• [ ] auto tool choice とパーサの有無が用途に対して過不足ない
• [ ] マルチモーダル制限が用途と一致している
• [ ] dry-run 出力を見て、YAML と最終コマンドが対応している
• [ ] 戻し先となる前の安定プロファイルが分かる

数値を急がない

設定を読まずにスループットだけ比較すると、条件違いの試合になります。同じ「Gemma4」でも、メモリ枠とコンテキスト長が違えば、別モデルに近い差が出ます。

連載のここまでで、「なぜ測るか」「どう記録するか」「どう起動を安全にするか」「設定をどう読むか」を揃えました。ここまで揃って初めて、次の性能と品質の二軸評価が機能します。

つまずいたこと

プロファイルを読み始めると、すぐにオプションの海に沈みます。効くキーと、過去の実験の残骸が同居していて、どれが意図でどれが忘れ物かが分からない。最初の数週間は、変更のたびに感想だけが残りました。

困ったのはドキュメント不足というより、読む順番がなかったことです。モデル前提 → 用途 → メモリ／文脈 → 並列 → キャッシュ／パーサ、の順に線を引いてから、ようやく差分が会話になりました。

この回の要点

• 主題は vLLM 起動プロファイルの読み方。Gemma4 はその具体例
• 先に「モデル系列・量子化・用途・ランタイム」を一文で固定する
• 各ノブは「何を増やし、何を犠牲にするか」を言えるまで触らない
• Gemma4 固有になりやすいのはパーサ名。メモリ枠や文脈長の読み方は転用できる
• 差分が説明できるまでオプションを増やさない

ここで示したのはプロファイルの読み順であり、Gemma4 固有の最終推奨値ではありません。メモリ枠・文脈長・パーサの実測は、再計測と匿名化のあとで足します。

次は「速さと正しさは別もの：二軸で評価する」です。一文で固定した用途を持ったまま進むと、二軸表の列がぶれにくくなります。