external-cannbot-ops-pypto-golden-generate

name	external-cannbot-ops-pypto-golden-generate
description	当需要生成 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、参考代码。
original-name	pypto-golden-generate
synced-from	https://gitcode.com/cann/cannbot-skills
synced-date	2026-05-26
synced-commit	ac5bbd2b4cf427d011874e11f8d1e8b1bef66eda
license	UNKNOWN

PyPTO Golden 参考实现生成

基于算子规格信息，自动生成 PyTorch golden 参考实现及完整验证代码。生成的 golden 脚本用于开发阶段快速验证算子实现的正确性，可以作为独立模块被 test_{op}.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 基于公式生成实现。

函数签名

# 单输入
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 不作为参数，计算精度跟随输入张量

边界条件映射

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

# 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. 验证机制

验证执行方式

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

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，在生成时读取模板并将占位符替换为实际算子内容。模板包含以下结构：

• 文件级 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

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