# External Cannbot Ops Pypto Golden Generate

> 当需要生成 golden 参考实现时使用此 skill。基于算子规格信息，生成纯 PyTorch golden 参考实现 `{op}_golden.py`，导出 `{op}_golden()` 函数，作为精度验证基准。触发词：生成 golden、生成参考实现、写 golden 函数、golden script、golden reference、reference implementation、generate golden、torch 参考、验证基准、baseline implementation、写验证代码、'帮我写 golden'、golden.py、参考代码。

- Skill: `ascend-ai-coding/external-cannbot-ops-pypto-golden-generate` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ascend-ai-coding/external-cannbot-ops-pypto-golden-generate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ascend-ai-coding/external-cannbot-ops-pypto-golden-generate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: UNKNOWN
- Author: ascend-ai-coding (https://skillmd.com/u/ascend-ai-coding)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ascend-ai-coding/external-cannbot-ops-pypto-golden-generate

---


# PyPTO Golden 参考实现生成

基于算子规格信息，自动生成 PyTorch golden 参考实现及完整验证代码。生成的 golden 脚本用于开发阶段快速验证算子实现的正确性，可以作为独立模块被 `test_{op}.py` 等其他脚本导入调用。基于固定模板 [templates/golden-template.py](templates/golden-template.py) 生成（在§9 生成文件结构阶段读取该模板）。纯 torch 实现，禁止引入 pypto。

1. 从用户输入提取算子名称、公式、输入输出规格等必要信息
2. 如果信息不足，向用户逐步提问补充
3. 按工作流执行 golden 函数生成和验证
4. 输出 `{op}_golden.py` 到当前目录或用户指定位置

## 1. 所需信息

| 项目 | 说明 |
|------|------|
| **输入** | 算子规格信息（如结构化规格内容、自然语言描述等） |
| **输出** | `{op}_golden.py`，导出 `{op}_golden()` 函数，路径由调用者决定 |

---

## 2. 算子信息获取

从输入中提取算子名称，或由调用者指定。如果信息不足，向用户逐步提问补充。

---

## 3. 规格字段检查

读取算子规格信息后，按以下分类检查字段完整性：

### 必须字段（缺失则报错退出）

| 字段 | 位置 | 用途 |
|------|------|------|
| 算子名称 | §1 基础信息 | 文件名、函数名 |
| 数学公式 | §1 基础信息 | 生成 PyTorch 实现 |
| 输入规格 | §4 数据规格 | 函数参数、验证 shape |
| 输出规格 | §4 数据规格 | 返回类型、验证 shape |

### 建议字段（缺失时引导补充）

| 字段 | 位置 | 用途 | 缺失时处理 |
|------|------|------|------------|
| 典型配置 | §11 应用场景 | 典型 case 验证 | 引导用户补充到规格信息中 |
| 动态轴范围 | §7 动态轴说明 | 泛化 case 采样 | 使用默认范围 (1-1024) |

### 典型配置缺失时的处理

```
检查规格信息中是否包含典型配置
    │
    ├── 有 → 直接使用
    │
    └── 无 → 引导用户提供
            │
            ├── 用户提供 → 补充到规格信息中，继续生成
            │
            └── 用户跳过 → 根据动态轴范围生成默认配置
                          │
                          ├── 有动态轴范围 → 按范围推荐
                          │   └── 补充到规格信息中，继续生成
                          └── 无动态轴范围 → 使用通用默认值
                              └── 补充到规格信息中，继续生成
```

典型配置采用 7 列格式：

| 配置名称 | 类型 | 优先级 | 参数 | 输入 Shape | 输出 Shape | 说明 |
|----------|------|--------|------|------------|------------|------|

---

## 4. Golden 函数生成规范

### 实现方式

使用 **PyTorch** 实现 golden 函数。优先使用 PyTorch 内置 API，在没有直接对应 API 时由 LLM 基于公式生成实现。

### 函数签名

```python
# 单输入
def silu_golden(x: torch.Tensor) -> torch.Tensor:

# 多输入
def swiglu_golden(x: torch.Tensor, gate: torch.Tensor) -> torch.Tensor:

# 带可选参数
def layer_norm_golden(
    x: torch.Tensor,
    normalized_shape: List[int],
    weight: Optional[torch.Tensor] = None,
    bias: Optional[torch.Tensor] = None,
    eps: float = 1e-5,
) -> torch.Tensor:
```

**规则**：
- 函数名：`{算子名}_golden`
- 参数顺序：必要张量参数在前，可选参数在后
- 所有 spec 中定义的参数都要实现，包括可选参数
- dtype 不作为参数，计算精度跟随输入张量

### 边界条件映射

根据规格信息中的边界条件定义生成对应代码逻辑：

```python
# spec 定义：零值返回 1
def safe_div_golden(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
    result = x / y
    result[y == 0] = 1.0  # 映射边界条件
    return result
```

---

## 5. 置信度系统

根据实现方式评估置信度，影响最终输出的标注和提示强度：

```
1. 是否有等效 PyTorch API？
   ├─ 有 → 直接调用 → ⭐⭐⭐⭐⭐
   │
   └─ 无 → 2. 是否为已知论文算子？
            ├─ 是 → 搜索第三方实现 → ⭐⭐⭐⭐
            │
            └─ 否 → 3. LLM 智能转换
                     ├─ 简单公式转换 → ⭐⭐⭐⭐
                     └─ 复杂公式转换 → ⭐⭐⭐
```

**低置信度加强提示**（⭐⭐⭐ 及以下）：

在输出文件的 docstring 中添加醒目警告，提醒人工审查代码逻辑、与论文对比验证、使用多组数据验证边界情况。

置信度和验证是独立机制——置信度只影响标注和提示强度，验证标准对所有算子一致。自动修复后根据最终代码更新置信度。

---

## 6. 验证机制

### 验证执行方式

生成文件后，**必须通过直接执行脚本完成验证**：

```bash
python3 {op}_golden.py
```

脚本内含 `if __name__ == "__main__": _validate()` 入口，会自动运行全部检查项（典型 case、泛化 case、值域、数值稳定性等）并输出验证报告。

**禁止**使用以下方式替代直接执行：
- `exec(open(...).read())` — 绕过脚本的独立执行环境
- 手动构造测试数据单独调用 golden 函数 — 与脚本内置验证逻辑重复且不完整

**门禁判定依据**：以 `python3 {op}_golden.py` 的 exit code（0 = 通过）和验证报告输出为准。

### 验证 shape 来源

**两层来源**：

```
├── 典型 case（来自算子规格中的典型配置）
│   ├── 性能类型：按优先级验证，P0 必须通过
│   └── 功能类型：按优先级验证，P0 必须通过
│
└── 泛化 case（来自算子规格中的动态轴取值范围）
    └── 每个动态轴采样：最小值、中间值、最大值
        如 b: 1-128 → [1, 64, 128]
           s: 64-2048 → [64, 1024, 2048]
        组合生成 shape
```

### 验证顺序（按重要性）

1. 性能类型 P0 配置（最高优先级，必须通过）
2. 性能类型 P1 配置
3. 功能类型 P0 配置（必须通过）
4. 功能类型 P1 配置
5. 泛化 case（边界+中间采样）
6. 其他低优先级配置

### 验证检查项

| 检查项 | 说明 | 级别 |
|--------|------|------|
| 语法检查 | 代码能正常 import | 🔴 严重 |
| 形状一致性 | 输出 shape 与 spec 定义一致 | 🔴 严重 |
| 函数签名 | 参数与 spec 定义匹配 | 🔴 严重 |
| 值域检查 | 从公式推导值域约束 | 🟡 警告 |
| 特殊点验证 | 边界值、零值等 | 🟡 警告 |
| 数值稳定性 | 无 NaN/Inf | 🟡 警告 |
| 数学属性 | 单调性、对称性、守恒量等 | 🟡 警告 |
| API 对比 | 与 PyTorch API 对比（如适用） | 🟢 信息 |

### 从公式推导的验证属性

**值域约束**：根据公式特性推导输出值域。例如 sigmoid 的输出在 (0, 1)、ReLU 的输出 >= 0、softmax 的输出在 (0, 1) 且沿归约轴和为 1。

**数学属性**：检查奇偶性（tanh 是奇函数）、单调性（sigmoid 单调增）、守恒量（softmax 和为 1）等。

**特殊点验证**：验证关键输入值的输出，如 sigmoid(0) = 0.5、tanh(0) = 0、relu(0) = 0。

---

## 7. 自动修复策略

验证失败时，按优先级自动尝试修复：

1. **使用 PyTorch 稳定 API** — 将手写实现替换为 PyTorch 内置 API
   - `x / (1 + torch.exp(-x))` → `torch.sigmoid(x)`
   - `torch.exp(x) / torch.exp(x).sum()` → `torch.softmax(x, dim=-1)`

2. **添加数值稳定性保护** — 防止除零、log 负数等
   - `a / b` → `a / (b + 1e-8)`
   - `torch.log(x)` → `torch.log(torch.clamp(x, min=1e-8))`

3. **使用更稳定的等价形式** — 数学等价但数值更稳定的替代

**限制**：最多 3 次修复尝试。修复后根据最终代码更新置信度。

---

## 8. 错误分级与输出控制

| 级别 | 含义 | 修复失败后处理 |
|------|------|----------------|
| 🔴 严重 | 语法错误、shape 不匹配、签名错误 | **阻止输出**，报告错误原因 |
| 🟡 警告 | 值域检查失败、数值不稳定 | 输出文件 + 在 docstring 中标注警告 |
| 🟢 通过 | 所有检查通过 | 正常输出 |

---

## 9. 生成文件结构

生成的文件遵循固定模板 [`templates/golden-template.py`](templates/golden-template.py)，在生成时读取模板并将占位符替换为实际算子内容。模板包含以下结构：

- 文件级 docstring（算子名、公式、置信度）
- `{op}_golden()` 函数：纯 PyTorch 参考实现（含示例注释）
- `_validate()` 函数：自动验证（典型 case、泛化 case、值域检查、数值稳定性、API 对比）
- `if __name__ == "__main__": _validate()` 入口

---

## 10. 用户交互

全自动生成与验证，仅在以下场景需要用户参与：

| 场景 | 交互方式 |
|------|----------|
| 生成代码、验证、修复 | 全自动，无需用户参与 |
| 典型配置缺失 | 引导用户提供或确认推荐配置 |
| 覆盖已有文件 | 通过 `AskUserQuestion` 询问确认 |

---

## 11. 异常处理

| 场景 | 处理方式 |
|------|----------|
| 缺少算子规格信息 | 报错退出，提示先补齐需求信息 |
| 规格信息解析失败 | 报错退出，提示输入格式不正确 |
| 规格信息缺少必须字段 | 列出缺失字段，引导用户补充 |
| 多个算子未指定 | 列出所有可用算子，要求用户指定 |
| golden 文件已存在 | 通过 `AskUserQuestion` 询问是否覆盖 |

---

## 12. 验证报告（必须执行）

文件生成完成后，向用户展示验证结果，示例：

```
✅ Golden 参考实现已生成:
  • {name}_golden.py

============================================================
attention_golden 验证报告
============================================================

[典型 case 验证]
  性能_P0: b=2,h=8,s=512,d=64,w=128 ... ✓ PASS
  功能_P0: b=1,h=4,s=256,d=64,w=128 ... ✓ PASS

[泛化 case 验证]
  b=1,h=4,s=128,d=32,w=64 ... ✓ PASS
  b=64,h=8,s=1024,d=64,w=128 ... ✓ PASS

[值域检查]
  检查 softmax 归一化 ... ✓ PASS

[数值稳定性检查]
  大值输入 (x=100) ... ✓ PASS
  小窗口 (w=4) ... ✓ PASS

[功能正确性检查]
  验证窗口边界 ... ✓ PASS

============================================================
✅ 所有验证通过
============================================================
```