昇腾部署第 E1 课：报错定位法——从一条报错定位到哪一层
课件编号：E1（排障层首课） 编制：观澜｜日期：2026-10-04 难度：入门偏中 时长：约 50 分钟 是否需要硬件：❌ 不需要 前置：第 0 课（A0 一张地图） 本课目标：拿到任何一条昇腾报错，三步之内说出"问题在哪一层、下一步用哪条命令确认"
第一段 · 章前定位
A0 那课给你画了地图，还留了一句最值钱的话：下面的不对，上面的全废。
但真到现场，你拿到的不是"第 L1 层故障"这种提示，而是一行乱七八糟的英文报错：
[ERROR] ASCENDCL(12345,main):2026-10-04-10:23:11.123.456 [runtime/feature/src/device.cc:312] ErrCode=507033, desc=[driver], pid=12345, tid=12346
Acl open device 0 failed, errorCode is 507033
这一课教的就是：怎么把这行东西，翻译成"问题在这一层"。
本课的一句话：报错不是一句"出错了"，它是一张写着地址的纸条——你得会读。
第二段 · 学习目标
学完这一课，你应该能：
- ✅ 把一条报错拆成 5 个组成部分，逐块读
- ✅ 看到错误码，从第一位数字判断它属于哪一类问题
- ✅ 用特征词在 3 秒内大致锁定层
- ✅ 知道三类日志分别在哪，以及什么时候该去看哪一个
- ✅ 会用官方故障案例库反查，而不是从零瞎试
第三段 · 一条报错，其实由 5 块组成
别把报错当成一坨文本读。拆开看。
以这条为例：
[ERROR] ASCENDCL(12345,main):2026-10-04-10:23:11.123.456
[runtime/feature/src/device.cc:312]
ErrCode=507033, desc=[driver], pid=12345, tid=12346
Acl open device 0 failed, errorCode is 507033
| # | 块 | 内容 | 告诉你什么 |
|---|---|---|---|
| ① | 级别 | [ERROR] |
严重程度。常见 INFO / WARNING / ERROR。别把 WARNING 当 ERROR 修 |
| ② | 模块 | ASCENDCL |
哪个组件报的——这一块最能定层（见下表） |
| ③ | 位置 | runtime/feature/src/device.cc:312 |
源码文件 + 行号。这一块在搜案例时最好用：device.cc 说明问题出在运行时访问设备这条路上 |
| ④ | 错误码 | ErrCode=507033 |
最重要的一块——5 开头说明是软硬件内部异常（见第四段） |
| ⑤ | 补充 | desc=[driver] |
它自己已经告诉你答案了：driver —— 驱动层 |
⭐ 看第 ⑤ 块：很多报错后面跟着
desc=[xxx]，那个xxx往往直接就是出问题的模块。先看这个，别再往下瞎找。
模块名 → 层 对照（②块）
| 模块名 | 属于哪层 |
|---|---|
driver / HDK / dmesg |
L0 硬件与驱动 |
ASCENDCL / ACL / runtime / GE / OPP / HCCL |
L1 基础软件（CANN 内部组件） |
torch_npu / PyTorch / MindSpore / ATB |
L2 框架 |
MindIE / vLLM / SGLang / service |
L3 服务 |
模型加载 / model / weight |
L4 应用 |
第四段 · 错误码：看第一位数字就够了
这是本课最实用的一张表。 官方对 AscendCL 返回码有明确的分段规则：
| 码段 | 官方定义 | 意味着什么 | 你能自己解决吗 |
|---|---|---|---|
1XXXXX |
开发人员的环境异常或代码逻辑错误 | 你的环境没配好，或者代码写错了 | ✅ 能（改环境 / 改代码） |
2XXXXX |
资源不足（Stream、内存等）；接口或参数与当前硬件不匹配 | 资源申请多了、卡不支持这个用法 | ✅ 能（合理使用资源） |
3XXXXX |
业务功能异常（队列满、队列空等） | 业务流程上的问题 | ✅ 能 |
5XXXXX |
软硬件内部异常（软件内部错误、Device 执行失败） | 不是你能修的 | ❌ 收集日志，反馈技术支持 |
500000 |
无法识别的错误 | 兜底码 | ❌ 同上 |
⭐ 这一条能省你几个小时： 看到
5开头，先去收日志、准备反馈，别在那儿死磕。 看到1开头，八成是你自己的环境或代码问题，先回头查环境变量。
几个高频具体码（官方错误码表）
| 错误码 | 名称 | 官方给的原因与解决方向 |
|---|---|---|
100000 |
ACL_ERROR_INVALID_PARAM |
参数校验失败 → 检查接口入参 |
100001 |
ACL_ERROR_UNINITIALIZE |
ACL 未初始化 → 检查是否已调用 acl.init，且要在其它接口之前调用 |
100002 |
ACL_ERROR_REPEAT_INITIALIZE |
重复初始化 → 检查是否重复调用 |
100003 |
ACL_ERROR_INVALID_FILE |
无效文件 → 检查文件是否存在、能否访问 |
100004 |
ACL_ERROR_WRITE_FILE |
写文件失败 → 检查路径是否存在、有无写权限 |
100011 |
ACL_ERROR_INVALID_MODEL_ID |
无效模型 ID → 检查模型是否正确加载 |
100012 |
ACL_ERROR_DESERIALIZE_MODEL |
反序列化模型失败 → 模型可能与当前版本不匹配，重新构建模型 |
100014 |
ACL_ERROR_READ_MODEL_FAILURE |
读取模型失败 → 检查模型文件 |
⚠️ 注意
100001（ACL 未初始化）：这是新手最常见的坑之一。 现象是"什么都没做就报错"，实际是调用顺序问题——初始化必须放在最前面。
第五段 · 三步定位法（本课的核心方法）
第 1 步：看 desc=[xxx] 和 模块名 → 先猜层
第 2 步：看错误码首位数字 → 确认层，并判断"能不能自己修"
第 3 步：回官方案例库搜特征词 → 找现成答案
第 1 步：先看有没有直接答案
在报错里找这两个东西：
desc=[driver] ← 直接告诉你模块
ASCENDCL / runtime ← 告诉你哪个组件
有 desc=[xxx] 就先信它。 没有就按第三段的"模块名 → 层"对照表猜。
第 2 步：用错误码确认
1XXXXX→ 环境或代码 → 自己能修，重点查环境变量、调用顺序2XXXXX→ 资源或兼容性 → 自己能修，重点查内存/Stream 申请、硬件是否支持该用法5XXXXX→ 内部异常 → 别死磕，收日志反馈
第 3 步：特征词反查官方案例库
把你的报错"去具体化"——去掉路径、去掉 pid、去掉时间戳，只留稳定特征：
| 原始报错 | 提特征词 | 搜什么 |
|---|---|---|
Acl open device 0 failed, errorCode is 507033 |
去掉数字 | Acl open device 或 507033 |
.../device.cc:312 ErrCode=507033 |
取文件名 | device.cc |
Failed to load the libdcmi.so dynamic library |
取库名 | libdcmi.so |
搜索入口：昇腾官方故障案例库
https://www.hiascend.com/document/caselibrary/
看到案例编号，可以直接拼链接：
https://www.hiascend.com/document/caselibrary/detail/<案例编号>
已知的实际例子（A0 课里那 8 条，这里挑 3 条演示）：
| 报错 | 特征词 | 官方案例 |
|---|---|---|
Acl open device 0 failed, errorCode is 507033 |
Acl open device |
topic_0000001633594041（10,585 次查看） |
Failed to load the libdcmi.so |
libdcmi.so |
toolboxcase_0054 |
EL0003，error code 507000 |
507000 |
case_95414 |
第六段 · 日志在哪（三类日志，分别管什么）
报错的正文只是"结论"，日志里才有"过程"。
类别一：应用类日志（你最常看的）
官方默认路径：
${HOME}/ascend/log
- 干什么用：在 Host 或 Device 上运行应用程序产生的调试和运行日志，看用户态发生了什么
- 什么时候看：程序跑起来报错、行为不对
类别二：推理服务日志（用了 MindIE 才看）
官方默认路径：
~/mindie/log ← 默认落盘路径
~/mindie/log/security ← 自动生成的安全日志
~/mindie/log/debug ← 自动生成的运行调试日志
文件命名格式（官方）：
mindie-<组件名称>_<pid>_<时间戳>.log
例子：mindie-service_123_202410080206.log
- 怎么看：
cat 日志文件 - 默认收集 Informational 级别及以上的日志
⭐ 命名规则很有用：你看到哪个文件，就知道是哪个组件、哪个进程、什么时候出的问题。
类别三：Device 侧系统类日志（底层问题才看）
包含 slog 日志、syslog 日志、黑匣子等——用于查看 Device 系统运行信息、驱动内核态信息。
这类日志不在 Host 上，需要导出。官方工具：msnpureport
# 官方示例的结构（导出到 Host 侧的自建目录）
msnpureport -d 0 -f ${HOME}/err_log_info/ # 具体参数以你所用版本的官方文档为准
⚠️ 参数用法随版本变化，以《日志参考》和你所用版本为准，本课不写死参数。
还有个"一键收"的工具：asys
官方提供 asys 工具在 Host 上一键收集所有故障相关信息：安装版本信息、Device 健康状态、dump 文件、算子编译信息、全量日志文件等。
⚠️ 但官方明确说：asys 使用场景有限——集群、容器、虚拟机、云场景不支持。
日志收集的一个官方注意事项
收集日志时，要收集"本次问题附近时间"的日志。 旧日志中不相关的信息或其它报错，会导致后续工具分析时出错。
这条很实用：不是"把所有日志都发过去"就完事，时间窗口选对才算有效。
第七段 · 实战演练：三条真实报错，走一遍三步法
演练 1
安装驱动时报错：
[ERROR]ERR_NO:0x0091;ERR_DES:username not permission for root, check /etc/ascend_install.info
| 步 | 做法 | 结论 |
|---|---|---|
| 1 | 看模块 | 报的是安装驱动，且提到 /etc/ascend_install.info → L0 驱动安装 |
| 2 | 看错误码 | 0x0091 是十六进制，不是 ACL 的十进制码段 → 属于安装器自己的错误码体系 |
| 3 | 搜特征词 | 搜 username not permission for root → 官方案例 case_92819 |
这一条的启发：不是所有错误码都走 1/2/3/5 分段——那是 AscendCL 的规则，安装器另有体系。先判断码的场合。
演练 2
跑 PyTorch 训练时报错：
set_device() 失败，RuntimeError，错误码 EL0003，error code 507000
| 步 | 做法 | 结论 |
|---|---|---|
| 1 | 看模块 | 报错在 PyTorch 层（set_device）→ 先看 L2，但根因可能在下层 |
| 2 | 看错误码 | 507000 是 5 开头 → 软硬件内部异常；set_device 是"选设备"，说明设备没被正确识别 |
| 3 | 搜特征词 | 搜 507000 → 官方案例 case_95414 |
这一条的启发：报错的位置 ≠ 问题的位置。
在 L2 报的错，根因可能在 L0/L1。set_device 失败几乎一定不是 PyTorch 的错。
演练 3
执行 ascend-dmi 命令报错：
Failed to load the libdcmi.so dynamic library
| 步 | 做法 | 结论 |
|---|---|---|
| 1 | 看模块 | 报错提到 libdcmi.so → 动态库 → L1 |
| 2 | 看错误码 | 没有错误码，是"加载失败" → 典型的环境变量/库路径问题 |
| 3 | 搜特征词 | 搜 libdcmi.so → 官方案例 toolboxcase_0054 |
这一条的启发：没有错误码不等于没法定位。 凡是不出码、只说"找不到 / 加载失败"的，先怀疑环境变量和库路径。
第八段 · 一页速查（建议截图存手机）
拿到报错，按顺序问自己 4 个问题
① 有没有 desc=[xxx]？ → 有，直接信它
② 报的是哪个模块？ → 查"模块名→层"对照表
③ 错误码第一位是几？ → 1/2/3 开头自己能修；5 开头去收日志
④ 去掉数字后，稳定特征词是什么？ → 拿去官方案例库搜
高频坑速记
| 现象 | 第一反应 |
|---|---|
| 只说"找不到库 / 加载失败"，没有码 | 环境变量（ASCEND_HOME_PATH / ASCEND_OPP_PATH / LD_LIBRARY_PATH） |
100001 ACL 未初始化 |
调用顺序问题——初始化放最前面 |
set_device / device 0 失败 |
不是框架的错，回头查 L0/L1 |
5XXXXX |
别死磕，收日志反馈 |
| 昨天好、今天新开终端就错 | 环境变量没写进 ~/.bashrc |
| 装 CANN 报驱动不兼容 | 查 CANN ↔ 驱动版本配套关系 |
日志位置速查
| 日志 | 路径 | 工具 |
|---|---|---|
| 应用类日志 | ${HOME}/ascend/log |
直接看 |
| MindIE 服务日志 | ~/mindie/log（+ debug / security） |
直接看 |
| Device 侧系统日志 | 不在 Host，需导出 | msnpureport |
| 一键全收 | — | asys（集群/容器/虚机/云不支持） |
第九段 · 小结与下一课
三句话带走
- 报错要拆开读：级别 / 模块 / 位置 / 错误码 / 补充，
desc=[xxx]常常直接给答案。 - 错误码看首位：
1/2/3开头自己能修，5开头别死磕。 - 搜案例要"去具体化"：去掉路径、pid、时间戳，只留稳定特征词。
钩子（E 层后续课）
| 课 | 要回答的问题 |
|---|---|
| E2 | Device 侧日志怎么导？msnpureport 怎么用？黑匣子是什么？ |
| E3 | 内存/显存类报错怎么定位？（2XXXXX 那一类，含 OOM） |
| E4 | 多卡/多机通信类报错怎么定位？（HCCL 相关） |
| E5 | 精度问题（不报错但结果不对）怎么查？ |
课后自测（3 题）
- 你看到
ErrCode=207012。你能自己修吗？为什么？ - 报错说
ACL_ERROR_UNINITIALIZE (100001)。你先查什么？ - 同事发来一行报错，里面有
desc=[hcom]、ErrCode=507018。你先判断是哪层，下一步做什么？
附录 · 本课引用的官方出处
| 内容 | 官方来源 |
|---|---|
| 返回码分段规则（1/2/3/5XXXXX） | CANN 9.2.0-beta.2《aclError — 数据类型及其操作接口》 |
| 具体错误码（100000/100001/100003/100011/100012/100014 等） | 同上（官方返回码列表） |
应用类日志默认路径 ${HOME}/ascend/log |
CANN 9.2.0-beta.2《收集进程中断问题信息》 |
Device 侧日志 / msnpureport / asys 限制 |
同上 |
| AI Core Error 需收集的信息类别 | CANN 9.2.0-beta.2《收集 AI Core Error 问题信息》 |
| MindIE 日志路径与命名格式 | MindIE 3.1.0《查看日志》 |
| "收集问题时选附近时间日志"的注意事项 | CANN 9.2.0-beta.2《收集 AI Core Error 问题信息》 |
| 3 条实战案例编号 | 昇腾官方故障案例库 |
⚠️ 数据说明：
- msnpureport 的具体参数未在本课写死（随版本变化），以《日志参考》为准。
- 模块名→层的对照表（第三段）是我按官方组件划分归纳的教学用归类，非官方表述 —— 用于快速判断，不作为判据。
- 演练 2 的 EL0003 保留官方案例标题里的原写法（同一案例中另有 EL0013 写法，以官方页面为准）。
附录 B · 本课出现的命令详解
看图对照：本课的命令分两类——看日志的（排障用）和导日志的（收集证据用）。
cat 日志文件
- 含义：把文件内容打印到屏幕上。
cat本意是 concatenate（拼接），现在最常用来看文件。 - 拆解：
cat（命令名）＋ 文件路径 - 用法：
cat mindie-service_123_202410080206.log # 看这个具体的日志文件
cat ${HOME}/ascend/log/xxxx.log # 看应用日志
- 期望：终端直接输出日志内容
- 不过会怎样：
No such file or directory→ 路径不对，或那个组件根本没产生日志（这本身就是线索：没日志说明它没跑起来）
日志太大怎么办？ 日志文件经常几十兆，
cat会刷屏。用grep先筛：bash cat xxxx.log | grep 507033 # 只看含 507033 的行|是管道——把左边命令的输出，交给右边命令处理。
grep 关键词
- 含义：在一段文本里，把含这个关键词的行挑出来。
- 拆解：
grep（命令名）＋ 要找的关键词 - 用法：
cat big.log | grep ERROR # 只看 ERROR 行
cat big.log | grep 507033 # 只看含 507033 的行
- 期望：打印出所有匹配的行
- 不过会怎样：什么都不输出 → 没有匹配，说明这个关键词不在日志里（换个关键词试）
⭐ 排障时
grep是你最常用的一个命令：日志成千上万行，你只需要含错误码的那几行。
msnpureport
- 含义：昇腾官方提供的工具，用来把 Device 侧的系统类日志（slog 日志、syslog 日志、黑匣子等）导出到 Host 服务器上。
- 为什么需要它：这类日志不在 Host 上，Host 上是看不到的——必须用这个工具"搬"过来。
- 官方给出的典型形态：
msnpureport -d 0 -f ${HOME}/err_log_info/
-d 0：指定要导哪一张设备（0 = 第 0 张卡）-f 目录：指定导出到哪个目录- ⚠️ 具体参数以你所用版本的官方《日志参考》为准——本文不写死，因为工具参数随版本会变。
- 期望：目标目录里出现导出的日志文件
- 不过会怎样：报权限错误 → 通常需要 root 权限执行
asys（一键收故障信息）
- 含义：在 Host 上一次性收集全部故障相关信息——安装版本信息、Device 健康状态、dump 文件、算子编译信息、全量日志文件等。
- 用法：直接执行（具体子命令以官方文档为准）
- 何时用：准备向技术支持反馈问题时
- ⚠️ 官方明确说明：
asys使用场景有限——集群、容器、虚拟机、云场景不支持。这些场景得手动收集。
收日志的一个官方注意事项
收集日志时，要收集"本次问题附近时间"的日志。 旧日志中的不相关信息或其它报错，会导致后续工具分析时报错。
- 含义：不是"把日志全打包发过去"就完事——时间窗口选对才算有效证据。
附录 C · 报错里的英文词，逐个翻译
| 报错里的词 | 中文意思 | 提示了什么 |
|---|---|---|
ErrCode / errorCode |
错误码 | 最重要，看第一位数字定类 |
desc=[xxx] |
描述，方括号里是模块 | 常常直接给出答案（如 [driver]） |
pid |
process id，进程号 | 定位是哪个进程出的问题 |
tid |
thread id，线程号 | 定位是哪个线程 |
device |
设备，通常指某张卡 | 出现它 → 先查 L0/L1 |
runtime |
运行时 | CANN 内部组件，属 L1 |
dynamic library / .so |
动态库 | 找不到库 → 先怀疑环境变量 |
initialize / init |
初始化 | 100001 就是"没初始化"→ 调用顺序问题 |
set_device |
选择/设置设备 | 在 L2 报，根因常在 L0/L1 |
permission |
权限 | 权限不对，看文件属主或用 sudo |
看懂报错里的路径
/var/log/ascend_seclog/ascend_install.log
└─ 这个路径告诉你：这是"驱动安装过程"的日志（和 CANN 无关）
读懂路径本身，就是在定位层。