メニュー
ATB 调试指南技能。当用户遇到 ATB 算子测试问题、需要分析错误原因、或需要了解 ATB 环境配置时调用此技能。 覆盖：环境配置问题、ABI版本不匹配、内存错误、CSV测试失败、ACLNN接口问题等常见场景。
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
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コマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
评估 CANN 算子仓的「进阶教程 / 开发指南」类文档质量——通读文档 + 对照算子代码**静态**查证(默认不跑),按五轴(找得到/信得过/学得会/可操作/读得懂)找出 漏讲/讲不清/过时/对不上代码/概念讲错,产出带证据与改进建议的体检报告(MD + HTML)。涉及「评进阶教程 / 开发指南文档质量 / 文档对不对得上代码 / 教程审稿 / tutorial 体检 / 文档信不信得过」等意图时使用。只评不改不跑,只对着文档与代码出诊断。
Run NPU inference/training tests on a remote SSH server with vllm-ascend Docker container. Use when the user asks to test models on NPU, run inference on Ascend devices, or deploy models to an SSH server.
Track daily PRs and Issues from vllm-project/vllm and vllm-project/vllm-ascend, filter by model (DeepSeek/Qwen/GLM/MiniMax/Kimi) and tech topics (PD disaggregation, MTP, quantization, graph mode, performance), analyze with LLM, and generate a Markdown report. Use when user wants vllm daily tracker, PR/Issue digest, or Ascend inference ecosystem monitoring.
| 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 - 格式标准化