3行でいうと

  • vLLMは、Prometheus形式の指標を/metricsで出します。見る場所は大きく3つです。待ち行列（実行中と待ちの数）、KVキャッシュの使用率、応答時間（最初の1トークンまで、トークンの間隔、全体）です。
  • KVキャッシュの空きがなくなると、vLLMは実行中の依頼をいったん戻して、あとで計算し直します（プリエンプション）。公式の対処は、メモリの割合を上げる、同時に扱う量を下げる、GPUを増やす、の3方向です。
  • 公式の文書には、名前の不一致や、廃止された指標、一覧の本体が読めない節もあります。ダッシュボードを作る前に、自分のバージョンの/metricsの出力を直接見て確かめるのが安全です。

この記事は、実際に使って確かめた記録ではありません。この記事は公式の文書を読んでまとめたもので、実際に使って確かめた記録ではありません。数字と設定の既定値は2026年10月16日に確認しました。変わることがあります。

先に結論

前提：何を運用するのか

vLLMは、モデルを読み込んで、複数の依頼をまとめて処理し、返事を作るサーバーのソフトウェアです。OpenAIのAPIと同じ形で呼べるサーバーを持ちます。しくみの中心にあるKVキャッシュ（会話の途中までの計算結果をGPUのメモリに置いておく場所）の工夫は、別の記事で扱っています。

運用側から見ると、vLLMは「GPUのメモリに、モデルの重みとKVキャッシュを置き、依頼を少しずつ束ねて回す」装置です。メモリの空きと、束ねる量が、速さと止まりにくさを決めます。

指標の出し方

公式の「Production Metrics」の文書によると、OpenAI互換のサーバーの/metricsにアクセスすると、Prometheus（指標を集める定番のしくみ）が読める形式で指標が出ます。例はvllm serve unsloth/Llama-3.2-1B-Instructで起動して、curl http://0.0.0.0:8000/metricsで見る、というものです。

指標には、model_nameのラベルがつきます。文書は、Prometheusサーバーの設定やスクレイプの手順までは書いていません。

見るべき指標の地図

公式の設計文書（Metrics）は、指標を型（ゲージ、カウンター、ヒストグラム）つきで挙げ、見るべき指標の分類も載せています。それを元に、僕らが表にまとめました。

見たいこと 指標（公式の名前） 型
待ち行列 vllm:num_requests_running、vllm:num_requests_waiting（後者は、設計文書の「_waitingもある」という書き方から組み立てた名前） ゲージ
KVキャッシュの余裕 vllm:kv_cache_usage_perc（使用中のブロックの割合、0〜1） ゲージ
最初の1トークンまで vllm:time_to_first_token_seconds ヒストグラム
トークンの間隔 vllm:inter_token_latency_seconds、vllm:request_time_per_output_token_seconds ヒストグラム
全体の時間 vllm:e2e_request_latency_seconds ヒストグラム
時間の内訳 vllm:request_queue_time_seconds、vllm:request_prefill_time_seconds、vllm:request_decode_time_seconds ヒストグラム
処理量 vllm:prompt_tokens_total、vllm:generation_tokens_total、vllm:request_success_total カウンター
依頼の形 vllm:request_prompt_tokens、vllm:request_generation_tokens ヒストグラム
キャッシュの効き vllm:prefix_cache_hits、vllm:prefix_cache_queries カウンター

プレフィックスキャッシュ（同じ前置きの計算結果を使い回す仕組み）の効き具合は、2つのカウンターの比で出す、と文書にあります。文書の例の式は、rate(vllm:prefix_cache_hits[5m]) / rate(vllm:prefix_cache_queries[5m])の形です（ただし、文書の例は実在しない仮の名前で書かれていて、上の式は実在の名前に直した僕らの書き換えです。動作確認はしていません）。

時間の測り方の定義

数字を比べるときに、定義の違いで混乱しやすい点が、設計文書に書かれています。

エンジンの中では、依頼に対してQUEUED（待ち行列に入った）、SCHEDULED（初めて実行に回った）、PREEMPTED（待ちに戻された）、NEW_TOKENS（出力ができた）の時刻が記録され、待ち、プリフィル、デコードの時間が計算されます。プリフィルの途中で戻されると（文書は「そのような事象が起こりうるなら」と前置きしています）TTFTが延び、デコードの途中で戻されるとトークンの間隔が延びる、と書かれています。

負荷とメモリ：困ったときに触る設定

KVキャッシュが足りなくなると何が起きるか

公式の「Optimization and Tuning」の文書によると、KVキャッシュの空きがなくなると、vLLMは、ほかの依頼のために一部の依頼を中断（プリエンプト）して、空きができてから計算し直します。ログには、「Sequence group 0 is preempted by PreemptionMode.RECOMPUTE mode…」という趣旨の警告が出ます。V1の既定は、メモリを退避する方式（SWAP）ではなく、再計算（RECOMPUTE）です。

文書が挙げる対処は次の4つです。

  1. gpu_memory_utilizationを上げる（KVキャッシュに使えるメモリが増える）。
  2. max_num_seqsまたはmax_num_batched_tokensを下げる（同時に扱う量が減る）。
  3. tensor_parallel_sizeを上げる（モデルをGPUで分ける。同期のぶんの負担が増えうる）。
  4. pipeline_parallel_sizeを上げる（遅延が増えうる）。

発生回数は、Prometheusの指標か、disable_log_stats=Falseにして累積のプリエンプションの回数をログに出す、と書かれています。ただし、僕らが読んだ指標の表には、プリエンプションの回数そのものの指標名は見つかりませんでした。Production Metricsの文書の、ヒストグラムの区切りを変える設定の表には vllm:request_num_preemptions という名前が出ていますが、何を数える指標かの説明は読めていません。

見立てです。vllm:kv_cache_usage_percが1に近いまま、vllm:num_requests_waitingが増え続けているなら、メモリが詰まっている可能性があります。そこにプリエンプションの警告が重なれば、上の4つを検討する根拠になります。この組み合わせの読み方は公式の記述ではなく、僕らの推測です。

束ねる量とTTFT・ITLのトレードオフ

チャンク化プリフィル（長い入力を分けて計算する仕組み）は、V1では可能な場合に既定で有効です。デコード待ちの依頼を先にまとめ、残ったmax_num_batched_tokensの枠でプリフィルを進め、入らない分は自動で分割されます。文書によると、この値は次のように効きます。

つまり、チャットのように「流れる速さ」を重視するか、バッチ処理のように「処理量」を重視するかで、同じ設定の最適値が違います。

メモリを節約する手段

「Conserving Memory」の文書は、メモリを節約する手段を並べています。モデルを複数のGPUに分ける（tensor_parallel_size）、量子化したモデルを使う、max_model_len（文脈の長さ）とmax_num_seqs（同時の数）を下げる、などです。CUDAグラフ（GPUの処理を記録して再利用する高速化）は既定で使われ、追加のGPUメモリを使います。enforce_eager=Trueで無効にできます。

公式の既定値と、運用時の環境変数

既定値（2026年10月16日に読んだ時点。mainブランチの文書とソースの記載）

項目 既定値や内容 出どころ
gpu_memory_utilization 0.92。1つのvLLMインスタンスごとの上限で、同じGPUの他のインスタンスの分は制限しない CacheConfigのソース
block_size 指定なしで16 同上
enable_prefix_caching 有効（True） 同上
チャンク化プリフィル V1では可能なら有効 Optimization and Tuning
プリエンプションの方式 再計算（RECOMPUTE） 同上
最適化レベル -O2 同上
mm_processor_cache_gb 4 GiB 同上、Conserving Memory
統計の要約ログ 5秒ごとにINFOで出力 Metrics（設計文書）

要約ログには、実行中と待ちの数、GPUキャッシュの使用率、毎秒のトークン数、プレフィックスキャッシュのヒット率が出ます。

トラブル対応の環境変数（Troubleshootingより）

  • VLLM_LOGGING_LEVEL=DEBUG：詳しいログ。
  • VLLM_LOG_STATS_INTERVAL=1.：待ち行列とキャッシュの統計を、より短い間隔で出す。
  • VLLM_TRACE_FUNCTION=1：トークン生成が100倍以上遅くなるので、必要なときだけ。
  • CUDA_LAUNCH_BLOCKING=1、NCCL_DEBUG=TRACEも挙げられています（用途の説明は、この記事では確認できていません）。

文書は、デバッグが終わったら外すことを注意しています。--load-format dummyで重みの読み込みを飛ばして、切り分けに使える、と書かれています。

KVキャッシュの寿命の指標

--kv-cache-metrics-sample（設計文書の名前。使い方の文書は--kv-cache-metricsと書いていて、文書の間で揺れています。自分のバージョンのヘルプで確かめます）を付けると、KVのブロックの寿命（vllm:kv_block_lifetime_seconds）、最後に触れてから追い出されるまで（vllm:kv_block_idle_before_evict_seconds）、再利用の間隔（vllm:kv_block_reuse_gap_seconds）が取れます。

運用で引っかかりやすい点

公式の文書そのものに書かれている注意です。

見立て：最初に作る画面

ここからは僕らの見立てです。公式が勧める手順ではありません。

気をつけること

出典

更新履歴