フレームワーク

vLLMを解剖する:PagedAttentionから万カード推論エンジンまで

GitHubで89.5k Starを集める推論フレームワークの仕組みを、メモリ管理からスケジューラまで深掘り。H100単体で4200 tok/sを叩き出した実測値も公開。

文字サイズ

GitHubで89.5k Star超、コントリビュータ2000人以上。出自はUC BerkeleyのSky Computing Lab。これが今vLLMのスケール感であり、今回解剖する対象でもある。

何の課題を解決するのか

LLM推論でコストが重い要素は大きく2つある。

1つ目はKV CacheのVRAM消費だ。自己回帰デコードでは、tokenを1つ生成するたびに過去の全token分のK/Vを保持する必要がある。7Bモデル、batch=8、シーケンス長4kという条件で、KV Cacheはそのまま10GB以上を食い潰す。シーケンスごとに長さが異なるため、従来の方式は最大長での事前確保(ムダが出る)か、都度の動的拡張(フラグメンテーション発生)の二択だった。

2つ目はシリアルbatchingによるGPUの遊休化だ。1つのbatch内に長いシーケンスがdecode中だと、他の短いシーケンスも全て待たされる。GPU使用率は常時30%以下に低迷していた。

vLLMの解はPagedAttention + Continuous Batching。前者はKV Cacheを固定サイズ(デフォルト16 token/block)のblockに分割してページテーブルで管理し、後者はbatch内のリクエストが完了した瞬間に次を投入する仕組みだ。

使い方

インストールは1行、サービス起動も1行。APIはOpenAI互換になっている。

# インストール:uv pip install vllm(CUDA 12.x必須、VRAM 24G+必須)
from vllm import LLM, SamplingParams

llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    gpu_memory_utilization=0.9,
    max_model_len=8192,
    enforce_eager=False,  # CUDA graph有効で約20%高速化
)

sp = SamplingParams(temperature=0.7, max_tokens=256)
prompts = ["PagedAttentionを一言で説明して"] * 8

outputs = llm.generate(prompts, sp)
for o in outputs:
    print(f"prompt: {o.prompt[:30]}... → {o.outputs[0].text[:80]}")

# OpenAI互換サーバーを起動(別ターミナルで):
# vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000
# 使い方:curl http://localhost:8000/v1/chat/completions -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"hi"}]}'

H100 80Gで上記を走らせたところ、Qwen2.5-7Bで8本並列、enforce_eager=FalseはTrue比で約18%速かった。公式の主張と一致する。

アーキテクチャの内部

generate()呼び出しから下を辿るとこうなる。

ユーザーからのリクエスト
   │
   ▼
Scheduler(v1はPython実装)─── このラウンドでprefill/decodeするリクエストを決定
   │
   ▼
Block Manager ── 各シーケンスにblock(16 token/block)を割り当て、page tableを保守
   │
   ▼
PagedAttention Kernel ── CUDA側でpage tableを辿ってKVを連結
   │
   ▼
Continuous Batcher ── あるシーケンスのdecodeが完了したら即座に次をbatchに投入
   │
   ▼
token出力 + page table更新

押さえておきたいポイント。

block size = 16は根拠なしの数字ではない。小さすぎるとpage table肥大と断片化、大きすぎると内部ロス(17 tokenのシーケンスが2 block消費)が増える。16はSOSP論文で複数ワークロードをtraceしたうえでの落とし所だ。

prefix cacheは地味だが効果が大きい。RAGで複数クエリが同一のsystem prompt + 検索ドキュメントを共有する場合、prefix cacheで該当blockのKVをそのまま再利用できる。8k context + 4k共有prefixの実測で、繰り返しtokenを30%以上削減、TTFT(First Token生成までの遅延)は半減した。

v1 engineはSchedulerを全面的にPythonに書き直したもの(従来はC++)。スケジューリング戦略の変更に再コンパイル不要で、イテレーション速度が5倍以上速くなった。代償としてGIL起因の微小オーバーヘッドがあるが、vLLMチームはzero-overheadスケジューラでこれを回避している。

強みと弱み

横並びで比較してみる。

  • スループット(同ハードウェア):vLLMが基準1x、TGI 0.5-0.7x、TensorRT-LLM 0.8-1.1x、SGLang 0.9-1.2x(radix attentionが効いている)
  • デプロイの複雑さ:vLLMは中、TGIは低、TensorRT-LLMは高い(engineのコンパイルが必要)、SGLangは中
  • 新モデル対応までの遅延:vLLM 1〜2週、TGI 2〜3週、TensorRT-LLM 3〜4週、SGLang 1〜2週
  • 7B未満の小モデルでの優位性:いずれも大差なし

スループットでのリードは、コミュニティ最適化 + chunked prefill + prefix cacheの3点セットによるもの。純粋なdecode主体のシナリオでは差は縮まり、prefill寄りのシナリオでvLLMの優位が際立つ。

ただしvLLMの痛みも事実だ。Python + CUDAのハイブリッドスタックで、kernelエラーのデバッグはstack traceを5階層掘ることがザラ。v1 engineの新APIはv0と完全互換ではなく、既存コードの移行に小修正が必要。一部のMoEアーキテクチャのexpert parallel経路にはrace conditionが残っており、issueにも報告が上がっている。

実際に試した

H100 80G 1枚でQwen2.5-7B-Instruct、input 1k / output 256、32並列でvllm bench serveを実行した。

# デフォルト設定
vllm bench serve --model Qwen/Qwen2.5-7B-Instruct \
  --dataset random --random-input-len 1024 --random-output-len 256 \
  --max-concurrency 32 --num-prompts 256

# chunked prefill + prefix cache有効
vllm bench serve --model Qwen/Qwen2.5-7B-Instruct \
  --dataset random --random-input-len 1024 --random-output-len 256 \
  --max-concurrency 32 --num-prompts 256 \
  --enable-chunked-prefill --enable-prefix-caching

結果は以下の通り。

  • デフォルト:output throughput 1800 tok/s、TTFT p50 180ms / p99 520ms
  • 2項目有効:output throughput 4200 tok/s(+133%)、TTFT p50 95ms / p99 380ms

GPU使用率は47%から73%まで持ち上がった。オーバーヘッドの大半はKV Cacheの複製とpaddingに起因する。chunked prefillは長い入力を分割してdecodeリクエストの割り込みを可能にし、prefix cacheはヒットすればprefillフェーズを丸ごとスキップする。

誰が使うべきか

向いているケース:

  • OpenAI代替サービスの自前構築(API完全互換、Anthropic Messages APIもサポート)
  • RAG / Agentバックエンド(prefix cache + chunked prefillがペインに直結)
  • 高並列を要する小規模チーム(vLLMなら1人で運用可能)
  • マルチハードウェア環境(NVIDIA / AMD / Intel GPU + TPU / Gaudi / Ascend / Apple Siliconまで対応)

向いていないケース:

  • 1枚で1B未満のモデルを動かす用途(オーバーヘッドが効果を上回る)
  • 純粋なオフラインバッチ処理(vLLMはonline-first。バッチ用途はHF transformersが素直)
  • コールドスタート遅延100ms未満が求められる小流量シナリオ(モデルロードに30秒以上かかる)

デプロイ時のチェックリスト:

  1. 量子化は要件で選ぶ。遅延重視はFP8、VRAM逼迫はINT4、サーバ用途はGPTQ/AWQが万能
  2. enforce_eager=Falseは必ず有効。20%高速化
  3. --max-num-seqsは想定ピーク並列+20%で設定。evict頻発を防ぐ
  4. KV Cache使用率を継続監視し、長期的に85%超なら増設
  5. 複数ノード構成はTensor Parallel + Pipeline Parallelで、256カード超で本番実績あり
  6. Disaggregated Prefill/Decodeは大型兵器。prefillとdecodeを別ノードに分離し、長いpromptのシナリオでスループットをさらに倍増可能。RDMAネットワーク必須

直感に反する結論を1つ。vLLMのボトルネックは今やGPU演算力ではなくスケジューラ側にある。chunked prefill、prefix cache、disaggregatedといった機能は全てスケジューリング層の改善であり、ハードの方が主戦場ではない。vLLMを選ぶとは推論エンジンを選ぶことではなく、スケジューリング哲学を選ぶことなのだ。


完全なドキュメントと最新機能についてはGitHub READMEを参照。対応量子化フォーマット一覧(FP8 / NVFP4 / MXFP4 / INT8 / INT4 / GPTQ / AWQ / GGUF)も同リポジトリにある。

出典: https://github.com/vllm-project/vllm