本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 28 天前 | ||
| 1 个月前 | ||
| 24 天前 | ||
| 12 天前 | ||
| 9 小时前 | ||
| 25 天前 | ||
| 1 个月前 | ||
| 14 小时前 | ||
| 29 天前 | ||
| 1 天前 | ||
| 14 小时前 | ||
| 3 个月前 | ||
| 24 天前 | ||
| 30 天前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 29 天前 | ||
| 5 个月前 | ||
| 1 个月前 | ||
| 6 个月前 | ||
| 6 个月前 | ||
| 3 天前 | ||
| 3 天前 | ||
| 10 天前 | ||
| 10 天前 | ||
| 17 天前 | ||
| 1 个月前 | ||
| 9 小时前 | ||
| 2 个月前 | ||
| 2 天前 | ||
| 10 天前 |
📖 项目简介
OAM-Tools（Operations, Administration, and Maintenance）是华为 CANN 的开源运维工具集，为昇腾 AI 处理器开发者提供故障定位与性能调优两大核心能力。工具集覆盖从故障信息采集、AI Core Error 分析到 AI 任务性能采集与分析的完整运维链路，帮助开发者快速定位软硬件问题、优化 AI 任务性能。
适用场景：
- AI 训练/推理任务运行异常时，一键采集故障信息、分析 AI Core Error 根因
- AI 任务性能调优，采集各运行阶段关键性能指标，定位性能瓶颈
- 分布式训练场景下，测试集合通信（HCCL）的功能与性能
✨ 核心特性
OAM-Tools 包含四大核心组件，协同覆盖昇腾 AI 处理器的运维全场景：
| 组件 | 功能定位 | 核心能力 |
|---|---|---|
| asys（故障信息收集） | 一键式故障信息采集与诊断 | 故障信息收集、业务复跑+信息收集、软硬件/Device 状态展示、健康检查、综合检测、组件检测、trace/coredump/stackcore/coretrace/UB 文件解析、实时堆栈导出、AI Core Error 故障信息解析、性能数据采集 |
| msaicerr（AI Core Error 分析） | AI Core Error 问题定位 | AI Core Error 问题分析、Dump 文件解析与数据类型转换、运行环境检查 |
| msprof（性能调优） | AI 任务性能采集与分析 | 采集 AI 任务运行性能数据、AI 处理器系统数据、Host 侧系统数据、msproftx 数据；支持动态/延迟采集；提供 ACL/Ascend Graph/acl.json/环境变量多种采集方式 |
| hccl_test（HCCL 性能测试） | 集合通信功能与性能测试 | 分布式训练/推理场景下，基于 HCCL 单算子 API 测试集合通信的功能正确性与性能 |
🏗️ 项目架构
OAM-Tools 采用模块化设计，四大组件相互独立又协同工作：asys 与 msaicerr 聚焦故障诊断，msprof 聚焦性能分析，hccl_test 聚焦通信测试。所有组件共享 CANN 运行时环境，通过统一的构建系统（CMake + build.sh）编译打包为 .run 安装包，安装后释放到 CANN 安装目录的 tools/ 子目录下。
目录结构：
oam-tools/
├── cmake/ # 构建配置（CMake 模块、第三方库下载脚本）
├── scripts/ # 辅助构建与检查脚本（oat_check.sh 等）
├── src/ # 源代码
│ ├── asys/ # asys：故障信息收集工具（Python）
│ ├── msaicerr/ # msaicerr：AI Core Error 分析工具（Python）
│ ├── msprof/ # msprof：性能调优工具（C++ collector + Python 分析脚本）
│ ├── hccl_test/ # hccl_test：HCCL 性能测试工具（C++）
│ ├── operator_cmp/ # 算子比对工具
│ └── third_party/ # 依赖的第三方库头文件
├── test/ # UT/ST 测试用例
├── docs/ # 项目文档（中/英文）
│ ├── zh/ # 中文文档（asys/msaicerr/profiling/hccl_test 用户指南）
│ ├── en/ # 英文文档
│ └── figures/ # 图片资源
├── init_env.sh # 开发环境一键安装脚本
├── build.sh # 项目编译脚本
├── CMakeLists.txt # CMake 主配置文件
└── version.cmake # 版本与依赖声明
🚀 快速开始
1. 环境安装
请先参考快速安装指南完成 CANN 软件包与编译依赖的安装。
2. 编译构建
编译前请先根据 CANN 安装路径加载环境变量：
source <CANN安装路径>/set_env.sh
root 用户默认路径为
/usr/local/Ascend/cann；非 root 用户默认为${HOME}/Ascend/cann；指定路径安装时为${install_path}/cann。
bash build.sh
3. 安装到 CANN 目录
./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full
🧩 支持的硬件环境
在搭建环境之前，请先确认硬件在本工具的支持范围内，若无昇腾设备也可以通过 docker 方式编译构建（详见快速安装）。
-
CPU 架构：
aarch64、x86_64 -
昇腾 AI 处理器：
npu-smi infoName 列适用产品 对应 CANN ops 包代号 910BAtlas A2 训练系列产品 / Atlas 800I A2 推理产品 910b910_93Atlas A3 训练系列产品 / Atlas A3 推理系列产品（业内"910C"对应此项） A3950Atlas 950 系列产品 950npu-smi info实际可能显示带子型号的字符串（如910B1/910B2/910B3/910B4），按"Name 列包含上述关键字"的规则匹配即可。- "910C"是商用别称。自 CANN 8.5.0 起，ops 包统一命名为
Ascend-cann-A3-ops_*，请勿在包名中拼写为910c、910_c、910_93等形式。 - 其它芯片暂不支持，欢迎提交 issue 反馈。CANN ops 包名拼接规则与下载详见快速安装。
🔧 源码编译
编译前请先根据 CANN 安装路径加载环境变量：
source <CANN安装路径>/set_env.sh
root 用户默认路径为
/usr/local/Ascend/cann；非 root 用户默认为${HOME}/Ascend/cann；指定路径安装时为${install_path}/cann。
执行以下命令进行编译：
bash build.sh
如需指定第三方库路径，可通过 --cann_3rd_lib_path 参数传入：
bash build.sh --cann_3rd_lib_path=${third_party_path}
--cann_3rd_lib_path：第三方库存储目录，默认值为./third_party。若本地不存在第三方库，编译脚本将自动从 gitcode 开源仓库下载各第三方库源码。- 编译过程中会自动下载闭源二进制包，该包含有保证功能正常运行所需的库及头文件，且仅提供 release 版本，即使编译选项指定为 debug，也只会下载 release 版本的 tar 包。
- 若编译环境无法访问网络，请参考离线编译环境准备提前完成依赖包的下载与配置，并通过
--cann_3rd_lib_path参数指定依赖包所在目录后再执行编译。 - 更多编译参数请通过
bash build.sh -h查看。
编译完成后，build_out 目录下会生成 cann-oam-tools_<cann_version>_linux-<arch>.run 软件包，其中 <cann_version> 为版本号，<arch> 为操作系统架构（可选值：x86_64 或 aarch64）。
📦 安装与验证
安装
可执行如下命令安装编译生成的 oam-tools 软件包：
./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full --install-path=${install_path}
安装完成之后，用户编译生成的 oam-tools 软件包会替换已安装 CANN 开发套件包中的 oam-tools 相关软件。
如果您的环境上
grep版本大于 3.8.0，安装时会出现告警，例如grep: warning: stray \ before -，这是由于 grep 高版本对表达式有更严格的校验，但并不影响安装和使用。
验证
编译完成后，用户可以进行测试验证项目功能是否正常。
Python 依赖安装已在环境准备中处理，无需额外操作。
# 执行所有组件测试
bash build.sh -u
# 指定单独组件测试（可选：asys / msaicerr / msprof / all）
bash build.sh -u --component msprof
UT 测试用例编译输出目录为 build，如果想清除历史编译记录：
rm -rf build_out/ build/
▶️ 功能运行示例
完成安装后，工具会被释放到 CANN 安装目录下的 tools/ 子目录（root 用户默认在 /usr/local/Ascend/cann/tools/）。运行示例前请先加载环境变量：
# root 用户默认路径；非 root 用户将 /usr/local 替换为 ${HOME}
source /usr/local/Ascend/cann/set_env.sh
# 指定路径安装时：source ${install_path}/cann/set_env.sh
执行上方命令后，
${ASCEND_INSTALL_PATH}即为 CANN 安装目录：
- root 用户默认：
/usr/local/Ascend/cann- 非 root 用户默认：
${HOME}/Ascend/cann- 指定路径安装：
${install_path}/cann
asys（故障信息收集 / 诊断）
src/asys/ 目录下同时存在 asys.py 和指向它的软链接 asys（src/asys/asys -> ./asys.py），CMake 通过 install(DIRECTORY ${ASYS_DIR} ...) 将整个目录原样拷贝，软链接也会保留。因此安装后两种调用都能直接用：
# 形式一：显式 python3 调用 .py
python3 ${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys.py -h
# 形式二：直接调用软链接 asys（asys.py 自带 #!/usr/bin/env python3 shebang）
${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys -h
asys 的子命令在 src/asys/cmdline/cmd_parser.py 的 Command 枚举中定义，包含 info / health / collect / launch / diagnose / analyze / config / profiling。在环境变量加载生效后，可以直接以 asys 调用：
# 采集主机与 device 的软硬件信息（不依赖待诊断任务，通常作为环境自检）
asys info -r="status" -d=0
# 体检 device 健康状态
asys health
# 采集环境中已存在的运维信息并打包到指定输出目录
asys collect --output <output_dir>
msaicerr（AI Core Error 分析）
msaicerr 入口为 src/msaicerr/msaicerr.py，安装后位于 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py。
# 1) 解析一个已有的 AI Core Error 报告路径，结果输出到 <output_dir>
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0
# 2) 解析单个 dump 文件（dtype 取值参见 -h 输出）
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16
# 3) 检测当前环境是否具备运行 msaicerr 所需的条件（仅依赖 device 编号）
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -e -dev 0
# 完整参数说明
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -h
msprof（性能调优）
msprof 由 C++ 侧 collector（basic、dvvp）和 msprof Python wheel（分析脚本）组成。bash build.sh 完成后，wheel（msprof-0.0.1-py3-none-any.whl）会被拷贝到 src/msprof/collector/dvvp/msprofbin/ 并打包进 .run 安装包；安装时自动解包到 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/ 目录下，无需手动 pip install。
分析脚本由 msprof collector 流水线内部调用（入口为 profiler_tool/analysis/msprof/msprof.py），不会在 PATH 中注册独立的命令行命令。如需手动运行分析脚本，可直接以 python3 调用安装目录下的入口：
python3 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h
C++ 侧 collector 一般作为 CANN profiler 流水线的内置组件被调用，开发者无需直接执行；回归通过 bash build.sh -u --component msprof 运行 gtest 用例（产物 build/test/ut/msprof/msprofbin/msprof_bin_utest）。
🅿️ Pre-commit
pre-commit 是一个用于管理和维护 Git 预提交钩子（hooks）的框架，通过在代码提交前自动化执行代码检查、格式化和安全扫描，确保代码质量并统一团队规范，显著减少 CI/CD 流水线失败并提升协作效率。
本仓已配置 pre-commit，用户可以参考 CANN 社区的pre-commit 配置指导书中第 3 章节安装 pre-commit。OAT 检查工具已改用 Python 版本 oat-py（通过 pip install oat-py>=1.0.0 安装），无需配置 Java/Maven 环境；首次运行时 pre-commit 会为各 hook 创建隔离的虚拟环境，耗时稍长。
📚 相关文档
组件用户指南
| 组件 | 文档链接 | 说明 |
|---|---|---|
| asys | asys 工具用户指南 | 故障信息收集、业务复跑+故障信息收集、软硬件和 Device 状态信息展示、健康检查、综合检测、组件检测、trace/coredump/stackcore/coretrace/UB 文件解析、实时堆栈导出、环境配置、AI Core Error 故障信息解析等 |
| msaicerr | msaicerr 工具用户指南 | 分析 AI Core Error 问题、解析 Dump 文件、检查环境等 |
| msprof | 性能调优工具用户指南 | 采集和分析昇腾 AI 处理器上 AI 任务各运行阶段的关键性能指标，定位软、硬件性能瓶颈 |
| hccl_test | HCCL 性能测试工具用户指南 | 分布式训练或推理场景下，测试集合通信的功能与性能 |