企业官网建设流程全解析

OAM-Tools：昇腾 CANN 运维工具集——从四大核心组件到源码编译、安装与验证全流程

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

OAM-Tools 是华为 CANN 的开源运维工具集，围绕昇腾 AI 处理器的故障定位与性能调优两大核心场景，提供故障信息收集、AI Core Error 分析、AI 任务性能采集与 HCCL 集合通信测试能力。本文基于仓库根目录的 README_en.md 展开，覆盖项目架构、支持硬件、编译参数、打包安装与分组件测试验证的完整链路，并结合 CMakeLists.txt、build.sh、scripts/run_tests.sh 等构建与测试源码，帮助读者从零完成一次可验证的编译安装，并理解每个环节背后的实现细节。

项目概述与适用场景

OAM-Tools（Operations, Administration, and Maintenance）为昇腾 AI 处理器开发者提供故障诊断与性能调优两类核心能力，覆盖从故障信息采集、AI Core Error 分析到 AI 任务性能采集与分析的完整运维链路。其典型使用场景包括：

• AI 训练/推理任务运行异常时，一键采集故障信息、分析 AI Core Error 根因；
• AI 任务性能调优，采集各运行阶段关键性能指标，定位性能瓶颈；
• 分布式训练场景下，测试集合通信（HCCL）的功能与性能。

四大核心组件

工具集由四个相互独立又协同工作的组件构成，各自的功能定位与核心能力如下：

注意：各组件的用户指南目前仅提供中文版（位于docs/zh/），英文翻译进行中。

从源码目录看，四个组件的实现语言与形态并不相同：asys 与 msaicerr 是纯 Python 工具（src/asys/、src/msaicerr/），msprof 由 C++ 采集器加 Python 分析脚本组成（src/msprof/collector/），hccl_test 为 C++ 实现（src/hccl_test/）。这一差异直接影响后续的编译与测试流程——例如 build.sh 中对 asys/msaicerr 的 UT 会跳过重量级编译打包环节，直接进入测试（见下文"分组件测试验证"一节）。

项目架构与目录结构

OAM-Tools 采用模块化设计：asys 与 msaicerr 聚焦故障诊断，msprof 聚焦性能分析，hccl_test 聚焦通信测试。所有组件共享 CANN 运行时环境，通过统一的构建系统（CMake + build.sh）编译，打包为.run（默认）/.rpm/.deb安装包；安装后释放到 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 # 版本与依赖声明

构建系统的实现要点

从 CMakeLists.txt 的源码结构看，构建系统在以下几个细节上与文档描述相互印证：

1. CMake 版本下限为 3.18：CMakeLists.txt 中声明cmake_minimum_required(VERSION 3.18)，原因是cmake/install_bundle.cmake解压闭源包使用的file(ARCHIVE_EXTRACT)子命令自 CMake 3.18 引入；低于该版本会在配置阶段直接报错中断。
2. 包类型决定安装路径形态：CMakeLists.txt 中，PACKAGE_TYPE为rpm/deb（或含 rpm/deb 组合的deb,rpm、all）时，INSTALL_TOOLS_DIR使用相对路径tools，交由 CPack 的CPACK_PACKAGING_INSTALL_PREFIX统一收口；run 包则使用绝对 staging 路径。源码注释特别指出：若只判断rpm/deb两个精确取值，deb,rpm与all会落入 else 分支，导致tools/*与lib64/*不进包载荷——这与 build.sh 中--pkg-type参数接受run/rpm/deb/deb,rpm/all五种取值的口径完全一致。
3. 闭源 bundle 包的组件级校验：配置期会把闭源二进制包解压出的 AML 库拷贝进包载荷，并对必需库（如libascend_ml.so、libascend_ml_detect.so）做存在性校验，缺失即在配置期FATAL_ERROR，避免产出"安装成功但运行期才崩"的残缺包（见 CMakeLists.txt）。
4. 版本与依赖声明：version.cmake 通过set_cann_package(oam-tools VERSION "9.2.0")声明包版本，并通过set_cann_build_dependencies/set_cann_run_dependencies声明构建与运行期对 runtime、metadef、hccl 等 CANN 包的版本依赖（当前要求>=9.0）。编译产物文件名中的<cann_version>即来源于此。

支持的硬件环境

在搭建环境之前，请先确认硬件在本工具的支持范围内；若无昇腾设备，也可以通过 Docker 方式编译构建（详见 快速安装指南）。

• CPU 架构：aarch64、x86_64
• 昇腾 AI 处理器：

三个使用要点：

• npu-smi info实际可能显示带子型号的字符串（如910B1/910B2/910B3/910B4），按"Name 列包含上述关键字"的规则匹配即可；
• "910C" 是商用别称。自 CANN 8.5.0 起，ops 包统一命名为Ascend-cann-A3-ops_*，请勿在包名中拼写为910c、910_c、910_93等形式；
• 其它芯片暂不支持，欢迎提交 issue 反馈。ops 包名拼接规则与下载方式详见 快速安装指南。

快速开始：从零编译到验证

以下是 root 用户默认安装路径下从零跑通的最短路径，四步即可得到可用的工具。第三方库定制、离线编译、调试构建等完整参数见"源码编译"章节，分组件的测试验证方式见"安装与验证"章节。

第 1 步：安装依赖

参考 快速安装指南 完成 CANN 软件包（toolkit + 与芯片匹配的 ops 包）与编译依赖的安装。该文档同时给出了 WebIDE、Docker、手动安装三种环境准备方式与前置依赖清单（python >= 3.10.0、gcc >= 7.3.0、cmake >= 3.18.0、ccache、protobuf 等）。

第 2 步：编译

# 非 root 用户将 /usr/local 替换为 ${HOME} source /usr/local/Ascend/cann/set_env.sh bash build.sh

编译产物为build_out/cann-oam-tools_<cann_version>_linux-<arch>.run，其中<arch>为x86_64或aarch64。

第 3 步：安装

./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full

第 4 步：验证

重新加载环境变量后调用 asys，能正常打印帮助信息即表示安装成功：

source /usr/local/Ascend/cann/set_env.sh asys -h

需要在真实环境中跑通各组件功能，见 运行示例：其deploy.sh会依次执行asys/run.sh（设备健康检查）、msaicerr/run.sh（内置样例算子环境检查）、msprof/run.sh（采集 5 秒系统级 CPU/内存性能数据）。

源码编译

加载环境变量

编译前请先根据 CANN 安装路径加载环境变量：

source <CANN安装路径>/set_env.sh

root 用户默认路径为/usr/local/Ascend/cann；非 root 用户默认为${HOME}/Ascend/cann；指定路径安装时为${install_path}/cann。

从 build.sh 的源码看，脚本在解析参数时会处理ASCEND_HOME_PATH：若环境中已存在该变量则直接沿用，否则 root 用户回退到/usr/local/Ascend/latest、非 root 用户回退到~/Ascend/latest。因此也可以显式使用--ascend_install_path=<PATH>参数指定 CANN 安装位置。

执行编译

基本编译命令：

bash build.sh

如需指定第三方库路径，可通过--cann_3rd_lib_path参数传入：

bash build.sh --cann_3rd_lib_path=${third_party_path}

如需构建 rpm/deb 格式的安装包，可通过--pkg-type参数指定：

• --pkg-type=<TYPE>：指定安装包格式，取值run/rpm/deb/deb,rpm/all（deb,rpm与all为一次构建多种包格式），默认run（--pkg为--pkg-type=run的别名）。build.sh 中对该取值做了白名单校验，非法取值会直接退出并打印 usage。
• 编译产物：run 包为cann-oam-tools_<cann_version>_linux-<arch>.run，rpm/deb 包为cann-oam-tools_<cann_version>_linux-<arch>.rpm/.deb。
• 构建 rpm/deb 包还需 rpmbuild >= 4.14.0 / dpkg（>= 1.19.0.5），仅构建期需要；rpm/deb 包的安装与卸载详见 安装包格式说明。

编译参数与依赖说明

• --cann_3rd_lib_path：第三方库存储目录，默认值为./third_party。若本地不存在第三方库，编译脚本将自动从 gitcode 开源仓库下载各第三方库源码。
• 编译过程中会自动下载闭源二进制包，该包含有保证功能正常运行所需的库及头文件，且仅提供 release 版本，即使编译选项指定为 debug，也只会下载 release 版本的 tar 包。
• 闭源二进制包按分支拉取：不指定时，编译脚本会依据当前 git 提交自动探测所属发布分支（从master拉出的分支拉 master 包，从 9.1.0 线拉出的分支拉 9.1.0 包），探测不出时回退master。也可通过--bundle_branch=<NAME>显式指定分支，个人分支探测不准时建议显式指定。当前提供闭源包的分支为master与9.1.0；指定其它分支会在配置阶段报错。从 build.sh 看，该参数取值会做字符白名单校验（仅允许[A-Za-z0-9._/-]），防止 shell 元字符注入到 CMake 命令行。
• 编译过程中会通过git clone拉取msprof和msprobe子仓（分别用于构建 msprof 分析 wheel 和同步 msaccucmp 工具）。子仓使用 HTTPS 协议克隆时需要配置个人访问令牌替代登录密码，否则克隆会失败。
• 若编译环境无法访问网络，请参考 离线编译环境准备 提前完成依赖包的下载与配置，并通过--cann_3rd_lib_path参数指定依赖包所在目录后再执行编译。离线预置脚本 cmake/download_libs.py 同样支持--bundle_branch指定要预置的闭源包分支（默认自动探测），须与联编时的分支保持一致。
• 闭源二进制包会解压到仓库根目录的bundle/下。若bundle/已存在且非空，构建会复用该目录并跳过下载；如需强制重新下载或修复残缺的bundle/目录，可执行bash build.sh --make_clean后重新编译，也可手动删除bundle/后再次执行bash build.sh。从 build.sh 看，--make_clean除了清理bundle/，还会清理子仓目录submodule/。
• 更多编译参数（如-j<N>编译线程数、-O<N>优化等级、--build-type=<TYPE>、--extra-cmake-args=<NAME=VALUE>等）请通过bash build.sh -h查看。

编译完成后，build_out目录下会生成cann-oam-tools_<cann_version>_linux-<arch>.run软件包，其中<cann_version>为版本号，<arch>为操作系统架构（可选值：x86_64或aarch64）。

安装与验证

安装

oam-tools 安装包支持.run（默认）、.rpm、.deb三种格式，概览如下：

rpm 包不支持在 Ubuntu/Debian 上安装，此类系统请使用 deb 或 run 包（背景见 安装包格式说明）。

注意：在 CANN 未以 deb/rpm 包方式安装的主机上，通过 deb 包安装本工具后执行apt upgrade等升级操作会因依赖不满足报错（apt --fix-broken install会移除本包），执行 apt 升级前请先卸载本包，详见 安装包格式说明。

可执行如下命令安装编译生成的 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 / install / upgrade / uninstall / all） bash build.sh -u --component msprof

--component与测试范围、环境准备章节的对应关系如下：

install、upgrade、uninstall仅包含 ST，用例依赖build_out/cann-oam-tools_<cann_version>_linux-<arch>.run。推荐通过上表中的build.sh -u --component ... --st运行，脚本会先完成构建打包；若直接执行 scripts/run_tests.sh，需先确保build_out/下已有可用.run包。

从测试框架源码看，build.sh -u最终会转发参数调用 scripts/run_tests.sh 执行测试。该脚本内部维护了各测试套件与执行引擎的映射（见 scripts/run_tests.sh）：asys/msaicerr 的 UT 与 ST 均基于 pytest，msprof UT 基于 gtest，install/upgrade/uninstall 仅含 ST 且同样基于 pytest。此外脚本内置了固定为 80% 的代码覆盖率基线，低于该值会判定为失败。

build.sh 中还有一个与组件形态相关的优化：asys 与 msaicerr 是纯 Python 组件、没有编译产物，因此当-u指定这两个组件时会跳过 cmake/make/cpack 打包等重量级构建环节，仅生成 asys 的 chip handler（src/asys/asys.cmake）后直接进入测试阶段——这与"组件测试范围"表中 asys/msaicerr 只跑 Python UT+ST 的口径一致。

UT 测试用例编译输出目录为build，如果想清除历史编译记录：

rm -rf build_out/ build/

Pre-commit

pre-commit 是一个用于管理和维护 Git 预提交钩子（hooks）的框架，通过在代码提交前自动化执行代码检查、格式化和安全扫描，确保代码质量并统一团队规范，显著减少 CI/CD 流水线失败并提升协作效率。

本仓已配置 pre-commit（见仓库根目录 .pre-commit-config.yaml）。OAT 检查工具已改用 Python 版本 oat-py（通过pip install oat-py>=1.0.0安装），无需配置 Java/Maven 环境；首次运行时 pre-commit 会为各 hook 创建隔离的虚拟环境，耗时稍长。贡献流程与规范详见 贡献指南。

相关文档与延伸阅读

• 快速安装指南：CANN 软件包与编译依赖的安装（WebIDE / Docker / 手动安装三种方式）、离线编译环境准备、环境验证与环境变量配置；
• 安装包格式说明：rpm/deb 包的安装与卸载细节；
• 运行示例：asys / msaicerr / msprof 各组件的即装即跑验证脚本；
• asys 用户指南、msaicerr 用户指南、msprof 用户指南、hccl_test 用户指南：各组件功能与限制说明；
• 贡献指南：社区贡献流程与规范；
• 安全声明 与 许可证（Apache 2.0）。

需要说明的是，本文档中的版本口径、构建参数与测试流程均以当前仓库实际内容为准；当构建脚本或 CMake 配置升级后，请以仓库最新的build.sh -h输出与上述源码文件为准。

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools