検証ラボの メトリフクロウ です。前回までで、「なぜ測るか」「run_id で残す」「dry-run で壊さない」を揃えました。次に必要になるのが、実際に何を起動しようとしているかを YAML として読めることです。
この回の主題は Gemma4 のモデル解説そのものではありません。主題は vLLM の起動プロファイルの読み方です。題材として、社内検証でよく使う Gemma4 系（NVFP4・coding-agent 向け）の例を開きます。モデル名だけで語らず、プロファイルに書かれた制約で比較するための回です。
※ 公開可能な設定項目の説明です。社内の実パスや秘密情報は含みません。数値例は読み方の補助であり、特定機種の実測値ではありません。
ポイント
読む対象は「Gemma4」という固有名より、vLLM 起動プロファイルに書かれた制約です。Gemma4 はその具体例です。
連載のどこにいるか
| ここまで | この回 | 次 |
|---|---|---|
| 測る理由 / run_id / dry-run | 起動プロファイルを読む | 性能×品質の二軸 |
| なぜ・残す・壊さない | 何を起動するか | どう比べるか |
dry-run は「生成された Compose / CLI を見る」安全弁でした。その生成元が起動プロファイルです。プロファイルが読めないと、dry-run 結果を見ても良し悪しが判断できません。
題材：Gemma4 とは（最低限）
Gemma は Google が公開しているオープン寄りの LLM ファミリーです。この連載の「Gemma4」は、社内検証で使っている Gemma 4 系の具体モデル（例: コーディング／ツール呼び出し向けの命令チューニング済み・NVFP4 量子化版）を指す呼び方です。
| 層 | この回での意味 |
|---|---|
| モデル系列 | Gemma4 系（公開モデルファミリーの一系統） |
| 量子化 | NVFP4（重み側。KVキャッシュ の fp8 とは別レイヤ） |
| ランタイム | vLLM（OpenAI 互換サーバとして起動。エンジン比較対象は vLLM / TRT-LLM / SGLang / Atlas。この例は vLLM） |
| 用途仮説 | coding-agent（コード＋ツール呼び出しを想定） |
| プロファイル名の例 | gemma4-nvfp4 のような用途付き起動定義 |
読者に持ってほしい前提は次です。
- 比較の主役は「モデル名」ではなく 起動の束ね方（プロファイル）
- 例として Gemma4 × vLLM × coding-agent を開く
- 同じ読み方は、別モデル／別用途の vLLM プロファイルにも転用できる
Gemma4 のベンチ数値や「最強か」は扱いません。扱うのは、YAML を見て意図を復元する手順です。
vLLM起動プロファイルとは何か
起動プロファイルは、次を1枚に束ねた YAML です。
- どのモデルを
- どのランタイム（ここでは vLLM）で
- どの資源枠で
- どの用途向けオプション付きで起動するか
社内では用途別にディレクトリを分けています（例: coding-agent / long-context）。コーディング用途と長文用途では、見るべき項目が違うためです。プロファイル名に用途が入っていないと、後からレポートを見返したときに「何の試合だったか」が消えます。
| 用途の型 | 優先して読む項目 | 落としやすい罠 |
|---|---|---|
| coding-agent | tool parser、prefix cache、max_num_seqs | 長文設定のまま同時実行を上げる |
| long-context | max_model_len、KV dtype、メモリ枠 | 速度比較だけで合格にする |
| 共有常駐 | ポート、healthcheck、gpu_memory_utilization | 他用途の枠を侵食する |
例：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-nvfp4 なら、仮説は「コーディングエージェント用途で、量子化済み Gemma4 を vLLM で常駐させられるか」です。
2. ネットワークとプロセス
- 待ち受けポート
- コンテナ名
- healthcheck の path / リトライ / start_period
検証機では「いつも同じポート」より、「プロファイルごとに明示」が事故を減らします。初回起動はモデルロードで時間がかかるため、healthcheck の開始待ちを短くしすぎないことも重要です。到達不能なのに品質ゼロと記録すると、モデル不合格と誤読されます。
3. メモリとコンテキスト（型付き項目）
ここからは vLLM 共通の型付き項目です。数字は Gemma4 coding-agent 例の値で、読み方の補助です。
gpu_memory_utilization（例: 0.40）
GPU 全体メモリのうち、vLLM が自分のプロセス用に使ってよい割合です。0.40 なら「この起動は GPU の約4割まで」という意味で、残りを他プロセスや余裕に残す意図になります。
| 見方 | 内容 |
|---|---|
| 大きいほど | KV キャッシュや同時処理に使える枠が増えやすい |
| 小さいほど | 一台を複数用途で分けやすい／OOM リスクを抑えやすい |
| 読み方の罠 | 「余っているから 0.95」は共有常駐では危険。枠の宣言なしに盛ると隣の用途を潰す |
coding-agent 例の 0.40 は、速さ最大化より 一台を占有しすぎない 側の設計です。後の回で扱う「半分メモリ枠」も、このノブの運用判断の延長です。
max_model_len（例: 131072）
モデルが扱える 文脈長の上限（トークン数） です。入力＋出力を合わせた長さの天井、と粗く理解して構いません。131072 は約 128K トークンです。
| 見方 | 内容 |
|---|---|
| 大きいほど | 長いプロンプトや履歴を載せやすい |
| 代償 | KV キャッシュの予約が増え、同時実行や他用途の余白が減りやすい |
| 読み方の罠 | 「モデルカードに 256K と書いてあるから常に 256K」は誤り。この例のようにプロファイルで 128K へ下げていることも多い |
長いコンテキストを常時確保することと、複数用途で一台を分け合うことは両立しにくいことがあります。数字より先に「この用途で本当に必要な長さか」を一文で書けるかが重要です。
max_num_seqs（例: 2）
同時に進められる シーケンス（会話／リクエスト）数の上限 に近い制約です。バッチ内で何本まで並列に抱えるか、の天井だと考えてください。
| 見方 | 内容 |
|---|---|
| 大きいほど | 同時利用者や並列ジョブを受け入れやすい |
| 代償 | 1本あたりのメモリ・スケジューリング競合が増え、TTFT の悪化や OOM につながりやすい |
| 読み方の罠 | throughput を盛るために上げた結果、体感待ちだけ悪化する |
coding-agent 例の 2 は、同時実行より 1本の安定 を優先した読み方ができます。
max_num_batched_tokens（例: 8192）
1回のスケジューリング（バッチ）に載せる トークン数の上限 です。長い入力や複数リクエストをまとめるときの「一度に噛める量」の制限、と捉えると分かりやすいです。
| 見方 | 内容 |
|---|---|
| 大きいほど | 長い prefill や複数本のまとめ処理が通りやすい |
| 代償 | ピーク時のメモリと計算スパイクが増えやすい |
max_num_seqs との関係 | seqs は「何本まで」、batched_tokens は「合計で何トークンまで」。片方だけ見ると説明が欠けます |
プロファイルレビューでは、この2つをセットで「同時に何を許容するか」と言い換えてください。
dtype（例: bfloat16）
推論時の 計算に使う数値型 です。model_key の NVFP4 のような 重みの量子化方式 とは別レイヤです。
| レイヤ | 例 | ざっくり何を決めるか |
|---|---|---|
| 重みの保存形式 | NVFP4（model_key 側） | ディスク／ロード時のモデル重みの量子化 |
| 計算 dtype | bfloat16 | 実行時の演算精度 |
| KV の保持形式 | fp8（kv_cache_dtype） | 生成中の文脈キャッシュの精度 |
だから「dtype: bfloat16 なのに NVFP4 と書いてあるのは矛盾」ではありません。この例プロファイルでは、重みは量子化済み、計算は bf16、KV は fp8、のように 役割が分かれている 読み方が正しいです（NVFP4 一般の演算形態をここで断定するものではありません）。
kv_cache_dtype（例: fp8）
生成途中の文脈を保持する KVキャッシュ を、どの数値精度で持つか です。fp8 は 8bit 系で保持し、メモリを抑えつつ長文や同時実行の余白を稼ぐ意図が典型です。
| 見方 | 内容 |
|---|---|
| 役割 | モデル重みの量子化（例: NVFP4）や計算 dtype とは別レイヤ。混同すると比較が無効になる |
| fp8 のねらい | KV のメモリ圧を下げ、同じ枠で長い文脈やもう1本の余白を作る |
| 読み方の罠 | 「量子化した」一語で重み・計算・KV を一緒に語らない。変更したレイヤを分けて書く |
Gemma4 例では「重みは NVFP4、計算は bfloat16、KV は fp8」と分かれている点を必ず分けて書いてください。「長いコンテキスト」と「メモリ枠」と「KV dtype」はセットで読む項目です。
4. 生成・ツールまわり（extra_args）
用途固有フラグは、型付き項目以外を extra_args で素通しする設計が扱いやすいです。スキーマを毎回増やさなくても新オプションを試しやすくなります。ただし素通しは便利な分、dry-run で最終コマンドを見ないと「入れたつもり」が起きやすいです。
Gemma4 例で効いてくるのは、とくに パーサ名が gemma4 であること です。同じ vLLM でも、モデル系列が変わればパーサ指定も変わります。
prefix caching（--enable-prefix-caching）
リクエスト先頭の共通部分（システムプロンプトや固定の指示文など）をキャッシュし、同じ input 先頭を毎回フルで計算し直さないための機能です。
| 見方 | 内容 |
|---|---|
| 効きやすい条件 | プロンプト先頭が安定している（エージェントの固定指示、共通ツール定義など） |
| 効きにくい条件 | 毎回先頭から違う／キャッシュキーが実質毎回変わる |
| 読み方の罠 | 有効化しただけで速くなるとは限らない。効いたかは同じプロンプト構造で再確認する |
coding-agent では固定の役割文が長いことが多く、候補として入りやすい項目です。
chunked prefill（--enable-chunked-prefill）
長い入力の prefill（入力を読んで KV を作る段階）を、まとめて一気にではなく チャンクに分けて進める 設定です。長いプロンプトと短いリクエストが混在するときに、スケジューリングの詰まりを緩和する意図があります。
| 見方 | 内容 |
|---|---|
| ねらい | 長大な prefill が他リクエストの応答開始を長く塞がないようにする |
| 向きやすさ | 長文と短文が同居する常駐・エージェント用途 |
| 読み方の罠 | prefix caching とセットで語られがちだが、役割は別。片方だけ無効／有効の差分を残す |
reasoning parser（例: --reasoning-parser gemma4）
モデルが出力する 思考過程（reasoning）領域を、API 応答としてどう分離・解釈するか を選ぶパーサです。モデル系列ごとに形式が違うため、例では gemma4 を指定しています。ここがこの回でいちばん Gemma4 固有な設定です。
| 見方 | 内容 |
|---|---|
| 役割 | 「考える過程」と「利用者に返す答え」を取り違えないための解釈器 |
| 必要になる場面 | reasoning 対応モデルで、過程を別フィールドとして扱いたいとき |
| 読み方の罠 | パーサ不一致だと、評価側が答えを正しく拾えず品質が全面赤に見えることがある |
用途に reasoning が不要なら、入れている理由を一文で説明できない項目は忘れ物候補です。
tool-call parser（例: --tool-call-parser gemma4）
モデルが返す ツール呼び出し（関数名や引数）を、構造化データとして解釈する パーサです。OpenAI 互換の tool calling を下流（エージェント実行基盤）が受け取れる形に揃えます。こちらも系列名 gemma4 が紐づきます。
| 見方 | 内容 |
|---|---|
| 役割 | 自然文のままの「ツールを呼んで」を、実行可能な tool call に落とす |
| 必要になる場面 | coding-agent / tool-calling 評価・運用 |
| 読み方の罠 | モデルは呼べていても、パーサ不一致で scorer や実行基盤だけ失敗する |
品質スイートの tool_call が落ちたら、モデル能力の前にパーサと auto tool choice を疑う、が現場の定石です。
auto tool choice（--enable-auto-tool-choice）
ツールを使う／使わない／どれを使うかの選択を、リクエスト側で強制しなくてもモデルに任せられるようにするフラグです。エージェント用途では、毎回 tool_choice を固定しない運用と相性が良いことがあります。
| 見方 | 内容 |
|---|---|
| ねらい | 会話の文脈に応じてツール呼び出しを自動選択しやすくする |
| 注意 | 「いつでもツールを呼ぶ」わけではない。呼ばない判断も許す |
| 読み方の罠 | 有効なのに tool-call parser が無い、または逆、という欠落が起きやすい |
マルチモーダル制限（例: --limit-mm-per-prompt '{"image":3,"video":0}'）
1プロンプトあたり受け付ける 画像・動画などの枚数／件数上限 です。例では画像最大3、動画0です。Gemma4 系はマルチモーダル対応の系統もあるため、プロファイル側で「どこまで許すか」を閉じる必要があります。
| 見方 | 内容 |
|---|---|
| ねらい | 想定外の大量画像でメモリと遅延が跳ねるのを防ぐ |
image: 3 | 視覚付きのコーディング／UI確認など、少数画像を許す |
video: 0 | 動画入力は明示的に閉じる |
| 読み方の罠 | モデルがマルチモーダル対応でも、プロファイルで閉じていることがある |
テキストだけの評価なのに画像上限が緩い、あるいはその逆、がないかを用途と照合します。
5. トレードオフを一文で書く
プロファイルを読むときは、数字単体より 意図したトレードオフ を先に書き出してください。Gemma4 coding-agent 例を強引に一文にすると、次のようになります。
Gemma4（NVFP4）を vLLM で coding-agent 用途に載せる。GPU は約4割まで、文脈は最大 128K、同時シーケンスは薄め。KV は fp8 で節約しつつ、prefix cache / chunked prefill と Gemma4 向けパーサでエージェント用途を優先する。画像は最大3枚、動画は受けない。
この文が書けないプロファイルは、まだレビュー通過ではありません。
読むときの質問テンプレート
未知の vLLM プロファイルを開いたら、次を埋めてみてください（Gemma4 以外でも同じです）。
- モデル系列と量子化は何か（例: Gemma4 / NVFP4）
- このプロファイルの主用途は何か
- 失敗したとき、何が壊れやすいか（メモリ、長文、ツール）
- 比較対象のプロファイルと、変えたい軸は1つか
- dry-run した生成物と、YAML の意図は一致しているか
- 常駐共有か、検証用の使い捨て起動か
- stable に進めるなら、制約（メモリ枠・用途）をどう書くか
埋めた答えは、レポートの冒頭にそのまま転記できます。数字より先に条件を固定する習慣が、比較可能性を支えます。
実務チェックリスト
プロファイルレビュー前に、短く確認します。
- [ ] 「何のモデルを、何の用途で、どのランタイムで」が一文で言える
- [ ] 用途タグとディレクトリ名／プロファイル名が一致している
- [ ] ポートとコンテナ名が他プロファイルと衝突しない
- [ ] メモリ枠（gpu_memory_utilization）と 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 と最終コマンドが対応している
- [ ] 戻し先となる前の安定プロファイルが分かる
数値を急がない
プロファイルを読めるようになると、ベンチマークの数字も解釈しやすくなります。逆に、設定を読まずに throughput だけ比較すると、条件違いの試合になってしまいます。同じ「Gemma4」でも、メモリ枠とコンテキスト長が違えば、別モデルに近い差が出ます。
連載のここまで（公開の意図、run_id、dry-run、vLLM 起動プロファイルの読み方）で、「なぜ測るか」「どう記録するか」「どう起動を安全にするか」「設定をどう読むか」を揃えました。ここまで揃って初めて、次に扱う性能と品質の二軸評価が機能します。
つまずいたこと
プロファイルを読み始めると、すぐにオプションの海に沈みます。効くキーと、過去の実験の残骸が同居していて、どれが意図でどれが忘れ物かが分からない。最初の数週間は、変更のたびに「何かが速くなった／遅くなった」感想だけが残りました。
困ったのはドキュメント不足というより、読む順番がなかったことです。モデル前提 → 用途 → メモリ／文脈 → 並列 → キャッシュ／パーサ、の順に線を引いてから、ようやく差分が会話になりました。
この回の要点
- 主題は vLLM 起動プロファイルの読み方。Gemma4 はその具体例
- 先に「モデル系列・量子化・用途・ランタイム」を一文で固定する
- 各ノブは「何を増やし、何を犠牲にするか」を言えるまで触らない
- Gemma4 固有になりやすいのはパーサ名。メモリ枠や文脈長の読み方は転用できる
- 差分が説明できるまでオプションを増やさない
いま公開しているのは評価の型です。実機ベンチの数字は、再計測と匿名化が済んだものから順に足します。合格ラインや用途別プロファイルの未確定は残っています。
次は「性能と品質の二軸でローカルLLMを評価する」へ進みます。いまのメモを1行残してから読むと、連載の筋がつながりやすくなります。
