昇腾 AI 部署 · 一页速查
18 节课压成两页 —— 五层关系图 ＋ 8 步部署流程
全部命令、路径、版本号、报错原文出自昇腾官方文档，逐字保留未经改写
图一 · 五层关系（记住这张就够）
依赖方向：上层依赖下层。下层不对，上层全废——排查报错时先问「它在哪一层」。
图二 · 软件配合（谁跟谁是一伙的）
同一个 CANN，上面能接四种用法。分清路线只需要问一句：装几个包？
八步部署流程（从左到右照做）
每一步都给出「装什么 / 关键配置 / 怎么验 / 失败去哪查日志」。第 8 步是把前面所有验证命令再跑一遍。
| 步 | 做什么 | 软件 / 包 | 关键配置（最容易出错的地方） | 验证 | 日志 |
|---|---|---|---|---|---|
| 1 | 确认硬件 | — | 卡装好、上电；确认机器架构（aarch64 / x86_64） | uname -m | — |
| 2 | 装驱动 + 固件 | HDK .run 包 | 首次：驱动 → 固件；升级：固件 → 驱动（顺序不能反）--check 先校验包完整性；--install-for-all 用就一路都用 | npu-smi info（能看到卡） | /var/log/ascend_seclog/ascend_install.log |
| 3 | 装 CANN | Toolkit → ops →（NNAL） | 七种装法选一；ops 包必须按产品型号选（选错＝找不到算子） root 装 /usr/local/Ascend，非 root 装 ${HOME}/Ascend | cat ascend_toolkit_install.info | /var/log/ascend_seclog/ |
| 4 | 配环境变量 | set_env.sh | 必须写进 ~/.bashrc，否则新终端就失效（报「找不到库」） | echo $ASCEND_HOME_PATH非空 | — |
| 5 | 装框架 | TorchNPU | PyTorch 用官方 +cpu 版 + TorchNPU whl（两个包）五个维度版本要配套：PyTorch / TorchNPU / Python / 架构 / CANN | torch.npu.is_available()→ True | ~/ascend/log |
| 6 | 部署推理服务 | MindIE Motor / vLLM Ascend / SGLang | 起容器要挂设备节点 /dev/davinci*，权限用 rwm（写 rw 有任务占用时才报错）A3 是双 DIE，要挂两个节点 | 端口监听 + curl 调通 | ~/mindie/log |
| 7 | 准备模型 | msModelSlim / 权重转换 | 权重转换、量化；确认模型格式与服务框架匹配 | 模型能加载、结果正确 | — |
| 8 | 整体体检 | — | 把上面每一步的验证命令从头跑一遍 | 5 条全过 = 部署成功 | — |
每层速查卡（装什么 · 装在哪 · 怎么验 · 日志）
报错先定位到层，再照这张卡查。
L0硬件与驱动层
装什么HDK ＝ 驱动 + 固件
装在哪
默认
.run 包默认
/usr/local/Ascend怎么验
npu-smi info日志
/var/log/ascend_seclog/ascend_install.logL1基础软件层
装什么CANN ＝ Toolkit + ops + NNAL
装在哪七种装法
root
root
/usr/local/Ascend／非 root ${HOME}/Ascend怎么验
cat ascend_toolkit_install.infoecho $ASCEND_HOME_PATH日志
${HOME}/ascend/logL2框架层
装什么TorchNPU / MindSpore
装在哪whl 离线 / 源码 / Pip
装在 Python site-packages
装在 Python site-packages
怎么验
torch.npu.is_available()日志同上
L3服务层
装什么MindIE Motor / vLLM Ascend / SGLang
装在哪Docker 镜像 / K8s
配置：
配置：
user_config.json＋env.json怎么验端口监听 +
curl日志
~/mindie/logL4应用层
装什么权重 / 量化模型 / 配置
装在哪msModelSlim（MindStudio 组件）
怎么验模型能加载、输出正确
日志—
五个最容易踩的坑
「明明按教程做了却跑不起来」，原因基本都在这五条里。
- 驱动/固件顺序 —— 首次装 驱动 → 固件；覆盖安装/升级 固件 → 驱动。顺序反了会出问题。
- 环境变量没落盘 ——
source set_env.sh只在当前终端有效。不写进~/.bashrc，一开新终端就失效——表现为「明明装好了却报找不到库」。 --install-for-all中途丢掉 —— 首次用了这个参数，覆盖安装时必须保留，否则 NPU 设备权限会变更。- ops 包装错型号 —— 「找不到算子」的头号原因。ops 包按产品型号分发（950 / A3 / 910b 等），装错型号＝没有对应算子。
- 容器权限写
rw—— 不是立刻不可用，而是有任务占用时才报错。设备节点必须挂rwm。
报错速查 —— 按「你看到的现象」定位到层
现场最常用的一张。先认层，再查那个层——不要从报错信息直接猜原因。
| 层 | 你看到的现象 | 先查什么（按这个顺序） |
|---|---|---|
| L0 | 容器里 npu-smi 说 command not found | 没挂宿主机那份。npu-smi 是随驱动装在宿主机的 /usr/local/bin/、/usr/local/sbin/，要显式挂进容器。 |
| L0 | 容器里 npu-smi 能用，但一有任务就报错 | 设备节点权限写成了 rw。官方明确要用 rwm——空跑看不出来，上生产才炸。同一根因的官方线索：torch.npu.set_device() 失败。 |
| L0 | 用 Conda 装完 CANN，npu-smi info 没输出 | 官方原文：Conda 那条路不装驱动。驱动要另外装。 |
| L1 | 换个终端窗口，程序就跑不起来（报找不到命令／找不到库） | 环境变量只在当前 shell 有效。source set_env.sh 必须写进 ~/.bashrc。这是最高频的一条。 |
| L1 | source .../set_env.sh 报「文件不存在」 | 八成是非 root 装的，路径不一样：root 用 /usr/local/Ascend/…，非 root 用 ${HOME}/Ascend/…。 |
| L1 | 「找不到算子」／算子版本不对 | 头号原因：ops 包装错产品型号（950 / A3 / 910b 各一套）。先 echo $ASCEND_OPP_PATH 看算子库根目录指得对不对。 |
| L1 | 「找不到动态库」／「找不到 Python 包」 | 分别查 LD_LIBRARY_PATH / PYTHONPATH。 |
| L1 | 不知道 CANN 到底装在哪 | echo $ASCEND_HOME_PATH（与 ASCEND_TOOLKIT_HOME 是同一个意思，官方明说）。 |
| L1 | 装 CANN 报「配套关系不满足」 | 驱动/固件/CANN 三者要配套，查官方《版本说明》。 |
| L1 | 想给 CANN 降级 | 官方规定没有直接降级：先卸载高版本 → 再装低版本。（--upgrade 只能往上走） |
| L1 | --upgrade 报「没指定路径」／合一包报错 | 升级必须指定 --install-path；「驱动&Toolkit 合一包」官方明确不支持 --upgrade。 |
| L1 | 安装/升级「检测不通过」 | --force 是跳过检查，不是修复问题——先看清检测报的是什么。 |
| L2 | import torch 失败 | PyTorch 根本没装上（或装成了 CUDA 版，那是给 NVIDIA 卡的）。 |
| L2 | import torch_npu 失败 | TorchNPU 插件没装上，或与 PyTorch/Python 版本不配套。 |
| L2 | a = torch.randn(3,4).npu() 报错 | 设备层问题 → 往上查容器有没有挂卡（B5）、驱动固件（L0）。 |
| L2 | print(a + a) 报算子相关错 | 算子层问题 → 查算子库（B2）或版本配套（B3）。 |
| L2 | MindSpore 装上了、run_check() 也过，但平台标识不是 Ascend | mindspore 与 mindspore-ascend 是两个不同的包。昇腾场景要装后者。 |
| L3 | curl 端口不通 | 直接嫌疑对象是 EngineServer（它才是提供端口和 OpenAI 接口的那个）；Coordinator 管的是请求怎么过来。 |
| L3 | 接口返回 {"detail":"Service is not available"} | 官方原文：多为 P/D 或 Coordinator 尚未完全就绪 → 等待后重试，同时看各 Pod 日志。 |
| L3 | 请求进不来／被限流 | 看 Coordinator（限流配置在它这：rate_limit_config）。 |
| L3 | 进程反复重启 | 看 NodeManager；「偶尔卡一下又好了」可能是异常实例重启在起作用（默认开启，无需配置）。 |
| L3 | 主备发生切换 | 看 Controller（+ etcd）。注意主备不能同节点、依赖 etcd 3 副本。 |
| L3 | 推理结果异常（但服务是通的） | 看 EngineServer／引擎侧日志。 |
| L3 | 想开虚推健康检查却报 warning | 虚推仅在 ERROR 日志级别下允许（ASCEND_GLOBAL_LOG_LEVEL=3，未配置时默认就是 ERROR）。 |
| L3 | 停服务时同名的进程被误杀 | pgrep -f "vllm serve" 可能匹配到别的 vLLM 进程——kill 前先确认 VLLM_PID；优雅停止用 kill -2（SIGINT），不是 kill -9。 |
| L4 | 模型加载不了／输出结果不对 | 权重格式与量化版本是不是和服务框架匹配（msModelSlim / 权重转换环节）。 |
一条命令拆出四层问题（最好用的诊断工具）
这一行官方验收命令，一次性验四件事。哪一步失败，就是哪一层的问题——照着下面这张图走。
python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
①
import torch 失败
说明PyTorch 没装上
②
import torch_npu 失败
说明插件没装／版本不配
③
.npu() 报错
说明设备层 → 容器挂卡 / 驱动
④
a + a 报算子错
说明算子层 → 算子库 / 版本配套
四句口诀（背下来）
一句话记住五层
自下往上：卡 → CANN → 框架 → 服务 → 模型。
下面不对，上面全废。
一句话分清所有路线
看装几个包：插件路线（PyTorch+TorchNPU、vLLM+vLLM Ascend）装两个；原生路线（MindSpore 带 -ascend）装一个；镜像路线一个都不用装。
一句话定位报错
跑的时候报 → 单算子 → 查算子库；建图的时候报 → 图模式 → 查版本配套；服务起不来 → 查 P/D 是否就绪。
一句话防版本坑
PyTorch ＝ TorchNPU ＝ Python ＝ 架构 ＝ CANN，五样必须互相对得上。
与昇腾 AI 部署课件体系（18 节编号课）配套使用
选修 · 昇腾 AI 部署实操
本机读完 0/51
选修 C · 昇腾 AI 部署实操
从零把昇腾 AI 部署学一遍：先看懂分几层，再逐层装起来，最后出问题能自己定位到哪一层。不需要先有卡就能开始。
下一站 → 昇腾部署第 F1 课：模型迁移——把 GPU 上跑得通的脚本搬到昇腾上 （文章）
看完整学习路径（6 站 + 3 门选修）
· 进度只存在你这台设备的浏览器里，不用登录