vllm-ascend 多模态

你手上有一台昇腾机器的卡，想把一个能读图的多模态模型用 vLLM 起成 OpenAI 兼容接口，结果发现官方文档更多在讲纯文本模型，多模态那条路要自己摸。这篇不重复「昇腾能不能跑 vLLM」这种结论，只给多模态这一支的部署动作清单和排查顺序：从版本与算子对齐、视觉塔权重与处理器加载，到图像预处理、单卡并发怎么估、报错先看哪一层。

你手上有一台昇腾机器，想把能读图的多模态模型用 vLLM 起成 OpenAI 兼容接口，翻文档发现大篇幅在讲纯文本模型，多模态这条支线得自己摸。这篇不讨论昇腾到底能不能跑 vLLM，只给多模态这一支的部署动作清单和排查顺序。

思路很简单：先把环境对齐，再确认视觉塔权重与处理器加载，然后验证图像输入链路，最后才估并发和调性能。顺序反了，你会在错误的地方调参，白花时间。

先把环境和版本对齐，别急着拉模型

起步阶段最忌讳一上来就下载几十 GB 权重。先确认三件事同时成立：昇腾驱动与固件、CANN 与 torch_npu、vllm-ascend 分支，三者要互相匹配。任何一处错位，表现可能是服务能起来但出图结果乱，也可能直接算子报错。

• 驱动、固件、CANN、torch_npu、vllm-ascend 五者的版本组合要成套，别只对其中两个
• 多模态比纯文本多一层视觉塔，视觉侧常用算子和文本侧不是同一批，先跑官方最小可跑样例
• 样例跑通的标准是日志里能看到图像预处理后的张量形状，且首次推理有正常输出
• 如果模型自带自定义算子需要额外编译，先把编译问题解决，再谈后面的调优

权重、处理器与模板：多模态最容易断的地方

多模态权重通常拆成语言模型和视觉塔两部分。加载时要确认两边都被识别到，只加载了语言侧的症状是服务一切正常，但模型完全看不见图，回答跟图毫无关系。

processor 和 chat template 必须和权重同源。图像占位符在模板里的写法各家族不同，模板不对时，模型会「收到图但当成文本读」，这种情况输出往往似是而非，最难判断。

1. 本地拼一条最小图文请求用一张纯色图加一句明确问题，先验证链路能不能通，避免把预处理 bug 误判成模型能力问题
2. 确认图像占位符检查模板里图像 token 的位置和数量是否与图片数一致，多图场景尤其容易漏
3. 对照目录结构拿不准模型的输入格式和目录结构，到站内模型库对照条目再改配置

图像进得来之后：接口与并发怎么估

多模态接口除了 prompt 还要传图像字段。起服务时注意图像的传输方式：走 URL 还是 base64 本地路径。内网环境走本地路径更稳，但要确认服务进程有权限读到那个目录，很多人卡在这里。

显存估算要分两块：语言侧按模型与量化档位估，视觉侧按输入图片分辨率估。高分辨率图会额外吃掉可观显存，所以单卡能带多少并发，取决于你实际喂多大的图，而不是只看模型参数量。

• 先小并发压一遍，记录单张图预处理耗时、首 token 延迟和生成速度
• 再按目标并发往上加，看延迟增长是否线性
• 明显超线性增长，说明卡在显存或预处理，不是算力不够
• 具体档位与并发口径不要照抄别处数字，到站内部署测算页按你的模型和卡型算一遍

出问题按这个顺序排查，别乱试

多模态报错信息往往很长，而且不同层的错误会互相伪装。按下面四层从下往上查，能省掉大量无效尝试。每一层只回答一个问题，答不上来就别往下走。

1. 第一层：服务能不能起起不来多半是驱动、CANN 或算子编译问题，和模型本身无关，先排除环境
2. 第二层：图片有没有被吃进去加日志确认预处理后的张量形状与数值范围，这一步能挡掉大部分「模型瞎说」的假象
3. 第三层：输出质量对不对文字正常但图像描述离谱，通常是 processor 或 chat template 与权重不匹配，不是模型不行
4. 第四层：性能与并发前三层都过了再谈并发、批处理和张量分片，顺序反了会在错误的地方调参

多模态部署的坑，八成不在模型本身，而在版本组合、模板匹配和图像预处理这三处。