前言

CANN（Compute Architecture for Neural Networks）是昇腾AI处理器的基础软件层，负责对接底层硬件资源与上层深度学习框架，为昇腾NPU集群提供编译、运行、通信全链路的软件抽象。当集群规模从单卡扩展到数十乃至上百个计算节点时，运维的复杂度呈指数级上升：驱动状态需要逐节点确认，AI Core异常的错误信息散布在多个日志层级，算子执行失败的原因往往隐藏在原始dump数据的二进制序列中。传统的故障定位方式要求运维人员同时熟悉NPU驱动接口、系统日志格式和AI Core硬件规格，这种知识储备的门槛限制了集群的可维护性。

oam-tools是CANN社区开源的运维与性能调优工具集，设计目标正是降低昇腾NPU集群的运维门槛。该项目将健康检查、故障诊断、信息采集三大能力整合为统一的命令行入口，运维人员无需深入理解驱动内部实现，只需掌握工具的调用方式即可完成从环境验证到故障隔离的完整流程。oam-tools面向的硬件环境覆盖Atlas A2训练系列、Atlas 800I A2推理产品、Atlas A3训练和推理系列以及Atlas 950产品，对应npu-smi输出中的910B、910_93（即商用场景中的910C）和950三种芯片型号。工具链支持aarch64和x86_64两种CPU架构，编译产物为自解压的run安装包，部署过程不依赖包管理器的介入。

整个工具链的核心模块分布在src目录下，包括负责故障信息收集与诊断的asys、专注AI Core错误深度解析的msaicerr、面向性能调优的msprof以及针对集合通信性能测试的hccl_test。其中asys和msaicerr是日常运维中使用频率最高的两个模块，前者覆盖了从环境自检到故障现场保全的全流程，后者则专门解决AI Core执行异常时数据难以解读的问题。理解这两个模块的源码结构和命令接口，是掌握oam-tools的切入点。

oam-tools源码结构全览

克隆仓库后的顶层目录中，src目录包含了所有模块的源代码，每个模块对应一个子目录。以asys模块为例，其目录结构如下：analyze/负责trace文件与coredump的解析逻辑；cmdline/定义了命令行参数解析器，其中cmd_parser.py中的Command枚举声明了所有子命令名称；collect/实现了运维信息打包功能；common/提供跨模块的公共工具函数；conf/存放配置文件的读写逻辑；diagnose/封装了综合诊断流程；drv/读取NPU驱动层面的状态数据；health/是健康检查的核心实现；info/采集软硬件信息；launch/支持带诊断信息收集的任务启动；params/管理命令行参数的结构化定义；profiling/对接CANN的性能分析接口；view/提供诊断结果的渲染输出。asys的主入口为src/asys/asys.py，同时源码目录中包含一个名为asys的软链接指向该文件，这一设计使得安装后的调用方式更加灵活。

msaicerr模块的目录结构相对扁平，主入口为src/msaicerr/msaicerr.py，核心解析逻辑由ms_interface/子目录提供。ms_interface/中的aicore_error_parser.py是AI Core错误解析的引擎，负责将原始错误码转换为人类可读的错误描述；aic_error_info.py维护错误信息的结构化数据；dsmi_interface.py封装了与设备管理系统（DSMI）的通信接口；dump_data_parser.py负责解析训练过程中dump出的算子输入输出数据；golden_op.py提供算子正确性验证的参考实现。proto_parse/子目录处理Protocol Buffers格式的数据反序列化，这与dump文件的二进制结构直接相关。从目录组织来看，ms_interface/目录下还包含了ascend910_96/和ascend950/两个芯片型号专属的目录，说明不同芯片的硬件抽象层接口存在差异，msaicerr需要针对具体芯片型号选择对应的解析路径。

msprof模块采用C++与Python混合实现，C++侧负责数据采集（collector），Python侧的wheel包负责分析脚本。这种设计充分利用了C++在高速数据采集场景下的性能优势，同时保留了Python在数据分析与可视化方面的灵活性。hccl_test模块则专注于集合通信的功能与性能测试，分布式训练场景中的通信瓶颈是常见的性能问题来源，hccl_test提供了量化通信效率的手段。

asys health：集群健康检查步步实操

asys工具的安装遵循标准的CANN软件包更新流程。在具备昇腾设备的环境中，编译完成后的产物位于build_out/cann-oam-tools_<cann_version>_linux-.run文件，执行该自解压包即可完成安装。

bash build.sh
./cann-oam-tools_<cann_version>_linux-<arch>.run --full --install-path=/usr/local/Ascend

The CANN安装路径的规范约束确保所有工具统一在${ASCEND_INSTALL_PATH}/tools/下释放，避免与系统包管理器的路径冲突，同时简化环境变量的配置复杂度。

安装完成后，需要加载CANN提供的环境变量脚本使工具在命令行中可见：

source /usr/local/Ascend/cann/set_env.sh

set_env.sh中设置了ASCEND_INSTALL_PATH、PATH和LD_LIBRARY_PATH等关键变量，工具依赖这些变量定位CANN的库文件和配置文件。若未加载环境变量直接运行工具，会因找不到依赖库而失败。

asys支持的子命令在src/asys/cmdline/cmd_parser.py中定义，包括info、health、collect、launch、diagnose、analyze、config和profiling共八个。health子命令用于检查NPU设备的健康状态，是集群上线前验证和周期性巡检的必选工具。

环境信息采集是进入业务前的第一步，使用info子命令可以一次性获取主机和所有NPU设备的软硬件状态：

asys info

asys info不依赖正在运行的训练任务，它通过npu-smi和DSMI接口读取驱动和固件报告的数据，在任务空跑状态下即可完成环境自检。这个特性使其成为环境搭建完成后的首个验证步骤。

该命令的输出包含每张NPU卡的型号、固件版本、驱动版本、芯片温度、内存占用率以及AI Core的计算单元占用情况。温度异常往往是硬件故障的最早信号，通过与正常基线值的比对可以快速判断设备是否存在过热或散热问题。驱动版本的不一致会导致集合通信握手失败，在多节点集群中尤其需要注意各节点驱动版本的对齐。

health子命令对指定设备执行主动健康检查，支持单个设备、连续设备范围和多设备枚举三种设备指定方式：

asys health --dev 0          # 检查第0张卡
asys health --dev 0-7         # 检查第0到第7张卡
asys health --dev 0,2,4,6     # 检查第0、2、4、6四张卡

大规模集群中并非所有卡都需要同时检查，按需指定设备范围可以减少不必要的检查时间开销，同时避免对无关设备的干扰。设备指定语法的三种形式（单个、范围、枚举）覆盖了日常运维中的各类场景需求。

health模块的核心实现位于src/asys/health/asys_health.py，该模块通过DSMI接口查询NPU硬件的内部状态。检查项覆盖NPU驱动模块的加载状态、DDR内存的ECC校验结果、AI Core计算单元的自检结果以及电源模块的工作状态。每个检查项返回通过（PASS）或失败（FAIL）的标识，失败时会附带错误码和初步的定位建议，帮助运维人员缩小排查范围。

输出结果的格式为结构化的检查项列表，关键信息包括设备编号、检查项名称、结果状态以及失败时的错误码。如果某个检查项失败，运维人员可以根据错误码在昇腾社区文档中检索对应的故障处理手册。检查过程中产生的原始数据同时保存到日志文件中，路径在命令输出中有明确提示，离线分析时可以回读这些日志。

msaicerr：AI Core错误深度解析

训练任务执行过程中出现AI Core异常时，原始的错误信息通常以错误码加内存地址偏移的形式呈现，人类无法直接从这些数据中理解故障原因。msaicerr的作用是将这些低层次的错误信号转换为包含根因定位和修复建议的高层次报告，大幅缩短从异常发生到原因确认的时间窗口。

msaicerr的主入口为src/msaicerr/msaicerr.py，安装后位于${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py，支持三种核心使用模式：报告目录解析、单个dump文件解析和环境检查。

第一种模式用于分析已有的AI Core错误报告，这是日常故障处理中最常见的场景。报告目录通常由训练框架在任务异常退出时自动生成，目录中包含错误发生时的上下文数据。调用方式如下：

python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py \
    -p /path/to/report_dir \
    -out /path/to/output_dir \
    -dev 0

报告目录是训练任务异常退出时由CANN runtime自动归档的结果，其中包含错误发生时各算子的执行上下文。-dev参数指定目标设备编号，工具会读取该设备对应的错误记录。路径参数必须使用绝对路径，相对路径在CANN的运行环境上下文中可能指向错误的位置。

分析完成后，输出目录中生成summary.txt和detail.txt两个文件。summary.txt提供错误的结构化摘要，包含出错的设备编号、涉及的AI Core模块名称、错误类型分类、调用栈中的关键函数以及针对该错误的处理建议。处理建议是msaicerr相对于传统方式最大的价值所在：它将错误码与CANN知识库中的已知问题进行了匹配，直接给出升级CANN版本、调整输入shape或修改算子融合策略等可操作的建议，而不是让运维人员在海量的文档中自行检索。

detail.txt包含完整的错误调用栈信息，展示了从顶层训练脚本到具体AI Core硬件执行单元的完整调用链路。通过调用栈可以精确地定位到是哪个算子在什么输入条件下触发了异常，这对于需要修改模型代码或提交算子bug的场景尤为关键。

第二种模式用于分析单个dump文件，这在需要精确定位某个算子执行异常的场景下非常有用：

python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py \
    -d /path/to/dump_file \
    -out /path/to/output_dir \
    -dtype float16

dump文件是训练过程中算子输入输出数据的持久化快照，不包含数据类型元数据。-dtype参数必须由用户明确指定，因为错误的类型声明会导致张量解析结果完全错误。这个设计体现了工具的诚实性：不猜测不确定的数据，而是要求用户提供明确的上下文信息。

-dtype的可选值包括float16、float32、float64、int8、int16、int32和int64，选择依据是待分析dump文件中实际使用的数据类型，通常可以在模型配置或训练脚本中找到对应声明。分析结果同样写入输出目录，包含数据摘要和每个算子输入输出张量的维度与数值范围信息。运维人员可以据此判断是输入数据异常导致的算子溢出，还是算子本身在特定输入shape下存在实现缺陷。

第三种模式是环境检查，用于在正式分析前确认运行环境是否满足msaicerr的依赖条件：

python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -e -dev 0

环境检查不分析任何数据文件，只验证工具所需的运行时依赖是否就绪。这种轻量级的预检机制避免了运维人员在故障现场花费时间排查工具本身的问题，确保故障定位工作从一开始就在正确的环境中进行。

该检查验证DSMI接口的可用性、CANN驱动模块的加载状态以及Python依赖包的完整性。若检查通过，说明工具本身的运行条件已满足，后续的分析失败则指向报告数据本身的问题而非工具配置的问题。若检查失败，工具会明确指出缺失的具体组件或权限问题。

msaicerr的源码结构中，ms_interface/目录下的文件是理解工具能力边界的钥匙。aicore_error_parser.py实现了错误码到错误描述的解码逻辑，这个解码器内置了CANN各版本累积的错误知识库，不需要访问外部文档即可完成大多数常见错误的解读。dump_data_parser.py使用Protocol Buffers的反序列化接口读取dump文件中的二进制数据，这种格式保证了数据在采集端和分析端的一致性。ascend_handler.py根据芯片型号（910_96/950）选择对应的硬件接口实现，确保不同芯片的差异对上层分析逻辑透明。

运维场景实战：三节点集群巡检案例

考虑一个典型的三节点昇腾NPU集群运维场景：每个计算节点配备4张NPU卡组成训练集群，节点之间通过RoCE网络互联。在执行大规模分布式训练任务前，运维人员需要对集群进行全面的健康验证。以下是完整的操作流程。

在管理节点完成环境准备，从CANN开源仓库获取最新版本的oam-tools源码并完成编译安装。整个编译过程由build.sh脚本驱动，脚本内部自动处理第三方库的下载、CMake配置和并行编译：

git clone -b ${branch} https://gitcode.com/cann/oam-tools.git
cd oam-tools
bash build.sh
./cann-oam-tools_<version>_linux-x86_64.run --full --install-path=/usr/local/Ascend
source /usr/local/Ascend/cann/set_env.sh

源码分支标签与CANN版本存在配套关系，需要从release仓库查询对应的分支名称。使用错误的分支可能导致API不兼容。build.sh在编译过程中会自动下载闭源的二进制包，该包包含工具正常运行所需的运行时库，即使在debug编译选项下也只会提供release版本的二进制。

集群环境验证的第一步是确认物理连接和驱动加载正常。使用asys info对全集群8张卡（3节点x4卡+1管理节点假设有1张卡）进行软硬件信息采集：

asys info

输出信息确认各节点的NPU卡均被正确识别，驱动版本一致（避免因版本不一致导致的集合通信兼容问题），芯片温度在正常范围内。如果info命令输出中出现了Unknown Device或驱动版本显示为空，说明对应节点的驱动安装存在问题，需要在进一步操作前解决该问题。

确认环境正常后，进入核心的健康检查阶段。使用asys health对全集群所有8张计算卡执行并行健康检查，指定设备范围为0到7：

asys health --dev 0-7

输出显示大部分设备状态正常，但Device 3报告AI Core模块状态为FAIL，附带错误码0xA12345。在大规模集群中，这种局部故障如果不被及时发现就启动训练任务，会导致整个分布式训练在执行若干step后异常退出，造成计算资源的浪费和故障定位的额外成本。asys health的价值在此处体现：它将故障检测前置到任务提交之前，使运维人员可以在受控状态下分析问题。

根据错误码0xA12345的提示，使用msaicerr对Device 3的错误报告进行深度解析。确认报告目录的路径（通常位于训练任务的日志输出目录下）后，执行分析命令：

python3 /usr/local/Ascend/cann/tools/msaicerr/msaicerr.py \
    -p /workspace/training_logs/run_001/error_report_device3 \
    -out /tmp/msaicerr_output \
    -dev 3

分析结果的summary.txt显示，Device 3的AI Core执行单元在执行某个特定算子时触发了溢出保护，错误发生时的调用栈指向算子融合边界处的一个除法运算，该运算的除数在某些输入条件下为零。处理建议部分给出了两条可操作的路径：调整模型中该算子的输入预处理逻辑以避免除数为零，或者在CANN知识库中检索该算子在特定版本中的已知问题并确认是否有更新的修复版本。

结合msaicerr的输出和asys info采集到的环境信息，运维人员可以形成完整的故障报告。如果确认需要升级CANN版本才能解决该问题，可以使用oam-tools的collect子命令将故障发生时的完整现场信息打包保存，供后续复盘分析：

asys collect --output /tmp/incident_20250617_device3

该命令将故障时间点的驱动日志、DSMI接口查询结果、错误报告目录和当时的系统状态快照打包到指定目录。这种故障现场保全操作在生产环境中尤为重要：在问题修复后进行复盘时，原始数据的完整性决定了能否准确定位根因。

除了故障定位之外，oam-tools还在日常巡检中发挥作用。运维团队可以定期执行asys health的全集群检查，将输出结果与基线数据进行比对，观察设备状态随时间的变化趋势。DDR内存的ECC错误计数如果呈现增长趋势，往往是硬件即将失效的前兆，此时可以在业务低峰期主动安排设备更换，避免在训练任务中途发生故障。

效率对比表

以下对比展示了oam-tools三个核心能力相对于传统运维方式在效率维度上的差异。传统方式的数据采集、错误分析和现场保全均依赖手工操作或分散的独立工具，而oam-tools通过统一的命令行接口和内置的智能解析引擎，在操作便捷性、分析深度和信息整合度上形成了质的提升。

维度	使用前（传统方式）	使用后（oam-tools）	差异来源
集群健康检查	SSH登录每个节点，手动执行npu-smi、查看dmesg和分析日志，多节点场景需要循环遍历，输出格式不统一，需要人工汇总	asys health --dev 0-7单命令覆盖全集群，输出结构化检查项列表，统一输出格式，可直接存档	串行手工操作改为并行命令驱动，信息格式从不一致的手工记录改为结构化JSON-like输出，整合成本归零
AI Core错误分析	手动定位dump文件，阅读原始错误码，通过错误码在昇腾社区文档中逐级检索，结合调用栈手动分析根因，全流程依赖运维人员经验	msaicerr -p <report_dir>一键解析，内置错误码知识库自动匹配，输出包含根因和修复建议的报告	人工检索文档改为工具内置知识库即时解码，经验依赖改为标准化流程，分析结果从原始码值变为可直接操作的建议
运维信息收集	手动编写脚本打包/var/log/、driver日志目录和dump目录，需要知道各日志的精确路径，不同节点的路径可能存在差异	asys collect --output一键打包，自动识别相关目录，按时间序整理归档，无需记忆路径约定	手工编写打包脚本改为工具自动发现相关目录，路径约定的不确定性由工具的标准化逻辑吸收
巡检配置与批量执行	每节点逐一执行检查命令，输出结果手工复制粘贴到电子表格，存在节点遗漏或记录错误的风险	asys health全集群覆盖，单次命令触发所有节点，输出可直接导入数据分析工具	多节点逐一操作改为单命令集群级覆盖，人工记录环节被结构化输出取代，数据可靠性提升

从表格中可以看出，三个维度的效率提升均来源于同一设计原则：用工具替代人工记忆和手工操作。传统方式中分散在多个层级和多个工具中的信息，被oam-tools整合为统一的命令行接口。这种整合不仅减少了操作步骤，更重要的是消除了人工整合过程中不可避免的信息损耗：手工复制日志内容时可能遗漏关键行，手工汇总检查结果时可能写错设备编号，而工具驱动的流程保证了数据从采集到归档的完整性。

oam-tools的设计在性能与通用性之间做了合理的权衡。对于健康检查这类高频操作，工具选择了牺牲一定的灵活性（参数语义固定）来换取操作的简洁性，运维人员不需要每次都指定检查哪些具体项目。对于错误分析这类需要灵活性的场景，msaicerr的多参数设计（-p/-d/-e）提供了足够的控制粒度，同时每个参数都有明确的语义和验证逻辑，避免了错误输入导致的误导性结果。

结尾

oam-tools作为CANN生态中面向昇腾NPU集群的运维工具链，通过asys和msaicerr两个核心模块覆盖了从环境自检到故障根因定位的主要运维场景。asys的子命令体系设计使得不同的运维操作（信息展示、健康检查、现场采集、综合诊断）共用统一的入口和参数风格，降低了运维人员的认知成本。msaicerr的错误码解码和dump解析能力将原本隐藏在二进制数据中的故障信号转换为人类可读的报告，配合处理建议的生成，使故障定位不再过度依赖运维人员的个人经验。

---

仓库地址：https://atomgit.com/cann/oam-tools