GPU 健康与故障预测
HeteroFlow 是本站的异构算力与大模型调度产品。GPU 健康与故障预测。GPU 健康与故障预测 GPU 健康与故障预测是 HeteroFlow 对 GPU 硬件错误的一套可观测性子系统：Agent 在节点上低频采集 ECC 错误、退役页、行重映射这五类单调累计计数，随心跳落成每张卡的时序样本，服务端的规则引擎定期扫描这些计数的变化趋势，在显存颗粒渐进…
GPU 健康与故障预测
GPU 健康与故障预测是 HeteroFlow 对 GPU 硬件错误的一套可观测性子系统：Agent 在节点上低频采集 ECC 错误、退役页、行重映射这五类单调累计计数，随心跳落成每张卡的时序样本，服务端的规则引擎定期扫描这些计数的变化趋势，在显存颗粒渐进劣化的早期发出带依据的预测，并在预测窗口到期后用实际观测回填命中与否——预测效果本身也被统计成命中率与预测率两张账，用来验证规则而非装饰界面。它解决的问题是：GPU 显存故障在生产上长期"零可观测"，一张卡往往要坏到出现不可纠正错误、任务崩溃才被发现，而此前平台对这类硬件错误计数没有任何采集，也就没有可用于校准任何预测算法的历史数据。
必须先说清定位：故障预测能力是实验性的，规则有效性尚未经真实数据充分验证。规则阈值是依据"可纠正 ECC 累积速率上升先于不可纠正错误出现"这一公开机理给出的初始经验值，不是从本平台历史故障数据拟合出来的——平台在上线这套采集之前对 GPU 硬件错误零可观测，不存在可用于校准的历史劣化数据。真实的预测率/命中率必须等真机采集攒够样本后才能给出；在那之前，样本不足时界面不显示任何百分比，只给原始计数。本页所有设计（计数"未知"绝不记 0、规则版本落库冻结、统计口径自证）都是为了让"还没验证"这件事保持可被看见。
功能总览
| 能力 | 一句话说明 | 状态 |
|---|---|---|
| 健康指标采集 | 五类硬件错误计数 60 秒低频采集，解析不出判"未知"绝不记 0 | 已适配（端到端未经真机核实） |
| 健康样本存储 | 变化才写 + 每 5 分钟保活一行，默认保留 180 天 | 已实现 |
| 写入去重缓存 | 稳态心跳零数据库访问，缓存只负责"可安全跳过"，库始终权威 | 已实现 |
| 显存故障预测规则 | 强信号即时触发 + 增速型主信号双条件，阈值全部可配置 | 实验性（未经真实数据校准） |
| 命中回填 | 窗口到期后按不可纠正 ECC 增长判定命中/未命中/无法判定 | 实验性（同上） |
| 规则版本冻结 | 每条预测落库即冻结规则版本与窗口，历史命中率不可事后调好看 | 已实现 |
| 预测效果统计 | 命中率（精确率）与预测率（召回）分母严格区分，样本不足给 null 不给 0% | 已实现 |
| 告警联动 | GPU_FAULT_PREDICTED 节点级告警，命中后不自动消解 | 已实现 |
| 单卡样本查询 | 原始时序按卡取数，前端自算每小时 ECC 增量速率 | 已实现 |
| 采集能力矩阵 | 每卡能采哪些指标由样本实际推出，不按厂商推断 | 已实现 |
| 仿真数据模式 | 独立来源标识的演示数据，绝不混入真实统计、不触发告警 | 已实现 |
| 多实例与租户隔离 | 预测 worker 仅主实例运行 + 存储层幂等双保险；数据按租户可见范围收窄 | 已实现 |
采集与存储：从心跳到样本
Agent 侧：60 秒低频采集
健康计数是慢变量，与 5 秒心跳里的温度/利用率/显存分频采集：Agent 每 60 秒采一拍，且一拍里每个厂商最多起一个查询进程（一次命令覆盖该厂商全部卡），采集成本不叠加到心跳路径。采到的计数写入带时效的进程内缓存，每拍心跳从缓存取值上报；缓存样本超过 180 秒（3 个采集周期）未刷新即判"未知"而不是继续上报旧值——采集线程卡住、厂商工具被卸载时，继续上报等于谎称"刚刚测过，一切正常"。
五类指标（心跳键名）：ecc_uncorrected_total 不可纠正 ECC 累计、ecc_corrected_total 可纠正 ECC 累计、retired_pages 退役显存页、remapped_rows_pending 待重映射行、remapped_rows_failure 行重映射失败。前四类刻画渐进劣化，最后一类（备用行耗尽）本身就是强预警。
口径上最要紧的一条：解析不出来就是未知，不是 0。[N/A]、[Not Supported]、空值、负数一律判未知，对应心跳键不出现。把"ECC 关闭/不支持"记成 0，预测引擎就会把一张没有任何可观测性的卡当成"零错误的健康卡"，给出虚假的安全结论——这是本模块明令禁止的失真方向。
厂商覆盖如实说明（本期实际实现）：
| 厂商 | 采集方式 | 状态 |
|---|---|---|
| NVIDIA | 运行时读 nvidia-smi --help-query-gpu 探测驱动真实支持的字段，再组一次 CSV 查询覆盖全部卡；能力探测结果缓存 30 分钟 | 已适配（字段名待真机核实） |
| 昆仑芯 | 三代 xpu-smi 的 "Volatile Uncorr. ECC" 列（真实输出夹具对齐）；一/二代 xpu_smi 无该列，判未知 | 已适配（无真机） |
| 寒武纪 | cnmon 的 "Ecc-Error" 列（真实夹具对齐；官方双卡样例该列为 N/A） | 已适配（该列语义待厂商确认） |
| 其余七家（沐曦/燧原/天数智芯/壁仞/海光/摩尔线程/昇腾） | 本期未采集，如实留白 | 未实现 |
NVIDIA 的字段名走运行时探测而非写死，是刻意设计：只有该驱动帮助文本里真实出现过的字段名才进查询，猜错的名字自动退化成"未采集"，不会污染数据也不会让温度功耗等其它指标陪葬。XID 错误码采集本期不实现（需读内核日志，权限与格式都要真机验证）。
由此带出平台的一条硬口径："这张卡能采哪些健康指标"没有任何可靠的先验来源——同一厂商不同型号能力不同（NVIDIA 消费级卡没有 ECC、数据中心卡有），同一张卡上 ECC 可以被运维一键关闭（关闭后驱动返回"不支持"），Agent 版本又决定了到底采不采、采了带不带这个键。所以能力矩阵只能从样本实际推出：某个指标在这张卡的样本里出现过非 NULL 值，才算"这张卡能采这一项"。这既是最保守的判据，也让"哪些卡真的在被监测"始终有事实依据可查，而不是一张写满推测的厂商支持表。
服务端：变化才写 + 保活行
心跳处理器把本拍 gpu_stats 里的健康计数落进 gpu_health_samples 表，是心跳的旁路写入：失败只记日志、绝不影响心跳返回（心跳失败会让节点被判离线，代价远大于少记一拍样本）。写入策略是"变化才写 + 每 5 分钟保活一行"：
- 计数有任何变化（含"未知变已知"）、或该槽位换了卡（UUID 变化）、或距库内最新样本超过 5 分钟——写一行；
- 全部计数未知的卡在读库之前就被挡掉，不产生任何数据库访问；
- 保活行的意义：没有它，一张卡的最后一条样本是三个月前的，无法分辨"三个月稳定无错误"还是"三个月前就采不到了"——这两种情况对预测的意义完全相反。
存储层的写入判定有四种情况会落一行：这张卡的第一条样本、计数有任何变化（含"未知变已知"）、槽位换了卡（UUID 变化）、距上一条样本超过保活间隔。逐心跳全量写会把这张表变成 99% 冗余——按 5 秒一拍估算一天 166 万行，而"变化才写"的上界只有每卡每天 288 行，两个数量级的差距。
每卡每天的落库量上界 288 行；样本默认保留 180 天（覆盖一个完整的"30 天窗口 + 7 天基线"评估周期，外加回看历史预测的依据），环境变量 GPU_HEALTH_RETENTION_DAYS 可覆盖，非法值（非数字/非正数）一律回落默认并告警——把配置笔误变成"清空全表"是不可接受的失败模式。清理按"真实写入次数"触发（每 5000 次写入一次），在独立协程与独立超时里执行，不挂在心跳请求上、不拖慢心跳响应；没有任何节点上报健康数据的部署（现网绝大多数）根本不会跑这个 DELETE。表上建有（节点、物理索引、采样时刻）复合索引与来源索引，支撑单卡时序回读与保留期清理两类查询。
两个防错位细节贯穿全链路：物理索引取 stat 自己声明的 index 而非心跳数组下标（乱序/缺卡上报时才不会把 A 卡的 ECC 历史接到 B 卡的时间线上）；样本同时记录硬件 UUID，同一槽位换卡后旧卡计数绝不能续到新卡头上，否则会凭空制造"计数暴涨"的假劣化信号。
写入去重缓存
健康采集 60 秒一拍，但采到的值跟着每 5 秒心跳重复上报。服务端对每张"有健康数据"的卡维护一个进程内缓存，记住"上一次已确认的库内最新行"：计数与 UUID 都没变、且距库内最新行还不到保活间隔时，这一拍完全跳过，零数据库访问。安全性基础有三条：缓存只在存储层报告库里最新行之后才被填充（不猜）；缓存丢失/过期的后果只是多一次 SELECT；保活的时间基准是库里那一行的采样时刻，不是心跳时刻——用后者会让基准每拍前移，保活行永远写不出来。缓存上限 4096 条（够 512 节点 × 8 卡），闲置 30 分钟自动清理，多实例部署下各进程缓存独立，最坏情况多写一行计数完全相同的保活行，对趋势判断无害。
显存故障预测机制（实验性）
> 本节所述规则的有效性尚未经真实数据验证。阈值是初始经验值，所有参数可经环境变量调整正是为了等真实数据到位后校准，而不是为了让演示数字好看。
信号分层
规则引擎只做判断不碰数据库，每条信号分三层：
| 层 | 信号 | 触发条件 | 能否单独触发 |
|---|---|---|---|
| 强信号 | 不可纠正 ECC 累计 > 0 | 已发生的双比特硬错误 | 能 |
| 强信号 | 行重映射失败累计 > 0 | 备用行耗尽，显存没有余量遮蔽坏行 | 能 |
| 趋势信号 | 可纠正 ECC 增速上升（主信号） | 双条件同时满足，见下 | 能 |
| 趋势信号 | 待重映射行观察期内增长且当前 > 0 | 增长而非出厂存量 | 能 |
| 趋势信号 | 退役页观察期内增长且当前 > 0 | 同上 | 能 |
| 弱信号 | （预留）温度/功耗等辅助信号 | —— | 永不单独触发 |
弱信号分层目前没有生产信号会命中（温度/功耗在另一张 7 天保留的指标表里，本期未接入预测引擎），它是一道给将来新增弱信号留的硬门禁：任何被标为弱信号的观测都无法独自产生预测，这条门禁由专门的单测钉住。
增速型主信号：双条件
可纠正 ECC 增速是本规则集的主信号，两个条件必须同时满足：
1. 量级门槛：近 24 小时增量 ≥ 32（防"小数字放大成大倍数"：基线一周共 1 个错误时，一天出 1 个就是 7 倍，纯噪声），且 ≥ 近 7 天日均的 1.2 倍（最近一天的出错速度比本周平均快 20% 以上，即确实在加速；恒速与减速被排除）；
2. 形态门槛：最近 3 个连续窗口的增量严格递增（把"持续加速劣化"与"一次性突发"分开——突发卡单窗增量很大但不会逐窗递增；严格而非非严格，等速出错的卡不该每轮都被预测）。
倍数门槛取 1.2 而不是直觉上的 3，是推演过的：这个比值的值域有界（[0, 7]），显存颗粒渐进劣化的二次加速形态算出来只有 1.2~1.4，取 3 会把所有渐进劣化全部挡掉、只剩阶跃突发能过，而突发又被递增条件挡掉——两条一叠加，整条规则就成了"有触发路径但实际永不触发的死代码"，且没有任何信号告诉你它没在工作。取 3 是这类事故的标准形态，本平台刻意避开。
任何边界点的值未知（历史不足、该卡没有可纠正计数）就放弃本信号，绝不用 0 补——"没有历史"不能被算成"从 0 涨到现在"的巨大增量。昆仑只有"易失不可纠正"一列、没有可纠正计数，走的就是这条路径：它只能做事后告警与命中回填，做不了增速型预测，这是如实的能力边界而非缺陷遮掩。
命中窗口与回填
每条预测落库时冻结规则版本（当前 v1-ecc-growth）与命中窗口天数（默认 7 天，可配 30 天），窗口到期后由回填流程判定：
- 命中（hit）：窗口内该卡不可纠正 ECC 计数增长（故障事件口径 F1；XID 采集未实现，本期只用 ECC 计数）；
- 未命中（miss）：窗口到期且窗口内有样本、计数未增长；
- 无法判定（voided）：窗口内换了卡（UUID 变化）或一条样本都没有（采集停滞/节点下线）——绝不记成 miss，不可判定的样本进分母会把命中率拉低，是另一个方向的失真。
窗口是左开右闭区间：预测所依据的那条样本不算窗口内新观测。这条边界曾在 PostgreSQL 微秒精度上翻过车（1 纳秒偏移被截断，窗口语义漂移、假成功消解告警），修复后改为在读回的数值之间做严格比较，与后端精度无关。
"同卡未到期窗口内不重复预测"有专门判据：一张正在劣化的卡每轮都会有新样本，若只靠主键去重，t0 跟着样本前移、预测会每半小时多一条，命中率分母被同一张卡刷爆。预测记录 ID 由（节点、物理索引、UUID、来源、规则版本、冻结窗口、t0）确定性派生，t0 取样本时刻而非当前时钟——这同时是多实例安全的基础：主实例交接的重叠窗口里两个实例扫到同一批样本会算出同一个 ID，主键冲突让库里只留一行；回填则是 WHERE status='pending' 的 CAS，只有一个实例的判定生效。预测 worker 正常情况下仅主实例运行（随选主生命周期启停，默认 30 分钟一轮），存储层幂等是交接瞬间重叠的安全网，不是常态设计。
worker 每 tick 的顺序是先回填、再预测：一张卡上一轮的预测若本轮到期，先把它结掉，"同卡未到期窗口内不重复预测"才不会把这张卡永远挡在外面。评估对象从能力矩阵出发而不是从节点列表出发——节点列表里的卡绝大多数采不到任何健康指标，对它们跑规则是纯浪费，还会让"这张卡没有预测"分不清是"健康"还是"压根没数据"。取样本序列时显式设置时间上界为当前时刻：不设上界时，任何时间戳晚于当前的样本（agent 时钟偏移、离线补数）都会把 t0 推到未来、命中窗口整体落到未来，回填时"窗口内一条样本都没有"被判无法判定——一条本该能验证的预测无声地变成不可判定，且没有任何报错。这个边界是端到端仿真测试实际抓到后才修复的。预测引擎的全部参数（总开关、扫描间隔、窗口天数、增速窗口、基线天数、倍数门槛、最小增量、连续窗口数、样本门槛等十余项）均可用环境变量覆盖，非法值一律回落默认并告警，绝不采用。
告警联动
新预测落库即触发 GPU_FAULT_PREDICTED 告警（WARN 级、节点作用域去重），文案与显存使用率告警（GPU_MEMORY_HIGH）严格区分：后者是"显存被任务占满，卡本身是好的"；前者是"硬件错误计数在劣化，运维动作是排维护窗口、准备换卡"。告警文案只说"预测"并附窗口、判据与规则版本，不写"已故障"、不暗示准确率。三道闸缺一不可：仿真预测绝不告警、规则开关不存在时视为开启（fail-open，防止"实现完整但默认关闭、从上线起从未触发"的事故重演）、同节点已有未结案同类告警不重复建。
命中之后的告警不会自动消解：命中意味着窗口内这张卡真的出现了不可纠正 ECC 增长——一个尚未处置的硬件问题，把它消解成"已恢复"就是用假成功掩盖真实情况。告警保持非终态，直到运维人工标记解决（留痕）或节点删除时由孤儿清扫收尾。同理，某槽位最新判定是"无法判定"时也不能声称恢复——对没观测到的卡说"已恢复"同样是编造。代价也如实登记：一条命中后长期无人处置的告警，会被平台 72 小时的告警看门狗归类为"运维积压"并提醒——一张确实在出硬错误的卡长期没被换掉，本来就该被看见，这里不做特殊豁免。
预测效果统计：两个分母，绝不混淆
统计接口固定给出 7 天与 30 天两档窗口的对照（只给当前配置那一档会让人误以为那就是全部事实）：
- 命中率（精确率）= 命中数 / 已到期预测数。未到期的保持 pending 不进分母；无法判定单独一类也不进分母。
- 预测率（召回）= 故障前已被预测到的卡数 / 窗口内发生真实故障的全部可监测卡数。分母必须包含漏报——故障事件由独立扫描样本序列找出（找计数递增点），而不是从预测记录反查；只在"已预测的卡"里数有几个真坏了，召回会虚高到接近 100%，因为没预测到的故障根本不在视野里。漏报卡数显式给出，这个数字本身就该被看见。
样本不足不给百分比是硬口径：已到期回填的预测数不足 20 条，或观察天数未知/不足 8 天——任一不满足，命中率与预测率都是 null（JSON null，不是 0%），只给原始计数与"已观察 X 天 / 需 ≥ Y 天、已回填 N 条 / 需 ≥ M 条"的如实说明。返回 0% 会被读成"预测一次都没准"，而真相是"还没攒够数据"。后端与前端按同一口径各自守住这道闸。曝光量按"每张卡首末样本之差"累计成卡·天，昨天才接入的卡只贡献 1 天，不会按统计期夸大成 30 天。
仿真数据模式
平台提供一个内部仿真生成器，可向库里写入 source='simulated' 的合成样本（健康卡/劣化卡等画像），用于演示规则形态与算法自测。仿真数据与真实数据在存储、查询、统计、告警四个层面完全隔离：所有查询默认只返回真实来源，看仿真必须显式传参；两种来源拒绝混合（混在一条序列里算出的增量是两套数据的拼接产物，毫无意义）；仿真预测绝不进对外统计、绝不触发告警。演示结束可单独清理仿真数据，绝不触碰真实样本。
页面功能介绍
GPU 健康页位于 /nodes/gpu-health，自上而下四个区块：预测效果统计、预测列表、ECC 速率、采集能力矩阵。页面顶部常驻"初始经验阈值，待真实数据校准"提示——不依赖接口成败，接口返回的诚实声明则原样展示；切换到仿真数据后整页出现显著横幅与角标。页面不自动刷新，按交互取数。
| 操作 / 区域 | 行为 | 背后 API |
|---|---|---|
| 数据来源切换（真实/仿真） | 清空全部旧数据与选中卡后重新拉取，防两套数据在界面短暂混显 | 下方四接口带 source 参数重拉 |
| 常驻校准提示 | 接口声明原样展示；加载中/失败时用同义本地文案兜底，提示永不缺席 | GET /gpu-health/prediction-stats 的 disclaimer 字段 |
| 统计卡（N=7 / N=30 两张） | 样本充足显示命中率与预测率；不足时整块切为"样本不足，暂不给命中率"并列出原因清单；四状态原始计数、故障卡/已预测/漏报、可监测卡/覆盖卡·天/观察跨度始终显示 | GET /gpu-health/prediction-stats |
| 预测列表-状态筛选 | 全部/待回填/命中/未命中/无法判定五选，切换即回第一页 | GET /gpu-health/predictions?status= |
| 预测列表-表格 | 列：卡（节点名+索引+UUID）、预测类型标签（按依据文本识别，识别不出显示"未识别"不瞎猜）、状态徽章、预测时间→窗口截止、规则版本、依据与回填结论；点击行选中该卡联动速率图 | GET /gpu-health/predictions（每页 50 条） |
| 预测列表-分页 | 上一页/下一页，页码与总条数如实显示；不足一页只显示总数 | 同上（offset 步进 50） |
| 预测列表-空态 | 如实说明"没有预测记录不代表所有卡都健康——没有采集能力的卡不会被预测"，引导看能力矩阵 | —— |
| ECC 速率-卡选择器 | 预设选中第一张有 ECC 计数的卡；可纠正/不可纠正两张每小时增量柱状图，读不到的小时留空并打"未知"阴影（不是 0）；整项采不到时显示大字"未知"并说明原因 | GET /gpu-health/samples?node_id=&gpu_index=（单次上限 20000 条） |
| ECC 速率-覆盖说明 | 可计算小时数/总小时数、合计增量；命中条数上限时显著警示"只含最近部分，更早的未加载"；增量只在一小时首尾都有新鲜样本且同一张物理卡时计算 | 同上 |
| 能力矩阵-表格 | 列：卡、节点厂商/型号（按节点汇总，不对位单卡）、五项指标逐项"可采集/未知"、"增速型预测"可/不可、最近样本时间与样本条数 | GET /gpu-health/capabilities + GET /nodes（节点名） |
| 能力矩阵-采集停滞徽章 | 超过阈值时长（默认 60 分钟）没有任何样本（含保活行）即标记"采集停滞" | 同上（collection_stalled） |
| 能力矩阵-未采样卡行 | 节点上报的 GPU 数多于有健康样本的卡数时，补"差额 N 张卡全部指标未知"的行，只报数量不猜是哪几张 | 同上 + GET /nodes |
| 能力矩阵-页脚 | 接口的读数说明原样展示："未知"表示统计期内没采到，不代表错误数为 0 | 同上（note 字段） |
速率图的三个计算条件（任一不满足该小时记未知）：小时首尾的计数都可读且距整点不超过停滞阈值（沿用旧值是在编数据）、首尾属于同一张物理卡（换卡后两张卡的计数不可相减）、增量非负（驱动重置/计数回绕记未知，不画负数也不截成 0）。
后端逻辑概念表
| 概念 | 定义 | 代码出处 |
|---|---|---|
| 健康计数 | 五类单调累计量（ECC 可纠正/不可纠正、退役页、待重映射行、重映射失败），nil = 未知 | agent/pkg/detection/health.go:93 |
| 保活行 | 计数没变也每 5 分钟写一行，让"稳定无错误"与"采集停了"在数据上可区分 | core/pkg/api/gpu_health_record.go:44 |
| 未知 ≠ 0 | 缺键/不可解析/负数一律 nil；表列可空严禁 DEFAULT，NULL 读回不为 0 | core/pkg/api/gpu_health_record.go:95、postgres/schema.go:555 |
| 物理索引 | 样本归属取 stat 自己声明的 index 而非心跳数组下标，防错位串卡 | core/pkg/api/gpu_health_record.go:186 |
| 去重缓存 | 进程内"库内最新行"缓存，计数与 UUID 未变且未到保活即整拍跳过 | core/pkg/api/gpu_health_dedup.go:120 |
| 信号分层 | 强信号/趋势信号可单独触发，弱信号永不单独触发的硬门禁 | core/pkg/api/gpu_fault_predict_rules.go:271 |
| 规则版本冻结 | 预测落库冻结 rule_version 与 window_days，事后调参不影响历史命中率口径 | core/pkg/api/gpu_fault_predict_rules.go:48 |
| t0 | 预测时刻 = 被评估序列最后一条样本的采样时刻（非当前时钟），多实例幂等的基石 | core/pkg/api/gpu_fault_predict_rules.go:302 |
| 命中窗口 | (t0, t0+N] 左开右闭；依据样本不算窗口内新观测 | core/pkg/api/gpu_fault_predict_rules.go:629 |
| voided | 换卡或窗口内无样本导致的无法判定，单独一类绝不记 miss | core/pkg/api/gpu_fault_predict_rules.go:644 |
| 能力矩阵 | 每卡能采哪些指标由样本里出现过非 NULL 值推出，不按厂商/型号推断 | core/pkg/types/gpu_fault_predict.go:113 |
| 采集停滞 | 最近一条样本（含保活行）距今超阈值（默认 1 小时），判定采集链路断了而非计数恰好没变 | core/pkg/api/gpu_fault_predict_api.go:406 |
| 可监测卡 | 至少采到过一项健康指标的卡，才进预测率/命中率分母 | core/pkg/types/gpu_fault_predict.go:154 |
| 样本不足语义 | 已回填 < 20 条或观察 < 8 天 → 比率为 null 不是 0%，note 写明差距 | core/pkg/api/gpu_fault_predict_stats.go:169 |
| 漏报 | 发生了故障但事前没有预测的卡数，显式返回，不让前端自己减 | core/pkg/api/gpu_fault_predict_stats.go:167 |
| GPU_FAULT_PREDICTED | 硬件错误计数劣化的预测告警（WARN/节点作用域），与显存使用率告警严格区分 | core/pkg/api/gpu_fault_predict_alert.go:43 |
| 仿真隔离 | source=simulated 全链路隔离：默认不可见、拒绝混合、不进统计、不告警 | core/pkg/api/gpu_fault_predict_api.go:128 |
API 参考
四条只读接口均挂 /api/v1/gpu-health/ 前缀（刻意不挂 nodes 下，避免与既有字面量路由在 Go 1.22 ServeMux 里冲突），统一 requireAuth + nodes:read 门禁，租户可见范围在 handler 内按节点白名单收窄（口径与节点列表接口同源），越权节点一律 404 反枚举。source 参数只接受 real（默认）/simulated，拒绝 all。
| 接口 | 说明 |
|---|---|
GET /api/v1/gpu-health/predictions | 预测列表；node_id/gpu_index/status/since/until/source 过滤，limit（1-500，默认 100）offset 分页；返回 current_rule_version 供与每条记录的冻结版本对照 |
GET /api/v1/gpu-health/prediction-stats | 7/30 两档窗口统计 + 诚实声明 disclaimer（须原样展示）；since 默认回看样本保留期 |
GET /api/v1/gpu-health/capabilities | 卡能力矩阵（五项指标可采集/未知、首末采样、样本数、采集停滞、能否增速型预测）；带说明"能力由样本推出，不是厂商支持矩阵" |
GET /api/v1/gpu-health/samples | 单卡原始样本；node_id 与 gpu_index 必填，since 默认近 7 天，limit 默认 5000 上限 20000，命中上限返回最近若干条并标 truncated=true |
已知边界
1. 规则未经真实数据校准（本篇最重要的边界）：全部阈值为初始经验值，依据公开机理而非平台历史故障数据；真实的预测率/命中率要等真机采集攒够样本才存在。样本不足时统计不给百分比只给原始计数，这不是缺陷，是口径。
2. NVIDIA 采集字段名待真机核实：候选字段名来自公开资料的推断，设计上靠运行时能力探测兜底（帮助文本里没有的字段自动不采），但真实字段名与 CSV 形态尚未在真机上逐字核实；探测失败时本拍健康字段整体判未知，不会污染其它指标。
3. 厂商采集覆盖有限：仅 NVIDIA/昆仑/寒武纪三家实现采集，其余七家国产厂商本期未采集（代码与夹具里都没有该厂商 ECC 列的证据，不做"也许能解析"的通用兜底）；昆仑只有不可纠正计数做不了增速型预测；寒武纪该列统计语义（可纠正还是不可纠正）待厂商确认。
4. XID 采集未实现：故障事件口径目前只有不可纠正 ECC 增长一条；显存相关 XID（48/94/95/64）的采集方案已做技术调研，接入后只需在判定里加一个或分支；掉卡类故障（XID 79）因数据来源不可靠（节点离线与掉卡在心跳层面无法区分）本期明确不统计，而不是用不可靠口径凑数。
5. 国产卡换卡识别失效：目前仅 NVIDIA 检测器上报硬件 UUID，国产卡槽位换卡后无法识别，旧卡计数可能接到新卡时间线上——能力缺口如实登记，不做"计数变小就认为换卡"这类推测性补偿。
6. 弱信号未接入：温度/功耗未进预测引擎输入，弱信号分层当前没有生产信号会命中，仅作为未来扩展的门禁存在。
7. 统计实现的规模边界：召回统计按卡逐个读样本序列，当前可监测卡数量级下没有问题；卡数或保留期大幅上去后应把故障事件检测下推成 SQL，本期未做。
<!-- 状态标注说明: 实验性=功能已实现但关键参数未经真实数据校准 / 已实现=代码+测试钉住 / 已适配=采集逻辑对齐厂商工具输出或设计探测策略但无真机端到端验证 -->