vLLMは、PagedAttentionによる効率的な[[KVキャッシュ]]管理と連続バッチングを活用し、高速かつ大規模にスケーラブルな大規模言語モデル推論を実現するフレームワークである。
PagedAttentionとは、KVキャッシュを固定長ブロックに分割しページング管理することで、長文や多数同時リクエストでも効率的にメモリを使える仕組みである。
連続バッチングとは、**リクエストの到着を待たずに動的にまとめて処理し、GPUの利用率を最大化する仕組み**です。
* vLLMの本質は **PagedAttention** を核にした **KVキャッシュのブロック管理**＋**連続バッチング** による高スループット化。プレフィックス共有とコピーオンライトで無駄を極小化。 ([Zenn][1])
* 2025年8月23日時点の最新安定は **v0.10.1.1**（セキュリティ＆重要バグ修正）。0.10系はV0エンジンのクリーンアップが進行中でBreaking Changesあり。新規はV1前提で。 ([GitHub][2])
* スケールは **TP（Tensor Parallel）× PP（Pipeline Parallel）**。単一ノードはPythonマルチプロセス、マルチノードはRayが標準。 ([VLLM Documentation][3])
* デプロイは **OpenAI互換HTTPサーバ**／Helm／Triton Backend。可観測性はPrometheus/Grafana＋OpenTelemetryが実用。 ([VLLM Documentation][4])
* 量子化は **INT4(AWQ/GPTQ)**（重み）＋ **FP8 KVキャッシュ** 等を選択肢にできる（精度/レイテンシ/メモリのトレードオフ）。 ([VLLM Documentation][5])
## 1. コア設計を最短理解
### PagedAttention（KVキャッシュのページング）
* KVを固定長**ブロック**に分割し、**論理ブロック→物理ブロック**をブロックテーブルでマップ。非連続配置OK。
* **Copy-on-Write**でプロンプト共有を安全に実現（同一プロンプト間で物理ブロック共有、更新時のみ複製）。
* これにより断片化・過剰予約を最小化し、長コンテキストや混在リクエストでも高スループットを維持。 ([Zenn][1])
### 連続バッチング（Continuous Batching）
* 到着順に拘らず**トークン毎に動的バッチング**。GPU稼働率を高めつつスループット最大化。Ray Dataでバルク/ストリーミング推論も。 ([VLLM Documentation][6])
### プレフィックスキャッシュ（Prefix Caching）
* 既処理のKVブロックを**ハッシュ**で再利用。V1では**SHA-256対応**や**cache\_salt**でマルチテナントの分離も可能。 ([VLLM Documentation][7], [docs.vllm.com.cn][8])
## 2. スケール戦略（TP/PP/DP）
* **TP＝ノード内のGPU数、PP＝ノード数**が基本指針。例：2ノード×8GPUならTP=8, PP=2。Rayで多ノード配備、単一ノードはPython MP。 ([VLLM Documentation][9])
## 3. 実運用のデプロイ選択肢
* **OpenAI互換サーバ**：`vllm serve`でCompletions/Chat両対応。既存クライアントをほぼそのまま流用可能。 ([VLLM Documentation][4])
* **Kubernetes/Helm**：公式チャートあり。Namespaceごとの設定差分運用が容易。S3モデル配布前提の例も。 ([VLLM Documentation][11], [docs.vllm.com.cn][12])
* **NVIDIA Triton Backend**：Triton上でvLLMをバックエンドとして運用。Speculative Decodingのチュートリアルも提供。 ([VLLM Documentation][13], [NVIDIA Docs][14])
## 4. 量子化・省メモリの実務ノート
* **重みINT4**：AWQ/LLM Compressor(GPTQレシピ)が代表。QPS低〜中でメモリ節約とレイテンシ低減のバランス良。 ([VLLM Documentation][5], [docs.vllm.com.cn][15])
* **KVキャッシュFP8**：`kv_cache_dtype="fp8"`がキモ。KVメモリ圧縮で**同時実行と長文**に効く。 ([VLLM Documentation][16], [docs.vllm.com.cn][17])
* **AMD GPU向け**：QuarkでAWQ/GPTQ/Rotation/SmoothQuant等をサポート。 ([docs.vllm.com.cn][18])
## 5. 機能ピック：LoRA／ツール呼び出し／Spec Decode
* **LoRAホットスワップ**：起動時指定に加え、**実行時に追加/切替**（OpenAI互換サーバ経由も可）。 ([VLLM Documentation][19], [docs.vllm.com.cn][20])
* **Tool Calling**：Outlinesの**ガイド付きデコード**でJSONスキーマ整合を保証（“妥当な形”は保証、質はモデル依存）。 ([VLLM Documentation][21])
* **Speculative Decoding**：Draftモデル/EAGLE等。0.10.0で一部制約や最適化途上の注意点あり。 ([VLLM Documentation][10])
## 6. 可観測性・運用
* **メトリクス**：[[Prometheus]]エンドポイント→[[Grafana]]ダッシュボードの例が公式にあり。V1の重要メトリクス指針も公開。 ([VLLM Documentation][22])
* **分散トレース**：OpenTelemetryでFastAPI経路をJaegerに送出。起動フェーズのトレース拡張も議論中。 ([VLLM Documentation][23], [GitHub][24])
## 7. バージョン動向（2025-08-23基準）
* **最新：v0.10.1.1（2025-08-20）**。HTTPヘッダ制限・`eval()`排除など**セキュリティ修正**含む。
* **v0.10.1（2025-08-18）**：GPT-OSS対応の強化、V0コードの段階的削除、Blackwell/SM100最適化、FP8/DeepGEMM/FlashInferなど多数。移行で**CLI/APIの非互換**に注意。 ([GitHub][2])
## 8. チューニングの実戦チェックリスト
1. **バッチングと上限**
* `--max-num-batched-tokens`/`--max-num-seqs` をワークロードとVRAMで詰める。連続バッチング前提でTPS最適化。 ([VLLM Documentation][6])
2. **KVブロックサイズ**
* 長文主体ならKVブロック大きめ、短文多数なら小さめでフラグメント低減（Prefix Cacheと併用）。 ([Zenn][1], [VLLM Documentation][7])
3. **Prefix Cacheのハッシュと分離**
* 長文/定型プロンプトは**SHA-256有効化**で衝突回避、**cache\_salt**でテナント分離。 ([docs.vllm.com.cn][8])
4. **並列化**
* **TP=ノード内GPU数／PP=ノード数**を原則に、VRAM充足まで増やす。Spec Decode併用時はPPを避ける。 ([VLLM Documentation][9])
5. **量子化**
* まず**FP8 KV**で同時実行改善→足りなければ**INT4重み**（AWQ/GPTQ）を評価。品質要件と相談。 ([VLLM Documentation][16])
6. **観測・SLO**
* **トークン毎レイテンシ**、**プリフィル/デコード比率**、**KV命中率**、**OOM/再ロード**を可視化。Prometheus/Grafana＋OTelでボトルネック特定。 ([VLLM Documentation][25])
## 9. すぐ使えるスニペット
### 9.1 OpenAI互換サーバ（LoRA同時提供）
```bash
# vLLM 起動（LoRA2本を同時提供）
vllm serve meta-llama/Llama-3-8B-Instruct \
--port 8000 \
--enable-lora \
--lora-modules sql-lora=/models/sql-lora qa-lora=/models/qa-lora
```
（クライアントはOpenAI SDK準拠の`/v1/chat/completions`をそのまま叩ける） ([VLLM Documentation][4])
### 9.2 FP8 KVキャッシュ（V1）
```python
from vllm import LLM, SamplingParams
llm = LLM(model="Llama-3.1-8B-Instruct-FP8-KV", kv_cache_dtype="fp8")
out = llm.generate("Tokyo is", SamplingParams(max_tokens=64))
```
（KVメモリ圧縮で同時実行向上） ([VLLM Documentation][16])
### 9.3 Helmでマルチ環境展開
```bash
# namespaceごとに values.yaml を切って環境差分管理
helm upgrade --install --create-namespace \
--namespace vllm-prod vllm charts/vllm -f values-prod.yaml
```
([VLLM Documentation][11])
### 9.4 Tool Calling（JSON整合強制）
```json
{
"model": "your-model",
"messages": [{"role":"user","content":"明日の大阪の天気を教えて"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {"city":{"type":"string"}},
"required": ["city"]
}
}
}]
}
```
（Outlinesによるガイド付きデコードで**必ず妥当なJSON**に） ([VLLM Documentation][21])
## 10. よくある落とし穴
* **v0→v1移行の非互換**：`--task` → `--runner` 等のフラグ変更や、Deprecated APIの削除に注意。固定化している運用スクリプトは要見直し。 ([GitHub][2])
* **Speculative Decodingの期待過多**：データやサンプリング次第で効かないケースがある。まずはA/Bで。 ([VLLM Documentation][10])
* **PPとSpec Decodeの非互換**：大規模分割で使うときは要計画。 ([VLLM Documentation][10])
---
[1]: https://zenn.dev/sinchir0/articles/c72dad5bd2c919?utm_source=chatgpt.com "論文まとめ: vLLM(Paged Attention)"
[2]: https://github.com/vllm-project/vllm/releases "Releases · vllm-project/vllm · GitHub"
[3]: https://docs.vllm.ai/en/latest/serving/parallelism_scaling.html?utm_source=chatgpt.com "Parallelism and Scaling - vLLM"
[4]: https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html?utm_source=chatgpt.com "OpenAI-Compatible Server - vLLM"
[5]: https://docs.vllm.ai/en/latest/features/quantization/auto_awq.html?utm_source=chatgpt.com "AutoAWQ - vLLM"
[6]: https://docs.vllm.ai/en/latest/examples/offline_inference/batch_llm_inference.html?utm_source=chatgpt.com "Batch LLM Inference - vLLM"
[7]: https://docs.vllm.ai/en/latest/design/prefix_caching.html?utm_source=chatgpt.com "Automatic Prefix Caching - vLLM"
[8]: https://docs.vllm.com.cn/en/latest/design/v1/prefix_caching.html?utm_source=chatgpt.com "自动前缀缓存 - vLLM 文档"
[9]: https://docs.vllm.ai/en/v0.8.0/serving/distributed_serving.html?utm_source=chatgpt.com "Distributed Inference and Serving — vLLM"
[10]: https://docs.vllm.ai/en/latest/features/spec_decode.html?utm_source=chatgpt.com "Speculative Decoding - vLLM"
[11]: https://docs.vllm.ai/en/latest/deployment/frameworks/helm.html?utm_source=chatgpt.com "Helm - vLLM"
[12]: https://docs.vllm.com.cn/en/latest/deployment/frameworks/helm.html?utm_source=chatgpt.com "Helm - vLLM 文档"
[13]: https://docs.vllm.ai/en/latest/deployment/frameworks/triton.html?utm_source=chatgpt.com "NVIDIA Triton - vLLM"
[14]: https://docs.nvidia.com/deeplearning/triton-inference-server/user-guide/docs/tutorials/Feature_Guide/Speculative_Decoding/vLLM/README.html?utm_source=chatgpt.com "Speculative Decoding with vLLM — NVIDIA Triton Inference Server"
[15]: https://docs.vllm.com.cn/en/latest/features/quantization/int4.html?utm_source=chatgpt.com "INT4 W4A16 - vLLM 文档"
[16]: https://docs.vllm.ai/en/latest/features/quantization/quantized_kvcache.html?utm_source=chatgpt.com "Quantized KV Cache - vLLM"
[17]: https://docs.vllm.com.cn/en/latest/features/quantization/quantized_kvcache.html?utm_source=chatgpt.com "量化KV缓存 - vLLM 文档"
[18]: https://docs.vllm.com.cn/en/latest/features/quantization/quark.html?utm_source=chatgpt.com "AMD Quark - vLLM 文档"
[19]: https://docs.vllm.ai/en/latest/features/lora.html?utm_source=chatgpt.com "LoRA Adapters - vLLM"
[20]: https://docs.vllm.com.cn/en/latest/features/lora.html?utm_source=chatgpt.com "LoRA 适配器 - vLLM 文档"
[21]: https://docs.vllm.ai/en/latest/features/tool_calling.html?utm_source=chatgpt.com "Tool Calling - vLLM"
[22]: https://docs.vllm.ai/en/v0.7.2/getting_started/examples/prometheus_grafana.html?utm_source=chatgpt.com "Prometheus and Grafana — vLLM"
[23]: https://docs.vllm.ai/en/v0.9.0.1/examples/online_serving/opentelemetry.html?utm_source=chatgpt.com "Opentelemetry - vLLM"
[24]: https://github.com/vllm-project/vllm/issues/19318?utm_source=chatgpt.com "[Feature]: Add opentelemetry tracing for vLLM start up phases"
[25]: https://docs.vllm.ai/en/latest/design/metrics.html?utm_source=chatgpt.com "Metrics - vLLM"