Skip to content

kali20gakki/msAgent / skills/accuracy/loss-gnorm-diff-analyzer

loss-gnorm-diff-analyzer

Verified

端到端分析两侧 msprobe PyTorch statistics 原始 dump 数据(dump.json + stack.json + construct.json)与精度问题现象(loss / grad norm / 输出不一致等),按「确定性预处理 → 多视角候选发现 → 汇总排序 → 分级定向验证 → 报告校验」流程识别可疑候选节点并构建到目标异常现象的因果链,交付主分析报告与结构化证据记录。当用户提供两侧 dump 目录并需要定位训练精度问题根因时使用。侧别判定:用户指定 target(待分析侧)/ golden(参考侧)优先;未指定时按目录名与数据内容推断(npu/gpu 等仅为软线索,不作硬性假设);不可靠时询问用户。

references/alignment-playbook.md

View on GitHub
# 对齐证据手册:什么算可靠对应,什么算强行匹配

> 每个"配对"进入因果分析前必须能回答:**为什么这两个节点是同一个逻辑计算?**对齐错误会把假差异送进因果链,比漏配更危险。

## 1. 证据类型清单

| 类型 | 来源 | 例 |
|---|---|---|
| 名称证据 | dump 节点名 | 全名精确相等(含调用号与方向) |
| 结构证据 | construct.json 父链/归属 | 两侧节点同属同名 Module |
| 栈证据 | stack.json 调用帧 | 两侧栈指向同一用户代码行 |
| 语义证据 | API 名称含义 | `NPU.npu_prompt_flash_attention` ↔ `Functional.scaled_dot_product_attention`(同为融合注意力) |
| 顺序证据 | dump 执行序 | 两侧处于相同相对位置、由相同前驱产生 |
| 数据证据 | shape/dtype(**统计量除外**) | 输入输出 shape 一致 |

**质量分级**:全名精确相等 = 高;命名变体匹配(shape 门槛 + 双侧唯一键)= 中,引用其差异需额外佐证;仅凭顺序/形状之一 = 低,不得单独作为配对依据。

## 2. 高置信模式

1. **两侧执行序列一致**(族序列公共前缀覆盖全程、族计数无漂移)时,同名匹配即可靠匹配。
2. **Module 节点是稳定骨架**:模块钩子调用次数通常两侧一致(结构由模型定义决定),先核对 Module 层对齐,再处理 API 层漂移。
3. **融合算子 ↔ 融合算子**:同一逻辑计算的不同硬件实现(NPU 融合算子 ↔ golden 组合算子)。需要 construct 父节点同名/栈同源 + 输出 shape 一致 + 调用次数相同等多项独立证据;优先映射 output 行,input 行逐槽位核对(参数顺序、kwargs 差异)。
4. **调用计数漂移段**:先确认漂移起点(族序列分叉点、计数差出现的锚点区间),段内逐个用 shape+顺序+栈确认;无法确认的保持未匹配,宁缺毋滥。

## 3. 已知错配模式(必须主动防范)

1. **族计数漂移后的同名错位**:一侧同族调用更多(分片、分解、重计算、额外前后处理)→ 同名同号的节点在漂移起点之后不再等位。信号:族计数不等、该族跨侧形状一致率低、或该族差异从某个调用号起系统性出现。
2. **反向调用号错位**:反向执行序对 loss 的拓扑序、重计算、梯度累积都会改变反向调用计数。逐族检查形状一致率;不一致的族其差异不可直接采信。
3. **分片/多卡变体**:`_rank<N>` 后缀族、DTensor(带 `device_mesh/placements`)、同族调用数成倍增长(如 2×),都是"该侧按分片执行"的标志。**分片统计量与全量统计量不可比**:形状不同(分片维度变小)、范数不等(部分和)。此类配对一律不进数值对比,只作结构证据。
4. **专用算子 ↔ 通用组合**:`NPU.*` ↔ `Functional.*` 语义等价需多项证据;仅凭名称相似不得配对。
5. **proc/PID 目录**:不是 rank 标识,按序号配对并说明。

## 4. 禁止入表(强行匹配)

- 仅凭名称相似(`conv1` ↔ `conv_1`)无结构/栈佐证。
- 仅凭 shape、dtype、调用顺序、统计量之一。
- **按"统计值相近"寻找或选择配对**——真正对应但已发散的节点统计差异大,按统计值配对等于用未知答案预筛选,会系统性洗掉差异点。
- 分片副本 ↔ 全量算子(形状门槛会挡住大部分;发现漏网时手工排除)。
- 一对多 / 多对一(破坏 1:1)。

## 5. 无法映射时的归类(写入报告)

- `ONE_SIDE_MISSING`:一侧没有该逻辑计算(设备专属 cast、搬运等)。
- `SHARD_ONLY`:分片/多卡变体命名,仅存在于分片侧。
- `FUSED_NO_COUNTERPART`:融合算子与组合无法 1:1。
- `ORDER_DIVERGED`:执行序差异过大,锚点夹逼失败。
- `AMBIGUOUS_MULTI_CANDIDATE`:候选 ≥2 且证据不足区分。
- `NAME_UNKNOWN`:名称语义无法判断且其他证据缺失。

报告应分别呈现两侧独有节点(按族聚合、给出执行序位置与前后锚点),避免只关注成功匹配的部分。**未匹配节点可能是根因所在**(一侧多出的预处理、缺失的计算、不同的执行路径),不是对齐失败的边角料。

## 6. 可比性门槛(数值对比的前提)

一对匹配槽位的统计量只有在以下条件同时满足时才作为数值证据:

1. dtype 相同(或明确论证网格等价);
2. shape 相同;
3. 无 DTensor/placements 差异(分片方式一致);
4. 匹配质量为精确匹配或有多项佐证的变体匹配;
5. 两侧统计口径一致(statistics 模式、同 step 同 rank 对应)。

任一不满足 → 记为结构分歧或不可比,**不得用数值差立论**,但结构差异本身(如 dtype、placements 不同)是根因候选线索。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall