vllm 部署模型报错怎么排查

本地或云端起 vLLM 服务时，最容易遇到的不是模型不会跑，而是报错信息又长又杂，看不出卡在哪一层。这篇按「先分清是哪一类错」的思路，把环境依赖、权重加载、显存与并发、服务起不来四类问题拆开，每类给出可执行的排查动作和判断标准。适合已经装好环境、正在调试参数的人；如果你还没选好框架，先去对照 vLLM 和别的推理框架怎么选。

本地或云端起 vLLM 服务，最容易遇到的情况不是模型不会跑，而是报错信息又长又杂，看不出卡在哪一层。同一个 traceback 里可能混着依赖告警、权重提示、显存警告，新手容易从头往下读，结果被第一行无关信息带偏。

这篇按「先分清是哪一类错」的思路，把环境依赖、权重加载、显存与并发、服务起不来四类问题拆开，每类给出可执行的排查动作和判断标准。适合已经装好环境、正在调参数的人；如果你还在选框架阶段，先去站内对照推理框架的选型页面，再回来调部署更省事。

第一步：先把报错归到哪一层

排查效率低，多数时候是因为把不同层的错当成同一类在改。同样一句启动失败，可能是装包阶段就崩了，也可能是模型加载到一半才炸，还可能是服务起来了但请求进不来。先定位层，再谈修法，方向才不会来回横跳。

• 看第一条 traceback 的末尾而不是开头，真正原因往往是被包了好几层的最后一行
• 区分「环境错」和「参数错」：前者换版本能好，后者改启动参数才有用
• 拿不准时先把日志里的关键英文词丢到站内术语词典查一遍，再决定往哪个方向改
• 改之前把完整日志、启动参数、报错时间点记下来，后面回退全靠它

环境与权重：最常见的两类硬伤

这一层占日常报错的大头，但两类问题的表象很像，容易修错方向。依赖不匹配通常在导入阶段就崩，权重问题则要等到读取文件才暴露。先把两者分开，再按固定顺序排查，会快很多。

1. 先确认依赖是否同代核对驱动、推理引擎版本与模型的适配说明是不是同一代，看到导入阶段就崩，基本可以锁定这一层。具体版本对照去站内模型资料库看当时的适配说明，别凭记忆。
2. 再校验权重文件完整性对照分片索引清点文件，缺一个分片就会在加载中途断掉。用文件哈希或体积比对都能验证。
3. 最后看模型类型是否被认识配置里的模型类型如果当前引擎版本还不支持，会在加载时直接报不认识。这种情况换权重版本比改参数更快。
4. 量化权重单独确认格式量化格式和当前引擎支持的量化方式对不上，会在加载中途才炸，排查时别漏掉这一步。

显存与并发：跑起来之后才报的错

模型能加载成功，不代表加并发后还能跑。这类报错往往出现在压测或业务第一次放量时，看着像服务不稳定，本质是显存预算没算明白。先把最小并发跑通，再逐步加量，就能分清是装不下还是撑不住。

显存预算

按权重、激活、缓存三块加总算，别只盯参数量；具体数字到站内部署测算页面按你的卡算一遍

最小并发

单请求、短上下文先跑通，作为后续加压的基准线

调参优先级

先降单次请求的上下文长度上限，再降并发上限，最后才考虑换精度或分片

残留进程

同一张卡跑多个服务时显存是被别人占走的，先确认卡上没有残留进程再谈参数

• 先单独起最小并发，确认能稳定跑通再往上加，一次只动一个变量
• 压测中途失败又伴随显存相关提示，优先怀疑预算不够，而不是模型坏了
• 长上下文请求比短请求更吃缓存，业务侧有长文本时要单独留余量
• 换精度或分片属于最后手段，改完要重新验证输出质量是否符合预期

服务起不来与请求失败：区分是谁的问题

进程活着、端口通、接口正常响应，是三件不同的事。很多人一看到请求失败就去改启动参数，其实问题可能在端口占用或者业务侧的超时设置。先用最简单的探活把边界划清楚。

• 先用最简单的探活请求确认服务本身活着，再去接业务侧的长请求
• 请求报错分清是输入超了限制、格式不对，还是并发排队超时，三种处理方式不一样
• 改端口、改监听地址这类动作，改完立刻重新探活，别攒着一起改
• 高频小请求和低频大请求对并发的影响不同，压测要覆盖真实流量形态

一张排查清单，照着往下走

上面四层是并列关系，但排查顺序有先后。按层往下走，每层都有明确的通过标准，比拿着日志乱翻要省时间。改不动的时候，退回上一次能跑通的配置，先保证有可用版本。

1. 固定现场记录报错时间点、完整日志段落和当时的启动参数，改动一次只改一项，避免越修越乱。
2. 按层过一遍按环境、权重、显存、服务、请求的顺序排查，每一步都有明确的通过标准再往下走。
3. 退回可用版本改不动时退回上一次能跑通的配置，先保证有可用服务，再逐步加参数。
4. 换代留回退路径版本换代时预留回退路径，别在同一个环境里反复升降版本，容易把依赖搞成四不像。