昇腾NPU部署指南：Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu国产化推理环境搭建完全手册

• 大模型
• 模型推理服务
• 本地部署

Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu 是专为**昇腾NPU（Ascend NPU）**优化的 Qwen2.5-3B 指令微调模型，内置 RAI 1.8.0 与 Medusa 1.0 投机解码头，可实现国产化环境下的高吞吐推理。本文将手把手带你完成昇腾NPU部署全流程：从环境准备、模型下载、依赖安装到推理验证，一篇搞定国产算力推理环境搭建。

一、认识这个模型：三大核心亮点 🔍

在开始搭建之前，先搞清楚这个模型名里的每一段含义：

💡Medusa 投机解码是本文档最值得关注的加速点：传统大模型逐 token 生成，瓶颈在解码阶段；Medusa 在主干网络旁挂上额外的预测头，一次前向同时"猜"多个后续 token，再用主干验证，从而把生成速度提升数倍，而模型质量几乎无损。

模型卡片详情可查阅仓库内的 README.md，其中列出了模型文件的完整说明。

二、部署前准备：硬件与软件清单 ✅

1. 硬件要求

• 芯片：昇腾 Ascend NPU（Atlas 推理卡或含 NPU 的 Atlas 服务器均可）
• 显存：3B 参数模型，单卡 16GB 及以上 HBM 即可轻松承载
• 存储：预留约 10GB 空间存放模型权重

2. 软件要求

⚠️ 常见误区：不要直接在 NPU 机器上用pip install torch安装官方 PyTorch，需使用昇腾社区发布的带 NPU 适配的 wheel，否则会提示设备不可用。

三、模型下载：两种方式任选 ⬇️

方式一：git clone 下载（推荐新手）

git clone https://gitcode.com/hf_mirrors/amd/Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu

方式二：ModelScope SDK 下载

from modelscope import snapshot_download model_dir = snapshot_download('amd/Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu')

下载完成后，目录中即包含config.json、模型权重分片及 tokenizer 配置等文件，npu后缀版本中的权重已完成昇腾算子映射，无需再做额外转换。

四、昇腾NPU部署：四步搭建推理环境 🚀

第一步：初始化 CANN 运行环境

登录 NPU 服务器后，加载 CANN 环境变量（路径以实际安装位置为准）：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

验证 NPU 状态：

npu-smi info

输出中能看到 NPU 型号、显存与温度信息，即说明驱动链路正常。

第二步：安装 PyTorch NPU 适配层

按照 CANN 版本选择对应版本的 torch-npu wheel 安装，安装完成后验证：

import torch import torch_npu print(torch.npu.is_available()) # 期望输出 True

第三步：部署 Medusa 加速推理引擎

以 NPU 版 vLLM 为例，安装后通过vllm-ascend启动服务，核心参数如下：

python -m vllm.entrypoints.openai.api_server \ --model ./Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu \ --tensor-parallel-size 1

🎯 若你的引擎版本支持 Medusa，启动时观察日志出现Medusa head loaded类似字样，即表示投机解码头已生效。

第四步：发送第一条推理请求

服务默认监听 8000 端口，直接体验国产算力上的对话推理：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-3b","messages":[{"role":"user","content":"请用一句话介绍昇腾NPU"}]}'

收到流畅的中文回复，恭喜你——昇腾NPU部署完成！🎉

五、性能验证：Medusa 加速效果实测 📊

建议部署后做一次简单吞吐对比（同机、同并发）：

提示：3B 小模型的解码本身就是显存带宽瓶颈，Medusa 的加速收益往往比大模型更明显；长输出场景下提升更为可观。

六、常见问题排查清单 🛠️

• NPU device not found：未执行 CANN 环境变量初始化，回到第三步的source命令重新执行。
• torch.npu.is_available()返回 False：torch 版本与 torch-npu 版本不匹配，检查版本对应表重装。
• 服务启动报算子不支持：确认使用的是npu后缀权重而非普通权重，且 CANN 版本满足模型要求。
• 吞吐量低于预期：检查并发数是否打满、是否启用了 Medusa 投机解码、其他进程是否占用 NPU。

七、总结 📌

本文完成了Qwen2.5_3B_Instruct_rai_1.8.0_medusa_1.0_npu 的昇腾NPU部署全流程：模型下载 → CANN 环境初始化 → PyTorch NPU 适配 → vLLM 启动 → Medusa 加速验证。得益于npu专用权重与 Medusa 1.0 投机解码头，这套国产推理环境在小模型高并发场景下表现出色，是国产化 AI 推理落地的一个高性价比方案。

📁 延伸阅读：模型文件说明见 README.md，模型权重分片位于仓库"模型文件"页面，可按需下载对应model-*.bin权重文件。

• 大模型
• 模型推理服务
• 本地部署