atb-debug-guide

ATB 调试指南是一个面向 ATB 算子测试排障的技能，适合在用户遇到 ATB 算子测试问题、需要分析错误原因或了解 ATB 环境配置时使用。使用前需要从用户处获取 CANN 安装路径（CANN_PATH，如 /usr/local/Ascend/cann-9.0.0-beta.2）和 ATB 仓库路径（ATB_REPO_PATH），未提供时可使用默认路径。\n\n主要能力按问题类型组织：\n\nABI 版本不匹配：典型错误为 libatb_test_framework.so 无法打开或 undefined symbol。原因是 ATB 输出目录存在 cxx_abi_0（旧）与 cxx_abi_1（新）两个 ABI 版本，测试框架库与依赖库必须一致。方案 A 使用 source <ATB_REPO_PATH>/output/atb/set_env.sh --cxx_abi=1；方案 B 为创建软链接（不推荐）。可用 ls 和 ldd 验证。\n\n内存错误：ERROR_OUT_OF_HOST_MEMORY，可能原因包括 Runner 中 IN_TENSOR_NUM/OUT_TENSOR_NUM 与接口规格不一致、输出 shape 推导错误、测试 shape 超出设备内存。需对照接口规格检查 Runner 与 InferShapeImpl，或减小 shape。\n\nTensor 维度错误：ERROR_INVALID_TENSOR_DIM_NUM、ERROR_INVALID_TENSOR_DIM，需检查维度数量、维度取值范围及可整除性。\n\n数据类型错误：ERROR_INVALID_TENSOR_INI_MATCH 或 KeyError，需使用 data_generation.py 支持的 dtype，如 float、float16/half、bf16/bfloat16、int8/char、int32/int、int64/long。\n\nACLNN 函数签名不匹配：undefined symbol 或 161001/161002 错误码。161001 为参数空指针，161002 为参数类型/维度/取值无效。可用 nm -D 检查符号。\n\nACLNN MoE 场景不匹配：ATB 算子为非 MoE 设计但 ACLNN 仅支持 MoE，需回退到 OPS 实现（推荐），或构造单分组 groupIndex 与全 1 smoothScales（复杂，不推荐）。\n\n日志分析：ATB 日志位于 <MY_DIR>/log/<log_name>/atb/atb_.log，下层组件 plog 位于 debug/plog/plog-.log，提供 grep 关键字和分析顺序（ATB 层、接口层、运行时层）。\n\n环境检查流程：npu-smi info 检查设备、source CANN 与 ATB 的 set_env.sh、验证 ATB_HOME_PATH 与测试框架库、运行 CSV 测试 atb_csv_ops_test.py。另提供调试检查表与新问题记录模板。限制方面，资料未提供支持的平台范围、安装方式、收费信息及效果保证，需以实际环境为准。