前言

在大规模深度学习训练场景中，昇腾NPU集群的稳定性直接决定了训练任务的成败。当集群规模扩展到数十乃至数百张NPU卡时，硬件故障的绝对概率随之上升，单卡温度异常、HBM内存泄漏、AI Core计算单元报错等问题时有发生。传统的运维方式依赖运维人员手动登录每台服务器，通过npu-smi、dcmi等零散工具逐台排查，不仅效率低下，还容易因信息分散而遗漏关键线索。CANN（Compute Architecture for Neural Networks）是华为为昇腾系列AI处理器提供的统一软件架构，其开源工具集oam-tools（运维与性能调优工具）为集群运维人员提供了一套完整的闭环操作流程：从批量健康检查到故障节点隔离，从AI Core报错解析到性能瓶颈定位，所有操作均可在命令行下快速完成。本文以手把手实操为导向，详细讲解如何借助oam-tools在真实的昇腾NPU集群环境中完成故障定位与节点隔离的完整闭环，涵盖安装部署、健康检查、错误诊断、节点隔离与恢复的全部关键步骤，并附上使用前后效率对比，帮助运维团队在实际工作中快速落地。

安装与环境准备：oam-tools的部署位置与依赖

oam-tools托管于atomgit开源社区，仓库地址为atomgit.com/cann/oam-tools。项目源码采用Python与C++混合编程实现，其中asys与msaicerr模块以Python为主，msprof模块的collector侧使用C++编写以确保性能采集的低开销，hccl_test模块提供集合通信层面的功能与性能测试能力。编译构建产物为一个.run格式的自解压安装包，安装后释放到CANN安装目录下的tools子目录中。

硬件环境与芯片支持

oam-tools支持两类CPU架构：x86_64与aarch64。在实际生产环境中，aarch64架构更为常见，因为昇腾AI处理器通常部署在基于ARM架构的服务器上。在NPU型号方面，当前版本明确支持三款芯片：通过npu-smi info命令的Name列可以识别出910B（Atlas A2训练系列及Atlas 800I A2推理系列产品，对应CANN ops包代号910b）、910_93（Atlas A3训练系列及Atlas A3推理系列产品，对应CANN ops包代号A3，也被称为业界通称的910C）以及950（Atlas 950系列）。npu-smi info输出的Name列可能包含子型号后缀（如910B1、910B2、910B3、910B4等），oam-tools按照"Name列包含上述关键字"的规则进行匹配，因此只要名称字符串中包含对应关键字即可被工具正确识别。对于没有昇腾物理设备的开发者，也可以通过Docker方式完成编译构建，只需挂载必要的设备节点即可。

源码获取与目录结构

从atomgit克隆指定分支的源码，源码分支标签与CANN版本存在配套关系，具体对应关系参考CANN release仓库的说明文档。克隆命令如下。

git clone -b ${branch} https://gitcode.com/cann/oam-tools.git

克隆完成后，进入源码目录可以观察到关键子目录的组织方式

The -b parameter locks the source branch to match the installed CANN version. Mixing mismatched versions can cause API incompatibility in the oam-tools CLI parsers.：src/asys存放ascend_system_advisor（系统诊断顾问）模块的源码与Python入口脚本asys.py；src/msaicerr存放AI Core报错分析模块；src/msprof存放性能调优模块的collector侧代码；src/hccl_test存放集合通信测试工具；src/third_party存放依赖的第三方库头文件；test目录包含UT/ST用例；CMakeLists.txt为构建配置入口，build.sh为封装好的编译脚本。

这段命令的作用是从远程仓库克隆指定分支的源码到本地。-b参数指定目标分支标签，这保证了源码版本与CANN包版本的一致性——不同版本的CANN可能对工具接口有细微差异，使用版本匹配的源码可以避免兼容性问题。

编译构建与安装

oam-tools的编译构建过程已高度自动化。执行编译的完整命令如下。

bash build.sh

编译脚本会自动检测本地是否存在第三方库

Auto-downloading dependencies eliminates manual prerequisite setup, but requires internet access during first build. Offline environments must pre-stage third-party packages via cmake/download_libs.py.（protobuf、abseil-cpp、boost、googletest等），如果third_party目录下缺少依赖，则自动从gitcode开源仓库下载对应版本的源码包并完成构建。对于需要指定第三方库路径的场景，可以使用–cann_3rd_lib_path参数传入本地已缓存的依赖目录路径，避免重复下载。编译过程中还会自动下载闭源二进制包，该包包含保证功能正常运行所需的驱动接口库和头文件，且仅提供release版本，即使CMake配置指定debug模式也只会下载release包，这是一个经过权衡的设计决策——调试版本带来的额外信息对普通用户价值有限，反而会增加下载量和复杂度。

编译完成后，build_out目录下会生成形如cann-oam-tools_<cann_version>_linux-.run的软件包，其中<cann_version>为当前CANN版本号，为操作系统架构标识（x86_64或aarch64）。安装命令如下。

./cann-oam-tools_<cann_version>_linux-<arch>.run --full --install-path=${install_path}

安装完成后，需要加载CANN环境变量使工具路径生效。root用户与非root用户的默认安装路径不同，通过set_env.sh加载环境变量后，${ASCEND_INSTALL_PATH}变量会指向正确的CANN根目录。加载命令如下。

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

工具安装后的实际释放路径为${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/目录

Environment variables are not persistent across shell sessions. Each new SSH connection or script must reload set_env.sh before invoking asys or msprof commands.，其中asys.py为主入口脚本，同目录下的asys软链接指向asys.py本体。msaicerr的Python入口脚本位于$ASCEN{D}_{I}NSTAL{L}_{P}ATH/tools/msaicerr/msaicerr.py。msprof的分析脚本位于${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py，C++侧collector作为CANN profiler流水线的一部分被集成调用，不暴露独立的命令行接口。hccl_test工具释放到${ASCEND_INSTALL_PATH}/tools/hccl_test/目录。这些工具路径在加载set_env.sh后均可直接通过命令名称调用，无需输入完整路径。

集群健康检查：一键扫描所有NPU卡的状态

对昇腾NPU集群执行批量健康检查是日常运维的第一步，也是发现潜在故障的最有效手段。在没有专用工具的时代，运维人员通常需要编写Shell脚本批量调用npu-smi并解析输出，不仅脚本维护成本高，而且不同工具的输出格式差异大，难以统一处理。oam-tools提供的asys模块将这一流程高度简化，所有子命令的功能定义存放于src/asys/cmdline/cmd_parser.py的Command枚举中，运维人员无需记忆复杂的脚本逻辑，只需掌握几个核心命令即可覆盖大多数运维场景。

asys info：采集集群软硬件信息

执行asys info命令可以一次性采集集群中所有NPU卡的软硬件状态信息。该命令调用底层DCMI（Device Communication Management Interface）接口获取设备列表，并通过npu-smi读取每张卡的详细状态数据。命令执行后输出的信息包括每张NPU卡的设备编号、芯片型号、健康状态、温度值、HBM内存使用率、功耗以及当前运行频率等。对于拥有64张NPU卡的大规模集群，这意味着一条命令即可获得全量设备的完整视图，而无需逐台登录并执行多条查询命令。

在日常巡检场景中，运维人员通常将asys info的输出重定向到指定日志文件，结合定时任务可以实现每日自动化的集群健康报告生成。输出的数据格式经过结构化处理，便于后续使用文本处理工具进行自动化比对和异常告警。

asys health：设备健康状态快速评估

asys health命令在asys info的基础上增加了健康评估逻辑。该命令会根据预置的阈值规则对每张NPU卡的各项指标进行评估，并给出综合健康评级：OK表示所有指标均在正常范围内，Warning表示部分指标接近阈值但尚未触发故障，Error表示存在明显异常需要立即关注。输出的内容还包含各设备的温度读数和HBM内存占用比例，这两项是NPU卡最常见的早期故障预警指标——HBM内存异常通常先于AI Core计算错误出现，持续的高温则可能导致芯片降频甚至损坏。

在实际运维场景中，建议将asys health作为节点故障排查流程的起点。通过该命令的输出，可以快速圈定哪些NPU卡处于异常状态，哪些节点需要进一步分析，为后续的asys collect故障信息采集提供明确的目标范围和操作依据。

asys collect：打包完整运维信息

asys collect命令是故障信息采集的核心工具。在确认异常节点后，运维人员执行asys collect并指定输出目录，该命令会将指定节点上所有相关的运维数据打包收集，包括设备驱动日志、固件状态快照、DCMI采集的实时数据以及AI Core报错记录等。打包后的数据按照标准目录结构组织，便于后续离线分析或提交给专家团队进行根因诊断。执行命令时需要指定输出目录路径，命令格式如下。

asys collect --output <output_dir>

这个命令的价值在于信息完整性

Collecting all fault data in one shot avoids repeated SSH sessions to the same node. In large clusters, repeated connections to a failing node can timeout due to hardware instability.——传统的故障信息收集需要运维人员手工定位并复制大量分散的日志文件，遗漏关键信息的风险很高。asys collect将这一过程自动化并标准化，确保每次采集的数据范围一致，减少了人为疏漏。同时，采集到的完整数据可以与asys analyze子命令联动，对特定类型的错误进行深入分析。

故障诊断：从错误码定位到根因分析

当集群中出现NPU计算报错时，定位根因是最耗时的环节。AI Core报错通常以一串十六进制的错误码形式出现，错误码本身包含错误类型、发生位置、触发算子等丰富的上下文信息，但原始错误码对人类阅读不友好，需要专用解析工具才能还原出可理解的分析报告。传统的错误分析方法需要运维人员手动搜索日志文件、使用多个互不关联的工具分别解析，凭借个人经验将零散的线索拼凑起来判断根因，整个过程费时费力且高度依赖个人经验。

msaicerr模块的AI Core错误分析能力

msaicerr（Multi-Source AI Core Error）是专门用于解析昇腾NPU AI Core错误的工具模块。当训练任务因计算错误而中断时，驱动层通常会生成一份AI Core错误报告，其中包含触发错误的算子名称、错误类型代码、发生时间戳以及调用栈信息。直接阅读这份原始报告对于大多数开发者而言门槛较高，msaicerr的工作就是将报告中的结构化数据翻译成人类可读的诊断结论，并给出可能的根因推测和排查建议。

使用msaicerr分析已有的错误报告时，命令格式需要指定报告目录、输出目录和目标设备编号这三个核心参数，示例命令如下。

python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0

其中-p参数指定asys collect打包输出的报告目录路径

The -dev parameter filters analysis to a single device. On multi-device nodes, running analysis without this flag would merge error data from all cards, obscuring per-device root cause.，-out参数指定分析结果的输出目录，-dev参数指定待分析的NPU设备编号。如果手中只有单个dump文件而没有完整报告目录，可以使用-d参数直接指定dump文件路径，并通过-dtype参数声明数据类型（如float16）。dtype参数的合法取值可以通过-h帮助信息查看具体列表。msaicerr还支持环境预检模式，使用-e参数可以快速验证当前环境是否满足运行条件，该检查仅依赖设备编号，不执行完整分析，适合在正式诊断前做快速健康确认。

msaicerr的输出结构与解读

msaicerr分析完成后，会在指定的输出目录中生成若干文件，其中包含错误摘要、错误分类统计以及每条错误的详细解释。摘要文件会按照错误严重程度对错误进行分组，帮助运维人员快速定位最关键的故障。详细解释中会说明错误类型（如内存越界、算子不支持、数据类型不匹配等），并给出触发该错误的算子名称和当时的张量维度信息。错误分析报告会按照错误类型进行分组统计，每组中列出具体的错误发生时间、设备编号、错误码值以及可能的根因描述。

结合asys collect采集的完整环境信息，运维人员可以判断错误是偶发的硬件故障还是必然的软件配置问题。例如，如果AI Core报错集中发生在特定的某个算子上，则可能是该算子的实现与当前CANN版本存在兼容性问题；如果错误随机分布在不同算子上且伴随HBM内存异常，则更可能是硬件层面的内存故障。在实际诊断中，msaicerr的分组统计功能可以帮助快速缩小排查范围，避免面对大量原始错误数据时无从下手。

性能瓶颈定位（msprof模块）

msprof是oam-tools中的性能调优模块，用于采集和分析AI任务各阶段的性能指标。在昇腾NPU集群上运行大规模训练任务时，性能瓶颈可能出现在数据加载、前反向传播、同步等待或通信集合等多个环节。msprof模块通过C++侧的低开销collector采集详细的运行时数据，再由Python分析脚本对数据进行解析和可视化，确保在生产级别的负载下也能保持足够低的性能开销。

msprof的使用流程分为数据采集和数据分析两个阶段。数据采集通常集成在训练脚本的启动命令中，由CANN profiler流水线自动触发；数据分析则由Python脚本在采集完成后执行，结果输出到指定目录并生成可视化的分析报告。分析脚本的执行方式如下。

python3 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h

执行后显示msprof分析脚本支持的全部参数选项

The -h flag works without NPU hardware present, making it safe to run in any environment. This is useful for documentation and scripting without requiring an active device allocation.，包括采集数据路径、输出报告路径和分析深度等参数。分析报告会按照执行阶段展示各环节的耗时占比，并给出瓶颈阶段的热点函数排名，帮助开发者识别优化方向。msprof还支持对集合通信性能进行分析，结合hccl_test工具可以对集群的通信带宽和延迟进行基准测试。

节点隔离与恢复：故障卡的在线隔离操作

当某张NPU卡被确诊为故障状态后，需要将其从集群调度池中移除，避免后续训练任务被调度到该卡上导致相同的错误再次发生。这个操作在昇腾NPU集群运维中被称为节点隔离，是保障集群整体可用性的关键措施。节点隔离的核心挑战不在于执行隔离命令本身，而在于如何准确判断何时应该隔离以及隔离后如何高效完成后续的诊断和恢复流程。

隔离前的确认流程

节点隔离是一个需要谨慎对待的操作，误隔离正常节点会导致计算资源浪费，同时也可能中断正在该节点上运行的任务。在执行隔离之前，建议按照以下确认步骤进行：其一，通过asys health确认目标设备的健康评级为Error或持续处于Warning状态；其二，通过msaicerr分析该卡的AI Core报错记录，排除偶发软件错误的可能；其三，通过asys info观察该卡的温度和HBM使用率是否长期处于异常水平。只有在多重证据一致指向硬件故障的情况下，才建议执行隔离操作。

通过作业调度器执行节点隔离

昇腾NPU集群通常使用SLURM、PBS等作业调度器管理计算节点的分配。不同调度器的节点隔离命令有所不同。以SLURM为例，可以使用scontrol update命令将故障节点标记为Drain状态，使其不再接收新的作业分配。隔离命令执行后，该节点上正在运行的任务会被保留（如果用户未主动取消），但不会有新任务被分配到该节点。具体命令如下。

scontrol update NodeName=<node_name> State=DRAIN Reason="NPU hardware fault detected by asys health"

完成隔离后，需要在作业调度器的管理界面或配置文件中记录该节点的故障信息

DRAIN state preserves running jobs but blocks new allocations. IMMEDIATE would kill active tasks, risking data corruption on the faulty NPU during an in-progress training step.，供后续故障修复和节点恢复使用。同时建议记录隔离前asys collect采集的完整故障数据，为后续向硬件供应商提交维修工单提供完整的证据链。

故障信息收集与归档

节点隔离完成后，运维人员应使用asys collect对故障节点执行一次完整的信息采集，并将打包结果归档保存。归档数据中应包含asys health的健康评级输出、msaicerr的分析报告以及asys info的设备状态快照。这些数据是后续向硬件供应商提交维修工单的必要依据，也是团队积累故障案例、完善运维知识库的重要素材。归档数据建议按照"节点名称_故障时间"的命名规范进行组织，便于后续查询和复用。

节点恢复验证

故障硬件修复完成后，需要对节点执行恢复验证，确保其可以安全地重新加入集群调度池。恢复验证的步骤与隔离前的确认流程类似，但侧重点有所不同：其一，通过asys health确认设备的健康评级已恢复为OK状态；其二，运行短时间的压力测试观察NPU卡在负载下的温度和内存表现是否稳定；其三，通过msprof执行小规模的性能采集，确认计算功能正常且性能指标在预期范围内。

在作业调度器侧，使用相应的命令将节点状态从DRAIN恢复为IDLE。以SLURM为例，恢复命令如下。

scontrol update NodeName=<node_name> State=IDLE

恢复完成后，建议将该节点先以单卡测试的方式分配一个小作业

Scheduling a lightweight test job before full re-admission validates that hardware repair actually resolved the fault. Unverified recovery risks cascading failures in production multi-node jobs.，观察一个完整的训练周期内是否出现任何异常。如果测试通过，再将该节点完全开放给集群调度池使用。这种渐进式的恢复策略可以有效避免修复不彻底的节点重新加入集群后引发二次故障。

效率对比

在昇腾NPU集群运维中引入oam-tools前后的效率差异体现在多个维度。下表从运维操作时间消耗、信息完整度、故障定位速度以及多节点协同能力四个方面进行概括性对比。

对比维度	使用前（传统方式）	使用后（oam-tools）	差异来源
集群健康检查	需要编写批量Shell脚本逐台调用npu-smi并解析输出，脚本维护成本高，不同工具输出格式不一致	单条asys health命令完成全集群扫描，输出格式统一，带综合健康评级	命令行工具集成替代了手工脚本，信息整合度高
AI Core错误分析	手动查找dump文件路径，使用多个独立工具逐个解析，人工关联驱动日志	msaicerr一键解析报告目录，自动解码错误码并生成结构化诊断报告	解析逻辑集成化，减少人工查找和关联成本
故障节点诊断与信息打包	手工定位并复制分散在多个目录下的日志文件，容易遗漏关键信息	asys collect一键打包完整运维数据，标准化目录结构确保信息完整	信息采集流程自动化，减少人为疏漏
故障恢复验证	分别执行温度检查、内存检查、功能测试等多个独立命令后综合判断	asys health一次执行返回完整状态，结合短时压力测试即可验证	健康检查命令整合了多种指标，减少重复操作

上述对比反映了oam-tools在运维效率上的主要改善方向：通过命令行的工具集成化替代零散的手工操作，通过标准化的输出格式降低信息解读成本，通过自动化的采集流程减少人为疏漏。对于拥有数十张乃至数百张NPU卡的大规模集群，这些改善的累积效果尤为显著。

结尾

oam-tools为昇腾NPU集群提供了一套完整的运维工具链，涵盖从日常健康检查到故障诊断再到节点隔离与恢复的全流程操作。asys模块是整个工具链的入口枢纽，info、health、collect三个子命令分别对应环境自检、故障发现和信息采集三个关键环节；msaicerr模块专注于AI Core报错解析，将难以阅读的错误码翻译为可行动的诊断结论；msprof模块则覆盖性能数据采集与分析场景，帮助定位训练任务的瓶颈环节。在实际运维中，这三个模块的协同使用可以显著缩短从故障发现到根因定位再到节点恢复的完整闭环时间。

---

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