kernel_bench 算子贡献指南【免费下载链接】cann-bench评测AI在处理CANN领域代码任务的能力涵盖算子生成、算子优化等领域支撑模型选型、训练效果评估统一量化评估标准识别Agent能力短板构建CANN领域评测平台推动AI能力在CANN领域的持续演进。项目地址: https://gitcode.com/cann/cann-bench创建算子目录在bench_lab/目录下创建以任务名例如driver_bench算子名称命名的文件夹例如bench_lab/driver_bench/my_new_op/。贡献规范算子原型需符合Ascend C算子开发规范支持动态shape、数据类型兼容性等特性。参考实现需通过PyTorch官方接口实现确保在CPU/NPU环境可正确运行。测试用例需覆典型场景。文档描述需清晰说明算子功能、适用场景及与同类算子的差异。文件用途proto.yaml算子原型定义schema、输入/输出、属性golden.pyPyTorch 参考实现用于精度对比desc.md算子 API 文档面向使用者的完整说明cases.yaml测试用例定义机器可读cases.csv测试用例定义与 cases.yaml 内容一致便于人工审查1. proto.yaml算子原型定义文件采用 YAML 格式。所有字段名、缩进、枚举值须严格遵循本规范。1.1 整体结构operator: name: Conv2D # 算子名PascalCase与目录名语义对应 category: Contraction # 算子类别见 1.2 difficulty: L3 # 难度等级L1 ~ L4 formula: y CONV(x, filter) bias # 数学公式单行 # formula: | # 多行公式用 YAML 多行字符串 # m_t beta1 * m_{t-1} (1 - beta1) * grad # v_t beta2 * v_{t-1} (1 - beta2) * grad^2 description: 计算2D卷积 # 一句话中文描述 shape_support: x: [N, C_in, H, W] # 输入 shape 约束说明 attrs: # 属性列表见 1.3 - name: strides type: ListInt description: 步长 required: true inputs: # 输入张量列表见 1.4 - name: x description: 输入特征图 dtype: - float16 - float32 outputs: # 输出张量列表见 1.5 - name: y description: 输出特征图 dtype: - float16 - float32 schema: conv2_d(Tensor x, ...) - Tensor y # API 签名见 1.61.2 顶层字段字段类型必填说明namestring是算子名称使用 PascalCase如Conv2D、ApplyAdamWcategorystring是算子类别difficultystring是难度等级取值L1/L2/L3/L4须与所在levelN/目录一致formulastring是数学公式单行直接写字符串多行使用 YAML|块标量descriptionstring是一句话中文描述shape_supportstring是输入/输出 shape 的格式约束说明attrslist否非标量属性列表kernelSize、stride、epsilon 等inputslist是输入张量列表outputslist是输出张量列表schemastring是API 函数签名notestring否补充说明1.3 category 常见枚举取值含义代表算子Elementwise逐元素运算Exp、SigmoidFusedComposite融合算子ApplyAdamW、SwiGLUReduction归约运算ArgMax、AdaptiveAvgPool3DContraction收缩/卷积/矩阵运算Conv2D、GroupedMatmulTransform张量变换Transpose、StridedSliceSort排序/去重TopK、UniqueIndex索引/散列Gather、ScatterVision视觉/检测ROIAlign、NMSWithMask1.4 attrs 属性定义每个属性项包含以下字段字段类型必填说明namestring是属性名使用 camelCase如kernelSize、weight_decaytypestring是数据类型取值见下方 type 枚举descriptionstring是中文描述defaultany否默认值。bool类型须用字符串true/falserequiredbool是是否必填使用字符串true/false或 YAML booltype 枚举取值含义示例float浮点标量lr: 0.001int整数标量groups: 1bool布尔标量maximize: falseListInt整数列表stride: [1, 1]ListFloat浮点列表scale: [1.0, 2.0]注意列表类型统一使用ListInt/ListFloat不使用IntArray/Int大小写不统一。 标量整数用Int标量浮点用float布尔用bool。1.5 inputs / outputs 张量定义每个张量项包含以下字段字段类型必填说明namestring是张量名如x、weight、ydescriptionstring是中文描述dtypelist[string]是支持的数据类型列表取值见下方 dtype 枚举dtype 枚举取值含义float16半精度浮点float32单精度浮点bfloat16Brain 浮点int3232位有符号整型int6464位有符号整型int1616位有符号整型int88位有符号整型uint3232位无符号整型uint6464位无符号整型uint1616位无符号整型uint88位无符号整型bool布尔型1.6 schema 签名格式op_name(Tensor input1, Tensor input2, attr1 type1, attr2 type2, ...) - Tensor output规则函数名使用 snake_case与name的 PascalCase 对应Tensor 参数只写Tensor name不写 dtypedtype 在inputs中定义属性参数写name后跟类型简写int[]列表、float、int、bool有默认值的属性写namedefaultValue返回值统一写- Tensor name示例conv2_d(Tensor x, Tensor filter, Tensor bias, int[] strides, int[] pads, int[] dilations[1,1], int groups1) - Tensor y2. golden.pyPyTorch 参考实现用于精度对比。2.1 文件结构import torch OpName算子Torch Golden参考实现 中文描述 公式: 数学公式 def op_name( input1: torch.Tensor, input2: torch.Tensor, attr1: list, attr2: int, ... ) - torch.Tensor: 中文描述 公式: 数学公式 Args: input1: 描述 attr1: 描述 Returns: 描述 # 参数转换list → tuple 等 # 调用 torch API return result2.2 编写要求要求说明优先使用 PyTorch 内置 API如torch.nn.functional.conv2d、torch.nn.functional.interpolate、torch.unique等参数名与 proto.yaml 一致golden 函数签名中的参数名须与schema中的参数名逐一对应无额外依赖只允许 importtorch不允许 import 第三方库参数转换明确list→tuple等转换须在函数体内显式写出无冗余代码不要写死代码、未使用的 import、多余类型转换dtype 保持输出 dtype 须与输入 dtype 一致除非算子本身改变 dtype公式与 proto 一致docstring 中的公式须与proto.yaml的formula字段一致2.3 常见模式# 列表 → tuplePyTorch API 需要 tuple 时 stride_val (stride[0], stride[1]) # 调用 PyTorch 函数式 API y torch.nn.functional.conv2d(x, weight, bias, stridestride_val, paddingpadding_val, dilationdilation_val, groupsgroups) # 直接调用 torch 函数 y torch.topk(x, k, dim-1, largestTrue, sortedTrue)3. desc.md算子 API 文档面向使用者。采用 Markdown 格式。3.1 章节结构# OpName 算子 API 描述 ## 1. 算子简介 中文描述 **主要应用场景** - 场景1 - 场景2 **算子特征** - 难度等级LNcategory - 输入输出描述 - shape 描述 ## 2. 算子定义 ### 数学公式 $$ LaTeX 公式 $$ 公式说明文字 ## 3. 接口规范 ### 算子原型 python cann_bench.op_name(参数列表) - Tensor output输入参数说明参数类型默认值描述Tensor必选描述必选 / 默认值描述输出参数Shapedtype描述yshape描述与输入相同描述数据类型输入 dtype输出 dtypefloat16float16float32float32bfloat16bfloat16须与proto.yaml中 inputs/outputs 的 dtype 列表完全一致规则与约束约束1约束24. 标准 Golden 代码完整 golden.py 内容5. 额外信息算子调用示例import torch import cann_bench 示例代码y cann_bench.op_name(x, weight, bias, stride, padding, dilation, groups)### 3.2 与 proto.yaml 的一致性要求 | desc.md 内容 | 对应 proto.yaml 字段 | |-------------|---------------------| | 算子名称 | operator.name | | 难度等级 | operator.difficulty | | 公式 | operator.formula | | 输入参数表 | operator.inputs operator.attrs | | 输出表 | operator.outputs | | 数据类型表 | operator.inputs[].dtype operator.outputs[].dtype | | schema | operator.schema | | Golden 代码 | golden.py 全文 | --- ## 4. cases.yaml 测试用例定义文件机器可读格式。 ### 4.1 整体结构 yaml cases: - operator: OpName case_id: 1 input_shape: [[shape1], [shape2], ...] dtype: [dtype1, dtype2, ...] attrs: {attr_name: value, ...} value_range: [[min1, max1], [min2, max2], ...] baseline_perf_us: None note: 简短描述 - operator: OpName case_id: 2 ...4.2 字段定义字段类型必填说明operatorstring是算子名称与proto.yaml中name一致case_idint是用例编号从 1 开始递增input_shapelist[list[int] | null]是每个输入张量的 shape顺序与proto.yaml中inputs顺序一致可选参数用null表示不使用dtypelist[string] | [string]是每个输入张量的数据类型支持单值简写[dtype]表示所有 tensor 使用相同类型attrsdict是属性键值对键名与proto.yaml中attrs[].name一致value_rangelist[list]是每个输入张量的随机数取值范围[min, max]数量与input_shape一致。特殊值[-inf, inf]、[nan, nan]、[0, 0]可选参数对应位置用[0, 0]或nullbaseline_perf_usfloat / None是性能基线微秒未测量时填Nonenotestring是用例简短描述建议格式dtype-数据规模-对齐/非对齐-特征4.3 input_shape 可选参数处理当算子有可选输入参数时用null表示该参数不使用# 可选参数示例QuantMatmul 的 offset、pertoken_scale、bias 可选 input_shape: - [1024, 3584] # x必选 - [3584, 3584] # weight必选 - [3584] # scale必选 - null # offset不使用 - null # pertoken_scale不使用 - null # bias不使用 dtype: [int8, int8, float32, null, null, null] value_range: - [-128, 127] - [-128, 127] - [0.001, 0.01] - [0, 0] # 不使用时填零值范围 - [0, 0] - [0, 0] attrs: {offset: null, pertoken_scale: null, bias: null, output_dtype: float16}4.4 dtype 单值简写当所有输入张量使用相同数据类型时可使用单值简写# 单值简写示例所有 tensor 都用 float32 input_shape: - [[1024, 1024], [1024, 1024]] # TensorList x12个tensor - [[1024, 1024], [1024, 1024]] # TensorList x22个tensor - [[1024, 1024], [1024, 1024]] # TensorList x32个tensor dtype: [float32] # 单值简写自动展开为6个float32校验逻辑会自动将单值 dtype 展开为与 input_shape 相同长度的列表。4.5 用例设计原则结合评测目标设计用例覆盖场景例如当前kernel_bench用例覆盖泛化场景建议 20 个用例note:当前场景仅供参考| 场景类别 | 说明 | |---------|------| |基准场景| 对齐 shape64 的倍数、典型 kernel/stride/padding | |参数变化| 不同 kernelSize、stride、padding、dilations 组合 | |非对齐 shape| 质数、奇数等非 64 对齐的 shape | |多形态 shape| 小 shape、大 shape、极端 shape | |特殊值| inf、nan、零值、边界值如 float16 的 65504 | |dtype 覆盖| float16、float32、bfloat16 至少各有用例 |4.6 value_range 特殊值取值含义[-1, 1]均匀分布在 [-1, 1] 区间的随机值[-inf, inf]包含正负无穷[nan, nan]NaN 值[0, 0]全零[-65504, 65504]float16 可表示的最大范围5. cases.csv测试用例定义文件与 cases.yaml 内容完全一致CSV 格式便于人工审查和 diff。5.1 列定义列名对应 cases.yaml 字段CSV 格式说明operatoroperator字符串case_idcase_id整数input_shapeinput_shapeJSON 数组字符串如[[2, 64, 32, 32], [64, 1, 3, 3], [64]]dtypedtypeJSON 数组字符串如[float16, float16, float16]attrsattrsPython dict 字符串如{kernelSize: [3, 3], stride: [1, 1]}value_rangevalue_rangeJSON 数组字符串如[[-1, 1], [-1, 1], [-0.1, 0.1]]baseline_perf_usbaseline_perf_us浮点数或Nonenotenote字符串5.2 一致性要求cases.csv与cases.yaml的用例数量、字段值必须完全一致修改用例时须同时更新两个文件case_id顺序一致不能跳跃或重复6. 四文件一致性检查清单提交前请确认proto.yaml的formula与golden.pydocstring 中的公式一致proto.yaml的schema参数名与golden.py函数参数名一致proto.yaml的inputs/outputsdtype 列表与desc.md数据类型表一致proto.yaml的difficulty与所在levelN/目录层级一致proto.yaml的attrs键名与cases.yaml/cases.csv的attrs键名一致cases.yaml与cases.csv内容完全一致desc.md中 Golden 代码块与golden.py内容一致desc.md中算子示例代码的参数名与proto.yamlschema 一致golden.py只 importtorch无额外依赖proto.yaml中 type 使用统一命名ListInt/ListFloat/Int/float/bool【免费下载链接】cann-bench评测AI在处理CANN领域代码任务的能力涵盖算子生成、算子优化等领域支撑模型选型、训练效果评估统一量化评估标准识别Agent能力短板构建CANN领域评测平台推动AI能力在CANN领域的持续演进。项目地址: https://gitcode.com/cann/cann-bench创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考