vllm recipe deepseekv4

你拿到一份 DeepSeek 系列权重，想用 vLLM 起服务，结果卡在权重能不能直接加载、张量并行怎么切、显存留多少给 KV 缓存这些具体问题上。这篇不讲框架原理，只给一份可照着走的配置检查表和出错后的排查顺序，帮你把第一次启动需要改的参数一次性定下来。

你拿到一份 DeepSeek 系列权重，想用 vLLM 起服务，结果卡在几个很具体的问题上：权重能不能直接加载、张量并行该切几份、显存里给 KV 缓存留多少、哪些参数必须写死。这篇不讲框架原理，只给一份可照着走的配置检查表和出错后的排查顺序，帮你把第一次启动要改的参数一次性定下来。

下面每一节都按「先确认什么、再改什么、怎么验证」来写。凡是涉及具体数值、支持的量化格式、框架版本对照这类会变的信息，都建议到站内对应页面核对当时的数字，别照搬别人文章里的旧结论。

第一步：先确认手里的权重 vLLM 能不能直接吃

部署失败的案例里，一大半死在加载阶段，根因是权重格式和框架支持范围对不上。先把权重分成两类看：一类是原始权重，通常是分片 safetensors 加一份 config；另一类是社区量化格式，比如 GPTQ、AWQ、FP8 这类。前者一般能直接加载，后者要先确认当前 vLLM 版本是否带了对应的量化后端。

原始分片权重

多个 safetensors 分片 + config，一般可直接加载，切分由框架按并行度处理。

量化权重

GPTQ/AWQ/FP8 等，加载时需要框架有对应后端，缺了会报不认识的量化配置。

config 字段

量化配置字段缺失，或字段声明的精度和权重实际精度不一致，是加载期最常见报错。

• 看模型目录里有没有量化相关配置字段，字段在不在、值对不对，先肉眼过一遍。
• 不要凭模型名字判断兼容性，同名不同发布方的权重结构可能不一样。
• 权重版本和框架版本的对照关系，到 /models/deploy 核对当时的支持范围。
• 拿不准就先只用单卡加载一次，能起来再上并行，能把问题范围缩小一半。

张量并行与流水线并行怎么切

单机多卡优先用张量并行，因为它把每层的计算切开，卡间通信频繁但延迟低，适合机内高带宽互联。流水线并行是把模型按层分段放到不同卡上，通信少但有流水气泡，通常是跨机才考虑。选错方向，后面调多久都补不回来。

张量并行的卡数有个硬约束：要能被注意力头数整除。取 2 的幂这类常见值一般安全，除不尽会直接报头数无法均分的错。跨机场景如果机内带宽不足，更稳的做法是先降并行度、再上量化，而不是硬堆卡数，堆上去往往吞吐不升反降。

1. 确定卡数先按模型能装下的最小卡数起，确认能跑通，再往上加。
2. 写成配置文件把并行度、最大长度、显存比例固化成一份文件存进仓库，换机器只改卡数。
3. 验证起服务后用一组固定请求压一遍，对比不同并行度下的吞吐，确认加卡确实有效。

显存预算：权重、KV 缓存、激活各留多少

显存分配的顺序不能反。先把权重占用算出来，也就是参数量乘以每参数的字节数；再决定给 KV 缓存留多少；剩下的才是激活和框架开销。反过来先设一个大的 KV 缓存，再去加载权重，很容易在起服务阶段直接 OOM。

KV 缓存这块最容易被误判。缓存给太少，服务不会崩，表现是请求排队、延迟变高，很多人会以为是模型本身慢。其实瓶颈在缓存不够，没法同时容纳更多并发序列。上下文长度是乘在 KV 缓存上的系数，开长上下文和开高并发，在同样显存下通常只能选一个。

• 权重占用：参数数量 × 每参数字节数，量化档位直接决定这一项。
• KV 缓存：决定并发上限，给少了表现为排队而不是报错。
• 激活与框架开销：随批大小波动，要留出余量。
• 上下文长度：乘在缓存上的系数，和并发互相挤占。
• 显存测算：按模型和量化方式算，用 /models/deploy 的测算入口核对当时的数字。

起服务时必须显式指定的几类参数

默认值会随框架版本变化，靠默认值跑通的环境，下次升级就可能挂。建议把四类参数全部显式写死：并行度、最大模型长度、显存占用比例、KV 缓存精度。写死的好处是配置可复现，换机器、换镜像时差异一眼可见。

量化权重还要同步指定量化方式，不指定会按全精度读，显存需求直接翻几倍，这是很多人第一次部署量化权重时踩的坑。端口和 API 兼容开关也提前定好，方便后续接上层应用或网关，别等上线前一天才发现接口格式对不上。

跑起来之后怎么判断配置是对的

服务能起来不等于配置合理。先量单请求的首 token 延迟和逐 token 输出速度，这两项反映的是裸算力表现；再看批量并发下的总吞吐。如果单请求很快、批量上不去，瓶颈通常在调度或缓存，而不是算力不够。

1. 压第一组长输入短输出，主要压预填充阶段，看首 token 延迟。
2. 压第二组短输入长输出，主要压解码阶段，看逐 token 速度。
3. 对比两组的瓶颈方向不同，指向不同的调参动作，别只用一种请求压。
4. 记录基线把数值记下来，改量化或并行度后再压一遍做对照。

没有基线就没法判断一次改动是变好还是变坏。换量化档位、改并行度、升级镜像之后，都值得重压一遍并和基线比。速度测试的工具和参照，可以去 /tools/speed-test 看。具体跑出来的数字因机器而异，不用强求对齐别人的结果。

常见报错按这个顺序排查

排错最怕东一榔头西一棒子。按阶段分：加载期报错先看权重格式和量化配置，再看框架版本；运行期 OOM 先降最大长度和并发，再考虑换量化档位。顺序错了会把时间浪费在无关参数上。

还有一种情况是启动成功但请求超时，优先查显存占用比例是不是设得太高，留给缓存的空间不够，其次查卡间通信有没有走错网卡。换了模型版本后行为异常，先回退到上一个能跑的镜像和参数组合，确认是权重问题还是框架问题，再逐步改，别在坏组合上继续调。

量化档位怎么和这套配置配套选

量化的取舍逻辑很简单：显存够就上高精度，能省下大量排查时间；显存卡在临界点，才用量化换并行度或换更大的上下文。量化同时影响权重显存和计算路径，改档位之后吞吐基线要重新压，之前的并发上限不能直接套用。

• 显存宽裕：优先高精度，先把功能跑通再谈优化。
• 显存临界：用量化档位换并发或上下文，二选一别都要。
• 改档位后：必须重压基线，并发上限重新测。
• 选格式前：先确认目标框架版本支持，再看精度损失能否接受。

从测试机搬到生产机的迁移检查表

测试机能跑不代表生产机能跑。迁移时最稳妥的做法是列一张对照表，逐项比对镜像版本、驱动版本、并行度、最大长度、显存比例这五项。任何一项不同，都要重新压一遍，不能默认结果一致。卡型换了即使显存相同也要重测，显存带宽差异会直接体现在解码速度上。

1. 逐项对照镜像、驱动、并行度、最大长度、显存比例，五项一一比对。
2. 重压基线有差异就重压吞吐基线，和生产环境对齐。
3. 留回退组合保留一份能一键回退的参数组合，出问题时不至于现场摸黑。
4. 观察上线上线后看首 token 延迟和排队情况，异常时先回退再分析。

模型换代时也可以沿用这套思路：先比权重格式，再比并行切分，最后比显存预算和基线。中转站和官方渠道的模型可用性、价格变化这类信息，可以到 /price-watch 看当时的情况，避免把配置问题和渠道问题混在一起排查。