5.1 部署知识地图与 checklist：把核心结论收拢成一张表

5.1 部署知识地图与 checklist：把核心结论收拢成一张表

写到第五章，我特意把前面四章翻了一遍，发现一件事——vLLM 部署 DeepSeek V4 这个事，难点从来不在于"会背几条启动命令"，而在于你能不能在脑子里维护一张知识地图：哪个组件决定什么、瓶颈在哪、出问题该往哪个方向查。这张地图建不起来，遇到陌生问题就只能瞎试；建起来了，你能从原理一路推到具体参数。

所以这一节我不重复前面讲过的细节，而是把整本书的核心结论收拢成一份可复用的部署 checklist，外加一张我自己排查问题时用的知识地图。希望它成为你下次部署前过一遍的工作底稿，或者出问题时的第一份排查参考。

知识地图：vLLM 部署的四个层面

我把整个部署拆成四个层面来看。不是为了对仗工整，是因为我每次排查线上问题，问题总能归到这四层之一里。

第一层：基础认知——你部署的到底是什么。这层要回答的是，DeepSeek V4 这个模型的结构特点是什么（MoE、共享专家、上下文长度）、vLLM 的核心思想是什么（PagedAttention + continuous batching）。这些不是知识点背了就完了，是排查问题的底层逻辑。比如有人问我"为什么我的服务并发上不去"，我从模型结构一查——MoE 模型每个 token 只激活部分专家，但权重全要装显存，显存吃紧导致 KV Cache 池子小，所以并发上不去。这个推理链路就是从基础认知出发的。

第二层：核心模块——vLLM 里谁在决定性能。这层的核心结论是三件事：PagedAttention 管 KV Cache 显存（决定并发能力）、continuous batching 管批处理调度（决定吞吐）、scheduler 管请求排队（决定延迟）。这三个模块互相耦合，调任何一个都会影响其他两个。比如调大 max_num_seqs（连续批处理的最大序列数），吞吐上去了，但每个序列要预留更多 KV Cache 显存，并发请求一多就可能 OOM。理解这种耦合关系，才能避免"调一个参数踩一个坑"。

第三层：进阶原理——高并发的瓶颈怎么定位。这层是真正实战用的。我自己定位性能问题，永远按固定顺序排查：先看 GPU 利用率（nvidia-smi 或 DCGM exporter），利用率低说明算力没吃满，瓶颈在调度或 IO；利用率高但延迟还是大，说明算力到顶了，瓶颈在硬件本身。然后再细分——如果是调度问题，看 vllm:num_requests_waiting 指标是不是堆积；如果是显存问题，看 KV Cache 使用率是不是接近上限；如果是 decode 阶段慢，看是不是 token 级延迟（TPOT，Time Per Output Token）异常。

第四层：实战部署——生产环境缺一不可的组件。这层讲的是 vLLM 本身之外的工程组件：反向代理（nginx/traefik，做负载均衡和会话亲和）、API 网关（限流、鉴权）、监控系统（Prometheus + Grafana + DCGM exporter）、日志系统（ELK 或 Loki）、容器编排（K8s 或 docker-compose）、CI/CD。我见过太多团队 vLLM 本身配得挺好，但没有监控，出问题完全瞎抓。生产部署这些组件是标配，不是可选项。

核心参数的取舍清单

vLLM 的参数几十个，但真正决定性能的就那么几个。我把它们和对应的取舍列成一张表，每次部署我都按这张表核对：

--max-model-len：能跑多长上下文。设大了显存爆炸（KV Cache 按这个预留），设小了业务用不了。我的做法是按业务实际最长 prompt 的 1.2 倍设，不要拉满。

--max-num-seqs：连续批处理的最大序列数。设大了吞吐高，但每个序列要预留 KV Cache，显存吃紧。设小了吞吐低。我从 gpu_memory_utilization × 显存 - 权重 算出 KV Cache 池子大小，再除以平均序列长度的 KV 占用，反推 max-num-seqs 的合理上限。

--gpu-memory-utilization：vLLM 预留多少显存。默认 0.9，意思是吃掉 90% 显存。如果机器上还跑别的（比如其他模型或监控），要调低。但调太低（比如 0.5）会导致 KV Cache 池子太小，并发上不去。

--tensor-parallel-size：张量并行度。和申请的 GPU 数必须一致，多卡部署的核心参数。单卡部署设 1。

--quantization：量化方案。DeepSeek V4 量化版用对应的量化方式（awq、gptq、fp8）。注意要和模型权重实际用的量化方案匹配，不匹配会报错。

--enforce-eager：是否禁用 CUDA Graph。开启省显存但慢，关闭快但占显存。生产环境我通常不开，性能优先。

--swap-space：KV Cache 换出到 CPU 内存的量（GB）。设大了能扛更高并发峰值但慢，设小了 OOM 风险高。我一般设 4-8GB。

这张表里的每个参数都不是"标准答案"，是"取舍点"。你根据自己硬件和业务特征做选择，而不是照抄。

部署前 checklist

我自己每次部署 vLLM 跑 DeepSeek V4 前，必过这样一份清单：

模型与权重：

• 模型仓库路径是 DeepSeek 官方公布的，没有抄错（很多问题来自路径错）。
• 权重完整下载，校验文件大小和官方一致（断点续传可能不完整）。
• 量化版本和 --quantization 参数匹配。

硬件与依赖：

• GPU 数量、显存大小确认，和 --tensor-parallel-size 一致。
• 驱动 / CUDA / cuDNN 版本组合验证过。
• vLLM 版本和模型兼容（DeepSeek V4 这种新模型需要较新的 vLLM）。

vLLM 参数：

• --max-model-len 按业务设，不拉满。
• --max-num-seqs 按 KV Cache 反推。
• --gpu-memory-utilization 考虑同机其他进程。
• 量化参数和权重匹配。

工程组件：

• 反向代理 + 会话亲和（多副本必备）。
• 监控覆盖 GPU 维度（DCGM exporter）和 vLLM 指标。
• 日志收集能查到单次请求级别。
• 容器编排有健康检查和资源 limit。

上线前验证：

• 压测出"并发/吞吐/延迟/显存"四联表。
• 找到延迟拐点，生产并发设拐点的一半。
• 演练一次回滚。
• 跑一组业务相关测试集，确认输出质量。

这份清单看着繁琐，但每次过一遍能挡掉绝大多数线上事故。我自己量化过——认真过清单的部署，上线后第一周的事故率比没过的低一个数量级。

一个真实案例：用知识地图定位问题

光讲 checklist 比较抽象，说一个我帮人排查过的真实案例。某团队 vLLM 部署的 DeepSeek V4 服务，并发一上来延迟从 200ms 飙到 5 秒，他们怀疑"vLLM 有 bug"。

我用知识地图一路排查：先看 GPU 利用率，发现利用率只有 40%，说明算力没吃满，瓶颈不在 GPU。再看 vLLM 指标，vllm:num_requests_waiting 在并发上来时堆积到几百，说明请求在排队。再看 KV Cache 使用率，发现并发 50 的时候 KV Cache 就满了（命中率掉到 60%），新请求没法 batch 进来只能等。

定位到瓶颈在 KV Cache 显存。再查配置——--max-num-seqs 设了 256，但 --max-model-len 设了 64K（业务实际只用 8K），导致每个序列预留了大量 KV Cache，把池子撑爆。把 --max-model-len 调到 16K、--max-num-seqs 调到 128，问题解决，并发能稳定到 100 而不丢请求。

这个排查过程，每一步都不是凭直觉，是基于知识地图——"GPU 利用率低 → 瓶颈在调度 → 看排队和 KV Cache → 找到配置失衡"。如果一开始就瞎改参数，可能调一周也调不到点上。

一些反复出现的"伪问题"

清单之外，我列几个被问过很多次、但其实不是问题的"伪问题"：

"vLLM 启动慢"——大模型加载到显存本来就慢，几分钟正常。慢到十几分钟要么是权重还在现下载，要么是 enforce-eager 没开导致 CUDA Graph 编译耗时长（这种慢可以接受，因为只编译一次）。

"并发 1 延迟就高"——单请求的 prefill 延迟本来就高（要算整个 prompt），这不是问题。看 TPOT（每个输出 token 的延迟）才反映 decode 阶段的性能。

"吞吐上不去"——先确认是不是 batch 没开。vLLM 默认 continuous batching 是开的，但如果你的客户端是同步串行请求（一个请求完了再发下一个），batch 就没用。要用异步并发客户端才能压出 batch 的收益。

"显存没用满是不是浪费"——vLLM 默认会预留显存给 KV Cache，看起来显存没用满是正常的（它预留了峰值余量）。强行调高 --gpu-memory-utilization 到 0.99，反而容易 OOM。

最后说一句

知识地图和 checklist 这两样东西，是这一节最想交付给你的。具体参数会变（vLLM 几乎每两周更新一版）、模型会换代（DeepSeek 出新一代是迟早的）、硬件会迭代，但"按层面定位问题 + 按清单核对配置"这套方法论不会过时。

下一节我会聊进阶方向——投机解码、prefix caching、自研调度这些更前沿的话题。但进阶的前提是基础扎实。这一节的 checklist 你能每次都过一遍，比追任何前沿方向都更有价值。我见过太多团队基础还没稳就去追新技术，最后基础问题反复踩坑，新技术的收益也被基础问题稀释掉。共勉。