cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/baseline.md

@@ -0,0 +1,69 @@
+# 确认比较与验收是否可信
+
+先确认“这次比较能否证明精度失败”。本页负责核对比较双方、有效区和比较器（evaluator）的实际判据；现场冻结、真实退出码、产物采用和重复运行统一见[复现性方法](reproducibility.md)。已有可信比较依据时直接复用。
+
+## 目录
+
+- [确认精度比对标准](#确认精度比对标准)
+- [数值相等与逐位一致](#数值相等与逐位一致)
+- [确认比较对象与有效区](#确认比较对象与有效区)
+- [校准 evaluator 的实际判据与算术](#校准-evaluator-的实际判据与算术)
+
+## 确认精度比对标准
+
+精度通过标准和参考结果由用户需求或项目已有测试给出；本 Skill 核对其实际执行，不制定通用标准或阈值表。信息缺失时先查看项目需求、比较器和 golden 生成入口，仍不明确的部分请用户补充。
+
+项目已有明确验收要求和 evaluator 时，先按现有入口复现。需求与比较器不一致时说明具体差异，不为了让失败样例通过而切换判据。
+
+记录本次采用的标准来源、evaluator、阈值、特殊值规则和有效区，核对实现是否覆盖所选标准的完整判据。例如浮点标准可能同时要求逐元素容差、通过元素比例和最大绝对误差上限，仅复用 `rtol`、`atol` 的辅助比较不一定等价。有疑点时按下文[校准 evaluator](#校准-evaluator-的实际判据与算术)核对。
+
+沿用已有验收报告；需要定位时，按输出、轮次或观察点整理判定，并补充错值坐标、分布和位模式。这些观察可与工程验收同时使用。逐元素全部通过与“通过比例＋误差上限”的判据可能双向不同，正式验收按项目规则判断。
+
+调用项目比较器时，加载本次真实输出与参考数组，使用项目要求的参数；比较前的类型转换可能改变结果，内置示例只用于理解调用。需要补充局部参考时对齐实际计算语义，不以辅助参考替换项目 golden。原始位比较和随机分布检查分别见下方对应章节。
+
+比较依据尚未核实时，仍记录现有 evaluator 实际返回的 PASS/FAIL，并说明待确认的部分；暂不据此认定算子正确或错误。比较有效后，通过结果也只覆盖本次输入和所采用的判据。
+
+### 随机输出：边际分布与序列要求分开验证
+
+若输出语义确实要求随机性质，先把项目要求拆成范围/边际分布、顺序或跨次依赖、seed/状态推进及可重复性等实际要求；确定性算子在固定输入下偶发错值，仍应先按重复性和设备数据流问题定位，不能因为“结果会变”就改用随机分布验收。
+
+同一批数值排序前后的经验分布完全相同；重复返回上一批结果，也可以保持每批边际分布不变。因此只看每批经验分布、均值或方差的 evaluator，无法单独区分这些变化。若约定要求顺序或跨次独立，用排序、整批复用或状态不推进等受控错误检查 evaluator 是否对相应要求敏感，并按约定增加能观察该要求的验证；约定允许固定 seed 重放时，重放本身并不是失败。这里的反例只说明观察能力，不证明原始序列随机、独立或满足任何统计阈值。
+
+冻结方案实际使用的参数，如实际样本数、批次数、输入/seed 身份、分布参数、检验实现、显著性水平和批量判定方案，并核对参数确实传入了每一层；无需显著性检验的要求不强加 alpha。单次检验仍用内部默认 alpha、批量汇总却按调用方 alpha 计算阈值，或公式使用的批次数与实际执行次数不同，都会让报告与预声明方案不一致。阈值、复测/停止规则由项目方案事前决定；不能从固定通过率倒推接受标准，也不能反复重测直到得到一次通过。
+
+统计通过只能报告当前样本在选定方案下未触发拒绝条件；不应改写成分布已被证明正确。缺少独立性要求的敏感证据、真实样本或可靠检验实现时，明确未验证的部分，不能用边际指标代替这些验证。
+
+## 数值相等与逐位一致
+
+按每个输出已给定的项目判据比较。约定明确要求与参考按原始位模式一致时，任何有效元素的位差都判失败，包括 `+0/-0`、NaN 符号和 payload；数值相等或双 NaN 类别相等不能抵消这些失配。只有函数名或报告字段写着 `exact`/`bitwise`、实际判等语义尚未定义时，才需进一步核对特殊值规则，不能因此将已明确的要求重新列为待定。
+
+已有可信 evaluator 直接复用；需要补充位模式观察时，核对双方 dtype、布局与有效区，再读取原始编码比较，保留代表位置的十六进制位模式。若已知位差违反明确约定，报告约定失配及现有 evaluator 的实际结果，缺失的其它位置或编码另列待查。项目明确采用数值零相等或双 NaN 判等时，按该规则验收，并将它与严格原始位比较分开说明。
+
+双 NaN 只说明类别相同，不证明符号或 payload 相同，也不证明它们不同；把已确认的位差与尚待读取的编码分别报告。现有 evaluator 返回通过也不能反推它采用了哪种特殊值规则；要解释这一通过，需有实际比较逻辑或校准结果作依据。
+
+最终输出逐位一致不自动要求内部计算步骤相同。项目另有求值顺序要求时按其验证；怀疑归约或特殊值导致位差时，再查[归约顺序](../patterns/mechanisms/accumulation-order.md)或[特殊值](../patterns/mechanisms/special-values.md)。
+
+## 确认比较对象与有效区
+
+actual、golden 和 evaluator 必须对应同一输出语义，包括 dtype、layout、逻辑 shape、物理存储、有效范围、容差和特殊值规则。把逻辑、分配、搬运、计算和有效输出元素数分开核对；只有原有要求已排除 padding，才可将它屏蔽，不能因为 padding 失配就事后缩小比较范围。
+
+多输出分别记录判据和结果，并展开整体 PASS/FAIL 的组合关系。仅当整体判据确实是逐输出条件的合取时，才能从某项通过推断剩余失败属于其他输出；若还有跨输出约束，需要单独观察。
+
+判断执行是否成功、输出是否来自本轮产物，按[现场与产物核对](reproducibility.md#冻结失败现场)确认。返回 0、构建成功或报告生成都不能单独证明比较有效，更不能证明精度通过。缺少可信 oracle、有效区或判据时，保留未知项并继续收集证据；不要用辅助工具的默认设置替代项目验收。
+
+## 校准 evaluator 的实际判据与算术
+
+当报告出现“原值不同却通过”“所有元素满足容差却整例失败”，先用小输入校准 evaluator，再定位 Kernel。把实现真正执行的判据逐项展开：逐元素比较、允许失配比例、最大误差上限、特殊值、有效区、多输出聚合及各项的 AND/OR 关系。函数名、报告中的 `bitwise` 字段或一行容差公式不能证明实际语义。
+
+| 反例/对照 | 要核对的边界 |
+|---|---|
+| 相同数值、不同 dtype；`+0/-0`；相同与不同编码的 NaN | 数值相等、NaN 类别等价和原始位一致是不同判据；先确定约定，再验证对应模式 |
+| `uint64` 最大值与有符号 `-1`；大整数的相邻值 | 比较前转窄、转符号类型或转浮点是否把不同原值合并；差值/绝对值是否超出计算类型范围 |
+| 全部元素满足逐元素容差，但某元素超过另设的最大绝对误差上限 | 整例实际使用了复合判据；附加上限及允许失配比例也要有约定来源，不能从 dtype 推出 |
+| shape 不同、空有效集合、含非有限值的输入 | 应按约定报输入无效或特殊值结果，不能依赖广播、空集合聚合或 NaN 指标偶然得到通过 |
+
+例如 `uint64(2^64-1)` 与 `int64(-1)` 是不同数学整数；若两边先转为有符号 `int64`，可能在比较前已变成同一个值。应保存原始 dtype/位模式，先做不会丢失原值的比较；计算整数误差时再选择能覆盖实际范围的表示。统一转成浮点也不能保证保留大整数低位。用于验收的比较布尔值与便于展示的误差摘要要分开核对：摘要经有损转换显示差值为零，不代表原整数相等。
+
+差值和误差摘要也需要核对计算类型；超出可表示范围或经过有损转换时，保留原始值并说明指标限制，不能用摘要零值覆盖可靠的失配判定。
+
+对每个真正影响 PASS/FAIL 的子条件，尽可能构造一个只触发该条件的失败输入和一个合法对照，保存调用参数与实际结果。若多个条件不能独立触发，说明其依赖关系和尚未区分的部分。复合标准可能是合法项目约定；出现上述分叉时，应先解释它实际验证了什么，不能为了消除 FAIL 自动删掉附加条件。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/checkpoint-design.md

@@ -0,0 +1,82 @@
+# Checkpoint 设计
+
+需要中间观察来区分可疑计算、搬运或数据依赖时使用。本页帮助选择观察位置、准备局部对照，并根据结果推进到具体代码问题；已有可信观察可直接复用。
+
+## 选择位置
+
+先明确本轮需要回答什么，例如“写回前已经算错，还是写回及后续访问时出错”。沿失败输出的实际计算链选择少量候选点，考虑每种观察结果会让下一步检查哪段代码、哪条数据依赖。若不同结果都不能改变调查方向，换一个位置或复用现有证据，不增加无区分力的 dump。
+
+优先选语义清楚、局部对照容易取得、采集成本和扰动较低的位置。按当前疑点参考以下选法：
+
+| 当前疑点 | 可选观察位置 | 希望区分什么 |
+| --- | --- | --- |
+| 不清楚偏差来自哪段计算 | 已有正常输入与失败输出之间的主要阶段边界 | 哪一段值得继续细查；具备二分条件时再缩区 |
+| 计算与搬运、写回难以区分 | 搬运前已就绪的源数据与搬运完成后的对应目标数据 | 源值已经偏离参考，还是传递后才出现差异 |
+| Cast 或量化前后出现变化 | 转换前输入与转换后对应输出 | 输入已有偏差，还是转换的参数、舍入或输出表示有问题 |
+| 尾块、周期或后续循环才失败 | 实际失败的 tile/轮次及可比的相邻正常区域 | 问题是否随有效长度、分片或缓冲复用出现 |
+| 多分支在融合节点汇合 | 相关分支进入汇合节点前的输入及该节点输出 | 哪条输入路径已有偏差，还是汇合计算引入了差异 |
+
+分支按真实 producer→consumer 关系分别检查，不能按源码先后把无依赖的点串成二分链。已有明确候选时，围绕其预测选点；无需先覆盖全部计算节点。
+
+## 对应到本次执行的数据
+
+同一源码位置可能处理多个 core、tile 和循环轮次。由原始失败的逻辑坐标反推执行归属，确定本次观察的分片、轮次、局部偏移和有效切片；前后两个点应对应同一批逻辑数据。涉及归约等跨元素计算时，局部参考还需取得该输出所依赖的完整输入范围。方法见[错误坐标与并行归属](localization.md#解释索引和并行归属)。某个正常 tile 的观察不能代表尚未采集的失败轮次。
+
+用已有报告或简短记录保留源码位置与执行归属、张量的 dtype/shape/layout/有效区、参考依据与比较规则，以及实际输入、运行产物和观察文件的关联。按当前问题补充必要信息，缺项注明，不要求另建固定格式的计划。
+
+观察某阶段的输出时，确认生产者已完成相关写入，且缓冲区尚未被下一轮复用；源码执行到该行不等于异步数据已就绪。就绪性不明时可保留瞬时值调查依赖，暂不据此判断该阶段的计算结果。使用 DumpTensor 输出 Tensor 值时，检查[数据就绪与插桩影响](dumptensor.md#数据就绪与插桩影响)；使用局部模型时按[数值对照](numerical-modeling.md#建立可比条件)确认可比范围。
+
+## 准备局部对照
+
+最终验收沿用用户需求或项目已有比较器与 golden。每个中间点还需匹配自身的公式、输入、dtype、量化或 Cast 位置、layout 和有效区；归约的轴、累加精度及必要的求值顺序也需对应。具体例子见[局部比较链](operator-modeling.md#从输出类型建立局部比较链)。最终输出的 golden 或容差不能直接套到所有中间张量；没有可靠局部判据时先保留数值和趋势，不自行设阈值判错。
+
+按本轮问题选择参考方式，说明它回答什么：
+
+- **从原始输入推导到该阶段的参考值**：观察截至该点的累计偏差，包含上游误差的传播。
+- **将该阶段的实际输入送入独立局部参考实现**：连同影响计算的属性和必要状态，检查本阶段是否产生超出局部判据的差异。该对照通过仍可能意味着上游错误被正常传递，不能据此把此前整段计算标为正确。
+
+两种参考的输入和用途不同，不能混成同一条正常/异常边界。需要区分误差传播与局部新增差异时，见[逐层分析的局部对照](progressive-error-analysis.md#区分传播与新增偏差)。
+
+### 无 golden 时的边界
+
+缺最终 golden 不等于停止观察。可以依据已确认的计算定义构造独立参考，用可手算小例或另一条可信路径核对；也可使用已验证对照、任务给定的中间值或适用的不变量。不要根据 actual 倒推一个能匹配它的答案；复用 Kernel 中可能出错的索引公式或 helper，也不能算独立验证。
+
+说明参考依据覆盖的性质。例如恒等搬运可检查元素映射和值是否保持，shape、范围或守恒关系只能验证各自性质。不变量通过不能证明完整计算正确，也不能替代数值比较来排除整段代码。依据不适用、数据不可比或采集不完整时保留 `AMBIGUOUS`，继续补对照或选择其他观察。
+
+## 判断观察是否有效
+
+存在插桩本身不表示已经改变原始故障，也不能凭一次结果未变就认定完全无影响。新增同步、改变分片、缓冲布局或计算路径时，说明这些干预及其影响；观察到错误位置、幅度或触发条件变化时，核对插桩与原程序的重复性差异。已有适用对照可复用，需要进一步区分时再按 [DumpTensor 方法](dumptensor.md#数据就绪与插桩影响)比较，影响未确认就保留未知。
+
+已知干预改变了关键执行条件，或对照支持原始故障受其影响时，注明受扰动；边界移动时保留原始基线与本轮观察。只要本轮输入、参考和采集仍支持有效比较，就保留本轮 PASS/FAIL，并说明对未插桩程序的代表性限制；无法建立有效比较时记为 `AMBIGUOUS`。
+
+### 结果状态
+
+- `PASS`：该点本次有效比较按声明的参考依据和规则通过。
+- `FAIL`：该点本次有效比较按相同规则失败，不要求先证明稳定复现。
+- `AMBIGUOUS`：参考依据、采集完整性或比较语义不足，无法判断本次观察；包括扰动破坏比较前提的情况。
+- `UNTESTED`：尚未获得观察证据。
+
+稳定、漂移或偶发描述重复观察，不能覆盖单次有效的 PASS/FAIL。状态只覆盖所比较的性质、数据范围和执行实例；某个切片通过不代表整个张量或所有轮次通过。
+
+保留可获得的最大误差、错误位置、有效元素数和特殊值差异，缺失指标保持未知。状态绑定实际观察文件或报告，不能仅凭日志中出现 checkpoint 名称生成，也不能因为最终输出通过而回填前面的 `PASS`。
+
+## 根据结果继续定位
+
+例如调查 `计算结果 → CopyOut → GM 输出`，选取同一失败切片，核对写回前源数据与写回后的对应目标数据。两处的输入、元素映射和采集时点可比时，按结果推进：
+
+| 有效观察或发现的缺口 | 下一步 |
+| --- | --- |
+| 写回前已偏离可信参考 | 沿该切片的上游输入与计算检查，必要时区分传入偏差和本段新增差异 |
+| 写回前匹配参考，GM 对应位置不匹配 | 核查搬运参数、目标地址、后续覆盖及可见性；这还不能证明 CopyOut API 本身有问题 |
+| 两点不对应同一批逻辑数据，或就绪性不明 | 先修正坐标、轮次或采集时点，暂不据此排除计算区间 |
+| 插桩后原始异常消失或边界移动 | 保留本轮有效结果，核对插桩影响与重复性，不用当前通过覆盖原始失败 |
+
+有观察或源码事实支持具体代码候选时，进入[针对性实验](hypothesis-experiment.md#实验设计)，验证其如何造成原始异常。需要继续缩区时，按[语义二分前提](semantic-bisection.md#前置条件)核对同一依赖链上的可比、稳定端点，`AMBIGUOUS` 点不能充当正常或异常端点；排除更早异常等更强结论另需依据。需要解释误差累积、放大或 `PASS → FAIL → PASS` 时，使用[逐层分析](progressive-error-analysis.md)。首次可见差异、首次超差和根因分别判断，不必为完成二分而继续加点。
+
+## 控制成本
+
+每轮优先增加能改变下一步判断的观察，复用已有输入输出、采集结果和报告。相同位置、相同方式不再提供有效信息时，按缺口更换观察位置、参考方式或采集手段，不堆叠无用 checkpoint。
+
+多轮缩区时，引用已有工程或官方比较报告，按观察点整理结果，保存到[任务产物目录](reporting.md#任务产物目录)。所选比较器决定各点 PASS/FAIL，首次非零误差与首次验收失败分别观察。真实依赖链、跨轮稳定性和插桩影响需单独核对；参与边界判断的点缺少比较依据、采集背景或扰动影响未知时，先补齐前提，不据此进行二分。
+
+取证结束后移除临时插桩；改过执行源码时干净重建并按原入口回放，如实保留结果，偶发问题不要求每次对照都失败。恢复确认只说明临时改动已清理，修复结论仍需对应正式修改和实际验证。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/dumptensor.md

@@ -0,0 +1,83 @@
+# DumpTensor 观察闭环
+
+本章只讨论在 Ascend C Kernel 内主动调用 `AscendC::DumpTensor` 获取 Tensor 值，用于定位计算、搬运和数据依赖问题。**Runtime 自动采集模型或算子输入输出的 Dump 不在本章范围内。**
+
+Kernel DumpTensor 生成的二进制调测数据使用 `show_kernel_debug_data` 解析，详情见 [kernel-debug-data.md](../tools/kernel-debug-data.md)。
+
+## 选择观察路线
+
+| 当前需要 | 最短操作路线 |
+| --- | --- |
+| 先看中间值或异常分布 | 选择少量数据就绪点 → 加入 DumpTensor 并确认编译开关 → 重新构建、运行原输入 → 保存终端输出，按核与轮次对应到逻辑数据 |
+| 保存原始数值并做精度比较 | 完成插桩和构建 → 由工程真实初始化入口启用二进制采集 → 运行并采集到新目录 → 用配套 `show_kernel_debug_data` 解析 → 核对记录身份、dtype 与有效区，再按局部判据比较 |
+
+已有可对应到输入和运行产物的 dump 时，直接从解析与比较继续。有限位数的终端文本适合观察趋势，不能用来恢复原始位模式；逐位比较需要保留二进制。
+
+## 准备
+
+按[检查点设计](checkpoint-design.md#选择位置)选择能改变下一步判断的张量，记录源码位置、语义、dtype、shape、layout、有效区和可用参考。没有可靠局部判据时，可以先采集数值或检查适用的不变量，不自行套用最终输出的阈值判对错。局部参考与精度标准入口见[准备局部对照](checkpoint-design.md#准备局部对照)。
+
+已有失败坐标时，反推实际 `core/row/tile/local offset`，按疑点选择首错位置、相邻正常区域或周期对照，方法见[错误分布与定位](localization.md)。采样范围由有效区和本轮问题决定，不固定只看核 0 或张量开头；尾块与后续循环的问题应观察对应轮次。
+
+保留插桩前源码与原始失败依据，新建的源码快照、采集和解析文件放入[任务产物目录](reporting.md#任务产物目录)。复用工程已有采集方式，准备独立目录和源码快照，保留本轮输入、实际产物与输出的关联。
+
+## 插桩与运行
+
+按当前接口支持的 Tensor 类型、内存位置和数据范围添加少量观察点。每个调用放在对应数据就绪的位置，使用可辨识的标签关联语义位置；观察范围由有效元素决定，展示形状不能代替可访问范围检查。
+
+例如排查 `CopyIn → Compute → CopyOut`，可按疑点观察搬入后的输入、计算后写回前的结果，或写回完成后的对应 GM 数据。不必三处都加；写回前后如何区分，见[根据结果继续定位](checkpoint-design.md#根据结果继续定位)。
+
+按工程原有命令重新构建，确认调试开关已被构建采用、实际运行使用该产物。保存构建与运行命令、日志和退出状态；仅修改环境配置不代表已有二进制随之改变。
+
+比较二进制前，核对有效元素数、原始 dtype 和数据范围，不能把对齐填充计入有效数据。文本展示不完整时，先查采样、容量与解析情况，不直接推定计算只写入了这些元素。当前接口、编译开关和支持条件见本页末尾的[详细说明](#详细说明)。
+
+## 采集
+
+1. 需要二进制时，在任务产物目录下选一个新的或空的 dump 子目录，按[配置与采集](../tools/kernel-debug-data.md#配置与采集)准备配置。这里的配置用于保存 Kernel 主动输出的调测数据，由工程真实的 ACL 初始化或框架入口加载；仅写出 JSON 文件不会启用采集。核对环境变量覆盖后的实际输出目录。
+2. 使用已确认的原始失败命令运行插桩产物，保留原输入与运行输出。终端观察无需为了完成流程另配二进制采集。
+3. 确认文件时间、输入、运行产物与本轮执行相符，而非陈旧结果。
+4. 对 Kernel 调测数据优先使用当前 CANN 配套的 `show_kernel_debug_data`，保留原始文件，将解析结果写入新的解析子目录，按[解析说明](../tools/kernel-debug-data.md)核对路径要求及失败产物。
+
+解析时同时查看退出码、异常文本和实际产物，不能仅凭返回 0 判断成功；完整性检查见[判断解析是否成功](../tools/kernel-debug-data.md#判断解析是否成功)。文件生成或出现 tensor block 本身不证明采集完整，还需核对期望的核、观察点、轮次和有效数据是否齐全。
+
+## 对齐观察记录
+
+将记录对应到本次 Kernel 调用中的具体逻辑数据，再与参考配对。优先复用输出已有的标识，缺少必要信息时补少量逻辑标记，不要求另建固定格式的记录表。
+
+- **观察标签对应语义位置**：标签用于找到输入、计算结果等观察点；同一标签可以重复出现，不应假定后一次覆盖前一次，也不能用标签大小推断数据依赖顺序。
+- **核标识对应执行归属**：调测输出中的核标识与程序的逻辑分片未必直接对应。先保留原始标识，通过已知分片、可辨识输入或少量逻辑编号输出建立对应，不要求把逻辑编号统一编码进标签。
+- **记录次序对应源码轮次**：结合实际调用次数、循环与分支条件，以及 tile 或偏移标记核对调测记录的顺序；多次 Kernel 调用还需区分调用实例。记录次序不自动等于源码的 tile 编号。
+
+例如同一核同一观察点的前两次记录，若该点仅在部分 tile 执行，就不能据此把它们当成 tile 0、1。身份或有效区尚未对齐时，先保留未知，不能把配错的差异判为算子精度问题。
+
+## 数据就绪与插桩影响
+
+每个 dump 点先核对数据就绪关系：哪个 producer 已完成、哪一个 consumer 即将读取、张量的有效区和允许观察的时点。把“代码执行到此处”与“目标数据已就绪”分开；前者不能证明 DMA、异步流水或其他 core 的写入已经对该观察可见。就绪性未确认时，保留采集值作为瞬时状态，不能据此判定该阶段的计算结果正确或错误。
+
+DumpTensor 的部分实现会在复制调测数据前后执行流水同步，如 `PIPE_ALL`，因此可能掩盖原来的同步缺陷；打印值正确不能证明未插桩程序的数据依赖正确。内部同步也不能替代跨核通信协议或正确的缓冲生命周期。DeQue 是队列流程中的一种就绪位置，TBuf 等流程应按自身依赖判断；不要为了打印统一添加 EnQue/DeQue 或额外的 `PIPE_ALL`。需要改变同步来验证候选时，将其作为单独的实验干预解释。
+
+插桩可能改变资源占用、布局、编译优化或时序。需要区分插桩影响与环境漂移时，再采用 `Parent → dump probe → Parent` 对照：Parent 为未插桩版本，使用同一输入与原运行条件，中间只引入计划的 dump 变化；已有适用基线可复用。偶发问题按[复现性方法](reproducibility.md#判断稳定性)比较同条件下的失败率、位置和误差分布，一次 Parent 通过不抹去有效失败，也不能据此断定插桩改变了故障。
+
+插桩改变原问题的关键时序、布局或观察条件时注明受扰动，不要求先取得两侧稳定失败。只要本轮比较仍有效，就保留其 PASS/FAIL 并限制对未插桩版本的推断；比较前提被破坏时才记为 `AMBIGUOUS`。边界变化另记 `BOUNDARY_CHANGED`，归因未明时保留待核实，不能用插桩后的通过覆盖原始失败。
+
+## 观察异常时如何继续
+
+| 现象 | 优先检查与下一步 |
+| --- | --- |
+| 没有预期打印 | 查实际产物、编译宏、调用分支和运行是否完成，再核对类型/位置支持、采样范围与容量；不要先假定 Kernel 未执行 |
+| 有终端值但没有二进制 | 查配置是否经真实入口加载、是否启用 Tensor 数据采集、最终输出目录是否被环境变量覆盖；终端输出本身不证明落盘配置生效 |
+| 有文件但解析报错、为空或缺少部分点 | 查工具与格式是否匹配、异常文本、路径限制及原始采集是否完整；保留已有文件，按配套说明处理，不将部分产物当成完整观察 |
+| 值与参考不同 | 先核对核/轮次、dtype、layout、有效区、局部判据和数据就绪，再沿前后可比点检查计算与传递；全零、NaN、固定偏移等只提供候选，特殊值是否允许由算子与任务语义决定 |
+| 插桩后原问题消失或边界变化 | 保留本轮有效结果，检查同步、资源与时序变化；按需做未插桩对照，不把插桩后的通过当成正式修复 |
+
+同样的观察不再提供新信息时，换位置、参考或采集手段。只有满足[语义二分前提](semantic-bisection.md#前置条件)时才二分，不按固定尝试次数切换。怀疑旧构建时先核对实际加载的产物，按需清理明确属于当前工程的构建内容，不把清空全局缓存作为常规步骤。
+
+## 比较与清理
+
+按[检查点的比较前提与局部判据](checkpoint-design.md#准备局部对照)，将 NPU 观察与选定参考比较；优先复用项目已有比较器，按已确认的局部判据分析。按[结果状态](checkpoint-design.md#结果状态)登记 `PASS`、`FAIL`、`AMBIGUOUS` 或 `UNTESTED`，注明实际覆盖的切片与轮次。不可比较、解析异常和资源截断保留为限制；下一步沿可比观察定位具体代码或数据关系，不能仅凭某个 dump 异常认定根因。
+
+取证结束后移除临时插桩，干净重建并按原入口回放，如实保留恢复后的比较结果；偶发问题本次未失败时注明，不要求为完成清理反复重跑到失败。保留源码恢复与干净回放的实际结果。恢复确认说明临时改动已清理，不表示精度已修复。
+
+## 详细说明
+
+版本变更、接口重载、编译开关及产品限制，请使用 `ascendc-api-knowledge-query` 查询，或查看 [asc-devkit 官方仓库](https://gitcode.com/cann/asc-devkit)。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/hypothesis-experiment.md

@@ -0,0 +1,114 @@
+# 假设与因果实验
+
+本页帮助把源码疑点变成可验证的解释，再根据结果继续定位。已有证据可直接复用；初筛范围与退出条件沿用 [SKILL 阶段 3](../../SKILL.md#阶段-3定位问题与验证根因)。
+
+## 低成本验证
+
+从本轮要解释的错值、位置或触发条件出发，用一句话说明：**哪处实现，在什么条件下，怎样造成这个差异**。候选应有源码或观察依据；暂时说不清时，先按[检查点设计](checkpoint-design.md)补观察，不随机改代码。
+
+按当前缺口选一个检查：
+
+| 当前疑点 | 具体怎么做 |
+| --- | --- |
+| 索引、偏移或搬运范围不对 | 从失败逻辑坐标算出应访问的位置，与代码实际计算的位置、对应输入值核对 |
+| 公式、参数或初始值不对 | 用已有真实输入计算该写法预测的错值或差值，与 actual、golden 对照 |
+| 不确定偏差在哪段产生 | 在可疑段前后选少量可比观察点，核对对应数据；需要观察 Kernel 内部 Tensor 值时，可在对应位置调用 [DumpTensor](dumptensor.md) 输出 |
+| 舍入或算术路径有多种解释 | 按已确认的 dtype 和运算语义建立局部模型，比较候选预测；见[局部算术模型](numerical-modeling.md#局部算术模型) |
+| 已有具体修改能检验机制 | 作局部、可撤销改动，沿原入口回放失败，检查预测涉及的值或位置是否改变 |
+
+优先选能改变下一步判断、准备和执行成本较低的检查，不要求把上表全部做一遍。多个候选都能解释现象时，优先找它们预测不同的输入或观察点；共同前提尚未确认时，检查它也有价值。例如两个计算候选都假定输入正确，发现入口数据已错就应先查上游。只有一个有依据的候选，也可以验证，不必另凑对手。
+
+## 实验设计
+
+需要运行对照或修改代码时：
+
+1. **写清预期变化**：哪个值、错误位置或数据关系应如何变化；没有变化时，要满足哪些前提才能排除候选。诊断输入先核对合法域、入口 dtype 的范围及量化后的值，再按实际计算链推导候选预测；若输入已先溢出或量化抹去了区别，换用仍有区分力的合法输入。只看整例 PASS/FAIL 不够时，补充目标切片的比较。
+2. **保留原比较口径**：沿用实际输入、golden 和验收标准。诊断需要改变输入时，单独记录它与原失败的关系；中间点按[局部判据](checkpoint-design.md#准备局部对照)比较。
+3. **控制主要改动**：优先只改变待验证因素，检查是否连带改变 dtype、分派、tile、核数或布局。无法分离时按组合解释，不假定改一个参数就只影响一个机制。
+4. **执行并核对**：确认改动生效、实际运行采用新产物、输出属于本轮，再比较预测与实际差异。采用存疑时按[复现性方法](reproducibility.md#核对环境与实际产物)检查；源码正则匹配不能替代运行与采用证据。
+
+可辨识输入能帮助追踪数值来自哪个组、槽位或轮次，但来源相同不等于机制相同：读错地址与读取尚未更新的缓冲，都可能得到同一份旧值。先比较候选在所选观察点的预测；预测重叠时，该实验仍可用于缩区，再按缺口观察实际地址、写入来源或就绪关系。全零、常量等输入还可能掩盖漏项、错序或未重置状态，必要时补一个不会掩盖当前候选的合法对照。
+
+## 一个完整例子
+
+以逐元素 `y[i] = x[i] + beta[i]` 为例，以下小整数可精确表示为 float32：
+
+```text
+x      = [ 1,  2,  3,  4]
+beta   = [10, 20, 30, 40]
+golden = [11, 22, 33, 44]
+actual = [11, 22, 13, 24]
+```
+
+发现相关代码使用 `beta[i % 2]`，怀疑后两个元素重复使用了前两个 beta：
+
+1. **先算预测**：若其他项相同，预测偏差为 `beta[i % 2] - beta[i] = [0,0,-20,-20]`，与 `actual - golden` 核对。吻合后再确认本次确实执行了该索引，且 beta 输入与记录一致。
+2. **针对性回放**：确认语义要求 `beta[i]` 后，只修正该索引并运行原失败。预期后两个元素恢复，前两个不变；仍用原比较器判定。
+3. **按结果继续**：变化符合预测时，结合实际路径与源码解释确认该问题；偏差未变时，先查改动采用和实际索引，必要时只观察 beta 读取位置。另一区域仍失败时，保留本处结果，再查剩余异常。
+
+这个例子演示“源码依据 → 错值预测 → 针对性验证”。一般浮点计算还需考虑舍入和局部判据，不能把示例的精确差值规则套到所有算子。
+
+## 解释结果
+
+先看本次观察能否用于比较，再判断它对假设意味着什么：
+
+| 实际结果 | 判断与下一步 |
+| --- | --- |
+| 构建失败、改动未采用、输出陈旧或数据不可比 | 本轮不能支持或排除候选；补齐具体缺口，或改用不依赖它的检查 |
+| 目标差异按预测变化 | 核对实际路径与源码解释；证据足够就确认根因，仍有合理竞争解释则继续区分 |
+| 有效观察与候选的必要预测矛盾 | 确认触发条件和观察范围覆盖该预测后，排除或修正被反证的具体主张；“该机制单独足以解释全部异常”被反证，不等于该机制毫无贡献，也不自动证明另一机制 |
+| 多个候选都预测了当前结果 | 保留能确认的共同范围，去预测不同的位置继续观察，不单独认定其中一个 |
+| 观察相互冲突或不足以判断 | 指出缺的是哪项数据、条件或对照，补最有用的一项，不重复相同尝试 |
+
+局部恢复但整体仍失败，不自动反驳本处解释；整体通过也不自动证明原因唯一。新反证出现时更新旧判断，保留原始失败与本轮结果。
+
+对会改变定位方向、修复或验收的关键判断，检查“观察 → 结论”是否成立；实验计划中的预期分支也这样处理：
+
+1. **核对本分支的前提**：结论依赖的输入、参考、执行路径、干预采用与比较结果，哪些已经确认，哪些只是待执行的条件？把必要条件写在对应分支中，别处列出一个参考或声明“尚未确认”不能代替它。
+2. **检查主要竞争解释**：在同样的已知条件下，另一种机制能否产生相同观察？若能，当前结果只支持它们共有的范围，下一步选择预测不同的输入或中间观察。可用一个合法反例检查“必然、排除、必须采用”等强结论，不要求穷举；暂未找到反例也不是证明。
+3. **给出可执行的下一步**：证据充分就确认；不足时说明具体缺哪项对照、为什么它能区分当前候选。不要只把确定词改成“可能”，也不必把每个普通步骤写成固定表格。
+
+候选模型吻合不能单独证明实现正确；高精度数学差异与是否符合项目规定的 dtype、求值顺序分别判断，参考用途见[局部算术模型](numerical-modeling.md#局部算术模型)。
+
+按局部阈值通过也不能证明输入无差异；需要区分上游传播与本段差异时，使用[逐层分析的独立局部参考](progressive-error-analysis.md#区分传播与新增偏差)。
+
+以下观察适合更新候选，但仍需保留尚未区分的部分：
+
+| 观察 | 可以更新什么 | 下一项有用的核对 |
+| --- | --- | --- |
+| 只改变一种求值顺序后误差不变 | 当前顺序对照未解释差异，或尚无区分力；不能外推所有顺序均无关 | 核对修改生效、各候选的必要预测及实际覆盖范围，再选预测不同的输入或路径 |
+| 只改变一种求值顺序后改善但仍超差 | 支持已试顺序与误差相关，不能据此认定 dtype 主导或排除其它顺序 | 保持原失败输入与受控路径，选预测不同的另一种配对或 dtype 对照；见[改变 dtype 的对照](numerical-modeling.md#改变-dtype-时核对哪些变化) |
+| 升精度后只有部分错误改善 | 支持该改动与现象相关，尚未证明各机制贡献或残差原因 | 取相关实际输入与中间量，区分精度、分派、参与集合等联动 |
+| 误差落在某个理论舍入上界内 | 该观察未反证这个界，仍可能存在满足该界的实现错误 | 核对界的假设和项目参考，不能直接写成“不可消除的精度下限”或“不是 bug”；见[局部算术模型](numerical-modeling.md#局部算术模型) |
+| 误差曲线在某个长度出现台阶 | 提示分组、路由或数值路径变化，尚未区分合法求值与实现问题 | 对照实际分派、参与集合和已确认语义的参考，选择候选预测不同的检查，不由曲线直接定位某类缺陷 |
+| 误差归一化后不再随长度增长 | 输出尺度可以解释原曲线的部分形态，原验收结果仍保留 | 核对项目判据及实际数值路径，不由曲线直接认定阈值错误或实现正确 |
+| 某节点前已有差异 | 更早已有可见差异，本节点是否另增偏差仍未知 | 用同一独立局部参考比较实际与可信输入，不把后续节点直接称为“只是放大点” |
+| 预填哨兵在运行后保留，或被零等值覆盖 | 保留时仍可能有同值写回；被覆盖只证明值发生变化，尚不能认定是谁写的或计算是否完成 | 核对本轮初始化、真实写者、写入范围与完成关系，再查看该写者的输入；不只凭输出值分流计算、搬运或漏写 |
+
+用简短文字记录结果即可。沿用标签时，`NO_DISCRIMINATION` 表示尚未区分候选，`INCONCLUSIVE` 表示因果判断证据不足。标签用于概括本轮观察，不能替代支持或排除候选的具体依据。
+
+## 按需处理复杂情况
+
+- **多项变化联动**：升精度、改 shape/tile 或单核运行，可能同时改变输入表示、计算路径、分片与调度。核对实际变化，按缺口增加局部观察或对照；多处修改一起通过只证明组合效果，不必穷举所有修改组合。
+- **并行或偶发错误**：核对谁写、谁读、何时等待以及缓冲复用和地址所有权。加全流水屏障后恢复，仍需区分这些关系，不能锁定某条同步。按[重复性方法](reproducibility.md#判断稳定性)比较同条件下的失败率、位置和误差，说明样本数；未修改版与干预版的交错对照按需执行。
+- **观察本身改变问题**：按 [DumpTensor 的插桩影响](dumptensor.md#数据就绪与插桩影响)保留本轮有效比较，说明对未插桩版本的限制。局部模型吻合也不单独证明设备指令行为，硬件语义缺口按[最小 NPU 数值探针](numerical-modeling.md#最小-npu-数值探针)处理。
+
+## 剩余或新增错误怎么处理
+
+围绕**剩余或新增错误对应的同一输出、区域或性质**比较，已有可比的原始结果可复用：
+
+| 未修改版本 | 修改后 | 下一步 |
+| --- | --- | --- |
+| 该区域通过，即使别处仍失败 | 该区域失败 | 优先查补丁引入的回归 |
+| 该区域已失败 | 该区域仍失败 | 比较错值和触发条件，判断原机制是否仍能解释；不同机制需要不同处置时再分别定位 |
+| 缺少可比观察 | 出现异常 | 先保留归因未定，补该区域的对照，不自动归咎于补丁 |
+
+位置不重叠不足以认定两个独立问题；尚未证明独立，也不等于已证明同源。同一依赖链上连续 FAIL，仍需用[局部参考](progressive-error-analysis.md#区分传播与新增偏差)区分传播与本段偏差，不能直接合并为纯传播或排除并存问题。保留总体失败和未完成回归，不靠拆分或合并线索提前关闭任务。
+
+## 确认根因与收口
+
+说明**哪处实现、什么触发条件、怎样产生原始异常**，将实际执行路径、源码推导、预测与观察连起来，并核对已有正常对照和反证。证据充分时直接收口；只支持某个区间或时序相关时，按该层级报告。无法运行时可继续源码或已有数据分析，但保留运行验证缺口。
+
+同类检查不再提供新信息时，初筛按阶段 3 转入系统定位，局部验证则补当前范围内能区分原因的观察；后续候选应有新观察或源码事实支持。有执行时限时，按实际准备、构建、运行及恢复成本安排下一步，给必要回归和交付留出时间；到时仍未闭合，就报告最后验证过的状态与未决项。
+
+清理本次仅用于取证的临时改动；改过执行源码时干净重建并按原入口回放，结果如实保留。要保留为正式修复的修改需符合项目要求并完成相关验证，不能仅凭临时绕过后通过。按用户目标进入[主流程](../../SKILL.md#六阶段调试流程)的修复、回归或报告阶段。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/index.md

@@ -0,0 +1,20 @@
+# 诊断方法
+
+阶段 2 复用已理解的实际计算链，按缺口查阅[算子建模](operator-modeling.md)或[计算链敏感点](sensitive-points.md)的相关部分，补齐影响当前判断的信息。本目录同时为[阶段 3](../../SKILL.md#阶段-3定位问题与验证根因)的低成本验证、系统定位和根因确认提供操作方法：结合计算链与 [patterns 中的沉淀经验](../patterns/index.md)做有限初筛，未解决时通过观察点、二分或逐层分析取得新证据。初筛范围与转向条件以 SKILL.md 为准，定位方法按当前缺口选择，已有证据可复用。
+
+| 当前问题 / 何时读 | 方法 | 适用条件与解释边界 |
+| --- | --- | --- |
+| 初筛已有候选，或系统定位后需要验证具体根因 | [假设与因果实验](hypothesis-experiment.md) | 选择有区分力且成本合适的检查；初筛无进展时转向系统定位，局部验证依据新证据展开 |
+| 只知道最终输出错误，想从错误分布、首错坐标或错值缩小范围 | [错误分布与定位](localization.md) | 把错误对应到实际计算和数据流；空间分布或数值吻合不直接证明根因 |
+| 不知道在哪里观察，或中间值缺少可信对照 | [观察点设计](checkpoint-design.md) | 按待区分的问题选择位置与执行实例，准备局部对照，根据有效观察推进到代码检查或实验 |
+| 同一依赖链上已有可比、稳定的正常/异常端点，仍需缩区 | [语义二分](semantic-bisection.md) | 缩出一处判定转变；排除更早异常等更强结论另需依据，缩区不直接确认根因 |
+| 要区分本段新增差异与上游传播，或解释累积、抵消与尺度变化 | [逐层误差分析](progressive-error-analysis.md) | 可在二分前后或局部区间使用；只有一次 PASS→FAIL 也可能涉及上游差异放大 |
+| 需要筛选算术链、dtype 候选，或确认关键设备数值行为 | [数值对照与设备探针](numerical-modeling.md) | 区分验收参考、局部模型与设备观察，按有效对照结果推进代码定位 |
+| 需要观察 Kernel 内部指定 Tensor 的值 | [DumpTensor 观察](dumptensor.md) | 在 Kernel 对应位置主动调用，确认数据就绪并控制插桩扰动；具体接口按目标环境查阅 |
+| 比较规则不清、精确相等含义不明，或测试判定可疑 | [比较与验收](baseline.md) | 确认输出语义、参与比较的元素和实际判据，区分数值相等和逐位一致 |
+| 失败不稳定、重编无变化、环境身份不明或当前未复现 | [复现同一个失败](reproducibility.md) | 现场、输入、产物与真实退出码集中在此核对；未复现不等于修复 |
+| 不清楚输出角色、验收要求或实际计算链 | [算子建模](operator-modeling.md) | 从需求和真实路径建模，按需要核对执行与存储；测试列表不代替需求 |
+| 已画出实际计算链，需要标记容易出错的位置和条件 | [计算链敏感点](sensitive-points.md) | 按当前缺口选择相关通用条目或算子页；标记不等于已确认错误 |
+| 开始定位或修复，需要保留关键事实或整理交付 | [报告指引与模板](reporting.md) | 随关键证据更新，按阶段产物整理结论、流程转向与缺口；末尾保留知识和工具的关键使用摘要，范围服从用户目标 |
+
+需要形成或核对候选原因时，查看[故障模式与案例](../patterns/index.md)并核对适用条件；架构能力与硬件模型使用 `knowledge-query` 查询，具体 Ascend C API 与调用语义使用 `ascendc-api-knowledge-query`，算子和样例使用 `knowledge-query`。CANN 工具与调试 API 的使用入口见[工具选用](../tools/index.md)。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/localization.md

@@ -0,0 +1,85 @@
+# 错误分布与定位
+
+从已有输出差异找到可疑代码或数据关系。先按现象选路线，已有具体候选时直接进入[假设验证](hypothesis-experiment.md)，不要求先缩到最小区域或找齐所有中间边界。
+
+## 目录
+
+- [整理已有错误](#整理已有错误)
+- [按现象选择路线](#按现象选择路线)
+- [解释索引和并行归属](#解释索引和并行归属)
+- [错值反解](#错值反解)
+- [沿数据流收敛](#沿数据流收敛)
+- [范围收敛后的下一步](#范围收敛后的下一步)
+
+## 整理已有错误
+
+复用原比较结果，先看哪个输出、哪些有效元素失配，再看代表位置的 actual、golden、绝对差和特殊值类别。结合完整数组或已有统计，判断错误是局部、周期分布还是覆盖大部分输出。只有部分日志时保留已有信息和覆盖限制；错误阶段、最小触发条件与稳定性未知时仍可继续分析。
+
+比较口径不清时先查 [baseline](baseline.md)。需要补充位置或局部指标时，分析已有输出与参考数据，保留项目 evaluator 的原判定；辅助逐元素失配不自动等价于项目整例失败。
+
+解释错误位置和统计范围时注意：
+
+- 报告中的首个失配位置需按实际比较器的遍历顺序、数组 shape 和 layout 解释，不代表设备执行时间上最早的错误。
+- 报告可能只列出部分异常样本。判断周期或覆盖范围时，应回到完整数组，按适用的逐元素规则统计相应行、通道或区域，不能把少量展示点当成全部错误。
+- 按原有输出语义确定有效区。只有有效元素在实际展开顺序中构成连续前缀时，才能截取前若干元素；与 padding 交错时，按逻辑位置选择有效元素，不能事后排除失败位置。
+
+## 按现象选择路线
+
+| 当前观察 | 先做什么 |
+| --- | --- |
+| 少数位置、某几行或尾部错误 | 将代表坐标映射到实际索引、搬运长度、尾块和有效区，检查对应代码 |
+| 错误呈周期 | 对照实际 stride 单位、行边界、tile/repeat 和分片表达式，选能区分这些解释的位置检查 |
+| 大部分输出有相似偏移、比例或可解释错值 | 用已有输入和计算关系做[错值反解](#错值反解)，不必先按 core、row、tile 逐级收缩 |
+| 固定输入下错误位置或幅度变化 | 按[重复性方法](reproducibility.md#判断稳定性)比较各轮结果，核对生命周期、所有权、同步与运行条件 |
+| 只有最终错误，尚不清楚在哪段产生 | [沿数据流](#沿数据流收敛)选择少量阶段观察，区分上游已错还是本段引入差异 |
+| 零、近零、NaN/Inf 相关差异 | 先按原规则分清类别、绝对差与参与范围，再回到对应坐标和上游操作 |
+
+这些形态只决定下一步检查方向。周期等于某个 tile 长度、全零或误差很大，都不能直接证明根因。零与近零处同时看原值、绝对差和项目判据，不临时给分母加 epsilon 或自设近零阈值改判；NaN/Inf 先比较类别，避免普通误差聚合掩盖差异。
+
+## 解释索引和并行归属
+
+选一个能代表当前疑点的失配位置，按下面的顺序回到代码：
+
+1. **确认坐标含义**：按比较数组的 shape、layout 和有效区解释索引。若比较前做过切片、转置或去 padding，先还原到原张量位置。
+2. **计算实际偏移**：按存储布局求元素偏移和字节偏移，分清 Tensor 起点、维度步长及单位，不把逻辑序号直接当地址。
+3. **确认执行归属**：从本次 Host tiling 和 Kernel 索引表达式求相应阶段的逻辑 block/thread、tile 和循环轮次。Dump 文件的核编号需按[记录配对方法](dumptensor.md#对齐观察记录)对应，不能直接当作逻辑 block。
+4. **代回实现检查**：将位置与偏移代回相关搬运、计算和写回的地址、长度、掩码及分支；有具体疑点就验证，缺状态时再围绕该执行实例观察。
+
+涉及归约等跨元素计算时，还要追踪该输出依赖的完整输入范围，一个输出坐标不代表一个输入元素。
+
+例如逻辑 shape 为 `(4,6)`，按行存储，每行分配 8 个 float32，末尾 2 个是 padding；比较器读取的是包含 padding 的 `(4,8)` 数组：
+
+| 同一失配元素 | 值或计算 |
+| --- | --- |
+| 物理数组坐标 | `[2,2]` |
+| 物理数组扁平索引 | `2 × 8 + 2 = 18` |
+| 紧凑逻辑数组中的序号 | `2 × 6 + 2 = 14` |
+| 相对该数组起点的字节偏移 | `18 × 4 = 72` |
+
+若工程明确每个逻辑 block 处理两行，才可进一步得到 `block = 2 // 2 = 1`；其他分派按实际公式计算。本例应选择每行前 6 列参与比较，不能将物理数组按行展开后直接取前 24 个元素：后者包含前几行 padding，却漏掉最后一行有效元素。
+
+按疑点选择错误点、邻点、周期对应点或正常对照，不要求固定样本角色和数量。筛选已有结果中的一个区域不改变原执行；减小 shape、核数或只运行某个 tile 则属于新的诊断实验，需核对分片、输入依赖与触发条件是否改变。
+
+## 错值反解
+
+计算关系明确时，直接用已有输入输出检验解释，无需先遍历空间或增加设备探针：
+
+1. 从实际可达源码提出少量候选，例如参数错位、漏乘、误写中间量或分支错误。数值相似但不可能到达该输出的候选先排除。
+2. 用同一套解释预测所选输入和位置的错值、差值或错位，与实际结果核对。保留相关 dtype 和运算语义；依赖舍入或逐位结论时才进一步核对位模式。完整短例见[假设验证示例](hypothesis-experiment.md#一个完整例子)。
+3. 若模型曾为匹配 actual 调整过，用未参与拟合的数据或独立观察再区分；已有可信对照可复用，不为每个点拟合不同常量。
+
+多个候选都吻合时，寻找它们预测不同的输入或观察位置。关键 API 行为不明时使用 `ascendc-api-knowledge-query` 核对；输入不可重建或打印丢失精度时保留缺口，不把近似拟合写成已确认事实。不同 dtype 命中不同表达式时，先核对实际分派与共享代码，再判断是否属于不同问题。
+
+## 沿数据流收敛
+
+需要判断偏差在哪段产生或传递时，沿失败输出反查真实计算链：输入和 tiling 参数如何进入 Kernel，经过哪些搬运、计算、同步及写回。选能改变下一步判断的前后观察点，例如计算后写回前的结果与对应 GM 数据，具体按[检查点设计](checkpoint-design.md)准备局部对照。
+
+前段已异常就向其输入与计算回查；前段正常、后段异常时，检查两点之间的计算、地址和数据依赖。比较需对应同一批逻辑数据及适用判据；缺少可信局部依据时可先保留数值或不变量观察，但不能宣称找到了首次计算错误。
+
+同一依赖链上已有可比、稳定的正常/异常端点时，可用[语义二分](semantic-bisection.md)缩出一处当前判据的转变，不据此排除更早异常；需要解释误差累积、抵消或 `PASS → FAIL → PASS` 时，按[逐层分析](progressive-error-analysis.md)调查产生与传播。插桩改变原现象时，按 [DumpTensor 方法](dumptensor.md#数据就绪与插桩影响)解释本轮结果，保留未插桩时的原始证据。
+
+## 范围收敛后的下一步
+
+把已有依据串成“哪个输出或位置异常 → 对应哪段代码或数据关系 → 当前候选及下一项检查”。只报告已核对的范围，内部阶段或归属未知时注明，不强行缩成最小区域或某行代码。
+
+新观察或源码事实支持具体候选时，进入[假设与实验](hypothesis-experiment.md)验证；没有候选或仍无法区分时，按当前缺口补最有用的观察，不重复相同缩区，也不重新开启全算子范围的猜测。定位到某个 tile 或看到数值吻合，都不自动等于确认根因。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/numerical-modeling.md

@@ -0,0 +1,94 @@
+# 数值对照与设备探针
+
+需要区分舍入、结合序、dtype 或设备数值行为等候选原因时使用。围绕原始 NPU 失败，选择局部数值对照或最小设备实验；已有可信输入输出和运行记录可直接复用。
+
+## 选择对照路线
+
+| 对照对象 | 主要用途 | 何时使用 |
+| --- | --- | --- |
+| 项目 reference / golden | 按项目验收标准判断输出是否符合预期 | 确认最终精度结果，或取得语义匹配的阶段参考 |
+| 局部算术模型 | 用 NumPy、PyTorch 或手算等方式模拟相关公式，比较候选对同一输入的预测 | 候选有明确的数值差别，可以利用已有样本降低区分成本 |
+| NPU 实际执行 | 观察目标设备上的失败、关键中间值及修改效果 | 确认实际路径、检验候选预测或验证修复 |
+
+已有局部模型和可信 NPU 失败时，下一轮定位可以这样安排，已确认的条件直接复用：
+
+1. 先核对实际输入、有效区、dtype/layout、执行分支和已确认的舍入点，沿用项目 golden 与原验收口径。确认模型与设备正在比较同一段计算，再解释差异。
+2. 用模型提出可检验的预测；某个模型更接近 actual 只提高候选优先级。优先选择候选预测不同的少量 NPU 中间观察，必要时用未参与拟合的样本区分。
+3. 用设备实际阶段输入送入已确认语义的独立局部参考，区分传入偏差和本段尚未解释的差异；用候选模型重放仍只是检验候选预测，不能据此判本段正确。根据下面的结果解释决定调查本段、回查上游或补可比条件，不从最终误差大小直接跳到根因。
+4. 先用适用文档或已有设备观察回答关键语义；仍无法确定且会影响定位选择时，再考虑最小 NPU 探针。得到支持的解释后回到原始 Kernel、失败输入和原验收口径验证。
+
+缺少 Kernel 内部 Tensor 值时，按[观察点设计](checkpoint-design.md)选点，在对应位置调用 [DumpTensor](dumptensor.md) 输出所需数值；涉及内存、竞争或同步时查[msSanitizer 官方仓库](https://gitcode.com/Ascend/mssanitizer)。具体 Ascend C 接口使用 `ascendc-api-knowledge-query`，实现示例和目标架构能力使用 `knowledge-query` 查询。
+
+## 建立可比条件
+
+参与本次对照的模型与设备执行应复用同一实际输入和属性。尤其核对目标 dtype 量化后的输入值、shape/axis、layout 映射、有效区，以及模型假设是否对应实际执行分支；用同一随机种子重新生成数据不自动保证输入相同。必要的运行身份核对见[复现性方法](reproducibility.md)。
+
+**最终验收**：沿用项目 reference 和比较器，具体见[比较与验收](baseline.md)。局部模型用于解释差异，不替换验收 golden 来消除失败；项目允许高精度参考与低精度实现按容差比较时，不要求两者内部舍入过程相同。
+
+**中间定位**：对齐观察点的公式、输入来源、dtype、量化位置、layout 和有效区，再按[准备局部对照](checkpoint-design.md#准备局部对照)选择参考。高精度整式的最终结果不能直接充当任一低精度中间张量的期望值；累计偏差参考与基于实际阶段输入的局部重放也不能混成同一条正常/异常边界。
+
+构建失败、命令未启动或未采到所需输出，属于执行或观察缺口，不记作数值 PASS/FAIL。比较有效时保留实际判定；参考或采集语义不足时按 checkpoint 方法保留 `AMBIGUOUS`，补对照或继续不依赖该观察的分析。
+
+## 局部算术模型
+
+使用定量误差界前，先区分它是上界还是有依据的不可避免下界，并核对输入、求值顺序和舍入假设。落在正确实现应满足的上界内，不证明实现正确或误差不可消除，漏项等错误也可能在界内。更高精度对照仍有自身的求值和舍入语义，未核实时不称为精确真值，也不自动替代项目参考；据这些量解释候选，不能直接更改验收或排除实现问题。
+
+结合序、clamp、错误中间量或不同舍入点都能解释 actual，且局部模型能降低区分成本时，模拟相关的算术链。按实际竞争解释建立候选即可，不要求每次实现完整的“当前实现、候选修复、oracle”三套模型。
+
+按已确认的中间 dtype、Cast、累加方式与舍入点建模。末尾一次 `astype` 不能代替实际存在的逐步缩窄；也不能机械地在源码每个运算符后加 Cast。例如目标若执行融合乘加，乘法后没有独立舍入步骤，是否发生融合仍需按本次 API、编译或设备证据确认。未知的舍入或求值方式可分别作为候选，NumPy/标准库行为不自动等于设备 API。
+
+入口可表示与算术区分力分别核对：能触发窄类型舍入的输入，改用更宽累加器后，可能在所比较的顺序下都精确。按当前中间 dtype、部分和量级与舍入点计算候选预测，并确认差异在所选观察面仍可见；必要时调整合法输入的大小关系、归约长度或观察位置。只称作“强消减”或“全同号”不能保证当前候选会分叉。
+
+先选能区分候选的少量原失败样本和正常对照，保留输入、实际输出、候选预测及采用的比较方式。问题涉及舍入、精确编码或特殊值时再保留必要位模式，NaN/Inf/subnormal 与边界样本按当前疑点及项目输入范围选取，不要求每次覆盖所有类别。缺 golden 时仍可比较候选预测，但这不构成最终验收。
+
+先用源码数据流排除不可能影响失败输出的候选，再选择预测差异最大的输入或观察点。模型与 actual 吻合只提高候选优先级；根据 actual 调整过的模型，要用未参与拟合的数据或独立观察再区分，不能把同一批拟合结果称为独立证明。参考实现也不应复用可能掩盖错误的 helper。
+
+后续实验应检验事先给出的错值、位置或数值类别预测，并控制相关混杂因素。只有观察有效且能区分竞争解释时，才支持相应机制；仅误差下降、按预测方向变化，或多个候选都预测同样结果时，仍需保留未决解释，具体按[实验结果解释](hypothesis-experiment.md#解释结果)处理。
+
+用设备实际阶段输入重放时，上游传入的偏差已经包含在输入中。按观察的实际含义继续：
+
+| 观察 | 能支持什么、下一步做什么 |
+| --- | --- |
+| 某个候选吻合，其他候选不符 | 支持该候选在当前范围的预测，结合源码和未被排除的解释验证机制；候选模型不是验收 golden，吻合不直接证明本段正确或根因成立 |
+| 所有候选仍有残差 | 先核对参考与采集是否可比，再调查本段计算、实际读取、状态或遗漏的语义；不能直接判为上游根因，也不能只凭残差认定某种设备语义 |
+| 已确认语义的局部参考能解释实际输出 | 这只说明当前局部比较通过；需要判断输入偏差的传播时，还要比较参考对实际输入与可信参考输入的预测，不能仅凭局部吻合宣称误差来自上游 |
+
+具体按[区分传播与新增偏差](progressive-error-analysis.md#区分传播与新增偏差)准备对象。局部重放能解释当前输出、输入偏差也能解释后续现象时，可回查上游差异来源；其他已有上游线索仍可独立核验。
+
+## 最小 NPU 数值探针
+
+目标版本的文档或源码不能回答关键设备行为、与当前观察冲突，或需要确认实际生成代码时，再考虑 NPU 最小探针。能由当前权威资料或已有可信观察回答的问题，直接复用，不重复搭建探针。
+
+围绕一个待确认行为固定相关 API、模式、dtype 和编译条件，使用触发样本及普通对照；调查表示边界时，再加入边界前后相邻的可表示值。检查数值产生、搬运和消费分别发生在哪里，避免把搬运或解析差异归因于算术。需要解释位级行为时保留输入与输出位模式，并确认缩减后的探针实际走到了目标路径。
+
+记录实际芯片、CANN、编译选项、API 模式、输入范围和观察结果；重复性有疑点时按[复现性方法](reproducibility.md#判断稳定性)处理。结果只覆盖实际执行的组合，不能外推其他架构、版本或模式。探针与被检验实现共享同一近似算法时，二者一致不能当作独立正确性证明。
+
+用探针结果修正候选模型后，回到原始失败输入和实际 Kernel 验证。若与适用的官方资料冲突，保留对应文档、设备环境、调用条件和原始观察，先排查路径与解释差异，不直接改写任一方的结论。
+
+## 改变 dtype 时核对哪些变化
+
+“改成 FP32 就通过”可能同时涉及输入量化、中间算术、编译分派和 tiling 变化。这样的观察可以缩小候选，但不能仅凭最终 PASS/FAIL 将原因归为累加精度。按实际改动核对以下层面，复用已有记录即可：
+
+| 层面 | 核对内容 | 存在变化时怎样继续 |
+| --- | --- | --- |
+| 数学目标 | 公式、shape/axis、有效元素、常量和 reference 定义 | 先确认仍在比较同一任务，明确同时改变的算法或参数 |
+| 输入表示 | Host 原始值、各 dtype 量化后的值与 Kernel 入口值 | 区分输入已经变化和同一输入在计算中产生差异 |
+| 实际计算路径 | 模板/重载、API 模式、中间 dtype、已确认的融合与舍入点 | 将实现路径差异列为候选，选择能区分它与输入量化的对照 |
+| tiling 与执行范围 | tile/repeat、核数、尾块、对齐和实际参与集 | 核查分片与参与范围；无法单独控制时保留组合解释 |
+| 输出表示 | 保留项目实际的输出 dtype、Cast 位置及模式，不为内部 dtype 对照新增收窄 | 输出也变了就按组合干预解释，或恢复原输出约定后比较 |
+
+需要单独调查运算中的 dtype 影响时，可选各 dtype 都能精确表示的公共输入，去掉该样本的输入表示差异。比较的是入口解码后的数学值，不要求不同 dtype 具有相同位模式。换一组公共输入通过，只覆盖新样本，不能证明原失败必须有输入量化；公共输入仍超差，也不能直接判实现缺陷，合法的低精度算术仍可能与项目参考超出容差。
+
+调查原失败的输入量化贡献时，保留同一组 Host 原始值和各 dtype 量化、解码后的值，用同一固定语义的参考分别计算两者。逐点核对量化带来的差值与实际差值的方向、位置，并比较 actual 与量化后参考的残差；两项最大误差相近不能说明量化主导。再按残差检查内部算术或路径。表示边界样本按当前疑点保留，两类实验按缺口选择，不用新样本的 PASS/FAIL 代替原失败的因果对照，也不替换项目 golden。
+
+dtype 与求值顺序可能共同作用，不必将二者设为互斥原因。只试一种新归约树，误差改善但仍超差，只说明该顺序对当前样本有影响；不能据此排除其它合法配对、认定 dtype 主导或必须升精度。先按原失败输入计算候选预测，再按缺口选择固定顺序改变 dtype，或固定 dtype 改用预测不同的配对，并核对实际路径；不要求穷举所有树。
+
+输出 Cast 或比较阈值可能遮住内部改善。需要用“没有变化”排除候选时，先核对该候选的必要预测在所选观察面是否可见；没有区分力时，可观察收窄前的部分和或选择预测不同的合法输入，不能仅由最终输出相同反证内部 dtype。
+
+若相关条件已受控，首次差异随明确的 Cast 或累加点变化，可提高该数值路径候选；分派和 tiling 同时变化时，保留实验的有效观察，再选择能区分这些解释的输入或局部检查。只在某 dtype 上拟合 NPU 的局部模型也不是设备机制证明。
+
+## 记录结果与收口
+
+记录比较范围、采用的 reference 或模型假设、关键差异、支持的代码候选及尚未区分的原因，沿用已有输入、产物和运行证据。保存实际执行命令、日志与退出状态，新增模型、采集值与报告保存到[任务产物目录](reporting.md#任务产物目录)，不重复建立台账。
+
+结果应落到实际路径上的代码、数据依赖或仍待确认的局部范围，模型与设备的差异、首次可见分叉都不能直接作为根因。依据观察与源码事实按[假设与实验](hypothesis-experiment.md)验证具体机制；修复任务按[主流程阶段 4—5](../../SKILL.md#六阶段调试流程)回放原始 NPU 失败并做相关回归。正式修复有意改变内部 dtype 或 tiling 时说明影响，保留原外部接口与验收要求。