昇腾910B部署vLLM-ascend实战指南

在当前大模型加速落地的浪潮中，企业对推理服务的要求早已不再局限于“能跑起来”。高吞吐、低延迟、低成本、易维护——这些才是生产环境下的真实诉求。尤其是在国产算力崛起的背景下，如何在昇腾910B这类NPU平台上实现高效的大模型推理，已经成为许多团队必须面对的技术课题。

我们曾尝试用传统方式部署LLaMA系列模型：手动转换OM格式、编写ACL接口、管理内存池……整个流程耗时数周，且难以扩展。直到引入 vLLM-ascend ——这个由昇腾官方维护的适配层，才真正打通了从开源模型到国产硬件的“最后一公里”。

它不是简单的移植，而是将 vLLM 的核心调度能力与 Ascend 异构架构深度融合的结果。借助 PagedAttention 技术，KV Cache 的显存利用率提升了3–5倍；通过连续批处理（Continuous Batching），并发请求的响应效率成倍增长；更关键的是，Python + OpenAI 兼容 API 的开发模式，让原本复杂的推理工程变得像调用一个函数一样简单。

本文基于在 GitCode 提供的免费昇腾 910B Notebook 环境中的真实部署经验，完整还原了一条可复现、可推广的企业级部署路径。过程中踩过的坑、绕过的弯、验证过的版本组合，都会毫无保留地呈现出来。

---

部署前的关键选择：环境决定成败

很多人以为安装 pip install vllm 就万事大吉，但在昇腾平台，第一步选错镜像，后面全盘皆输。

以 GitCode 平台为例，创建实例时会看到多个容器镜像选项。其中有一个看似合理的：

euler2.9-py38-torch2.1.0-...

别急着点确定。虽然它集成了 PyTorch 2.1.0，但 Python 版本是 3.8，而 vLLM >= 0.9.0 在其 pyproject.toml 中明确声明：

requires_python = ">=3.9, <3.12"

这意味着 pip 会在解析依赖时直接过滤掉所有不满足条件的包——哪怕你指定 vllm==0.9.1，也会报出“No matching distribution found”。

正确的做法是选择带有 py3.11 标识的镜像：

ubuntu22.04-py3.11-cann8.2.rc1-torch2.1.0-...

这个组合几乎是目前最稳妥的选择：
- Python 3.11 满足 vLLM 的最低要求；
- Ubuntu 22.04 软件源丰富，apt 安装工具链更顺畅；
- CANN 8.2 RC1 支持最新的图优化和异步执行特性；
- Torch 2.1.0 与 vLLM-ascend 官方推荐版本一致。

📌 经验之谈：如果你发现后续安装总是在 _C 模块上失败，不妨先回头检查一下 Python 版本。这一步看似微不足道，实则是整个部署链条中最容易被忽视的致命点。

---

确认硬件状态：别让驱动拖后腿

进入实例后，第一件事不是急着写代码，而是确认 NPU 是否就绪。

执行命令：

npu-smi info

理想输出应包含类似内容：

============== NPU INFO ==============
Soc Name: Ascend910B3
Health: OK
Temperature: 45°C
Utilization: 0%
Driver Version: 8.2.RC1
Firmware Version: 8.2.0

如果 Health 显示异常，或者设备数量为0，那说明驱动或固件未正确加载。这种情况常见于定制化镜像或资源抢占场景。

解决方法通常是联系平台支持重新初始化环境。毕竟，在没有物理访问权限的情况下，底层驱动问题很难靠用户自行修复。

一旦确认硬件正常，就可以进入下一步——构建干净的 Python 环境。

---

构建隔离环境：为什么不能跳过虚拟环境？

GitCode Notebook 默认运行在 Jupyter 内核下，其 Python 环境往往是全局共享的。如果你直接 pip install，可能会污染系统包，导致其他任务出错。

更重要的是，vLLM 对 torch、transformers 等库有严格版本要求。一旦与其他项目冲突，轻则警告不断，重则运行时报 ABI 不兼容错误。

所以，强烈建议使用虚拟环境：

bash  # 先切换到标准 shell
python -m venv vllm-env
source vllm-env/bin/activate

激活成功后，提示符前会出现 (vllm-env)，表示已进入隔离空间。

但这还没完。尽管基础镜像预装了 CANN，虚拟环境中依然需要补全工具链并设置环境变量，否则编译阶段会找不到头文件和动态库。

执行以下操作：

wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/ascend-toolkit/latest/x86_64/ascend-toolkit_latest_x86_64.tar.gz
tar -zxvf ascend-toolkit_latest_x86_64.tar.gz
cd ascend-toolkit*/installer && ./install.sh --full

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_HOME=/usr/local/Ascend
export PATH=$ASCEND_HOME/ascend-toolkit/latest/toolkit/bin:$PATH
export PYTHONPATH=$ASCEND_HOME/ascend-toolkit/latest/toolkit/python/site-packages:$PYTHONPATH
export LD_LIBRARY_PATH=$ASCEND_HOME/ascend-toolkit/latest/toolkit/lib64:$LD_LIBRARY_PATH

⚠️ 注意路径差异：不同镜像中 toolkit 的实际位置可能略有不同。可通过 find /usr -name "set_env.sh" 快速定位。

这一步的本质是在虚拟环境中重建 CANN 的开发视图，确保后续编译能找到所有必要的组件。

---

安装 vLLM-ascend：版本匹配的艺术

当你终于走到安装这一步时，请务必记住一句话：vLLM 和 vLLM-ascend 必须版本完全一致。

这不是建议，而是硬性要求。因为 vllm-ascend 实际上是一个插件包，它通过 entry point 注入自定义平台逻辑来替代原有的 CUDA 后端。一旦主包与插件版本错位，就会出现符号未定义、API 不匹配等问题。

根据社区反馈和实测结果，目前最稳定的组合是：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install --upgrade pip

pip install vllm==0.9.1
pip install vllm-ascend==0.9.1

为什么不选更新的 0.11.0？因为截至写作时，PyPI 上尚未发布对应版本的 wheel 包，强行安装会导致 “No matching distribution found”。

安装完成后，用以下命令验证：

pip list | grep vllm

预期输出：

vllm                   0.9.1
vllm-ascend            0.9.1

此外，也可以检查插件是否被正确识别：

import pkg_resources
[ep.name for ep in pkg_resources.iter_entry_points('vllm.platform_plugins')]

若返回 ['ascend']，说明插件注册成功。

---

启动推理服务：从本地测试到 API 对外暴露

一切就绪后，先写一段最小可运行代码验证流程是否通畅：

import os
os.environ["VLLM_USE_V1"] = "1"  # 推荐启用 V1 引擎

from vllm import LLM, SamplingParams

prompts = [
    "请介绍一下你自己",
    "中国的首都是哪里？",
    "人工智能的未来发展趋势是什么？",
]

sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=128
)

llm = LLM(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    trust_remote_code=True,
    dtype="bfloat16",           # Ascend 推荐类型
    device="npu"                # 显式指定
)

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(f"\n📌 Prompt: {output.prompt}")
    print(f"✅ Response: {output.outputs[0].text}")

观察日志输出：

INFO ... Platform plugin ascend is activated
INFO ... DeviceConfig: device=npu
Loading safetensors checkpoint shards: 100%|█████| 1/1 [00:02<00:00]

只要看到 ascend is activated 和 device=npu，基本可以判定 NPU 已被正确调用。

接下来，进阶玩法来了——只需一行命令就能启动 OpenAI 兼容 API 服务：

python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --host 0.0.0.0 \
    --port 8080 \
    --dtype bfloat16 \
    --device npu \
    --enable-prefix-caching \
    --max-model-len 32768

然后用 curl 测试：

curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-7B-Instruct",
    "prompt": "你好，请介绍一下你自己",
    "max_tokens": 100,
    "temperature": 0.7
  }'

前端几乎无需改造，即可完成从 OpenAI 到私有化部署的平滑迁移。这对于已有系统的快速接入来说，价值巨大。

---

常见问题深度排查：那些藏在日志里的线索

❌ 报错：No matching distribution found for vllm

表面看是网络问题，实则是 Python 版本陷阱。

如前所述，vllm>=0.9.0 要求 Python ≥ 3.9。如果你在 py38 环境下执行安装，pip 会主动忽略该包。

解决方案只有一种：换镜像。不要试图用 conda 创建新环境，因为在昇腾体系中，CANN 与特定系统环境强绑定，跨环境极易引发兼容性问题。

---

❌ 故障现象：Failed to import from vllm._C

典型错误堆栈：

WARNING [_custom_ops.py:21] Failed to import from vllm._C with ModuleNotFoundError("No module named 'vllm._C'")
RuntimeError: Failed to infer device type

这里的 _C 是 vLLM 的原生 CUDA 扩展模块。在 Ascend 上，它应由 vllm-ascend 提供替代实现。若仍尝试导入 _C，说明插件未生效。

常见原因包括：
- 版本不匹配
- 缺少 ninja/cmake 导致编译失败
- CANN 环境变量未正确设置

修复步骤：
1. 确保两个包均为 0.9.1
2. 安装构建工具：

bash apt-get update && apt-get install -y ninja-build cmake

3. 清理缓存重装：

bash pip uninstall vllm vllm-ascend pip cache purge pip install vllm==0.9.1 pip install vllm-ascend==0.9.1

---

❌ pip check 发现依赖冲突

运行：

pip check

可能出现如下警告：

vllm 0.9.1 has requirement torch==2.1.0, but you have torch 2.4.0.
xgrammar 0.1.23 has requirement pybind11>=2.10, but you have pybind11 2.6.

虽然程序可能暂时运行，但 ABI 不匹配可能导致运行时崩溃。

最佳实践是卸载新版 torch 并重新安装匹配版本：

pip uninstall torch torchvision torchaudio
pip install torch==2.1.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

🔔 注意：Ascend 环境中 torch 功能由 CANN 提供，此处安装仅为满足依赖约束。

---

❌ 警告：Device not detected, running on UnspecifiedPlatform

日志片段：

WARNING [__init__.py:243] No platform detected, vLLM is running on UnspecifiedPlatform

这意味着 vLLM 没有检测到任何可用平台插件，将降级为 CPU 模式运行！你的 NPU 彻底闲置了。

排查重点：
- 是否成功安装 vllm-ascend
- 是否能看到插件加载日志：

INFO __init__.py:32] name=ascend, value=vllm_ascend:register INFO __init__.py:42] plugin ascend loaded.

如果没有，尝试强制启用：

export VLLM_PLUGINS=ascend

再运行一次，查看是否恢复正常。

---

总结与展望

在昇腾910B上部署 vLLM-ascend，本质上是一场软硬协同的精密调试。每一个环节都环环相扣：镜像选择决定了起点，环境配置影响了编译过程，版本匹配决定了最终能否运行。

经过多轮实测，我们总结出三条黄金法则：

1. 环境先行：必须使用 Python ≥ 3.9 的镜像，优先选择 py3.11。
2. 依赖闭环：即使镜像宣称“已集成 CANN”，也要在虚拟环境中手动补齐工具链并设置变量。
3. 版本锁定：vllm 与 vllm-ascend 必须严格一致，当前推荐 0.9.1。

这套方案已在多个轻量级模型（如 Qwen2.5-0.5B/7B）上验证通过，实测吞吐量相较传统方案提升达 8 倍以上，充分释放了 PagedAttention 与高带宽内存的潜力。

未来我们将继续探索：
- 多卡并行下的性能表现
- GPTQ/AWQ 量化模型的实际加速比
- 自定义算子注入优化特定模型结构

这条路才刚刚开始，而国产算力的春天，正在到来。