菜单
ATB 调试指南技能。当用户遇到 ATB 算子测试问题、需要分析错误原因、或需要了解 ATB 环境配置时调用此技能。 覆盖：环境配置问题、ABI版本不匹配、内存错误、CSV测试失败、ACLNN接口问题等常见场景。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ascend-ai-coding/awesome-ascend-skills --skill external-gitcode-ascend-atb-debug-guide命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | external-gitcode-ascend-atb-debug-guide |
| description | ATB 调试指南技能。当用户遇到 ATB 算子测试问题、需要分析错误原因、或需要了解 ATB 环境配置时调用此技能。 覆盖：环境配置问题、ABI版本不匹配、内存错误、CSV测试失败、ACLNN接口问题等常见场景。 |
| keywords | ["atb","debug","error","troubleshooting","昇腾","NPU","调试","aclnn","moe"] |
| metadata | {"author":"ascend-transformer-boost-team + Claude Code + opus4.7","version":"1.1.1","created":"2026-04-19","updated":"2026-04-28","skill-type":"debug"} |
| original-name | atb-debug-guide |
| synced-from | https://gitcode.com/Ascend/agent-skills |
| synced-date | 2026-05-26 |
| synced-commit | 1f7666e7768a0ceb21bb1d40ce4b5179fcb6f1d6 |
| license | UNKNOWN |
提供 ATB 调试指南，覆盖环境配置问题、ABI版本不匹配、内存错误、CSV测试失败、ACLNN接口问题等常见场景。
在以下情况下调用此技能：
执行此技能前，必须从用户处获取以下路径（如未提供则使用默认路径）：
<CANN_PATH>: CANN 安装路径（如 /usr/local/Ascend/cann-9.0.0-beta.2）<ATB_REPO_PATH>: ATB 仓库路径| 问题类型 | 快速定位 |
|---|---|
| ABI版本不匹配 | undefined symbol, shared object file |
| 内存错误 | ERROR_OUT_OF_HOST_MEMORY |
| Tensor维度错误 | ERROR_INVALID_TENSOR_DIM |
| 数据类型错误 | KeyError: 'float32', ERROR_INVALID_TENSOR_INI_MATCH |
| ACLNN函数签名错误 | 161001, 161002, undefined symbol |
| ACLNN MoE场景不匹配 | {xxx}Quant 等非MoE算子 |
| 日志分析方法 | plog日志, atb日志 |
OSError: /path/to/atb/output/atb/cxx_abi_0/lib/libatb_test_framework.so: cannot open shared object file
或
undefined symbol: _ZN3atb13OpParamToJson...
ATB 输出目录有两个 ABI 版本：
cxx_abi_0: 旧版本（g++/libstdc++abi_0）cxx_abi_1: 新版本（g++/libstdc++abi_1）测试框架库和依赖库必须使用相同 ABI 版本。
方案A：使用正确的 set_env.sh 参数
source <CANN_PATH>/set_env.sh
source <ATB_REPO_PATH>/output/atb/set_env.sh --cxx_abi=1
echo $ATB_HOME_PATH
方案B：创建软链接（不推荐）
ln -s <ATB_REPO_PATH>/output/atb/cxx_abi_1 <ATB_REPO_PATH>/output/atb/cxx_abi_0
ls -la $ATB_HOME_PATH/lib/libatb_test_framework.so
ldd $ATB_HOME_PATH/lib/libatb_test_framework.so | grep libatb
ActualError: S:ERROR_OUT_OF_HOST_MEMORY
// 检查接口规格中的输入输出定义
// 例如 SwigluQuant:
// - 输入：1个 [ntokens, 2*hidden_size]
// - 输出：2个 [ntokens, hidden_size] + [ntokens]
// Runner 必须匹配这些规格
ActualError: I:ERROR_INVALID_TENSOR_DIM_NUM
ActualError: I:ERROR_INVALID_TENSOR_DIM
ActualError: I:ERROR_INVALID_TENSOR_INI_MATCH
KeyError: 'float32'
在 CSV 中使用 data_generation.py 支持的数据类型：
float (对应 float32)float16 / halfbf16 / bfloat16int8 / charint32 / intint64 / longundefined symbol: aclnn{xxx}QuantGetWorkspaceSize
ActualError: S:ERROR_CANN_ERROR (161001, 161002)
# 检查函数符号
nm -D <ATB_PATH>/output/atb/cxx_abi_1/lib/libatb.so | grep -i {xxx}
nm -D $ASCEND_TOOLKIT_HOME/lib64/libopapi_nn.so | grep -i {xxx}
| 错误码 | 名称 | 含义 |
|---|---|---|
| 161001 | ACLNN_ERR_PARAM_NULLPTR | 参数为空指针（如 x/yOut 为空） |
| 161002 | ACLNN_ERR_PARAM_INVALID | 参数类型/维度/取值无效 |
问题: ATB 算子为非 MoE 场景设计，但 ACLNN 接口仅支持 MoE 场景。
{xxx}Quant:
groupIndex 和 smoothScales[ERROR] errno[161001] Check yOut != nullptr failed
实际上由于 smoothScalesOptional 和 groupIndexOptional 不支持空指针（当前版本）。
方案A：回退到 OPS 实现（推荐）
// 禁用 ACLNN 路径
std::shared_ptr<Runner> XxxOperation::CreateRunner(Context &context) const
{
// TODO: 待 ACLNN 支持非 MoE 场景后启用
return std::make_shared<XxxOpsRunner>(param_);
}
方案B：构造 MoE 参数模拟非 MoE（复杂，不推荐）
groupIndexsmoothScales查阅 ACLNN 文档：
"当前 xxx 仅支持 MoE 场景"
| 日志类型 | 路径 | 内容 |
|---|---|---|
| ATB 日志 | <MY_DIR>/log/<log_name>/atb/atb_*.log | ATB 算子调度、infershape、setup |
| 下层组件日志 | <MY_DIR>/log/<log_name>/debug/plog/plog-*.log | GE、RUNTIME、OP、ASCENDCL |
# 查找 ACLNN 加载
grep -i "aclnn\|LoadMethod\|workspace" atb_*.log
# 查找错误
grep -i "error\|fail\|ERROR" atb_*.log
# 查找测试用例执行
grep -i "Case\|times" atb_*.log
# 查找 ACLNN 底层错误
grep -i "161001\|161002\|errno" plog-*.log
# 查找 kernel 执行
grep -i "kernel\|execute" plog-*.log
# 查找内存分配
grep -i "malloc\|aclrtMalloc" plog-*.log
npu-smi info
source <CANN_PATH>/set_env.sh
source <ATB_REPO_PATH>/output/atb/set_env.sh
# 或指定 ABI 版本
source <ATB_REPO_PATH>/output/atb/set_env.sh --cxx_abi=1
echo "ATB_HOME_PATH=$ATB_HOME_PATH"
ls -la $ATB_HOME_PATH/lib/libatb_test_framework.so
cd <ATB_REPO_PATH>/tests/framework/python/CsvOpsTestTool
python3 atb_csv_ops_test.py -i <CSV_FILE_PATH>
| 检查项 | 命令 | 预期结果 |
|---|---|---|
| NPU 设备 | npu-smi info | 显示可用设备 |
| ATB_HOME_PATH | echo $ATB_HOME_PATH | 指向 cxx_abi_0/1 目录 |
| 测试框架库 | ls $ATB_HOME_PATH/lib/libatb_test_framework.so | 文件存在 |
| 依赖库版本 | ldd $ATB_HOME_PATH/lib/libatb_test_framework.so | 所有依赖可解析 |
| ACLNN 符号 | nm -D $ASCEND_TOOLKIT_HOME/lib64/libopapi_nn.so | grep aclnn | 符号存在 |
## 问题名称
**错误信息：**
[粘贴错误信息]
**日志分析：**
- ATB 日志: [关键行]
- 下层日志: [关键行]
**根本原因：**
[分析原因]
**解决方案：**
[解决方案]
**验证方法：**
[验证命令]
版本: 1.1.0
更新: 2026-04-25 - 格式标准化