CANN算子规范生成器使用场景

应用场景【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills本文描述从 REQUIREMENTS.md 出发的完整操作步骤 包括 spec 生成场景二和 spec 独立评审场景五。场景二从 REQUIREMENTS.md 生成 spec.yaml强制规则ID规则S1必须使用scripts/generate_spec.py生成骨架禁止手写 spec.yamlS2生成完成后必须跑scripts/validate_spec.py spec.yaml9-stage 校验全 PASSstage 9 SKIP 视为通过S3建议scripts/compute_spec_hash.py工具链尚未交付v1 不要求锁 spec_hash待工具与 schema 字段就绪后启用S4字段值必须与 REQUIREMENTS.md 一致——dtype / shape 约束 / 平台限制 / 容差由 REQUIREMENTS 推导不允许凭空添加S5numerical_stability.techniques.anti_pattern_id 引用必须在registries/anti_pattern_registry.yaml中已注册如未来 schema 加 enumS6必须填op.platform_constraints.supported_chips来自 REQUIREMENTS §2 运行环境与 chip_registry.yaml 对齐S7建议interface_binding.arg_order/aclnn/ge_ir字段尚未纳入schemas/op-spec.json顶层additionalProperties: falsev1 不填待 schema 扩展后启用S8建议performance_budget同上schema 未定义v1 不填S9建议performance_baseline同上schema 未定义v1 不填执行步骤Step 1: 读取 REQUIREMENTS.md提取以下字段映射到 spec.yamlREQUIREMENTS.md 字段spec.yaml 字段算子类别op.category算子范式多选op.paradigms范式间组合方式横向组合 / 纵向融合op.paradigm_groups--paradigm-groups参数见下方说明算子接口描述中的非张量参数声明attributes[]--axis-source参数见下方说明数据排布格式支持NCHW/NHWC/NCDHW 等math_semantics.format_variants[]--format-variants参数输入张量列表 dtypeinputs[].name / dtype_set / shape.symbolic输出张量 dtype 推导规则outputs[].dtype_rule / shape_rule数学公式math_semantics.formula参考实现 / oraclemath_semantics.reference_oracle数值稳定性技术numerical_stability.techniques精度容差numerical_tolerance.per_dtype边界 caseboundary_conditions[]/extreme_inputs[]§2 运行环境芯片号op.platform_constraints.supported_chips§2 运行环境DAV 宏 / CANN 版本REQUIREMENTS.md继续承载schema 未定义时不要写入 spec§5 ACLNN API 接口参数列表 / 顺序v1 暂缓interface_binding.*尚未纳入 schema§6 GE IR 定义IR 算子名 / 动态 shapev1 暂缓interface_binding.ge_ir.*尚未纳入 schema§8 资源约束workspace 上限 / 对齐v1 暂缓performance_budget尚未纳入 schema§7 性能指标利用率 / 带宽 / 延迟v1 暂缓performance_baseline尚未纳入 schemaattribute / axis_source 选择规则查看 REQUIREMENTS.md 中的算子接口描述可能以 REG_OP 宏、ACLNN API 参数表、GE IR 表格或自然语言描述等形式出现判断归约轴是如何指定的接口特征--axis-source值说明归约轴作为非张量参数声明如 REG_OP 的.ATTR(dim, ...)、ACLNN 参数表中的 int64/list 类型参数、GE IR 表格的 ATTR 行attribute默认归约轴作为 attribute 传入归约轴作为整型 tensor 输入声明如 REG_OP 的.INPUT(axes, ...)、ACLNN 参数表中的 aclTensor 类型参数input_tensor归约轴作为 tensor input无归约轴参数归约轴固定如 reduce 特定维度fixed归约轴硬编码在算子内部无归约轴参数reduce 所有轴输出为标量implicit_all隐式归约所有轴无需显式指定注意当 REQUIREMENTS.md 的算子接口描述中无归约轴相关参数时必须根据算子语义选择fixed或implicit_all不能使用默认的attribute否则会注入不存在的dim/keep_dimsattribute。paradigm_groups 选择规则当算子有多个范式且不同属性值触发不同计算模式时需要声明范式间组合方式判断条件--paradigm-groups值说明属性值切换导致计算模式根本性变化如 reductionnone→逐元素 vs reductionsum/mean→归约modetraining vs modeinferencecombination横向组合多范式择一由属性值决定激活哪个。每个 paradigm 独立一条 combination 组多范式串联执行如先 Elementwise 再 Reduction 再 Elementwise所有范式始终参与fusion纵向融合所有范式按序执行仅 1 个范式或所有属性值走同一范式不传默认无需声明组合关系关键判断检查 REQUIREMENTS.md 中是否存在模式切换属性——某个属性值使算子退化为完全不同的计算模式如reductionnone使 Reduce 算子退化为逐元素、trainingFalse跳过 dropout。若存在必须选combination并在 spec 中补 Elementwise 范式。Step 2: 调用生成器非交互式CI 友好python3 ops/ops-spec-gen/scripts/generate_spec.py \ --op-name {operator_name} \ --category {category} \ --paradigms {Paradigm1},{Paradigm2},... \ --paradigm-groups {combination|fusion} \ --inputs {name1}:{dtype1},{dtype2};{name2}:{dtype1},... \ --outputs {name} \ --axis-source {attribute|input_tensor|fixed|implicit_all} \ --description {REQUIREMENTS 中的一句描述} \ --output-dir operators/{operator_name}/docs--paradigm-groups仅当有 ≥ 2 个范式且存在模式切换时使用。combination模式下 Elementwise 不会被自动过滤。生成后需手填每组switch属性名和when属性值。--axis-source仅对 Reduction 类算子有效。默认值为attribute需根据上方规则表对照 REQUIREMENTS.md 算子原型选择正确值。注交互式向导用法见 SKILL.md §3.1。Step 3: 手填 TODO 字段生成器只给骨架详见 SKILL.md §3.4math_semantics.formula— numpy 可 eval 的表达式math_semantics.reference_oracle— 单 callable api或填 absenttrue governance 签字dtype_policy.supported_combinations— 显式枚举 (input dtypes) → output dtypesnumerical_tolerance.per_dtype— 覆盖输出 dtype默认值见registries/tolerance_defaults.yamlop.platform_constraints.supported_chips— 来自 REQUIREMENTS §2与registries/chip_registry.yaml对齐op.paradigm_groups[].switch/when— 当使用--paradigm-groups combination时需手填每组的switch属性名和when属性值将属性值映射到对应的范式子集v1 暂缓interface_binding/performance_budget/performance_baseline尚未纳入 schema顶层additionalProperties: false不要写入待 schema 扩展后启用Step 4: 跑 9-stage 校验python3 ops/ops-spec-gen/scripts/validate_spec.py operators/{operator_name}/docs/spec.yaml预期 stage 1-8 全 PASS。stage 9 在测试机未装 torch 时走 SKIP不算失败。任一 FAIL 必须修复后重跑禁止跳过。校验详情见 SKILL.md §4。Step 5: 锁 spec_hash建议compute_spec_hash.py工具链 v1 未交付不要求执行待工具就绪后再纳入流程。完成标志spec.yaml 已生成并通过 9-stage 校验字段与 REQUIREMENTS.md 内容一致dtype / shape / 平台 / 容差均可追溯到需求场景五spec 独立评审14 条 SPEC-* 条款评审在 CP1.5 用户人工 review 前先做 14 条 SPEC-* 条款级评审——逐项对照 spec ↔ REQUIREMENTS 中机器可判的项。把明显错误dtype 漏一个、芯片不匹配、attribute 凭空注入、错误码缺漏、性能字段没填 先拦下避免拿一份机器自洽但语义错的 spec 去骚扰用户。前置条件已存在operators/{operator_name}/docs/spec.yaml9-stage 全 PASS已存在operators/{operator_name}/docs/REQUIREMENTS.md14 条 SPEC-* 条款条款 ID检查项数据来源对照SPEC-CHIP-1spec.op.platform_constraints.supported_chips ⊆ REQUIREMENTS §2 目标芯片字符串集合包含关系SPEC-DAV-1v1 暂缓— DAV 宏由 REQUIREMENTS / DESIGN 承载dav_macros尚未纳入 schema—SPEC-DTYPE-1spec.dtype_policy.supported_combinations 输入 dtype 集 REQUIREMENTS §4 支持类型集集合相等SPEC-DTYPE-2spec.inputs[].dtype_set 覆盖 REQUIREMENTS §4 数据类型集合包含SPEC-IO-1spec.inputs/outputs 数量 name 与 REQUIREMENTS §5 ACLNN 参数列表对齐长度 名字集合SPEC-ATTR-1spec.attributes[].name 集合 ⊆ REQUIREMENTS 算子接口描述中声明的非张量参数集合接口描述中无归约轴等 attribute 类参数时 spec.attributes 应为空集合包含SPEC-ARG-1v1 暂缓—interface_binding.arg_order尚未纳入 schema待扩展后启用—SPEC-ERROR-1spec.op.error_codes ⊇ REQUIREMENTS §8 错误码集合集合包含SPEC-PERF-1v1 暂缓—performance_baseline尚未纳入 schema待扩展后启用—SPEC-RES-1v1 暂缓—performance_budget尚未纳入 schema待扩展后启用—SPEC-FORMULA-1spec.math_semantics.formula 至少引用所有 input name字符串包含SPEC-PARADIGM-1spec.op.paradigms 与 category 隐含范式 REQUIREMENTS 暗示的修饰范式对齐集合差SPEC-LIFECYCLE-1spec.op.lifecycle 与 REQUIREMENTS 描述匹配experimental vs stable字符串匹配SPEC-INTERFACE-1v1 暂缓—interface_binding.*尚未纳入 schema待扩展后启用—执行步骤逐条对照 spec ↔ REQUIREMENTS按 14 条条款表逐项评审每条输出 ✓/⚠/❌ 证据spec 字段值与 REQUIREMENTS 来源的对照生成必看清单列出 agent 独立评审无法判但必须由人 review 的项见下文状态判定任一 ❌ → 状态❌失败全 ✓ 或 ⚠ → 状态✅通过⚠ 提示用户但不阻塞输出 SPEC_REVIEW.md按下文报告格式模板输出注意本场景只读、只评审、只输出报告不得修改 spec.yaml。修复由场景二spec-generation执行。必看清单用户对照摘要必含agent 独立评审无法判但必须由人 review 的项强制规则以下每一项必须出现在评审报告的必看清单中。即使判断为 ✓ 也必须输出并附简要证据不允许省略。必看项为什么 agent 判不了公式数学意图y (x - mean) / sqrt(var eps) 写得对但用户真想要的可能是 RMSNorm 不是 LayerNormtolerance 数值合理性1e-3 还是 5e-3需要算子领域知识 上下游精度标准boundary case 业务覆盖业务上 K 维 4096 是否常见需领域知识composition 拆分合理性FusedComposite 算子的 primitives 拆分是否符合预期融合方式reference_oracle 选择选 torch.matmul 还是 torch.linalg.matmul两者数值差异在边界 case 可能很大范式选择正确性spec.op.paradigms 列出的范式是否完整覆盖了算子的所有计算路径典型陷阱reductionnone 时算子退化为 Elementwise但 spec 只声明了 Reduction FusedComposite漏掉了 Elementwise。agent 只能校验声明的范式是否与 category 对齐无法判断是否漏了一条独立的计算路径范式组合方式paradigm_groups多个范式之间的关系是横向组合combination按属性值择一激活还是纵向融合fusion串联执行agent 只能做结构校验switch/when 格式无法判断组合方式是否符合算子实际的分发逻辑。典型陷阱存在模式切换属性但未声明 paradigm_groups导致下游 design 无法生成分区 TilingKey报告格式精确模板供主 Agent 机读判定**状态**: ✅通过 / ❌失败 **spec.yaml 路径**: operators/{op}/docs/spec.yaml **REQUIREMENTS.md 路径**: operators/{op}/docs/REQUIREMENTS.md ## 14 条 SPEC-* 条款评审 | 条款 ID | 状态 | spec 字段值 | REQUIREMENTS 来源 | 证据 / 备注 | |---------|------|-------------|------------------|------------| | SPEC-CHIP-1 | ✓ | [Ascend910B, Ascend910D] | §2 Atlas A2/A3 训练系列 | 字段值与需求对齐 | | SPEC-DAV-1 | ⚠ | v1 暂缓 | §2 编译宏 | DAV 宏尚未纳入 spec schema由 REQUIREMENTS / DESIGN 承载 | | SPEC-DTYPE-1 | ⚠ | {fp16, bf16} | §4 fp16/bf16/fp32 | spec 漏 fp32用户确认是否真要去掉 fp32 | | ... | ... | ... | ... | ... | ## 必看清单CP1.5 人工 review 用 ⚠ **公式数学意图**spec.formulay np.exp(x) / np.exp(x).sum(axisdim) ⚠ 注意未做 max-shift 数值稳定。REQUIREMENTS §4 公式同未提但 NumericalStable 范式已声明。 → 人工确认是否真不做 max-shift ⚠ **tolerance 数值合理性**fp16 用 1.0e-3bf16 用 4.0e-3 → 来自 ops-precision-standard 默认是否需要按业务收紧 ✓ **boundary case 业务覆盖**含 reduce 轴1 / rank0 / 空 Tensor / fp16 上溢边界 共 4 条 → 自动覆盖 Reduction NumericalStable 范式必含 case业务关键路径请人工确认 ⚠ **范式选择正确性**spec.paradigms[Reduction, FusedComposite] → 人工确认是否存在某些属性值使算子退化为完全独立的计算模式如 reductionnone→逐元素 若是需要添加 Elementwise 范式并声明 paradigm_groups combination。 ⚠ **范式组合方式**spec.paradigm_groups 未声明 → 人工确认多个范式之间是横向组合按属性值择一还是纵向融合串联执行 若存在模式切换属性需声明 paradigm_groups。 ## 问题清单仅状态❌时必填 | 条款 | 严重度 | 问题描述 | 修复建议 | |------|--------|---------|---------| | ... | HIGH/MED/LOW | ... | ... |主 Agent 处理规则供调用方参考状态✅ → 进入 CP1.5 人工确认状态❌ → 主 Agent 自动调 (scene: spec-generation) 按 SPEC_REVIEW 修订 spec.yaml修订后重跑 9-stage 重跑本场景最多重试 2 次禁止把 ❌ 报告直接抛给用户【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考