| 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。
- 从用户输入提取算子名称、公式、输入输出规格等必要信息
- 如果信息不足，向用户逐步提问补充
- 按工作流执行 golden 函数生成和验证
- 输出
{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 不作为参数，计算精度跟随输入张量
边界条件映射
根据规格信息中的边界条件定义生成对应代码逻辑：
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
验证顺序（按重要性）
- 性能类型 P0 配置（最高优先级，必须通过）
- 性能类型 P1 配置
- 功能类型 P0 配置（必须通过）
- 功能类型 P1 配置
- 泛化 case（边界+中间采样）
- 其他低优先级配置
验证检查项
| 检查项 | 说明 | 级别 |
|---|
| 语法检查 | 代码能正常 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. 自动修复策略
验证失败时，按优先级自动尝试修复：
-
使用 PyTorch 稳定 API — 将手写实现替换为 PyTorch 内置 API
x / (1 + torch.exp(-x)) → torch.sigmoid(x)torch.exp(x) / torch.exp(x).sum() → torch.softmax(x, dim=-1)
-
添加数值稳定性保护 — 防止除零、log 负数等
a / b → a / (b + 1e-8)torch.log(x) → torch.log(torch.clamp(x, min=1e-8))
-
使用更稳定的等价形式 — 数学等价但数值更稳定的替代
限制：最多 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
============================================================
✅ 所有验证通过
============================================================
