大模型在线服务场景下，传统静态批推理存在显存浪费、排队时延高的痛点。vLLM 凭借 PagedAttention 分页 KV 缓存、连续批处理调度能力，大幅提升 LLM 服务吞吐。vLLM‑MindSpore Plugin 作为对接 MindSpore‑Transformers 的适配插件，把 vLLM 的调度引擎与 MindSpore 图编译、算子融合、混合量化能力结合，在昇腾 Atlas 系列硬件上实现高吞吐 LLM 推理服务。本文从插件架构原理、环境部署、实操调用、性能测试、故障排查完整介绍实践方案，提供可复用代码，帮助开发者快速把 MindSpore‑Transformers 模型转为 vLLM 在线推理服务。

一、vLLM‑MindSpore Plugin 核心原理

vLLM‑MindSpore Plugin 整体分为两层：上层复用原生 vLLM 调度层（Scheduler、BlockAllocator、Cache Engine），负责请求排队、分页 KV 缓存管理、连续批处理；下层替换 Model Executor，接入 MindSpore‑Transformers 作为模型后端，利用 MindSpore 图编译、算子优化、金箍棒量化套件完成昇腾 NPU 上的模型前向计算。

核心能力：

1. PagedAttention 分页 KV 缓存：把 KV 缓存切分为固定大小 Block，显存碎片化大幅降低，支持超高并发请求；

2. MindSpore 图算融合：Prefill/Decode 阶段算子做图编译优化，Cube/Vector 单元异构调度；

3. 无缝对接 MindSpore‑Transformers：直接读取 MindSpore 格式 ckpt 权重，支持 AWQ、SmoothQuant、KVCache 量化；

4. 兼容 OpenAI API 接口，无需修改上层业务代码，即可切换 MindSpore 推理后端。

适用场景：MindSpore‑Transformers 训练产出的大模型，需要对外提供高 QPS 推理服务；不适合极简单请求离线推理场景，该场景建议直接调用 MindSpore 原生推理接口。

二、实验环境准备

• 硬件：Atlas 800T A2（Ascend910B，单机 8 卡）；

• 软件栈：openEuler22.03，CANN8.0.RC2，MindSpore 2.7.1，MindSpore‑Transformers 2.0.0；

• 版本约束：vLLM‑MindSpore Plugin 0.5.1，适配 vLLM‑0.9.1；Python3.9‑3.11；

• 模型：Qwen‑7B MindSpore 权重（MindSpore‑Transformers 导出）。

源码编译安装插件：

# 拉取插件仓库
git clone -b v0.5.1 https://atomgit.com/mindspore/vllm‑mindspore.git
cd vllm‑mindspore
bash install_depend_pkgs.sh
# pip版本大于25.3增加--no‑build‑isolation参数
pip install --no‑build‑isolation .

环境校验脚本，确认插件、MindSpore 导入正常：

python -c "
import mindspore
import vllm_mindspore
print('vLLM‑MindSpore Plugin install ok')
"

设置后端环境变量，指定使用 MindSpore‑Transformers 作为模型后端：

export VLLM_MS_MODEL_BACKEND=MindFormers
export MINDFORMERS_MODEL_CONFIG=/path/to/qwen7b_config.yaml

三、实操：离线推理与启动 API 服务

3.1 离线 Python 调用示例

from vllm import LLM, SamplingParams

# 采样参数配置
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.8,
    max_tokens=256
)

# 初始化LLM，指定MindSpore‑Transformers权重路径
llm = LLM(
    model="/data/mindspore_qwen7b",
    trust_remote_code=True,
    tensor_parallel_size=2, # TP张量并行卡数
    max_model_len=2048,
    block_size=128,
    gpu_memory_utilization=0.85
)

prompts = [
    "请简单介绍昇思MindSpore框架",
    "解释PagedAttention分页缓存原理"
]

outputs = llm.generate(prompts, sampling_params=sampling_params)
for out in outputs:
    prompt = out.prompt
    generated_text = out.outputs[0].text
    print(f"Q:{prompt}\nA:{generated_text}\n")

3.2 启动 OpenAI 兼容 API 服务

vllm‑mindspore serve \
--model /data/mindspore_qwen7b \
--trust‑remote‑code \
--tensor‑parallel‑size 2 \
--max‑model‑len 2048 \
--block‑size 128 \
--gpu‑memory‑utilization 0.85 \
--port 8000

客户端 curl 调用测试：

curl http://127.0.0.1:8000/v1/completions \
‑H "Content‑Type: application/json" \
‑d '{
"model":"qwen7b",
"prompt":"什么是MindSpore‑Transformers",
"max_tokens":128
}'

四、关键调优参数说明

1. block_size：KV 缓存块大小，推荐 128；块过小会增加调度开销，过大造成块内显存浪费；

2. gpu_memory_utilization：NPU 显存占用上限，一般设置 0.8‑0.9，预留部分显存给 MindSpore 图编译临时内存；

3. tensor_parallel_size：张量并行 TP 卡数，大模型开启 TP，多卡拆分权重；

4. max‑num‑seqs：服务最大并发序列，受显存和 block 数量约束。

重要提示：MindSpore 图编译发生在第一次 prefill 请求，首请求会有明显编译耗时，属于正常现象；后续请求直接复用编译后的图，吞吐显著提升。

五、常见问题排查

1. ModuleNotFoundError: No module named 'mindspore' 排查：MindSpore 未安装成功；确认 pip 环境，源码安装时 pip>=25.3 需要增加--no‑build‑isolation参数。

2. 首请求耗时极长，后续请求很快 现象：第一次推理延迟很高，后续请求性能正常。 排查：MindSpore 执行图编译；生产环境建议服务启动后发送预热请求，完成编译再接入业务流量。

3. NPU OOM 显存溢出 排查：调小gpu_memory_utilization，降低max‑num‑seqs并发数；开启 KVCache 量化，减少 KV 缓存显存占用；增大 TP 并行卡数拆分模型权重。

4. 报 aclnn 算子 RuntimeError 排查：CANN 版本与 MindSpore 版本配套关系不匹配，核对官方版本矩阵；升级或者回退 CANN、MindSpore 版本。

5. 权重加载失败，提示 yaml config 找不到 排查：环境变量MINDFORMERS_MODEL_CONFIG指向 MindSpore‑Transformers 的 yaml 配置文件，路径必须正确。

六、性能实测对比

测试硬件 Atlas800T A2，Qwen‑7B 模型，max‑len=2048，对比MindSpore 原生静态批推理

实测结果可见，依托 PagedAttention 分页 KV 缓存和连续批调度，vLLM‑MindSpore Plugin 可以显著提升 MindSpore‑Transformers 模型的服务并发、吞吐，降低长尾时延，适合真实线上业务流量。

七、总结

vLLM‑MindSpore Plugin 打通 MindSpore‑Transformers 训练到高吞吐在线推理链路，保留 MindSpore 图编译、混合量化优势，同时继承 vLLM 成熟调度与分页 KV 缓存能力。开发者可以复用 MindSpore 完整训练微调链路，不需要迁移权重格式，快速上线 OpenAI 兼容的 LLM 推理服务。