大型语言模型(LLM) vLLM 高性能推理落地实战专栏大纲

专栏定位

本专栏以 vLLM 的真实工程使用为主线，从“把模型跑起来”开始，逐步进入 OpenAI 兼容服务、批量推理、KV Cache、调度策略、分布式部署、性能调优、可观测性与源码剖析。每一章均采用「项目背景 -> 剧本式交锋对话 -> 项目实战 -> 项目总结」的四段式结构，让读者在业务场景中理解概念，在可运行实验中验证结论，在源码阅读中建立长期维护能力。

专栏写法坚持“实战为主，理论为辅”：基础篇让新人可以独立部署一个 vLLM 服务；中级篇让开发、测试、运维可以围绕吞吐、延迟、成本和稳定性协作；高级篇面向架构师和资深开发，深入 Engine Core、Scheduler、Worker、PagedAttention、CUDA Graph、KV Transfer 与生产级 SRE 体系。

阅读路线建议

基础篇（第 1-16 章）

核心目标：掌握 vLLM 的核心术语、单机部署、离线推理、OpenAI 兼容服务、常见模型能力与基础故障排查。
源码关联：vllm/entrypoints/、vllm/engine/、vllm/v1/engine/、vllm/config/、examples/basic/。

第1章：vLLM 术语全景与工作原理

定位：专栏开篇，建立统一语系，理解 vLLM 为什么能提升 LLM 推理吞吐。

核心内容：

• 术语词典：LLM、Token、Prompt、Sampling、Prefill、Decode、Batch、KV Cache、PagedAttention、Scheduler、Worker、Engine Core
• vLLM 解决的核心问题：显存碎片、请求排队、动态批处理、长上下文成本、服务吞吐与延迟平衡
• V1 多进程架构：API Server、Engine Core、GPU Worker、DP Coordinator 的职责边界
• 请求生命周期：HTTP 请求 -> Tokenizer -> Scheduler -> Model Runner -> Sampler -> Streaming Response
• 架构图建议：画出 API Server、ZMQ 通信、Engine Core、Scheduler、KV Cache、GPU Worker 与模型执行链路
• 源码关联：vllm/entrypoints/openai/api_server.py、vllm/v1/engine/core.py、vllm/v1/worker/gpu_worker.py

实战目标：用一张架构图讲清楚“一个 Chat 请求如何在 vLLM 中生成第一个 Token 和后续 Token”，并输出团队 Wiki 版本。

第2章：环境准备与安装路线选择

定位：从零搭建可复现实验环境，避免一开始就卡在 CUDA、PyTorch、Python 版本上。

核心内容：

• Python 版本、CUDA/ROCm/TPU/CPU 等硬件路线差异
• uv、虚拟环境、Docker 镜像与源码安装的选择
• NVIDIA CUDA 环境下的最小安装命令与版本检查
• 模型下载源：Hugging Face、ModelScope、离线模型目录
• 常见环境坑：驱动不匹配、glibc、PyTorch 后端、显存不足、Windows 本地开发与 Linux 部署差异
• 源码关联：pyproject.toml、docs/getting_started/quickstart.md、docs/getting_started/installation/

实战目标：准备一台最小 GPU 实验机，完成 vLLM 安装，运行 vllm –help、python -c "import vllm" 并记录环境清单。

第3章：离线批量推理入门

定位：先不启动服务，用 Python API 跑通最小推理闭环。

核心内容：

• LLM 类与 SamplingParams 的基本用法
• prompts 列表、批量生成与 RequestOutput 结构
• generation_config 与 vLLM 默认采样参数的关系
• Instruct/Chat 模型为什么需要 Chat Template
• 输出解析、异常处理与最小测试脚本组织方式
• 源码关联：vllm/entrypoints/llm.py、examples/basic/offline_inference/

实战目标：编写一个 offline_inference.py，对 10 条业务提示词批量生成结果，并统计总耗时、平均输出 Token 数和失败样本。

第4章：OpenAI 兼容服务快速上手

定位：把 vLLM 变成一个可被业务系统调用的 HTTP 推理服务。

核心内容：

• vllm serve 的启动方式与常用参数
• Chat Completions、Completions、Responses、Embeddings 等 API 能力边界
• OpenAI Python SDK 的 base_url、api_key、model 参数适配
• extra_body 传递 vLLM 扩展参数
• Request ID、流式输出、超时与重试的基础处理
• 源码关联：vllm/entrypoints/cli/main.py、vllm/entrypoints/openai/api_server.py、vllm/entrypoints/openai/

实战目标：启动一个 OpenAI 兼容服务，用 curl 和 OpenAI SDK 分别完成 Chat 请求、流式请求和异常请求验证。

第5章：采样参数与生成质量调试

定位：理解 temperature、top_p、top_k 等参数如何影响输出质量与稳定性。

核心内容：

• temperature、top_p、top_k、max_tokens、stop、presence_penalty、frequency_penalty 的直观含义
• 贪心解码、随机采样和业务可控性的取舍
• generation_config.json 对线上服务的隐性影响
• 低温客服、高温创作、结构化抽取等场景参数模板
• 常见问题：输出太短、重复、跑题、无法停止、JSON 不合法
• 源码关联：vllm/sampling_params.py、vllm/v1/sample/

实战目标：设计 3 组参数模板，分别服务“客服问答、营销文案、信息抽取”，并对同一批提示词做生成效果对比。

第6章：Prompt、Chat Template 与对话协议

定位：解决“模型能跑但回答不像预期”的第一类问题。

核心内容：

• Base 模型、Instruct 模型、Chat 模型的输入差异
• Chat Template 的作用、加载来源与常见错配
• system/user/assistant/tool 消息结构
• 多轮对话的历史裁剪与上下文预算
• 提示词注入风险与服务端输入规范
• 源码关联：vllm/transformers_utils/、vllm/entrypoints/openai/chat_completion/

实战目标：为一个企业知识库助手设计 Chat 请求模板，验证无模板、错误模板、正确模板三种情况下的输出差异。

第7章：模型加载、权重格式与显存预算

定位：让读者知道模型为什么加载慢、为什么爆显存，以及如何提前估算资源。

核心内容：

• 模型目录结构：config、tokenizer、权重文件、generation_config
• dtype、max_model_len、gpu_memory_utilization、swap_space 等参数
• safetensors、分片权重与本地缓存
• CPU 内存、GPU 显存、KV Cache 显存的基本估算
• 小模型实验到大模型部署的迁移路径
• 源码关联：vllm/config/、vllm/model_executor/model_loader/

实战目标：选择一个 1B/3B 级别模型，记录不同 dtype、max_model_len、gpu_memory_utilization 下的启动日志与显存占用。

第8章：结构化输出与 JSON 结果约束

定位：把“会聊天”的模型变成“能接业务系统”的稳定组件。

核心内容：

• JSON 输出不稳定的业务风险
• structured_outputs、choice、regex、schema 等约束思路
• 信息抽取、分类、路由决策的典型请求格式
• 结构化输出与采样参数的配合
• 失败兜底：重试、校验、降级、错误码设计
• 源码关联：vllm/entrypoints/openai/protocol.py、vllm/entrypoints/openai/

实战目标：实现一个“工单自动分类”接口，要求模型只返回合法 JSON，并用 20 条样例验证成功率。

第9章：Embedding、Pooling 与检索增强基础

定位：从生成模型扩展到向量检索、排序和语义匹配场景。

核心内容：

• Generative Model 与 Pooling Model 的区别
• Embeddings API、Classify、Score、Token Embed 的适用场景
• RAG 基础链路：切分、向量化、检索、重排、生成
• 向量维度、归一化、批量大小与吞吐
• 与向量数据库的集成边界
• 源码关联：vllm/entrypoints/pooling/、docs/models/pooling_models/

实战目标：构建一个最小 RAG Demo：用 vLLM 生成文档向量，检索 Top 3 片段，再调用 Chat API 回答问题。

第10章：多模态输入入门

定位：理解 vLLM 如何服务图文、音频等多模态模型。

核心内容：

• 文本模型与多模态模型的请求差异
• 图片 URL、本地图片、Base64 输入的处理方式
• Vision、Audio 相关 OpenAI 兼容参数
• 多模态数据加载线程与 CPU 资源
• 多模态服务的延迟、带宽和安全注意事项
• 源码关联：vllm/multimodal/、vllm/entrypoints/openai/chat_completion/、docs/features/multimodal_inputs.md

实战目标：部署一个视觉语言模型，完成图片问答接口，并记录图片大小、并发数对首 Token 延迟的影响。

第11章：Docker 部署与服务参数固化

定位：把实验脚本变成可交付、可迁移、可回滚的服务单元。

核心内容：

• 官方 Docker 镜像与源码镜像的区别
• GPU 容器运行参数、模型目录挂载、端口暴露
• 启动参数固化：模型名、dtype、max_model_len、并行参数、日志级别
• 环境变量、镜像标签、模型版本的变更管理
• 容器启动失败的排查路径
• 源码关联：docs/deployment/docker.md、docker/

实战目标：编写一个可复用的 docker run 或 Docker Compose 示例，完成模型挂载、服务启动和健康检查。

第12章：压测入门与吞吐延迟指标

定位：建立 LLM 服务的性能度量方法，而不是只看 QPS。

核心内容：

• TTFT、TPOT、ITL、E2E Latency、Throughput 的含义
• 输入 Token、输出 Token、并发数与延迟的关系
• vLLM benchmark 工具与常见压测脚本
• 在线服务压测与离线批处理压测的差异
• 压测误区：短 Prompt 代表不了生产、平均值掩盖 P99
• 源码关联：benchmarks/、docs/benchmarking/

实战目标：用同一个模型分别测试 1、4、16、64 并发下的 TTFT、TPOT、P95/P99 延迟，输出简单报告。

第13章：日志、Metrics 与基础可观测性

定位：让服务出问题时有数据可查，而不是靠猜。

核心内容：

• API Server 日志、Engine 日志、请求 ID 的关联
• /metrics 端点与 Prometheus 指标类型
• 核心指标：请求数、Token 数、队列长度、KV Cache 使用率、GPU 利用率、错误率
• Grafana 最小大盘设计
• 指标版本兼容与隐藏指标策略
• 源码关联：vllm/engine/metrics.py、vllm/v1/metrics/、docs/usage/metrics.md

实战目标：接入 Prometheus 抓取 vLLM /metrics，制作一个包含吞吐、延迟、错误率和 KV Cache 使用率的基础看板。

第14章：常见错误与故障排查 SOP

定位：系统整理新手最容易遇到的问题，形成可复用排查手册。

核心内容：

• 安装错误：CUDA、PyTorch、驱动、依赖冲突
• 启动错误：模型路径、显存不足、dtype 不支持、max_model_len 过大
• 请求错误：400、401、404、422、500 的常见原因
• 输出异常：乱码、空回复、重复输出、JSON 失败
• 性能异常：TTFT 高、吞吐低、GPU 利用率低、CPU 打满
• 源码关联：docs/usage/troubleshooting.md、vllm/logger.py

实战目标：模拟 8 类常见故障，记录报错日志、根因、修复命令和复盘模板。

第15章：测试策略与接口验收

定位：让 vLLM 服务可以进入 CI/CD 和业务验收流程。

核心内容：

• 单接口 smoke test、回归测试、性能基线测试的分层
• Chat、Completions、Embeddings、结构化输出的验收用例
• 非确定性输出的断言方式：格式、关键词、长度、语义相似度
• 流式响应测试与超时测试
• 灰度前的验收清单
• 源码关联：tests/entrypoints/、tests/v1/、examples/

实战目标：编写一套 pytest + OpenAI SDK 的接口验收脚本，覆盖正常请求、错误请求、流式请求和 JSON 输出校验。

第16章：【基础篇综合实战】搭建企业级 vLLM 问答服务

定位：融会贯通基础篇知识，交付一个可演示、可压测、可观测的单机服务。

核心内容：

• 场景：为公司内部知识库搭建 LLM 问答 API
• 需求拆解：模型选择、环境安装、OpenAI 兼容服务、Prompt 模板、结构化输出、日志指标、压测报告
• 分步实现：Docker 部署、客户端调用、RAG 简化链路、Prometheus 监控、pytest 验收
• 验收标准：接口可用、P95 延迟达标、错误率可观测、故障排查文档完整
• 交付物：部署脚本、客户端示例、压测报告、监控看板截图说明、运维 SOP

实战目标：在单机 GPU 上交付一个“内部制度问答助手”，完成从部署到验收的闭环。

中级篇（第 17-31 章）

核心目标：掌握 vLLM 的生产架构、调度、KV Cache、并行、量化、LoRA、推测解码、K8s 部署、监控告警与性能调优。
源码关联：vllm/v1/engine/、vllm/v1/executor/、vllm/v1/worker/、vllm/distributed/、vllm/lora/、vllm/model_executor/layers/quantization/。

第17章：V1 多进程架构与资源 sizing

定位：从“服务能跑”进入“服务如何分进程协同”的生产视角。

核心内容：

• API Server、Engine Core、GPU Worker、DP Coordinator 的进程职责
• TP、PP、DP 与进程数量的关系
• ZMQ 通信、请求路由与多 API Server 拓扑
• CPU 线程、媒体加载线程、Tokenizer 资源的 sizing
• 单机多卡与多机多卡的部署差异
• 源码关联：vllm/v1/engine/core.py、vllm/v1/executor/multiproc_executor.py、vllm/v1/engine/coordinator.py

实战目标：分别启动单卡、4 卡 TP、8 卡 DP+TP 三种配置，绘制进程拓扑图并记录 CPU/GPU 资源占用。

第18章：Scheduler 与连续批处理机制

定位：理解 vLLM 吞吐提升的核心调度逻辑。

核心内容：

• Prefill 与 Decode 两阶段的调度差异
• Continuous Batching 与静态 batch 的区别
• 请求队列、运行队列、抢占、等待与完成状态
• 长短请求混部对公平性和 P99 的影响
• 调度参数如何影响吞吐和首 Token 延迟
• 源码关联：vllm/v1/core/scheduler.py、vllm/v1/engine/core.py

实战目标：构造短 Prompt、长 Prompt、长输出混合流量，对比不同调度参数下的 TTFT、TPOT 和 P99。

第19章：KV Cache、PagedAttention 与显存治理

定位：深入理解 vLLM 管理长上下文和高并发的关键能力。

核心内容：

• KV Cache 在 Prefill/Decode 中的作用
• Block、Block Table、Cache Hit、Cache Eviction 的概念
• PagedAttention 如何减少显存碎片
• KV Cache 使用率与并发上限的关系
• max_model_len、block_size、gpu_memory_utilization 的调优思路
• 源码关联：vllm/v1/core/kv_cache_manager.py、vllm/v1/attention/、csrc/attention/

实战目标：通过不同上下文长度和并发数压测，观察 KV Cache 使用率、请求等待和 OOM 边界。

第20章：前缀缓存与重复请求加速

定位：让系统在 RAG、Agent 和多轮对话中复用相同上下文，减少重复计算。

核心内容：

• Automatic Prefix Caching 的适用场景
• 系统提示词、知识库片段、工具说明的前缀复用
• 命中率、缓存粒度与内存占用的权衡
• 前缀缓存对 TTFT 和吞吐的影响
• 失效场景：动态时间、用户私有上下文、随机拼接 Prompt
• 源码关联：docs/features/automatic_prefix_caching.md、vllm/v1/core/kv_cache_manager.py

实战目标：构造 1000 条共享系统提示词的请求，开启/关闭前缀缓存，对比 TTFT、吞吐和 KV Cache 命中情况。

第21章：并行策略：TP、PP、DP 与专家并行

定位：掌握多 GPU 部署时模型切分、请求分发和通信开销的基本决策。

核心内容：

• Tensor Parallel、Pipeline Parallel、Data Parallel 的区别
• MoE 模型中的专家并行与负载均衡问题
• NCCL 通信、跨卡带宽与拓扑约束
• 单机多卡、跨机多卡、异构卡的选择建议
• 并行参数与模型大小、吞吐、延迟、可用性的关系
• 源码关联：vllm/distributed/、vllm/v1/executor/、vllm/model_executor/layers/fused_moe/

实战目标：对同一模型测试 TP=1/2/4 的吞吐与延迟，分析什么时候增加 GPU 反而收益下降。

第22章：量化部署与成本优化

定位：在效果、吞吐、显存和成本之间找到可接受平衡。

核心内容：

• FP16、BF16、FP8、INT8、INT4 的基本差异
• AWQ、GPTQ、GGUF、torchao、compressed-tensors 等路线
• 量化模型加载参数与兼容性检查
• 量化对输出质量、吞吐和显存的影响
• 生产验收：质量集、回归指标、灰度策略
• 源码关联：vllm/model_executor/layers/quantization/、docs/features/quantization/

实战目标：选择一个原始模型和一个量化模型，比较显存占用、吞吐、P95 延迟和业务样例通过率。

第23章：LoRA 与多租户模型服务

定位：用一个基础模型服务多个业务微调版本，降低部署成本。

核心内容：

• LoRA、Adapter、基础权重与增量权重的关系
• vLLM LoRA 加载、切换与请求参数
• 多租户隔离：模型权限、Adapter 版本、请求路由
• LoRA 与量化、并行、缓存的兼容性
• 文件系统与 Hugging Face Hub Resolver 的使用
• 源码关联：vllm/lora/、vllm/plugins/lora_resolvers/

实战目标：部署一个基础模型和两个 LoRA 适配器，用请求参数切换业务风格，并验证并发请求隔离。

第24章：推测解码与低延迟优化

定位：理解如何用草稿模型或 n-gram 等技术降低生成延迟。

核心内容：

• Speculative Decoding 的基本流程：draft、verify、accept/reject
• n-gram、EAGLE、MTP、并行草稿模型等路线
• 接受率、草稿成本与总吞吐的关系
• 适用场景：短响应客服、代码补全、高并发聊天
• 监控指标与调优方法
• 源码关联：vllm/spec_decode/、docs/features/speculative_decoding/

实战目标：为一个聊天模型开启推测解码，对比开启前后的 TPOT、吞吐和输出一致性。

第25章：工具调用、结构化推理与 Agent 接入

定位：让 vLLM 服务具备承接 Agent、函数调用和业务编排的能力。

核心内容：

• Tool Calling 的请求协议与模型支持条件
• 工具 JSON Schema、parallel_tool_calls 与结果校验
• Reasoning Parser 与思维链输出处理
• Agent 系统中的超时、幂等、重试和安全边界
• 与 LangChain、LlamaIndex、LiteLLM 等框架的集成点
• 源码关联：vllm/tool_parsers/、vllm/reasoning/、docs/features/tool_calling.md

实战目标：实现一个“查天气 + 查日程”的双工具调用 Demo，验证工具选择、参数解析和失败重试。

第26章：Kubernetes 与生产部署模式

定位：把单机服务扩展到可调度、可伸缩、可发布的云原生形态。

核心内容：

• GPU 节点、镜像、模型 PVC、服务暴露与健康检查
• Deployment、StatefulSet、DaemonSet 的选择
• KServe、Ray、Helm、生产栈集成路线
• 滚动发布、蓝绿发布、金丝雀发布
• 多模型服务的资源隔离与队列治理
• 源码关联：docs/deployment/k8s.md、docs/deployment/integrations/、docs/deployment/frameworks/

实战目标：在 K8s 中部署一个 vLLM 服务，配置 GPU 资源、模型挂载、Service、Ingress 和 Prometheus 抓取。

第27章：监控告警与容量规划

定位：建立生产系统的 SLO、告警和扩容决策依据。

核心内容：

• LLM 服务 SLO：可用性、TTFT、TPOT、P99、错误率、排队时长
• Prometheus 指标、Grafana 大盘与日志关联
• GPU 利用率、显存利用率、KV Cache 使用率的告警阈值
• 容量模型：请求并发、输入输出 Token、模型大小、显存预算
• 成本模型：GPU 小时、吞吐、缓存命中率、量化收益
• 源码关联：docs/usage/metrics.md、docs/design/metrics.md、vllm/v1/metrics/

实战目标：为一个日均 100 万次调用的服务设计容量规划表和 10 条核心告警规则。

第28章：性能调优方法论

定位：系统掌握 vLLM 调优路径，避免盲目改参数。

核心内容：

• 性能问题分类：CPU 瓶颈、GPU 瓶颈、网络瓶颈、调度瓶颈、模型瓶颈
• 参数调优：max_num_batched_tokens、max_num_seqs、max_model_len、gpu_memory_utilization
• Chunked Prefill、CUDA Graph、编译优化、异步输出处理
• 压测数据采集、变量控制与对比实验设计
• 调优报告模板：现象、假设、实验、结论、回滚条件
• 源码关联：docs/configuration/optimization.md、docs/design/cuda_graphs.md、vllm/config/

实战目标：对一个低吞吐服务做完整调优实验，至少提升 30% 吞吐或降低 20% P95 延迟，并解释收益来源。

第29章：分布式故障排查与稳定性治理

定位：面对多进程、多 GPU、多节点故障时，建立分层排查能力。

核心内容：

• API Server、Engine Core、Worker、NCCL、模型加载的故障边界
• ZMQ 通信异常、Worker 退出、GPU OOM、NCCL hang 的定位
• 日志、指标、进程、GPU、网络的联合诊断
• 超时、限流、熔断、降级与自动重启策略
• 分布式场景下的复盘与演练
• 源码关联：docs/serving/distributed_troubleshooting.md、vllm/distributed/、vllm/v1/executor/

实战目标：模拟 Worker 崩溃、NCCL 配置错误、显存耗尽、请求堆积四类故障，输出排查 SOP。

第30章：安全、权限与服务治理

定位：把 vLLM 从内部实验服务提升为可暴露给业务团队的受控能力。

核心内容：

• API Key、网关鉴权、租户隔离与请求审计
• Prompt 注入、越权工具调用、敏感信息泄露的风险
• 输入输出过滤、内容安全、速率限制与配额
• 模型来源、权重文件、依赖镜像的供应链安全
• 日志脱敏与合规留存
• 源码关联：docs/usage/security.md、vllm/entrypoints/openai/

实战目标：在 vLLM 前增加一个轻量 API 网关，实现 API Key 鉴权、租户限流、日志脱敏和异常审计。

第31章：【中级篇综合实战】构建生产级 LLM 推理平台

定位：融会贯通中级篇知识，构建一个面向多业务团队的生产推理平台。

核心内容：

• 场景：企业内部 10 个业务团队共享 LLM 推理能力
• 功能需求：多模型路由、LoRA 多租户、量化降本、监控告警、容量规划、灰度发布、安全治理
• 架构设计：API Gateway + vLLM 集群 + Prometheus/Grafana + 日志平台 + 模型仓库
• 分步实现：K8s 部署、模型服务模板、压测基线、告警规则、租户配额、故障演练
• 验收标准：SLO 达标、成本可解释、故障可定位、发布可回滚

实战目标：交付一套生产级 vLLM 推理平台设计与最小可运行环境，支撑至少 2 个模型和 3 个租户。

高级篇（第 32-40 章）

核心目标：从源码和内核层面理解 vLLM，掌握调度器、Worker、Model Runner、PagedAttention、CUDA Graph、自定义扩展、KV Transfer 与极端场景 SRE。
源码关联：vllm/v1/、vllm/model_executor/、vllm/compilation/、vllm/distributed/kv_transfer/、csrc/、tests/。

第32章：源码阅读路线与工程结构

定位：为高级篇建立源码地图，避免一上来迷失在庞大目录中。

核心内容：

• 入口层：LLM、CLI、OpenAI API Server
• Engine 层：V0 与 V1 的代码边界，Engine Core 的职责
• Executor/Worker 层：单进程、多进程、GPU Worker
• Model Executor 层：模型加载、模型定义、层实现、采样
• csrc 与 kernels：Attention、通信、量化、自定义算子
• 源码关联：vllm/entrypoints/、vllm/v1/、vllm/model_executor/、csrc/

实战目标：绘制一张源码阅读路线图，从 vllm serve 入口追踪到一次模型 forward 调用。

第33章：Engine Core 与请求生命周期源码剖析

定位：深入理解请求如何进入核心循环、被调度、执行并返回。

核心内容：

• Engine Core 初始化、主循环与请求队列
• 请求添加、取消、完成与异常处理
• API Server 与 Engine Core 的通信协议
• 输出回传、流式响应和 backpressure
• 请求生命周期日志插桩方法
• 源码关联：vllm/v1/engine/core.py、vllm/v1/engine/async_llm.py、vllm/v1/engine/output_processor.py

实战目标：给一次 Chat 请求加上 request_id 追踪日志，输出从 API Server 到 Engine Core 再到响应返回的调用链。

第34章：Scheduler 源码与调度策略改造

定位：从源码层面掌握 vLLM 如何决定“本轮该跑哪些请求”。

核心内容：

• Scheduler 的核心数据结构与状态转换
• Prefill、Decode、Resume、Preempt 的处理流程
• KV Cache 分配失败时的决策
• 调度公平性、吞吐优先与延迟优先的权衡
• 自定义调度策略的设计边界
• 源码关联：vllm/v1/core/scheduler.py、vllm/v1/core/kv_cache_manager.py

实战目标：阅读并注释 Scheduler 主流程，添加一项调度统计指标，观察混合负载下的请求等待时间。

第35章：Worker、Model Runner 与执行后端

定位：理解 GPU Worker 如何加载模型、准备输入并触发模型执行。

核心内容：

• GPU Worker 的启动、设备绑定和内存初始化
• Model Runner 的输入准备、forward 调用和输出处理
• CUDA Graph 捕获与普通 eager 执行的差异
• 多后端支持：CUDA、ROCm、CPU、XPU 等扩展边界
• Worker 崩溃与恢复的源码排查方法
• 源码关联：vllm/v1/worker/gpu_worker.py、vllm/v1/worker/gpu_model_runner.py、vllm/platforms/

实战目标：在 Model Runner 关键路径插入 profiling 日志，统计一次 step 中输入准备、forward、采样各阶段耗时。

第36章：PagedAttention Kernel 与 KV Cache 内存布局

定位：进入 vLLM 高性能推理的内核层，理解注意力计算和缓存访问的底层机制。

核心内容：

• Query、Key、Value、Block、Thread Group、Warp、Grid 等内核术语
• KV Cache 的块化存储与 block table 查找
• PagedAttention Kernel 的访存模式和并行粒度
• FlashAttention、PagedAttention 与普通 Attention 的差异
• 内核调试和性能分析的基本工具
• 源码关联：docs/design/paged_attention.md、csrc/attention/、vllm/v1/attention/

实战目标：结合源码和示意图讲解一个 Decode Token 如何读取分块 KV Cache，并用 Nsight 或日志观察 kernel 调用。

第37章：编译优化、CUDA Graph 与算子融合

定位：理解 vLLM 如何减少 Python/Kernel 调度开销并提升 GPU 利用率。

核心内容：

• CUDA Graph 的捕获、复用与限制
• torch.compile、Inductor Pass 与自定义编译流程
• 算子融合、MoE Kernel、量化 Kernel 的性能收益
• 动态 shape、批大小变化与 graph 复用问题
• 编译缓存、warmup 与线上发布注意事项
• 源码关联：vllm/compilation/、docs/design/cuda_graphs.md、docs/design/fusions.md

实战目标：对比 CUDA Graph 开启/关闭时的 step latency，并分析哪些请求形态无法充分复用 graph。

第38章：自定义模型、插件与扩展机制

定位：从使用者进入贡献者视角，掌握如何让新模型或新能力接入 vLLM。

核心内容：

• 新模型接入流程：配置、权重映射、forward、测试
• 多模态模型、Pooling 模型、Transcription 模型的扩展差异
• LoRA Resolver、插件注册与自定义参数
• 自定义 Logits Processor、Tool Parser、Reasoning Parser
• 贡献测试、文档和兼容性要求
• 源码关联：vllm/model_executor/models/、vllm/plugins/、vllm/logits_process.py、docs/contributing/model/

实战目标：以一个简化模型或自定义解析器为例，完成从代码实现到测试用例再到文档说明的最小贡献闭环。

第39章：KV Transfer、跨节点缓存与极端性能 SRE

定位：面向大规模部署，理解跨实例缓存、超长上下文和极端流量治理。

核心内容：

• KV Transfer 的业务背景：长上下文、Prefill/Decode 分离、缓存复用
• NIXL、Mooncake、HF3FS 等连接器的使用边界
• 跨节点缓存的一致性、租约、回收与故障处理
• 极端场景：突发流量、超长 Prompt、热点前缀、GPU 局部故障
• SRE 策略：限流、排队、降级、隔离、演练、容量水位
• 源码关联：vllm/distributed/kv_transfer/、docs/features/nixl_connector_usage.md、docs/design/nixl_kv_cache_lease.md

实战目标：设计一个 Prefill/Decode 分离的长上下文服务方案，说明 KV 传输链路、失败兜底和容量水位告警。

第40章：【高级篇综合实战】从源码到生产的 vLLM 推理系统优化

定位：把高级篇源码理解转化为一次完整的生产优化项目。

核心内容：

• 场景：某业务高峰期 TTFT 和 P99 延迟超标，GPU 成本持续上升
• 诊断路径：指标分析、压测复现、Scheduler 日志、KV Cache 水位、Worker profiling、kernel 观察
• 优化方案：参数调优、前缀缓存、量化、并行策略、CUDA Graph、LoRA 多租户、SRE 降级
• 源码改造：添加调度统计指标或轻量自定义策略，并补充测试
• 验收标准：P99 下降 30%、吞吐提升 40%、错误率不升高、回滚方案明确
• 交付物：优化报告、源码补丁、测试结果、监控看板、故障演练记录

实战目标：完成一次端到端 vLLM 性能与稳定性优化演练，产出可被架构评审和运维接手的技术方案。

附录与资源

附录 A：源码阅读路线图

附录 B：实验环境建议

• 入门环境：Linux + Python 3.12 + uv + 单张 16GB 以上 NVIDIA GPU
• 中级环境：单机 2-4 张 GPU，用于 TP、LoRA、量化、压测和监控实验
• 高级环境：多机多卡或至少一套可模拟多进程/多 Worker 的测试环境
• 兜底环境：无 GPU 时优先阅读源码、跑 CPU 小模型示例和接口协议测试
• 版本策略：记录 vLLM commit、模型版本、镜像标签、驱动版本、CUDA/PyTorch 版本

附录 C：推荐工具链

• 环境管理：uv、Docker、Docker Compose
• 服务调用：curl、OpenAI Python SDK、httpx
• 压测：vLLM benchmark、wrk、hey、locust
• 监控：Prometheus、Grafana、dcgm-exporter
• 日志：Loki、ELK、jq
• GPU 观察：nvidia-smi、Nsight Systems、Nsight Compute
• 源码调试：pytest、py-spy、cProfile、torch.profiler
• 部署：Kubernetes、Helm、KServe、Ray

附录 D：每章文章模板提醒

每章独立成文件时，建议统一使用以下结构：

附录 E：综合实战验收清单

• 功能：接口可调用，输出格式符合业务约束
• 性能：记录 TTFT、TPOT、吞吐、P95/P99、GPU 利用率和 KV Cache 使用率
• 稳定性：具备超时、重试、限流、降级和错误码说明
• 可观测性：日志、指标、Trace ID 或 Request ID 能关联一次请求
• 安全：API Key、租户隔离、日志脱敏、模型来源审计
• 运维：部署脚本、回滚方案、故障排查 SOP、容量规划表