背景
分布式训练失败时，一个底层硬件故障会在多个节点上引发级联报错。例如一块 GPU 的 NVLink 信号完整性问题触发 XID 149，随后其他节点上的 NCCL 集合通信失败，调度器记录作业异常退出，日志里留下数千条相关消息。开发者看到的往往是最后一个报错点——某个 rank 的 NCCL 超时或 OOM，而不是真正引发故障的硬件事件。
人工排查需要串联分散在 Kubernetes 事件、Slurm 日志、Loki 查询结果和 Prometheus 指标里的证据，判断哪些是症状、哪些是诱因。团队可能把调试精力花在正常节点上，而真正的坏卡继续影响后续作业。NVIDIA Attribution 把这个过程自动化了：它接收一次作业执行的全部证据，返回一个结构化诊断，包含终止状态、根因域、受影响节点、支持症状和证据链。确定性规则保证同样的输入产生相同的诊断，方便与现有健康检查、修复流程集成。
核心原理
Attribution 由 Service 和 Blueprint 两部分组成。Service 通过 REST API 暴露归因引擎，Blueprint 是 Python 参考编排器，负责对接调度器和遥测数据源。Blueprint 内置了 Slurm、Kueue、静态输入三种执行上下文连接器，以及 Loki、本地文件、Kubernetes pod 日志和 PromQL 指标的收集器。
归因流程分四个阶段。第一步是划定作业范围，Blueprint 从调度器标识符或显式时间窗口和节点分配中确定一次执行尝试。第二步收集观测数据，日志和指标连接器从应用日志、syslog、GPU 驱动和 Fabric Manager 消息、调度器历史、节点与网络指标中产生作业范围内的观测记录。第三步提取和关联事件，Service 调用归因引擎识别 GPU XID、NCCL 失败、调度器状态转换、指标条件等显著事件，规则根据时间序列和事件交互分离下游症状与导致失败的事件，找出根因。第四步返回结构化结果，Blueprint 组合裁决、作业终止状态、归因域、症状、受影响节点、收集器覆盖情况和错误记录。
归因引擎的规则流水线包含提取、过滤、症状精炼三个阶段。提取阶段把原始日志转换成类型化事件并保留来源信息。过滤规则处理事件流，例如 EARLY 阶段的 HandleXidBurstEvents 规则读取 XID burst 证据，解码错误字段，对于 XID 149 和特定错误码的组合，它会发出"信号完整性问题"归因事件，同时保留原始 NCCL 错误不变。精炼阶段将事件物化为每节点症状，执行逐节点清洗后聚合成作业级症状集。FINAL 精炼规则 Xid149AndNvlinkFiltering 保留信号完整性症状并降级其他节点症状，Gb200PriorityRootCause 减少活跃症状集，结果映射产生硬件故障归因。降级的症状被标记为"有意思"，仍可供检查，避免丢失有用证据。
局限与注意
诊断质量取决于遥测数据的完整性和质量。如果证据不完整或多个原因都符合现有证据，sub_domain 会标记为 ambiguous，系统正确反映不确定性而非强行给出结论。规则引擎是确定性的，相同输入产生相同输出，但规则本身需要根据集群特征定制。例如在 RDMA 集群中关联端口错误和连接重置的规则，在 InfiniBand 和 RoCE 环境下可能需要调整。
目前 Blueprint 只连接了 Slurm、Kueue 和静态输入三种调度器，其他调度器需要自己实现连接器。日志和指标收集器也需要根据实际使用的可观测性栈调整，比如把 Loki 换成 Elasticsearch 或 Splunk 需要写新的连接器。系统一次只分析一个作业尝试，对于跨作业的故障模式（例如某个交换机端口持续影响多个作业）需要在外部聚合多次归因结果。
Service 和 Blueprint 分离的架构意味着团队要部署两个组件。Service 暴露 HTTP API，Blueprint 作为编排器调用 Service 并写入输出接收器，包括只读仪表板。这种设计让核心归因逻辑可以复用，但增加了部署复杂度。
对开发者的意义
Attribution 已在 NVIDIA 内部生产环境运行多年，每周分析数十万 GPU 上的数百万次作业。在一个大型 RDMA 集群中，它关联端口错误、连接重置和调度器事件，识别出特定主机和交换机端口的故障模式，帮助团队定向修复网络和调优拥塞控制。
开源后，开发者可以把它部署到自己的集群。快速开始流程是克隆仓库，运行示例工作流并在本地仪表板里查看诊断。Blueprint 配置文档解释了如何对接自己的调度器和遥测后端。对于自定义规则，需要理解提取、过滤、精炼三个阶段的事件流处理逻辑。
它的价值在于把手工排查自动化，并把结果标准化。健康检查系统告诉你集群当前状态，Attribution 告诉你作业为什么失败。修复系统可以根据归因结果决定是重启作业、隔离节点还是触发硬件更换。对于运行大规模训练的团队，这套系统能减少从故障发生到定位根因的时间，降低重复故障的成本。
原文地址：tools.wflynn.cn/aitools/tre…
关注公众号「YourTools」，每天推送 GitHub 趋势与开源工具速报：
