CANN 调试与错误处理：问题排查指南与实战技巧

CANN 调试与错误处理问题排查指南与实战技巧遇到报错无从下手这篇总结昇腾 NPU 开发中的常见错误与排查方法让你快速定位问题。调试环境准备1.1 诊断工具清单工具用途常用场景npu-smi设备状态监控查看 NPU 使用率、显存占用ascend-historian训练过程采集分析算子耗时、内存峰值msnpureport异常日志导出导出 NPU 侧错误详情atc --log编译日志ATC 转换失败时定位问题1.2 日志目录# 运行时日志ls/var/log/npu/# 芯片微架构日志ls/var/log/npu/slog/# 训练 profile 输出ls~/ascend-works/logs/常见错误分类2.1 运行时错误错误码含义排查方向E00001内存分配失败显存不足检查模型占用E00005算子不支持检查算子类型是否在白名单E00010数据格式不匹配检查输入 tensor 的 shape/dtypeE00015设备间通信超时检查 HCCL 配置网络是否畅通2.2 编译错误错误信息原因解决Parse op failedONNX 模型解析失败用onnx simplifier预处理模型Op not supported算子未适配改用支持的算子或自定义实现Shape unknown动态 shape 无法推导固定 batch size 或设置 input_shapeMemory overflow资源块过大开启 reduce memory 或分图场景一Torch-NPU 训练报错3.1 典型报错RuntimeError: NPU error, error code: 0x9101E001这个错误码表示数据搬运过程中发生错误通常是 Host-Device 拷贝不匹配导致的。3.2 排查步骤# 1. 查看 NPU 状态npu-smi info# 2. 检查进程是否异常退出psaux|greppython# 3. 查看设备日志cat/var/log/npu/slog/device_log/0/*.log|tail-1003.3 常见原因场景原因修复方法数据 shape 不匹配输入张量维度错误检查torch.randn初始化的 shape数据类型不匹配dtype 是 int32 但算子需要 float添加.float()转换batch size 过大显存溢出减小 batch_size 或开启 gradient accumulation设备 ID 错误指定了不存在的 NPU改为npu:0或动态获取3.4 代码修复示例# 错误写法datatorch.randn(batch_size,3,224,224)# 默认 CPUoutputmodel(data)# 没有移到 NPU# 正确写法devicetorch.device(npu:0)datatorch.randn(batch_size,3,224,224).to(device)outputmodel(data)场景二ATC 模型转换失败2.1 错误分析atc--modelmodel.onnx\--outputmodel\--framework5\--soc_versionAscend910Error: Cannot find op [CustomLayer] in opt这种报错是 ONNX 模型中包含了自定义算子ATC 无法识别。2.2 解决方案方案一简化模型# 用 onnx simplifier 移除自定义算子pipinstallonnxsim python-monnxsim model.onnx model_simple.onnx方案二注册自定义算子frommsame.modelimportModel# 创建自定义算子映射custom_op_map{CustomLayer:AscendCustom,# 映射到 ATC 支持的算子}# 在转换时指定atc--modelmodel.onnx \--outputmodel \--framework5\--op_select_levelcustom \--custom_op_mapscustom_op_map2.3 常见 ATC 错误错误信息原因解决Can not parse modelONNX 文件损坏重新导出或用netron可视化检查Input shape not matchinput_shape 与实际不符设置正确的维度1,3,224,224Op kernel not found算子未在 NPU 实现改用 ATC 支持的标准算子SocVersion mismatch芯片型号不匹配确认是 Ascend910 还是 Ascend310场景三多卡训练通信失败3.1 HCCL 错误[HCCL] ERROR: 0x81001 - Timeout when rank 0 tries to communicate with rank 2这是集合通信超时通常是某个进程卡住或网络不通。3.2 排查命令# 检查 NCCL 配置exportNCCL_DEBUGINFO python train.py21|teetraining.log# 检查网络连通性ping-c3192.168.1.101# 查看 HCCL 日志cat/var/log/npu/hccl/*.log3.3 常见原因原因表现处理单卡进程卡死某个 rank 无响应重启训练或增加 timeout网卡故障节点间 ping 不通更换网线或检查交换机集合通信配置错误allreduce 失败检查hccl.json配置梯度不同步部分节点计算慢开启async_grad_accumulation3.4 hccl.json 配置示例{rank_table:/path/to/rank_table.json,machine_list:[{devices:[{id:0,ip:192.168.1.100},{id:1,ip:192.168.1.101}]}],timeout:300}场景四显存溢出OOM4.1 错误日志RuntimeError: NPU out of memory. Allocated: 31.2 GB, Total: 31.4 GB4.2 排查方法# 查看显存占用npu-smi q-smemory# 使用 msnpureport 采集详细日志msnpureport-tmemory-o./memory_report4.3 优化策略策略效果适用场景减小 batch size显存降低 ~50%显存刚好不够混合精度 FP16显存降低 ~50%精度可接受梯度累积等效 batch 增大收敛受影响ZeRO 分片显存降低 ~N 倍多卡训练启用 recompute显存降低 ~30%激活值过大4.4 优化代码示例# 显存优化配置modelmodel.to(torch.bfloat16)# 启用 gradient checkpointingmodel.gradient_checkpointing_enable()# 减小 batchbatch_size8# 从 16 降到 8场景五算子执行失败5.1 错误日志[ERROR] Op [Conv] execution failed. Error code: 0x8900A1235.2 定位方法# 开启算子级别的详细日志exportASCEND_GLOBAL_LOG_LEVEL3python train.py# 查看具体是哪个算子grepOp execution failed./ascend_log/*.log5.3 常见原因算子常见问题解决方案Convkernel size 不支持改用 3x3 或 1x1MatMulshape 不对齐检查矩阵维度Softmaxaxis 参数越界确认 dim 范围Reshapeshape 冲突检查目标 shape 可行性调试技巧6.1 断点调试importtorch.npuasnpu# 在关键位置插入调试outputmodel(input_data)print(fOutput shape:{output.shape})print(fOutput dtype:{output.dtype})print(fNPU memory:{npu.memory_allocated()/1e9:.2f}GB)# 检查梯度forname,paraminmodel.named_parameters():ifparam.gradisnotNone:print(f{name}: grad norm {param.grad.norm()})6.2 日志分级importlogging# 设置日志级别logging.basicConfig(levellogging.DEBUG)# 只在关键节点输出deftrain_step():logging.info(fStep{step}, loss {loss.item()})ifloss.item()10:logging.warning(fLoss too high at step{step})6.3 自动化检测#!/bin/bash# NPU 健康检查脚本echo NPU Status npu-smi q-smemoryecho Process List psaux|greppython|head-5echo Recent Error Logs tail-20/var/log/npu/slog/device_log/0/*.log错误处理流程图报错 → 记录错误码 → 查文档/社区 → 定位根因 → 修复/提 Issue记录错误码保留完整的错误日志查文档对照上文的错误码表定位原因查社区搜索昇腾论坛是否有类似问题提 Issue复现步骤清晰描述发到官方仓库相关仓库ascend-toolkit- 官方工具链 https://gitee.com/ascend/ascend-toolkittorch_npu- NPU 适配 https://gitee.com/ascend/torch_npuAtlas- 论坛与支持 https://bbs.huaweicloud.com/forum/forum-729