kali20gakki/msAgent / skills/profiler/ascend-fusion-op-replace
ascend-fusion-op-replace
Verified针对昇腾 NPU 上的 PyTorch 模型,识别可做融合算子替换的代码段、替换为 torch_npu 融合算子并做性能/精度验证。当用户提到融合算子、NPU 算子替换、RMSNorm/SwiGLU/RoPE/Attention 融合、torch_npu 亲和算子等关键词是,使用本 Skill。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
| assets/validation_report_template.html | other | 22.9 KB |
| references/common_fusion_ops.md | markdown | 14.1 KB |
| references/fusion_value_assessment.md | markdown | 4.5 KB |
| references/identification_report_format.md | markdown | 2.6 KB |
| references/verification_workflow.md | markdown | 11.9 KB |
| scripts/merge_jsonl.py | script | 3.7 KB |
| scripts/query_torch_npu_api.py | script | 21.4 KB |
references/verification_workflow.md
View on GitHub# 阶段二:验证工作流
本文件是 SKILL.md 阶段二的展开:逐个验证替换的完整流程、逐 step 数据记录、HTML 报告生成和 REPORT_DATA 字段说明。
## 进入条件
只有在用户输入包含**可以实际运行模型的脚本、命令或等价拉起方式**时,才进入完整验证流程。可运行入口至少要能复现 baseline 和替换后任务,通常包括:
- 训练/推理脚本或启动命令。
- 必要参数、配置文件、环境变量。
- 数据集、权重、tokenizer、checkpoint 等路径,或可获取方式。
如果缺少可运行脚本/命令,不要宣称已完成验证;先记录"验证阻塞:缺少可运行模型入口",向用户索要拉起脚本或复现实验命令。此时最多只能做代码审阅、候选替换建议或静态改法。
## 核心原则
- 代码可以一次改完,但**评测必须一个一个来**。
- 每次只验证一个替换,和未修改的 baseline 对比。
- **精度优先**:精度不过直接否决,跳过性能评测。
- 长任务,需要 TaskList + 过程记录,方便中断后续接。
## 验证单个替换的流程
```
改这一个替换的代码
│
▼
跑精度(50+ 迭代,对比 baseline loss)
│
├── loss diff > 1% → 标注「不通过」,结束(不测性能)
│
└── loss diff ≤ 1%(或早期迭代就明显发散,提前结束)
│
└── 看每个 step 耗时是否有稳定下降
│
▼
逐 step 数据写入 JSONL → 生成 HTML 报告 → 给出结论
```
## 精度评测
- 跑 50+ 个迭代。
- 修改前后 loss diff **在 1% 以内**算通过。
- **早停**:如果比较早的迭代就有明显精度 loss 差异,提前结束,没必要跑完浪费时间。
- 精度不满足 → 直接标注不通过,不进性能评测。没收益的替换不值得再花时间。
## 性能评测
看端到端每个 step 耗时是否有稳定下降(不是噪声波动)。端到端耗时有明显下降 = 有收益。
### (可选)所有候选验证完后统一做一次 profiling
当所有候选替换都逐个验证完毕、确认精度和性能都有收益后,可以统一做一次 profiling 采集,目的:
1. **确认算子已替换**:profiling 的 `kernel_details.csv` 里,替换前的小算子序列应消失,替换后的融合算子应出现。
2. **耗时对比**:替换前那段 device 算子序列(原始几个算子的总耗时)vs 替换后融合算子耗时。
3. **调用次数**:融合后调用次数应减少(多次 launch 合并为一次)。
注意,profiling 不要采集太久,1-2个step即可,够看就行。
## 对比口径
- 性能对比的 baseline 是**未做任何替换的原始版本**,不是"上一次替换后的版本"。
- 每个替换都独立对比 baseline,不在一个替换上叠加另一个替换的对比。这样每个替换的收益归因清晰。
- 精度也是每次和 baseline 对比,不累积。
---
## 逐 step 数据记录(JSONL)
验证期间,从训练/推理日志中提取每个 step 的关键指标,写入 JSONL 文件。
### 目录结构
```
fusion_verify/
├── baseline.jsonl # baseline 逐 step 数据
├── rmsnorm.jsonl # 候选 rmsnorm 逐 step 数据
├── rope.jsonl # 候选 rope 逐 step 数据
└── ...
```
### JSONL 行格式
```json
{"step": 0, "loss": 12.598, "step_time": 2.927}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `step` | int | 是 | 迭代序号,从 0 开始 |
| `loss` | float | 是 | 该 step 的训练 loss |
| `step_time` | float | 是 | 该 step 的端到端耗时,**单位秒** |
| `phase` | str | 否 | `wait`/`warmup`/`active`/`tail`,用于区分不同阶段的步耗时特征;日志里有就填 |
### 数据来源
从训练日志中提取 stdout 日志、TensorBoard 事件、或训练脚本输出的 JSON/metrics 文件。不要编造数据;如果日志中没有逐 step 记录,只能记录能拿到的 step,其余标注为缺失。
---
## HTML 报告生成(模板填充)
每个候选验证完(精度通过或失败)后,**复制模板、替换 REPORT_DATA** 生成 HTML 报告。不通过脚本生成 HTML。
### 步骤
1. **合并 JSONL**:
```bash
python3 scripts/merge_jsonl.py fusion_verify/baseline.jsonl fusion_verify/rmsnorm.jsonl
# stdout → metrics JSON 数组,直接粘贴进模板
# stderr → thresholds(max_rel_diff、first_fail_step)
```
2. **复制模板**到工作目录,命名为 `validation_<candidate>.html`:
```bash
cp assets/validation_report_template.html validation_rmsnorm.html
```
3. **替换 REPORT_DATA**:把模板里的 `const REPORT_DATA = {...}` 整块替换为真实数据。需要填的字段:
```javascript
const REPORT_DATA = {
basic_info: {
task_name: "DeepSeek V4 Tiny Train", // 模型/任务名
candidate_name: "RMSNorm -> npu_rms_norm", // 候选名
report_title: "", // 可选:覆盖自动生成的 HTML 标题
baseline_status: "Completed", // baseline 运行状态
fused_status: "Completed", // fused 运行状态
final_conclusion: "Pass", // Pass / Fail / Skip / Blocked
work_dir: "/path/to/work", // 工作目录
hardware: "Ascend NPU (Atlas A2)", // 硬件
world_size: 8, // world size
rank_count: 8 // rank 数
},
commands: {
baseline_cmd: "torchrun ... train.py", // 真实执行的 baseline 命令
fused_cmd: "torchrun ... train.py --use_fused_rmsnorm", // 真实执行的 fused 命令
script_path: "tmp/run_train.py", // 启动脚本
data_path: "/data/corpus", // 数据路径
ckpt_path: "/checkpoints/baseline" // checkpoint 路径
},
diffs: [
{
file_path: "src/model.py", // 修改的文件
hunks: [
{
old_line: 50, // 原始起始行号
new_line: 50, // 修改后起始行号
old_code: "...", // 修改前代码(来自 git diff / 文件快照)
new_code: "..." // 修改后代码
}
]
}
],
metrics: [ // ← 从 merge_jsonl.py 输出粘贴
{ step: 0, phase: "wait", base_loss: 12.59, fused_loss: 12.59, base_time: 2.92, fused_time: 2.74 },
// ...
],
thresholds: {
max_rel_diff: 0.01, // 精度阈值(小数,0.01 = 1%)
first_fail_step: null // 首次偏差 step,精度通过则 null(从 merge_jsonl.py stderr 获取)
}
};
```
> **命令必须来自实际执行记录**(shell history、日志头部、启动脚本),不能凭空编造。代码修改前后内容必须来自实际文件、git diff 或保存的快照。
4. **保存**,用浏览器打开查看。
模板使用 ECharts(CDN),内置完整的渲染和交互逻辑:
- Loss / Step time 双曲线对比(hover 显示 abs diff / rel diff / speedup)
- 对数/线性坐标切换
- 精度失败时 markPoint 标注首次偏差 step,性能区域显示遮罩"性能验证跳过:精度未通过"
- 逐 step 表格(搜索、hover 联动图表、dataZoom 缩放)
> 模板使用 ECharts(CDN: `cdn.jsdelivr.net`),查看报告的机器需能访问该 CDN。
---
## REPORT_DATA 字段说明
### basic_info(基本信息)
| 字段 | 类型 | 说明 |
|------|------|------|
| `task_name` | string | 模型或任务名称 |
| `candidate_name` | string | 候选替换名称 |
| `report_title` | string | 可选。非空时覆盖标题;为空时 HTML 自动生成“模型/任务名 \| 候选替换名称 \| 算子融合替换验证报告” |
| `baseline_status` | string | baseline 运行状态(Completed / 未运行) |
| `fused_status` | string | fused 运行状态 |
| `final_conclusion` | string | `Pass` / `Fail` / `Skip` / `Blocked`(决定 badge 颜色和性能遮罩是否触发) |
| `work_dir` | string | 工作目录 |
| `hardware` | string | 硬件信息 |
| `world_size` | int | world size |
| `rank_count` | int | rank 数 |
### commands(运行命令)
| 字段 | 类型 | 说明 |
|------|------|------|
| `baseline_cmd` | string | **真实执行的** baseline 命令 |
| `fused_cmd` | string | **真实执行的** fused 命令 |
| `script_path` | string | 启动脚本路径 |
| `data_path` | string | 数据路径 |
| `ckpt_path` | string | checkpoint 路径 |
> 命令必须来自实际执行记录,不能编造。没有真实命令时填 `"信息缺失"`。
### diffs(代码修改对比)
数组,每个元素代表一个文件的修改:
| 字段 | 类型 | 说明 |
|------|------|------|
| `file_path` | string | 文件路径 |
| `hunks` | array | 修改块列表 |
每个 hunk:
| 字段 | 类型 | 说明 |
|------|------|------|
| `old_line` | int | 原始代码起始行号 |
| `new_line` | int | 修改后代码起始行号 |
| `old_code` | string | 修改前代码原文(`\n` 分隔多行) |
| `new_code` | string | 修改后代码原文 |
> 代码内容必须来自实际 git diff / 文件快照,不能用伪代码代替。
### metrics(逐 step 数据)
数组,每条对应一个 step。用 `scripts/merge_jsonl.py` 从 JSONL 合并得到:
| 字段 | 类型 | 说明 |
|------|------|------|
| `step` | int | 迭代序号 |
| `phase` | string | 可选。`wait`/`warmup`/`active`/`tail`;缺失时表格显示空 |
| `base_loss` | float | baseline 该 step 的 loss |
| `fused_loss` | float | fused 该 step 的 loss |
| `base_time` | float | baseline 该 step 耗时(秒) |
| `fused_time` | float | fused 该 step 耗时(秒) |
> 以下字段由模板 JS 自动计算,agent 不需要填:`abs_diff`、`rel_diff`、`time_delta`、`speedup`、`is_precision_fail`。
### thresholds(精度阈值)
| 字段 | 类型 | 说明 |
|------|------|------|
| `max_rel_diff` | float | 精度阈值(小数,0.01 = 1%) |
| `first_fail_step` | int / null | 首次明显偏差 step;精度通过则 `null` |
> 从 `merge_jsonl.py` 的 stderr 输出获取。
---
## 数据真实性要求
- **metrics**:必须来自 `merge_jsonl.py` 合并的 JSONL 数据,不能用模拟数据。
- **commands**:必须来自实际执行记录,不能编造。
- **diffs**:必须来自实际文件/git diff,不能用伪代码。
- 如果某些数据缺失,在对应字段填 `"信息缺失"` 或空值,不要用假数据填充。
---
## 长任务过程记录
阶段二是长耗时过程,需要重复拉起任务。必须有:
- **TaskList**:跟踪每个候选替换的验证状态(待测 / 精度验证中 / 精度不通过 / 性能验证中 / 已结论)。
- **结论记录**:每个替换的最终结论(是否替换、是否有收益、收益量级、失败原因)写进本地 markdown,方便中断后续接和最终汇总。
示例记录格式:
```markdown
## 替换验证记录
### 候选 1:RMSNorm → npu_rms_norm
- 状态:✅ 通过
- 精度:50 迭代 loss diff 0.3%,通过
- 性能:step 耗时降 8%,profiling 确认算子已替换,调用次数不变
- 结论:替换,有收益
- 报告:validation_rmsnorm.html
### 候选 2:Attention → npu_fusion_attention
- 状态:❌ 精度不通过
- 精度:第 5 迭代 loss diff 12%,早停
- 原因:causal mask 构建有误(排查中)
- 结论:暂不替换,修复 mask 后重测
- 报告:精度失败,性能跳过
```
## 何时全部结束
- 所有候选替换都验证完,或
- 用户决定停在某几个替换上,或
- 剩余替换预期收益太低不值得继续测。
最终汇总一份"该换哪些、不该换哪些、收益多少"的结论清单给用户。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |