CANN 组织链接： https://atomgit.com/cann
oam-tools 仓库链接： https://atomgit.com/cann/oam-tools

---

在复杂的异构计算环境中，特别是在 AI 处理器上进行深度学习模型的开发与部署时，故障诊断和性能瓶颈定位是一项极具挑战性的工作。模型的运行涉及多层次的软件栈，从用户态的应用逻辑、深度学习框架（如 PyTorch/TensorFlow）的 CANN 插件，到 CANN Runtime、图引擎（Graph Engine, GE）的编译优化，再到最底层的驱动和 AI 处理器硬件本身。一旦出现问题，其根源可能分散在这些层级的任何一处，使得传统的排查方法效率低下，高度依赖开发者的经验。

oam-tools 项目应运而生，它提供了一套系统化的诊断工具集，旨在彻底改变这种局面。其核心价值在于实现故障现场的自动化、完整性捕获，从而将故障排查的效率从依赖人工经验转变为依赖数据驱动的科学分析。这个工具集不仅能提供对软硬件状态的全面快照，更能对 AI Core 级别的深层错误进行解析，这对于开发和调试自定义算子（例如使用 Ascend C 编写的算子）至关重要。通过 oam-tools，开发者能够更快速、更精准地定位问题，显著缩短故障解决时间，提升整体开发效率和系统稳定性。

一、 oam-tools 在复杂异构系统中的关键定位

oam-tools 是 CANN 生态系统中的一个核心诊断组件，专为应对异构计算环境的独特挑战而设计。

1.1 异构计算环境的挑战与复杂性

AI 处理器系统是一个由硬件、驱动、固件、运行时库、编译工具链和上层框架共同构成的复杂生态。

• 多层次抽象：应用代码通过多层抽象最终下达到硬件执行，每一层都可能引入错误或性能瓶颈。
• 并发与同步：AI 处理器通常有多个计算核心（如 AI Core）并行工作，数据在不同内存层级（HBM、Unified Buffer）间流动，并发与同步机制的任何失配都可能导致死锁、数据不一致或崩溃。
• 黑盒性：底层硬件行为、驱动和固件的细节对于上层开发者而言往往是“黑盒”，缺乏透明度使得问题定位极其困难。

1.2 故障诊断从经验到数据的转型

传统的故障诊断往往依赖于开发者的经验，通过猜测、日志关键字搜索和逐层回溯来定位问题。

• 低效且主观：这种方式耗时、低效，且容易遗漏关键信息，诊断结果受限于个体经验水平。
• oam-tools 的贡献：oam-tools 倡导一种数据驱动的诊断范式。它通过自动化脚本全面采集故障现场的各类信息，将碎片化的、分布式的上下文数据聚合成结构化的快照，使得诊断过程更加客观、高效和可复现。

1.3 oam-tools 的核心价值主张

oam-tools 的设计目标是成为 AI 处理器系统故障诊断的“瑞士军刀”。

• 全栈覆盖：从应用层到硬件层，全面覆盖所有可能出现问题的组件。
• 自动化采集：通过一系列命令和脚本，一键式获取所有诊断所需信息，减少人工干预。
• 深度解析：不仅采集原始数据，更对底层硬件错误码、二进制文件进行深度解析，提供语义化的诊断结果。

二、 全面系统快照：构建可复现的故障诊断上下文

故障定位的首要步骤是确保诊断信息的完整性与一致性。oam-tools 通过脚本化操作，自动化地收集了故障发生时刻的上下文数据，从而构建一个可复现的故障环境快照。

2.1 多层次日志的智能聚合与筛选

系统日志分散在不同的路径和组件中，oam-tools 集成了日志的集中化采集能力，并进行初步的智能筛选，以去除无关信息。

• 应用与框架日志：采集来自 PyTorch/TensorFlow CANN 插件的报错信息、用户编写的 Python/C++ 应用程序日志。这有助于快速定位问题是否源于模型输入格式错误、API 调用不当或应用逻辑缺陷。
• CANN 软件栈日志：聚合图引擎（GE）编译过程中的 IR 转换日志、融合优化日志、算子调度日志，以及 CANN Runtime 的任务下发、内存管理、设备管理日志。这对于诊断算子融合失败、图编译错误、资源分配冲突或调度异常至关重要。
• 驱动层与系统日志：访问操作系统内核空间相关的日志文件（如 /var/log/messages 或 dmesg 输出），用于验证 AI 处理器设备的初始化状态、驱动是否稳定运行、是否存在硬件级的错误或超时。

2.2 运行环境与版本依赖的精确校验

为了确保故障可以在不同环境中复现，并排除环境配置问题，oam-tools 会抓取关键的版本信息。

• 软件版本矩阵：记录 CANN Driver、固件（Firmware）、CANN Toolkit（包括 Ascend C 编译器、GE 库等）和 ops-nn 库的精确版本号。版本不匹配是导致间歇性错误或兼容性问题的常见原因，自动化检查可以迅速排除这类环境配置问题。
• 环境变量与配置：采集相关的环境变量（如 $LD_LIBRARY_PATH, $ASCEND_RT_PATH）和关键配置文件内容，确保运行时环境的正确性。

2.3 硬件状态与资源使用详情捕获

oam-tools 能够获取 AI 处理器的实时状态，为诊断提供硬件层面的背景信息。

• 设备健康状态：采集 AI 芯片的实时状态，包括温度、频率、功耗、HBM 内存使用率、AI Core 使用率等。如果故障发生在 AI 处理器过载、过热或内存耗尽的状态下，这些数据提供了关键的背景信息。
• 拓扑与连接：在多设备或多机场景下，工具会采集设备的互联拓扑信息，辅助诊断通信故障。

三、 AI Core 错误的深层溯源与解析机制

AI Core 异常是底层算子执行失败的直接体现，通常表现为非法内存访问、指令执行异常或硬件错误。oam-tools 提供了将硬件级错误码转化为可操作性信息的解析能力，从而将“看不懂”的底层错误转化为“可理解”的诊断指引。

3.1 硬件异常后的二进制数据转储

当 AI Core 发生硬件异常时，AI 处理器会自动触发一个机制，将当前 AI Core 的关键上下文信息转储到文件中。

• 寄存器状态捕获：oam-tools 能够解析这些转储的二进制文件（通常被称为 Dump 文件），提取当前 AI Core 的所有关键寄存器状态。这包括程序计数器（PC）指向的指令地址、堆栈指针（SP）、通用寄存器值，以及向量和矩阵运算单元的累加器值。这些信息对于分析错误发生时的硬件执行状态至关重要。
• 内存快照：某些情况下，Dump 文件还会包含部分本地内存（Unified Buffer）的快照，有助于分析错误发生时的数据内容。

3.2 从底层错误码到语义化诊断

硬件返回的原始错误码通常是十六进制数字，缺乏直接的语义信息，难以理解。

• 内置错误码对照：oam-tools 内置了一个全面的错误码对照表和解析引擎，能够将这些底层的硬件错误码翻译为明确、易懂的硬件异常类型，例如：“L1 Cache Memory Access Violation”（L1 缓存内存访问越界）、“Invalid Instruction Address”（非法指令地址）、“Floating Point Exception”（浮点异常）等。
• 分级告警：对错误进行分级，区分致命错误、警告和信息性消息，帮助开发者聚焦最严重的问题。

3.3 算子与源代码级别的精准定位

定位的最终目标是识别是哪个上层算子或哪行源代码导致了硬件异常。

• Task ID 溯源：CANN Runtime 在下发计算任务时，会为每个任务生成唯一的 Task ID。oam-tools 利用 AI Core 错误上下文中的 Task ID，能够精确指出是哪个算子（例如，来自 ops-nn 库的 MatMulV3 算子，或者自定义的 Ascend C 核函数）触发了该异常。
• Ascend C 调试信息映射：如果算子是使用 Ascend C 开发，并且在编译时包含了调试符号（DWARF 信息），oam-tools 的工具链可以进一步将硬件异常的程序计数器（PC）地址映射回 C++ 源代码的文件名和行号。这实现了从底层的硬件错误到高级语言源代码的直接定位，极大地加速了自定义算子的调试过程。

四、 诊断自动化：oam-tools 在 CI/CD 中的集成应用

oam-tools 的命令行接口（CLI）设计使其非常适合集成到持续集成/持续部署（CI/CD）流水线中，实现质量左移，即在开发周期的早期发现并解决问题。

4.1 持续集成中的自动化故障熔断

在自动化测试套件（如单元测试、集成测试或端到端测试）中，oam-tools 可作为实时监控组件。

• 实时日志监控：工具持续扫描测试运行过程中产生的日志流，或通过回调机制接收错误通知。
• 即时错误报告：一旦检测到任何与硬件相关的致命错误（如 AI Core Error、驱动级别的同步超时或设备通信中断），测试流程会立即终止，并报告“诊断失败”。这种“Fail Fast”机制避免了不必要的资源消耗，并迅速将问题反馈给开发者，而不是等待整个测试套件运行结束。
• 自动生成诊断报告：在故障熔断时，oam-tools 可以自动触发，收集故障现场的关键信息并打包生成诊断报告，供开发者后续分析。

4.2 性能回归的预防与量化分析

除了功能性错误，oam-tools 还支持性能指标的采集和分析。

• 性能基准测试：如果 CI 流程中包含性能基准测试，oam-tools 可以同时采集硬件计数器数据（如 AI Core 周期数、HBM 带宽、Cache Misses 等）。
• 回归告警：通过与历史基线数据进行对比，如果新代码提交导致某个关键算子的执行时间、吞吐量或能效比超出预设的容忍度，系统会触发性能回归告警。这要求开发者在代码合并前进行优化或解释性能下降的原因，从而确保代码质量和性能的持续改进。

4.3 CLI 接口与自动化脚本的整合

oam-tools 提供了丰富的命令行工具。

• 脚本化操作：开发者可以编写 shell 脚本或 Python 脚本，调用 oam-tools 的 CLI 命令来执行各种诊断任务，如收集日志、查询设备状态、解析 Dump 文件等。
• 与现有系统融合：其标准化的输出格式（如 JSON）使得 oam-tools 可以轻松与现有的监控、告警和报告系统集成，形成完整的自动化运维和开发体系。

五、 实践应用：使用 oam-tools 进行诊断操作

oam-tools 提供了一系列简单而强大的命令行工具，可用于不同的诊断场景。

5.1 常见的诊断场景与操作流程

开发者在遇到 AI 处理器相关问题时，可以遵循以下典型流程：

1. 初步判断：根据报错信息或程序行为，初步判断问题是否与 AI 处理器相关。
2. 触发诊断：在疑似故障发生后，立即使用 oam-tools 收集环境信息。
3. 分析报告：解读 oam-tools 生成的诊断报告，定位故障点。
4. 调试修复：根据报告提供的线索，修改代码或配置，然后再次验证。

5.2 核心诊断命令示例

以下是一个概念性的 oam-tools 命令行使用示例，展示了如何收集系统信息和解析错误。

#!/bin/bash

# 定义诊断报告的输出目录
DIAG_REPORT_DIR="./oam_diag_$(date +%Y%m%d%H%M%S)"
mkdir -p "$DIAG_REPORT_DIR"

echo "开始收集诊断信息到目录: $DIAG_REPORT_DIR"

# 1. 收集系统和 CANN 环境基本信息
# oam-tools diagnose 命令通常用于收集通用诊断信息，如版本、环境变量、系统日志等
echo "收集系统与环境信息..."
oam-tools diagnose --output "$DIAG_REPORT_DIR/system_env_info.log" --full

# 2. 收集 AI 处理器设备状态信息
# oam-tools dev-info 命令用于获取 NPU 设备的实时状态，如温度、功耗、HBM 使用率等
echo "收集 AI 处理器设备状态..."
oam-tools dev-info --json --output "$DIAG_REPORT_DIR/npu_device_status.json"

# 3. 收集 CANN Runtime 运行时日志 (假设日志路径为 /var/log/npu/runtime)
echo "收集 CANN Runtime 日志..."
cp /var/log/npu/runtime/* "$DIAG_REPORT_DIR/" 2>/dev/null || true

# 4. 检查是否存在 AI Core Dump 文件并进行解析
# 当 AI Core 发生致命错误时，系统会自动生成 dump 文件。
# oam-tools dump 命令可以列出和解析这些 dump 文件。
echo "检查并解析 AI Core Dump 文件..."
DUMP_FILES=$(oam-tools dump list --json | jq -r '.[].path') # 假设 dump list 返回 JSON 且包含路径

if [ -n "$DUMP_FILES" ]; then
    echo "发现 AI Core Dump 文件，正在解析..."
    for dump_file in $DUMP_FILES; do
        FILENAME=$(basename "$dump_file")
        oam-tools dump parse --dump-file "$dump_file" --output "$DIAG_REPORT_DIR/dump_parsed_${FILENAME}.log"
    done
else
    echo "未发现 AI Core Dump 文件。"
fi

echo "诊断信息收集完成。请检查 $DIAG_REPORT_DIR 目录下的报告文件。"

5.3 报告解读与下一步行动

oam-tools 生成的报告通常包含结构化的日志、设备状态快照和错误解析结果。

• 日志分析：在日志中搜索关键词（如 “ERROR”、“FAIL”、“Timeout”），结合时间戳，定位异常发生的时间点。
• Dump 解析报告：仔细阅读 Dump 解析报告，它会指出硬件错误类型、错误发生时的 PC 地址、寄存器状态，以及可能的算子 Task ID。如果提供了 Ascend C 源代码映射，可以直接跳转到源代码行。
• 设备状态：检查 AI 处理器在故障发生时的温度、功耗是否异常，HBM 是否耗尽，这可能指示硬件过载或资源分配不当。

六、 oam-tools 的未来展望与价值总结

oam-tools 不仅是当前 CANN 异构计算环境中的一个重要诊断工具，更是未来 AI 芯片系统可靠性和可维护性发展方向的一个缩影。

6.1 提升开发效率与系统可靠性

通过提供自动化、全栈的故障诊断能力，oam-tools 显著降低了自定义算子开发和模型部署的门槛。

• 加速调试周期：开发者可以更快地定位和解决问题，将更多精力投入到算法创新和性能优化上。
• 增强系统韧性：在 CI/CD 中集成 oam-tools，能够提早在开发流程中捕获潜在问题，从而构建更加健壮和可靠的 AI 系统。

6.2 简化复杂故障定位流程

面对日益复杂的 AI 模型和多样的应用场景，oam-tools 将繁琐的故障排查过程标准化和自动化。

• 降低技术门槛：即使是非底层硬件专家，也能通过 oam-tools 生成的语义化报告，理解底层错误并进行初步判断。
• 促进团队协作：结构化的诊断报告便于团队成员之间的沟通和问题交接，提升协作效率。

6.3 持续演进与生态支持

作为一个活跃的开源项目，oam-tools 将随着 AI 处理器硬件的演进和 CANN 软件栈的更新而持续发展。

• 支持新硬件特性：不断适配新的 AI 处理器型号和其引入的新功能、新错误类型。
• 集成更多诊断维度：未来可能集成更多高级诊断功能，如性能瓶颈自动分析建议、内存泄漏检测等，进一步提升其在 AI 异构计算领域的领导地位。

总之，oam-tools 构成了 CANN 异构计算环境稳定性的关键保障。它通过自动化、全栈的信息采集能力，将分散复杂的日志和硬件状态转化为结构化、可操作的诊断报告。特别是在 AI Core 异常的深度解析方面，该工具极大地缩短了自定义算子调试的时间周期，是提升 CANN 平台整体开发效率和系统可靠性的重要基础设施。

---

CANN 组织链接： https://atomgit.com/cann
oam-tools 仓库链接： https://atomgit.com/cann/oam-tools