메뉴
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에서 현재 제공할 수 있는 파일을 다운로드하세요.
评估 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.
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 - 格式标准化