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 等仅为软线索,不作硬性假设);不可靠时询问用户。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 31.9 KB |
| references/alignment-playbook.md | markdown | 4.8 KB |
| references/candidate-discovery.md | markdown | 6.1 KB |
| references/causal-validation.md | markdown | 4.8 KB |
| references/dump-analysis-mechanism.md | markdown | 44.9 KB |
| references/evidence-and-state.md | markdown | 11.2 KB |
| references/hard-constraints.md | markdown | 68.6 KB |
| references/report-validation.md | markdown | 12.4 KB |
| scripts/dump_analyzer.py | script | 77.4 KB |
| scripts/make_evidence.py | script | 5.7 KB |
| scripts/query.py | script | 63.4 KB |
| scripts/report_check.py | script | 8.5 KB |
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 不同)是根因候选线索。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |