手里有昇腾卡、想跑 vLLM 的人，卡住的地方通常不在「装没装上」，而在装完之后：版本对不上、镜像起不来、服务起来了但吞吐难看。这篇按「先确认前提、再搭环境、再调参、最后排查」的顺序给一条能照着走的路，只讲判断标准和动作，具体版本号和跑分请到站内页面按当天数字核对。
手里有昇腾卡、想跑 vLLM 的人，卡住的地方通常不在「装没装上」，而在装完之后：版本对不上、镜像起不来、服务起来了但吞吐难看。更麻烦的是，昇腾这条链上很多报错信息会指向一个不相关的模块，让你越查越远。为避免这种情况，整条路要按「先确认前提、再搭环境、再调参、最后排查」推进，每一步都先拿到一个可验证的结果再往下走。
这篇只讲判断标准和可执行动作，不写死任何具体版本号和吞吐数字——昇腾生态的版本强耦合，别人博客里的组合过几周就不适用了，具体对应关系请到站内页面按当天数字核对。下面按四个环节拆开：前提条件、环境搭建、起服务与调优、排查顺序。
先确认你的前提条件够不够
动手装之前先核对三件事：卡型与驱动版本、CANN 与 Python 环境、要跑的模型是不是已经有人在该分支上跑通过。三者缺一项，后面所有报错都会指向错误的方向——你会以为是代码问题，其实是版本问题。这一步花十分钟，能省掉后面几小时的瞎试。
| 要核对的东西 | 去哪对 | 核对到什么程度算过关 |
|---|---|---|
| 卡型与驱动版本 | 站内 compute/gpus 的加速卡规格库 | 你的卡型在目标分支的支持列表里，驱动在要求范围内 |
| CANN 与 Python 环境 | 站内 models/deploy 的部署测算页 | 四者（驱动、CANN、框架侧、vllm-ascend）版本组合能对上 |
| 目标模型 | 站内模型资料库对应的部署说明 | 有明确说明该分支跑通过这个结构，或至少没列在已知不支持里 |
- 昇腾生态的版本是强耦合的：驱动、CANN、torch_npu、vllm-ascend 四者的对应关系，去站内 models/deploy 的部署测算页和 compute/gpus 的加速卡规格库确认，别照搬别人博客里的组合。
- 如果只是想先看看能不能跑，优先在别人验证过的容器镜像里试，跑通了再回头拆依赖；一上来就在宿主机裸装，排错成本最高。
- 不适用的情况：卡是较老型号、或者模型用了该分支还没支持的结构，这时硬调环境不如先换模型或换分支，把精力花在能出结果的组合上。
环境搭建的最短路径
环境搭建的原则是逐层验证，不要攒到最后一起试。按「驱动 → CANN → 框架侧 → vllm-ascend」的顺序，每装完一层就跑一次最小自检：能看到卡、能分配显存。某一层没通过就停在那里解决，别继续装下一层，否则最后报出来的错已经离根因很远了。
- 选容器还是裸机容器胜在依赖隔离和可复现，裸机胜在能改底层。团队里多人共用一台机器时优先容器，避免互相污染环境；自己单机且确定要改底层时才走裸机。
- 逐层装、逐层验每装完一层跑一个最小自检：驱动装完能识别卡，CANN 装完自检能过，框架侧装完能分配显存。哪一层过不去就停在这一层。
- 先小模型冒烟装完先拉一个小模型做一次单请求推理，确认基本链路通了，再上你要用的目标模型。跳过这步，后面无法区分是环境问题还是模型问题。
- 判定环境过关服务能起、能返回一段完整文本、显存占用稳定，这三条同时满足才算环境过关，可以进入调参阶段。
起服务与推理调优：先调什么后调什么
调优要分轮做，每轮只动一个变量。最怕的是一上来就把并发、显存比例、批处理参数全改了，结果吞吐上去了但不知道是哪个参数起的作用，下一次换个模型又得从头试。下面三轮的顺序是从稳到快，不要跳。
| 轮次 | 目标 | 动什么 | 判断标准 |
|---|---|---|---|
| 第一轮 | 先把服务稳定起起来 | 用默认参数，不调 | 能返回完整文本，记录单请求响应时间作为基线 |
| 第二轮 | 提吞吐 | 并发请求数与显存占用比例这两个旋钮，一次只动一个 | 吞吐有提升且请求不失败 |
| 第三轮 | 解决显存吃紧 | 先降上下文长度上限、调显存预留比例 | 单请求延迟不明显劣化 |
- 第一轮只求稳：用默认参数把服务起起来，记录单请求的响应时间作为基线；没有基线，后面的调优全是盲调。
- 第二轮调吞吐：影响最大的通常是并发请求数与显存占用比例这两个旋钮，其次才是批处理相关参数；改完复测，别凭感觉。
- 第三轮调显存：显存吃紧时优先考虑降低单请求的上下文长度上限、调整显存预留比例，而不是立刻换量化版本；量化属于「确实不够用」之后的动作。
- 判断标准：吞吐上去但单请求延迟明显劣化、或者开始出现请求失败，说明调过头了，往回收一档。
卡住时的排查顺序
排查最忌讳跳步。按固定顺序往下走，哪一步断了就停在哪一步：卡与驱动能不能被识别 → CANN 自检能不能过 → 框架层能不能用上 NPU → 模型权重能不能加载 → 服务能不能起 → 能不能出结果。跳着查的后果是，你会在一个下游现象上耗很久，而根因还在上游没解决。
- 报错在加载权重阶段
- 多半是模型格式或权重切分的问题，先核对模型结构而不是环境
- 报错在服务启动后第一次请求
- 多半是显存或参数配置的问题，回到调参那轮逐项排查
- 报错在跑了一段时间之后
- 多半是并发和显存碎片的问题，往回收并发或调整显存预留
还有一个高频误区：环境类报错优先怀疑版本组合，而不是怀疑代码。昇腾这条链上，版本不匹配导致的报错信息经常指向一个不相关的模块，你顺着报错去改代码，改到最后发现是版本没对上。如果冒烟测试就异常，先用站内工具目录里质量检测和校验类页面的口径确认是服务问题还是输出质量问题，避免把两类问题混在一起排。
- 按顺序查，别跳步：卡与驱动识别 → CANN 自检 → 框架层用上 NPU → 权重加载 → 服务启动 → 出结果。
- 环境类报错先查版本组合，再去动代码。
- 冒烟测试就异常时，先分清楚是服务起不来还是服务起来了但输出不对，这两类的排查路径完全不同。
- 确认是输出质量问题而非服务问题时，再去看模型本身和参数设置，不要继续在环境上耗。
常见问题
没有昇腾卡能不能先学 vllm-ascend？
可以，但要知道你在学的是配置流程而不是性能表现。没有卡的话，环境搭不起来、调参也没有反馈，学到的多半是记忆性知识。更划算的做法是先用普通 GPU 把 vLLM 的起服务参数和调参思路摸熟，等拿到卡再补昇腾这层适配，两者在参数逻辑上是相通的。
服务起来了但吞吐很低，先动哪个参数？
先别急着改参数，先量基线：用单并发跑一批请求，记下响应时间，再用你预期的并发量跑一遍看变化曲线。多数情况问题不在参数上，而在并发给得不够、显存预留比例不合适，或者请求长度分布和你的预期不一致。确认这几点之后再去调批处理相关参数，一次只改一个。
昇腾上跑的模型和 GPU 上跑的结果不一致，正常吗？
属于要分情况看：输出措辞不同是正常的，不同硬件和不同算子实现本来就不会逐字一致；但如果是同一个输入下反复出现明显错误、截断或者乱码，那就是适配问题，不是「正常差异」。判断方法是拿一组固定输入两边各跑几次，看错误是不是稳定复现，稳定复现就要往算子适配和版本组合上查。
