Atb Ops To Aclnn Migration Workflow

ATB OPS→ACLNN 迁移标准化工作流

功能概述

定义 ATB 算子从 OPS 接口迁移至 ACLNN 接口的标准化 7 阶段工作流，含 Human in the Loop 用户确认机制。

调用时机

• {xxx}Quant、{xxx}Norm、Softmax 等算子的 OPS→ACLNN 迁移
• 910B/950 设备启用 ACLNN 加速
• 保持对其他设备的兼容性

详细内容

阶段 Gates 概览

[Phase 0] 前置知识学习
    │
    ▼
[Phase 1] 设计文档生成 ────→ [用户确认 Gate 1] ───┐
    │                                         │
    ▼                                         │
[Phase 2] CSV用例设计 ─────→ [用户确认 Gate 2] ───┤
    │                                         │
    ▼                                         ▼
[Phase 3] 实际迁移（TDD） ←───────────────────────┘
    │
    ▼
[Phase 4] 编译验证（≤3次尝试）
    │
    ▼
[Phase 5a] 小范围验证
    ├─ Step 1: 前台跑 _func.csv（正例+反例, ~30s）
    └─ Step 2: 后台 subagent 跑 _perf.csv（性能, ~10min, 不阻塞）
    │
    ▼
[Phase 5b] 全量回归（所有相关 CSV）──→ [Gate 5b: 全量通过] ──┐
    │ （汇合 subagent 性能结果）                               │
    ▼                                                        ▼
[Phase 6] 交付报告 ←──────────────────────────────────────────┘

Phase 0-6 详细说明

详见下方各阶段详细文档。

禁止跳步规则 ⛔

⚠️ 以下规则在每次 Phase 转换时必须强制执行，不可绕过：

Phase 依赖矩阵

每阶段开始时必须执行的检查

1. 确认上一阶段 Gate 状态:
   - Gate X 是否已获用户确认?
   - 确认记录在哪里 (commit message / working_files / 对话记录)?

2. 如果 Gate 未通过:
   - 立即停止
   - 向用户报告: "Phase Y 需要 Gate X 确认，当前 Gate X 状态: 未确认"
   - 等待用户指示

3. 如果 Gate 已通过:
   - 明确告知用户: "Gate X 已通过，进入 Phase Y"
   - 继续执行

常见跳步错误与拦截话术

Agent 启动时的 Phase 状态自检

每次 Agent 被调用执行迁移任务时，必须先执行：

1. git log --oneline -5    → 检查当前分支做了什么
2. ls working_files/        → 检查哪些阶段产物已存在
3. 判断当前处于哪个 Phase  → 报告用户当前状态
4. 确认下一 Phase 的前置 Gate 是否通过 → 按依赖矩阵校验

Skills 调用时序

快速参考

# Phase 0-1: 设计和用例生成
# → atb-aclnn-operator-replacement-designer
# → atb-csv-testcase-generator
# → [等待用户确认 Gate 1 & 2]

# Phase 3: 实际迁移
# → atb-aclnn-operator-migration

# Phase 4: 编译
# → atb-testframework-build
# → [失败] atb-debug-guide

# Phase 5a: 小范围验证
# → atb-csv-tester（不指定 -t，正例/反例默认1次，性能默认400次）
# → [失败] atb-debug-guide
#
# Phase 5b: 全量回归
# → atb-csv-tester (Gate 5)
# → [失败] atb-debug-guide

详细阶段文档

目标

理解算子相关技术背景，为后续设计打下基础。

前置条件

无

输入

• 算子名称（如 {xxx}Quant）
• 任务背景文档（如有）

输出

• 前置知识总结文档（保存至 working_files）

学习内容

检查点

Gate 0

• 类型: 自动通过（无用户确认）
• 条件: 学习文档已生成

目标

生成完整的算子替换详细设计文档（7章结构）。

前置条件

• Phase 0 完成
• ATB/ACLNN 接口文档链接已提供

Skills 调用

atb-aclnn-operator-replacement-designer

检查点

Gate 1: 用户确认 ⭐

⚠️ 强制检查点 - 不可跳过

未收到确认前，禁止进入 Phase 2

目标

设计覆盖正例、反例、性能测试的 CSV 测试用例集，产出两个独立文件。

输出产物

前置条件

• Phase 1 已通过 Gate 1 用户确认

Skills 调用

atb-csv-testcase-generator

检查点

Gate 2: 用户确认 ⭐

⚠️ 强制检查点 - 不可跳过

未收到确认前，禁止进入 Phase 3

目标

实现 ACLNN Runner 并修改 Operation 启用 910B/950 加速。

前置条件

• Phase 2 已通过 Gate 2 用户确认

Skills 调用

atb-aclnn-operator-migration

实现要点

1. 继承 AclnnRunner: 新 runner 必须继承基类
2. 实现四大方法:
   • BuildAclnnVariantPack: 处理输入输出张量
   • SetAclNNWorkspaceExecutor: 配置工作空间
   • LaunchAclnnKernel: 执行计算
   • LoadMethod: 动态加载 ACLNN 函数
3. 设备检测: 使用 GetSingleton<Config>().Is910B() 和 Is950()
4. 向后兼容: 非 910B/950 设备保持 OPS 实现

目标

验证代码编译通过，最多尝试 3 次。

Skills 调用

atb-testframework-build
atb-debug-guide（编译失败时）

编译规则

目标

分两步运行 Phase 2 产出的 CSV：前台快速验证功能，后台 subagent 运行性能测试。

前置条件

• Phase 4 编译通过
• Phase 2 已产出 {op}_func.csv 和 {op}_perf.csv

Step 1: 前台运行功能 CSV

cd <ATB_REPO_PATH>/tests/framework/python/CsvOpsTestTool
python3 atb_csv_ops_test.py -i <CSV_DIR>/{op}_func.csv

• 不指定 -t，默认 1 次，秒级完成
• 必须等待全部通过，有失败则停止排查

Step 2: 后台 Subagent 运行性能 CSV

Agent(
    description="运行 {op} 性能测试",
    prompt="""
逐个运行 {op}_perf.csv 中的性能测试用例，避免 OOM：

cd {ATB_REPO_PATH}/tests/framework/python/CsvOpsTestTool
source {CANN_PATH}/set_env.sh
source {ATB_REPO_PATH}/output/atb/set_env.sh

# 获取性能用例总数
lines=$(tail -n +2 {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv | wc -l)

# 逐个运行每个性能 case
for i in $(seq 1 $lines); do
    echo "=== 运行性能 case $i/$lines ==="
    python3 atb_csv_ops_test.py -i {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv -n $i:$i
done

完成后汇总：通过/失败/耗时。
""",
    subagent_type="general-purpose",
    run_in_background=True
)

关键点：

• 使用 -n N:N 逐个运行，每次只加载 1 个性能 case
• run_in_background=True 后台执行，不阻塞主流程
• subagent 完成后自动通知，结果汇入 Phase 6 交付报告

Skills 调用

atb-csv-tester（双文件 + 前台/后台两种模式）
atb-debug-guide（测试失败时）

完成后操作

Step 1 全部通过后，启动 Step 2 后台 subagent，前台立即继续 Phase 5b 全量回归。

目标

运行所有与目标算子相关的 CSV 文件，确保不引入回归问题。

前置条件

• Phase 5a Step 1（前台功能 CSV）全部通过
• Phase 5a Step 2（后台性能 subagent）可仍在运行中

Skills 调用

atb-csv-tester（Gate 5 全量回归门控模式）

测试范围

枚举并运行所有相关 CSV：

find <ATB_REPO_PATH>/tests/apitest/opstest/csv/ -name '{op_name}*.csv' -type f | sort

Subagent 结果汇合

若后台性能 subagent 尚未完成，等待完成后汇总：

### Phase 5a 后台性能测试结果
| Case | ExecuteTime(us) | precision | 状态 |
|------|----------------|-----------|------|
| case 1 | xxx | 100% | ✅ |
| ...

测试要求

Gate 5b: 全量回归确认

强制检查点 — 不可跳过

## Gate 5b — 全量回归结果

| CSV 文件 | 总用例 | 通过 | 失败 | 状态 |
|---------|--------|------|------|------|
| {op}_test.csv | N | N | 0 | ✅ |
| {op}.csv | M | M | 0 | ✅ |

**全部通过，Gate 5b 满足，可进入 Phase 6 交付。**

阻断时参见 atb-csv-tester Gate 5 阻断话术。

目标

自动聚合 Phase 1/2/5 的输出，生成标准化交付报告。

前置条件

• Phase 5a 测试通过
• Phase 5b 全量回归通过（Gate 5b 确认）

自动聚合流程

交付报告的数据应从前序阶段自动提取，勿手工填写：

自动聚合命令片段

# 统计 CSV 用例数
tail -n +2 {CSV_FILE} | wc -l

# 统计正例/反例/性能
tail -n +2 {CSV_FILE} | grep -c 'NO_ERROR$'
tail -n +2 {CSV_FILE} | grep -c 'Performance'
tail -n +2 {CSV_FILE} | awk -F'|' '{print $21}' | sort | uniq -c | sort -rn

# 代码变更
git diff --stat HEAD~1..HEAD
git log --oneline -5

报告模板

# {Op} OPS→ACLNN 迁移交付报告

> **自动生成时间**: {timestamp}
> **生成方式**: 自动聚合 Phase 1/2/5 输出

## 任务概述
- **算子名称**: {Op}
- **迁移目标**: OPS → ACLNN
- **目标设备**: 910B/950
- **执行日期**: {date}

## 阶段完成情况
| 阶段 | 状态 | 关键输出 |
|------|------|----------|
| Phase 0 前置学习 | ✅ | working_files |
| Phase 1 设计文档 | ✅ | {op}_replacement_design.md |
| Phase 2 CSV用例 | ✅ | {op}_test.csv（{total} 个用例） |
| Phase 3 实际迁移 | ✅ | 代码变更（{files}个文件） |
| Phase 4 编译验证 | ✅ | 第 {N} 次编译通过 |
| Phase 5a 小范围验证 | ✅ | {designed_pass}/{designed_total} 通过 |
| Phase 5b 全量回归 | ✅ | {regression_total} 通过（{csv_count} 个 CSV） |
| Gate 1/2 确认 | ✅ | 用户已确认 |
| Gate 5b 全量回归 | ✅ | 所有 CSV 通过 |

## 测试结果汇总
### Phase 5a: 小范围验证
- 执行 CSV: {op}_test.csv
- 通过: N/N

### Phase 5b: 全量回归
| CSV | 总用例 | 通过 | 失败 |
|-----|--------|------|------|
| {op}_test.csv | N | N | 0 |
| {op}.csv | M | M | 0 |

## 代码变更

{git diff --stat ...}

## 遗留事项
[如有未通过用例或已知问题]

## 附件清单
- 设计文档: {path}
- CSV用例: {path}
- 代码变更: git commit {hash}
- 交付报告: {path}

Gate 6: 最终交付 ⭐

⚠️ 强制检查点

常见问题

禁止跳过 Gate 1 和 Gate 2。如用户未及时响应：

1. 提醒用户确认 pending
2. 24小时后仍未响应，记录风险并暂停任务
3. 不得擅自进入下一阶段

1. 记录完整错误日志到 working_files
2. 使用 atb-debug-guide 分析
3. 向用户提问（苏格拉底式）：
   • 现象描述
   • 已尝试的修复
   • 可能的根本原因假设
   • 需要的支持

相关文档

• 任务提交模板
• ATB Skills 索引