SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsexternal-gitcode-ascend-atb-aclnn-operator-replacement-designer

external-gitcode-ascend-atb-aclnn-operator-replacement-designer

Coding & development

View repository

Updated 10-15 17:19

About this skill

ATB to ACLNN Operator Replacement Detailed Design Document Generator

Function Overview

This tool can automatically generate a complete operator replacement detailed design document based on the ATB and ACLNN interface document links provided by the user. It supports multiple operator types and provides a standardized document structure and content.

When to Invoke

Invoke this skill in the following situations:

  • The user needs to replace an ATB operator with an ACLNN operator and write a design document
  • The user already has ATB operator interface and ACLNN interface document links
  • The change involves standard operators such as LayerNorm, Softmax, RmsNorm, etc.

Scale Detection and Classification

When invoking this skill, scale detection must be performed first to determine whether to use the full template or the lightweight template.

Detection Steps

# 在 ATB 仓库中搜索目标算子的 ACLNN Runner 是否已存在
find <ATB_REPO_PATH>/src/ops/ops_infer/<op_type>/ -name '*_aclnn_runner.cpp' -type f 2>/dev/null
find <ATB_REPO_PATH>/src/ops/ops_infer/<op_type>/ -name '*_aclnn_runner.h' -type f 2>/dev/null

Classification Criteria

Scenario Judgment Condition Template Level Description
Existing Runner integration *_aclnn_runner.cpp already exists and is registered REG_RUNNER_TYPE Lightweight template (4 sections) Only requires parameter mapping + constraints + risks
Brand-new migration *_aclnn_runner.cpp does not exist Full template (7 chapters) Requires a complete design document

Standard phrasing for reporting detection results to the user

## 规模检测结果

算子: {OpType}
ATB 仓库: <ATB_REPO_PATH>

检测: {op_type}_aclnn_runner.{h,cpp} [✅ 已存在 / 不存在]

→ 使用 [轻量模板 / 完整模板] 生成设计文档。
→ 预计生成 [4 节 / 7 章] 文档。

Lightweight Template (Existing Runner Mode)

When an ACLNN Runner already exists (for example, when only the Operation's CreateRunner needs to be modified to mount an existing runner), generate the following simplified document:

# {OpType} OPS→ACLNN 替换设计文档（轻量版）

## 文档信息
| 项目 | 内容 |
|------|------|
| 算子名称 | {OpType} |
| 迁移类型 | 挂载已有 ACLNN Runner（{op}_aclnn_runner.cpp 已存在） |
| 变更范围 | 仅修改 {op}_operation.cpp 的 CreateRunner，添加 910B/950 设备检测 |
| 目标设备 | 910B / 950 |

## 需求简述
- 将 {OpType} 算子在 910B/950 上从 OPS 切换至 ACLNN
- 非 910B/950 设备保持 OPS 路径
- ACLNN Runner 已存在且通过 REG_RUNNER_TYPE 注册，仅需接入分发

## 参数映射关系
| ATB参数 | ACLNN参数 | 映射类型 | 说明 |
|---------|-----------|----------|------|
| [从已有 runner 代码提取] | [从已有 runner 代码提取] | [直接/计算] | |

## 规格约束
- 数据类型: [从已有 runner 和接口文档提取]
- 输入约束: [提取]
- 参数约束: [提取]
- 设备相关: 950 上仅支持 {受支持的变体}

## 风险评估
| 风险项 | 风险等级 | 应对策略 |
|--------|---------|---------|
| 设备检测逻辑错误 | 低 | 参考已有 runner (Gather/Split/Repeat) 的分发模式 |
| 变体路由错误 | 中 | 在 CreateRunner 中加严格的 layerType/quantType 过滤 |
| 非目标设备回归 | 低 | 非 910B/950 设备保持 OPS 路径不变 |

Lightweight template generation rules:

  1. Keep only 4 sections: Document Information + Requirement Summary + Parameter Mapping + Constraints + Risks
  2. Skip the full version's Requirement Details, Specification Description (DFX), Development Self-Testing, Implementation Plan, and Conclusion sections
  3. The document is still saved to {WORKING_DIR}/{op_type}_replacement_design.md, marked as the lightweight version

Lightweight Version Confirmation Checklist

The lightweight version uses a simplified 3-item confirmation table:

## 设计文档确认 - {OpType}（轻量版）

| 检查项 | 说明 | 用户确认 |
|--------|------|----------|
| 参数映射关系正确 | ATB→ACLNN 映射准确 | [ ] |
| 规格约束清晰 | 数据类型、参数约束完整 | [ ] |
| 风险评估完整 | 风险项和应对策略充分 | [ ] |

⚠️ Path Constraints (Must Be Enforced)

Before executing this skill,the following paths must be obtained from the user：

  • <CANN_PATH>: CANN installation path (e.g., /usr/local/Ascend/ascend-toolkit/latest）
  • <ATB_REPO_PATH>: ATB repository path (e.g., {your working path}ascend-transformer-boost）

If the user does not provide them or the paths are invalid, stop immediately and report an error.

Script validation example:

if [ -z "$CANN_PATH" ] || [ ! -f "$CANN_PATH/set_env.sh" ]; then
    echo "ERROR: CANN_PATH 未设置或无效，请用户提供。"
    exit 1
fi
if [ -z "$ATB_REPO_PATH" ] || [ ! -d "$ATB_REPO_PATH" ]; then
    echo "ERROR: ATB_REPO_PATH 未设置或无效，请用户提供。"
    exit 1
fi

Prerequisites

  • ATB operator interface document link (to be provided by the user)
  • ACLNN operator interface document link (to be provided by the user)
  • (Optional) Operator type name (e.g., LayerNorm)

WebFetch Failure Blocking Rule ⛔

⚠️ Mandatory rule — cannot be bypassed by inferring from code

WebFetch is the means of obtaining interface documents. The following rules cover all scenarios:

Scenario Behavior
Both WebFetch URLs succeed Continue analysis
Either WebFetch URL fails Stop immediately and interrupt the user
WebFetch returns 404/403/timeout Stop immediately, interrupt the user
ACLNN Runner already exists in the code repository Documentation success is still required — code cannot replace official documentation

Standard script for interrupting the user：

## ⛔ WebFetch 失败 — 需要接口文档

获取以下接口文档失败：
- [URL] → [失败原因]

**请提供以下任一形式**：
1. 可直接访问的文档 URL
2. ACLNN 开源仓中对应算子的接口头文件路径/内容
3. CANN 安装目录下的接口文档（如 `$ASCEND_TOOLKIT_HOME/opp/*/op_proto/` 下的算子定义）
4. 手动提供的完整参数列表（类型、含义、约束）

在没有完整接口文档前，禁止进入设计阶段。

Prohibited actions：

  • ❌ From *_aclnn_runner.cpp code, reverse-infer interface parameters
  • ❌ From infer_op_params.h structs, infer ACLNN constraints
  • ❌ Skip documentation acquisition on the grounds that "the code repository already has an implementation"

Workflow overview

规模检测（是否存在 *_aclnn_runner.cpp）→ 接口文档分析 → 参数映射建立 → 按模板等级生成文档

Checkpoint system: After each stage is completed, please refer to the execution results section's checkpoint table to confirm the status.

Input requirements

The user needs to provide the following information:

  1. ATB operator interface documentation link
  2. ACLNN operator interface documentation link
  3. Optional: operator type (such as LayerNorm, Softmax, RmsNorm, etc.)

Core functions

Automatically analyze interface documentation

  • Parse the parameter structure of the ATB operator
  • Parse the interface definition of the ACLNN operator
  • Extract key parameters and constraints

Generate standardized document structure

  • Requirement details
  • Operator IR and parameter configuration
  • Specification description (DFX, specification constraints, functional conflicts)
  • Development self-testing (functional testing, negative testing, performance testing)
  • Implementation plan
  • Risk assessment and response strategies
  • Conclusion

Intelligent parameter mapping

  • Automatically establish the mapping relationship between ATB and ACLNN parameters
  • Identify parameter differences and conversion rules
  • Handle the adaptation logic of special parameters

Stage 1: Interface documentation analysis

ATB operator analysis

  • Extract the operator parameter structure from the ATB interface documentation
  • Identify core parameters (such as epsilon, axis, quantType, etc.)
  • Determine parameter constraints

ACLNN operator analysis

  • Extract the interface definition from the ACLNN interface documentation
  • Identify input and output parameters
  • Determine the interface invocation method

Stage 2: Parameter mapping establishment

Mapping type Handling method
Direct mapping The parameter names and meanings are completely identical, direct mapping
Computed mapping Convert according to formulas or rules (such as beginNormAxis → normalizedShape)
Deprecated parameters Identify parameters that are no longer needed and explain them
New parameters Identify new parameters and explain their default values or calculation methods

Stage 3: Document content generation

Requirement details

## 需求详情

### 项目背景
为了兼容性和性能提升，需要将ATB中的{算子类型}算子替换为ACLNN算子。

### 需求目标
- 将ATB中的{算子类型}算子替换为对应的ACLNN算子
- 保持原有接口的兼容性，确保上层应用无需修改代码即可迁移
- 提升算子执行性能，充分利用昇腾硬件加速能力
- 确保替换后的算子功能正确性和稳定性

### 适用范围
本设计适用于ATB仓中的算子：
- {算子类型}算子

Operator IR and parameter configuration

## 算子IR与参数配置

### ATB算子参数结构
```cpp
struct {OpType}Param {
    // 从文档中提取的参数结构
};

ACLNN operator interface

// 从文档中提取的ACLNN接口

Parameter mapping relationship

ATB parameter ACLNN parameter Mapping relationship
param1 param1 Direct mapping
param2 param2 Computed mapping
param3 - Deprecated parameters 
</details>

## 参考实现

### softmax_aclnn_runner 参考

softmax_aclnn_runner是一个已实现的ACLNN runner示例，可作为参考。详细实现请参考 `references/softmax_aclnn_runner_reference.md` 文件，其中包含完整的头文件和源文件实现。

### 实现模式

所有ACLNN runner实现应遵循以下模式：

1. **继承自AclnnRunner基类**
2. **实现核心方法**：
   - `BuildAclnnVariantPack`：构建ACLNN变体包，处理输入输出张量
   - `SetAclNNWorkspaceExecutor`：设置ACLNN工作空间和执行器
   - `LaunchAclnnKernel`：启动ACLNN内核执行计算
   - `LoadMethod`：加载ACLNN函数指针
3. **注册Runner类型**：使用 `REG_RUNNER_TYPE` 宏注册Runner

### 代码结构

src/ops/ops_infer/{op_type}/{op_type}_aclnn_runner.h/cpp


其中 `{op_type}` 为算子类型，如 `softmax`、`layernorm` 等。

## 最佳实践

1. **接口文档分析**：仔细阅读ATB和ACLNN接口文档，确保准确理解参数含义和约束条件
2. **参数映射**：建立清晰的参数映射关系，特别注意计算映射和特殊参数的处理
3. **测试用例设计**：设计全面的测试用例，覆盖正常、异常和性能场景
4. **风险评估**：充分考虑可能的风险并制定应对策略
5. **代码结构**：遵循现有ACLNN runner的实现模式，保持代码一致性
6. **working_files 集成**：设计文档必须保存至 `working_files` 目录，便于用户确认和后续追溯

## Human in the Loop: 用户确认检查点 ⭐

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

设计文档生成完成后，必须等待用户确认后方可进入下一阶段。

### 确认前准备
1. **保存文档**: 将生成的设计文档保存至 `working_files` 目录
   - **文件路径**: `{WORKING_DIR}/{op_type}_replacement_design.md`
   - **变量说明**:
     - `WORKING_DIR`: 由用户指定的 working_files 目录
     - `op_type`: 算子类型小写（如 `swigluquant`, `layernorm`）

2. **准备确认清单**: 供用户逐项确认

### 用户确认检查表

```markdown
## 设计文档确认 - {OpType}

### 待确认文档
- **设计文档路径**: `{WORKING_DIR}/{op_type}_replacement_design.md`
- **ATB 接口链接**: [用户提供的链接]
- **ACLNN 接口链接**: [用户提供的链接]

### 确认检查表
| 检查项 | 说明 | 用户确认 |
|--------|------|----------|
| 参数映射关系正确 | 第 2.3 节参数映射表准确反映了 ATB→ACLNN 的映射关系 | [ ] |
| 风险评估合理 | 第 6 章识别的风险项和应对策略完整 | [ ] |
| 实现方案可行 | 第 5 章实现方案符合 ATB ACLNN Runner 标准模式 | [ ] |
| 测试用例设计可行 | 第 4 章测试用例覆盖全面，可进入 CSV 设计阶段 | [ ] |
| 规格约束清晰 | 第 3 章规格约束明确，便于编写反例测试 | [ ] |

### 确认方式
- **通过**: 回复 "确认通过" 或逐项打勾确认
- **修改**: 指出具体问题，返回修改后重新确认

### 后续步骤
确认通过后，将进入 Phase 2: CSV 用例设计阶段
- 下一步调用: `atb-csv-testcase-generator`

**⚠️ 未收到用户确认前，禁止进入 CSV 用例设计阶段**

Presentation method to the user

我已生成 {OpType} 算子的替换设计文档，请确认以下内容：

📄 **文档位置**: `{WORKING_DIR}/{op_type}_replacement_design.md`

请检查：
1. 第 2.3 节"参数映射关系"是否正确？
2. 第 6 章"风险评估"是否遗漏重要风险？
3. 第 5 章"实现方案"是否符合预期？
4. 第 4 章"开发自测"是否覆盖全面？

回复 "确认通过" 进入 CSV 用例设计阶段，或指出需要修改的地方。

Tool integration

This skill can be used in conjunction with the following tools:

  • WebFetch: Automatically obtain and parse interface documentation content
  • Read：Read existing code files to understand implementation patterns
  • Write：Generate a design document and save it to working_files
  • Edit：Adjust the document content as needed

By using this skill, users can quickly generate high-quality ATB to ACLNN operator replacement design documents, improving development efficiency and document quality.

Execution Results

⚠️ Fill in after execution：After the skill execution is complete, fill in the actual execution results according to the format below.

Checkpoint Checklist

Step Checkpoint Description Status
- ATB API URL has been provided ✅ PASS / ❌ FAIL / ⏭️ SKIP
- ACLNN API URL has been provided ✅ PASS / ❌ FAIL / ⏭️ SKIP
1 ATB operator parameters have been extracted ✅ PASS / ❌ FAIL / ⏭️ SKIP
1 ACLNN API parameters have been extracted ✅ PASS / ❌ FAIL / ⏭️ SKIP
2 Parameter mapping table has been created ✅ PASS / ❌ FAIL / ⏭️ SKIP
2 At least one computation mapping has been defined ✅ PASS / ❌ FAIL / ⏭️ SKIP
3 The 7 sections of the design document are complete ✅ PASS / ❌ FAIL / ⏭️ SKIP
3 The risk assessment table exists ✅ PASS / ❌ FAIL / ⏭️ SKIP
4 The AclnnRunner subclass pattern has been recorded ✅ PASS / ❌ FAIL / ⏭️ SKIP
4 The implementation code structure has been defined ✅ PASS / ❌ FAIL / ⏭️ SKIP
HIL The design document has been saved to working_files ✅ PASS / ❌ FAIL / ⏭️ SKIP
HIL The user has confirmed the design document ⭐ ⬜ Pending confirmation

VERDICT: ✅ SUCCESS / ⚠️ PARTIAL / ❌ FAILED / ⏭️ SKIPPED

Issue List (if any)

Severity Checkpoint Issue Description Suggestion
🔴 CRITICAL - - -
🟡 WARNING - - -

Execution Summary

  • Execution Time：
  • Operator Type：
  • ATB API Link：
  • ACLNN API Link：
  • Pass Rate：