| name | offline-NPU-fault-diagnosis |
| description | 通过分析服务器离线日志（iBMC、OS Messages、InfoCollect）诊断 NPU（神经网络处理器）及其关联的 PCIe 链路、驱动固件及内存故障。当用户提供日志并询问 NPU 掉卡、HBM 故障、AER 链路错误、驱动加载失败、Acl Error 及温度过高保护时，调用本技能。 |
| platforms | ["linux"] |
离线 NPU 故障诊断
本技能通过分析从服务器收集的标准日志文件，重点诊断 NPU（如华为昇腾 Ascend 系列）及其关联通信链路、固件与存储（HBM）子系统的故障。
技能目录结构
本技能的目录结构如下，包含诊断脚本、参考资料和文档：
offline-NPU-fault-diagnosis/
├── SKILL.md # 本技能的主文档
├── scripts/ # 诊断脚本目录
│ ├── diagnose_summary.py # Step 0: 故障日志采集脚本
│ ├── diagnose_ibmc.py # Step 2: iBMC日志分析脚本
│ ├── diagnose_infocollect.py # Step 2: InfoCollect专项分析脚本
│ └── diagnose_messages.py # Step 2: OS消息日志分析脚本
└── references/ # 参考资料目录
├── NPU_fault_scenarios.md # NPU 故障场景分类表
├── NPU_scenario_analysis.md # NPU 故障场景专项分析指南
├── infocollect_guide.md # InfoCollect诊断指南
├── messages.md # OS消息日志分析指南
├── huawei_ibmc.md # 华为iBMC分析指南
├── h3c_ibmc.md # H3C iBMC分析指南
└── Inspur_ibmc.md # Inspur iBMC分析指南
输入日志目录结构与对应诊断脚本
以 /path/to/logs/xxxx 为例，标准的服务器日志收集包通常具有以下层级结构。本技能提供了针对性的脚本来分析不同层级的日志。
注意：在实际场景中，用户提供的日志包可能不完整，可能仅包含以下三种目录中的一种或多种。请根据实际存在的日志类型灵活选择对应的分析脚本。
<日志根目录> (例如: 10.120.6.76)
├── ibmc_logs/ # iBMC 硬件带外管理日志
│ └── (PCIe/硬件故障/过温报警) -> 使用 scripts/diagnose_ibmc.py
├── infocollect_logs/ # 系统信息收集工具生成的分类日志
│ └── (npu-smi/固件信息/环境数据) -> 使用 scripts/diagnose_infocollect.py
└── messages/ # 操作系统层面的系统日志
└── (dmesg, syslog, ascend日志) -> 使用 scripts/diagnose_messages.py
⚠️ 强制执行流程
必须严格按以下顺序执行，禁止跳过或乱序：
Step 0 (故障日志采集) → Step 1 (场景分类) → Step 2 (深入分析) → Step 3 (根因校验) → Step 4 (界面输出分析报告)
执行规则：
- 顺序强制：必须完成当前步骤并验证通过后，才能进入下一步。
- 场景分支：Step 1 输出场景标签后，Step 2 必须针对性收集相关证据。
- 数据校验：Step 3 必须通过证据矩阵校验后才能得出最终结论。
- 文件适配：日志文件不全时自动降级分析策略，但必须至少有一个日志文件。
- 专注 NPU：分析过程应锁定 NPU 计算单元、HBM 显存、PCIe 拓扑及相关驱动栈。
每步完成标志：
- Step 0：输出日志文件时间范围、文件统计、错误关键词（Acl Error, HBM, ECC, PCIe AER等）概览。
- Step 1：确定故障场景（如 NPU_HARDWARE_FAILURE 等）。
- Step 2：输出物理级精准定位（NPU ID / PCIe Slot）、传导链及初步根因。
- Step 3：输出根因证据校验表、原生日志证据及置信度定性。
- Step 4：在界面上按固定结构输出最终的分析报告（严禁生成独立文件）。
分析流程总览
| 步骤 | 阶段目标 | 主要工具/方法 |
|---|
| Step 0 故障日志采集 | 全量/定点扫描日志目录并识别关键报错 | diagnose_summary.py <log_dir> [-k/-d/-s] |
| Step 1 场景分类 | 判定现象并确定故障场景类型 | 根据 Step 0 采集结果进行场景匹配 |
| Step 2 深入分析 | 构建起止 T0 的传导链并执行诊断 | 使用 diagnose_ibmc.py/diagnose_infocollect.py/diagnose_messages.py 获取多维证据 |
| Step 3 根因校验 | 交叉质询证据链，执行证据双向校验 | 对比 iBMC/内核/系统日志的一致性，防止结论发散 |
| Step 4 界面输出分析报告 | 汇总证据链与确认根因，在界面直接输出报告内容 | 结构化输出：结论 + 故障链条 + 修复建议 |
Step 0：故障日志采集
全量扫描（宏观分析）
目标：快速扫描所有日志文件，识别 NPU 子系统的异常，建立故障全景视图。当存在特定报错或时间范围时，利用参数进行第一轮初步精确定位。
执行命令（根据场景选择）：
python3 scripts/diagnose_summary.py <log_dir>
python3 scripts/diagnose_summary.py <log_dir> -k "npu" "pcie" "aer" "ecc"
python3 scripts/diagnose_summary.py <log_dir> -d "Mar 16"
python3 scripts/diagnose_summary.py <log_dir> -s "2026-03-10 08:00:00" -e "2026-03-10 12:00:00"
精细定位（微观分析）
目标：在优先使用上述带有参数的扫描命令锁定范围的基础上，结合全量扫描结果，辅以 grep / less 等文件操作命令查看更细节的原始日志上下文。尤其关注 dmesg 中的 Ascend/NPU 内核报错栈。
注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。
Step 1：场景分类
根据 Step 0 采集的日志概览，分析故障现象并确定故障场景类型。
场景分类概述
根据 Step 0 采集的日志概览，分析故障现象并从以下标准场景中确定故障场景类型。
📖 参考详见：NPU 故障场景分类
| 场景标签 | 中文描述 | 主要特征 |
|---|
NPU_HARDWARE_FAILURE | NPU 核心硬件故障 | NPU 芯片损坏、不可恢复的物理级缺陷、设备处于 Offline 状态 |
NPU_PCIE_LINK_ISSUE | PCIe 链路与拓扑故障 | AER 报错、PCIe 训练失败、NPU 设备 Missing、链路重置 |
NPU_DRIVER_SW_STACK | 驱动与软件栈报错 | CANN 与 Driver 不匹配、Acl Error、驱动加载失败、调度崩溃 |
NPU_HBM_PERFORMANCE | HBM 与显存故障 | ECC 未修正/可修正错误频繁、显存访问超时、带宽受限 |
NPU_THERMAL_POWER | 热电与功耗异常 | iBMC 过温保护（Thermal Throttling）、电源供给异常、电涌掉卡 |
场景辅助分析与根因假设
确定场景标签后，必须参考专项分析指南进行候选根因的初步验证：
🔍 专项分析指南：NPU 故障场景专项分析指南
| 场景标签 | 候选根因假设（需在 Step 2 中验证） |
|---|
NPU_HARDWARE_FAILURE | ① NPU 核心计算单元损坏 ② 固件死锁或崩溃触发不可逆离线 |
NPU_PCIE_LINK_ISSUE | ① PCIe Riser 卡或主板槽位虚接 ② CPU 侧 PCIe 控制器异常 |
NPU_DRIVER_SW_STACK | ① 内核版本与驱动不兼容导致 Panic ② 应用越权访问导致设备失联 |
NPU_HBM_PERFORMANCE | ① 显存颗粒物理损坏引发大量 Uncorrectable ECC ② 持续高负载引发纠错瓶颈 |
NPU_THERMAL_POWER | ① 风扇故障或风道堵塞引发高温限频/降级 ② 插槽供电不足导致瞬时断电 |
⚠️ 强制要求：在进入 Step 2 深入分析前，应先通过 NPU_scenario_analysis.md 了解对应场景的分析路径与关键证据点。分析结束后，必须对上述候选根因方案逐一标注：✅ 已证实 / ❌ 已排除 / ❓ 证据不足。
Step 1 完成标志：
- ✅ 确定主要故障场景标签（从上述类型中选择）。
- ✅ 记录故障现象与关键证据。
- ✅ 为 Step 2 深入分析提供明确的故障场景方向。
Step 2：深入分析
根据 Step 1 的场景分类结果，必须首先完成时序关联与故障传导链重建，然后再通过多源脚本收集证据，最终给出精确的物理坐标定位。
2.1 时序关联与传导链重建 (核心理论框架)
目标：通过多源日志的时间戳对齐，重建故障发生的完整时间轴，厘清事件的先后顺序与因果链，为根因定位提供时序证据。
2.1.1 确定 NPU 故障零点 (T0)
故障零点（T0）是时序分析的基准锚点，定义为最早可观测到异常的时间戳。确定优先级（由高到低）：
| 优先级 | 来源 | 说明 |
|---|
| P1 | 硬件错误日志（iBMC / SEL） | 底层致命报错（如 PCIe Fatal Error, Over Temperature, Hardware Failure），时间点最准确。 |
| P2 | 内核感知层（dmesg / messages） | 最早出现的 PCIe AER (Advanced Error Reporting)、ECC Uncorrectable Error、NPU Driver 初始化失败或设备 Reset。 |
| P3 | 驱动与组件层（syslog / OS 日志） | npu-smi 服务状态异常日志、Host 侧调度器卡死报错。 |
| P4 | 应用感知层 | 上层训练任务崩溃、Acl Error 报错、算子执行超时（HCCP timeout），通常滞后较大。 |
⚠️ 时钟偏差处理：多节点/集群场景下，需留意 iBMC 时间与 OS 时间（NTP）是否存在时钟偏移。多源对齐时需留意并修正该偏差量。
2.1.2 多维日志对齐与时间轴矩阵
以 T0 为基准，将 iBMC 传感器告警、dmesg 报错、npu-smi 状态和应用程序报错统一映射到绝对时间轴上，构建事件序列矩阵。
示例：因 HBM 物理损坏引发的业务中断传导链
T0-5m ├─ [OS dmesg] 系统检测到个别可修正的 HBM ECC Error，系统尝试后台修正。
T0 ├─ [iBMC SEL] 上报 NPU Slot 4 `Uncorrectable ECC Memory Error` -> 致命故障零点 T0。
T0+1s ├─ [OS dmesg] 内核捕获 NMI，NPU 驱动上报设备状态变为异常（Abnormal/Offline）。
T0+5s ├─ [OS sys/dmesg] 正在执行的训练进程抛出 `Device Unreachable` 异常。
T0+1m ├─ [App Log] 上层框架（如 MindSpore/PyTorch）级联报错退出（Acl Error）。
2.1.3 NPU 故障传导链推断 (示例)
结合对齐的时间轴矩阵，运用以下规则推导故障传导链方向：
- 规则一：自底向上（硬件主导损坏）
- 传导链：HBM ECC 物理击穿 (T0) → 触发 iBMC 及 dmesg 硬件报错 → NPU Driver 重置设备 → 上层应用抛出报错退出。
- 规则二：环境向硬件传导（散热/链路主导）
- 传导链：机房空调故障/散热不良 → iBMC 检测 NPU Die 过温告警 (T0) → NPU 触发 Thermal Throttling 降频 → 最终导致驱动超时（Timeout）。
⚠️ 精确定位强制要求：在 NPU 诊断中，严禁仅得出“NPU 掉卡”或“NPU 坏了”这类含糊结论。
必须通过证据追踪到细粒度的物理坐标及具体子模块定位，例如：
- ✅ 正确结论：
PCIe Slot X (NPU ID: Y) -> HBM Uncorrectable ECC Error -> 内存颗粒物理损坏。
- ❌ 错误结论：
发生 Acl Error 或仅仅说是 NPU Offline。
2.2 日志脚本分析执行 (执行工具动作)
2.2.1 通用分析流程
通用分析流程适用于所有 NPU 故障场景，提供基础的日志提取与数据分析能力：
python3 scripts/diagnose_ibmc.py <log_dir>
python3 scripts/diagnose_infocollect.py <log_dir>
python3 scripts/diagnose_messages.py <log_dir>
注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。
2.2.2 按场景专项分析
当 Step 1 确定故障场景后，优先分析对应的关键指标：
- PCIe 链路故障：重点在
dmesg 与 iBMC 中检索 AER、PCIe training 和 Link reset 相关字眼。
- HBM 显存故障：重点检索
ECC, Memory Error, HBM 关键字。
- 驱动与软件栈：检查
npu-smi info 历史输出（如有），分析 CANN 版本与 OS Kernel log 中驱动抛出的 Panic Call Trace。
2.2.3 分析执行原则
- 场景优先原则：当故障现象明确匹配某个场景时，优先针对该场景取证。
- 组合使用原则：必须同时使用带外（iBMC）和带内（OS）脚本进行相互验证。
- 逐步深入原则：从宏观概览开始，逐步根据时序对齐结果深入特定日志行。
Step 2 完成标志：
- ✅ 输出故障零点 T0 的精确时间戳及其所依托的具体日志行。
- ✅ 梳理出以 T0 为基准的结构化事件序列矩阵与核心故障传导链。
- ✅ 给出精确到物理部件（例如 Slot ID / NPU ID）的细粒度定位结果。
- ✅ 收集脚本产出的相关原生日志片段作为强有力的支撑证据。
Step 3：根因反思与证据双向校验 (Cross-Examination Rules)
目标：对 Step 2 输出的“初步传导链与定位结果”进行“交叉质询”，确保得出的最终结论 100% 由底层日志支撑。
3.1 交叉质询铁律 (Cross-Examination Rules)
- 孤证不立原则：任何物理级 NPU 故障（如 HBM 损坏引发掉卡），绝对不能仅凭系统驱动层的一个报错（如
Device Missing）就下断言。必须同时找到硬件层（如 iBMC SEL）的独立证据源支撑（如果 iBMC 日志存在）。
- 逻辑闭环原则：从 T0 到最终业务故障结果，传导链不允许出现跳跃。例如：
PCIe AER 警告不能直接等同于NPU 核心完全烧毁，必须考量中间的 Reset 恢复机制与日志的连续性。
- 互斥排异原则：如果判定故障是 PCIe Riser 卡损坏，则必须说明同一 Riser 卡上的其他 PCIe 设备（如有）的表现，以排除单 NPU 故障或共因。
3.2 强制：根因证据校验表 (Evidence Validation Matrix)
在确认最终结论前，强制要求进行证据校验：
| 校验维度 | 校验标准要求 | 强制证据格式（分析打样要求） |
|---|
| E1: 时序连续性 | 硬件/环境级告警时间是否早于或同步于驱动与应用层崩溃时间？ | [✅/❌ 结果] + 时序对齐说明（含 T0） + 原生日志片段 |
| E2: 物理同一性 | 各级日志指控的 OS 逻辑设备（/dev/davinciX）与物理槽位（Slot Y）映射是否准确不冲突？ | [✅/❌ 结果] + 设备编号与槽位映射对齐说明 |
| E3: 现象排他性 | 是否排除了宿主机 OOM Kill、手动重启引发的合法 Offline 及散热故障引发的连带表现？ | [✅/❌ 结果] + 环境及系统级日志排除说明 |
3.3 结论防发散拦截机制 (Anti-Hallucination Mechanism)
- 断链阻断：若无法从网络或存储日志中找到证明因果传导的片段（只有应用报错而毫无底层记录），强制触发流程拦截，回溯重新收集线索。
- 降级处分：若确实缺乏某一层关键日志（如缺少 iBMC，仅有 dmesg），必须在报告中声明为**“疑似故障 (Suspected)”**并标注证据断层位置。
- 严禁用词限制：在证据链未能满足完全闭环标准前，严禁使用“绝对”、“必须更换主板”等无回旋余地的决定性断言。
Step 3 完成标志：
- ✅ 结构化地产出《根因证据校验表》中每一项的自查结论。
- ✅ 每个通过项均附带 Trace 日志中的 Timestamp 和原生日志摘录。
- ✅ 输出与之等位置信度（已证实 / 高度疑似 / 多重原因交织）的严谨研判方向。
Step 4：界面输出分析报告
汇总 Step 0～3 的所有分析结果，直接在当前对话界面输出结构化的诊断结论。禁止生成任何额外的文档或报告文件。
报告结构：
- Executive Summary（故障摘要） — 故障物理节点与受影响的 NPU Device ID、直接原因、后果概述。
- Fault Chains（故障链条分析） — 必须包含以下两级链条：
- 故障时间链 (Fault Time Chain)：列出带关键节点的事件序列，每个节点必须包含准确的时间戳（精确到具体时间与时区，明确标出 T0）。
- 故障传播链 (Fault Propagation Chain)：清晰描绘引发系统表现的物理/链路因果传导路径（例如：
风扇异常停转 -> NPU 核心触发 Overtemp 阈值 -> BMC 切断供电保护 -> 驱动上报 Device Lost）。
- Technical Analysis & Root Cause（技术分析与根因） — 基于 Step 2 的传导链回溯与 Step 3 的交叉质询，给出硬件/驱动/链路维度的实质性根因，并提供多源证据链（E1/E2/E3）强力支撑。
- Recommendations（修复建议） — 例如：重新插拔 Riser 卡、更换 NPU 模组备件、修复机柜散热、升级驱动固件对应版本等。
诊断分析完成性检查（输出报告前必检）：
在得出结论前，必须回答以下问题：
参考资料
