| name | ascendc-st-design |
| description | Ascend C 算子测试设计技能，基于aclnn接口md资料完成算子测试用例设计。当需要（1）设计算子测试用例、（2）编写测试计划（plan.yaml）、（3）分析算子参数和依赖关系、（4）提取测试因子、（5）生成测试用例组合时使用此技能。 |
Ascend C 算子测试设计
本技能提供 Ascend C 算子测试设计的完整工作流程，基于aclnn测试框架进行算子功能和精度验证。
核心工作流程
1. 输入文件校准
在项目根目录下查找算子资料 {operator_name}.md 文件；或者指定文件路径。
1.1 输出路径规范
所有测试设计结果统一存放到项目根目录的 result/ 下：
{项目根目录}/
└── result/
└── {operator_name}/
├── 03_参数定义.yaml
├── 04_测试因子.yaml
├── 05_约束定义.yaml
├── 06_求解配置.yaml
├── 07_因子值.csv
├── L0_test_cases.csv
├── L0_coverage_report.yaml
└── L1_test_cases.csv
路径变量：
PROJECT_ROOT：项目根目录（执行脚本时的工作目录）RESULT_DIR：{PROJECT_ROOT}/result/{operator_name}/
2. 算子参数定义
根据参数类型（aclTensor/aclScalar/int8_t等）定义参数规范。
详细规范：参考 parameter-definition.md
关键要点：
- 为每个参数定义
name、type、required、io_type 属性
- 数据类型必须完整：从原始资料的数据类型列中完整复制所有类型，不允许遗漏
io_type 字段：标识参数的输入输出类型
input：输入参数（需准备测试数据）output：输出参数（无需定义value_range和special_range/special_value）
- Tensor类型需定义
format、dimensions、dtype_with_ranges
- Scalar/整型需定义
is_enum、dtype_with_values
- 明确
value_range 和 special_range/special_value
- 无需定义workspaceSize和executor参数
2.1 value_range 定义规范
必须覆盖的取值范围：
- 全量默认值：按照
references/parameter-definition.md 中的默认值定义
- 算子特定值：根据算子功能识别的特殊值
定义步骤：
- 复制默认值模板（从 parameter-definition.md）
- 根据算子功能删除不适用的范围（如归一化操作删除负值范围）
- 添加算子特定的约束值
示例：
- 通用算子：使用全量默认值
- 归一化算子：仅保留 [0, 1] 相关范围
- 矩阵运算：关注数值稳定性范围
float16 全量默认值示例：
- dtype: "float16"
value_range: [[0, 0.001], [0.001, 0.01], [0.01, 1], [1, 2], [2, 10], [10, 1000], [-0.001, 0], [-0.01, -0.001], [-1, -0.01], [-2, -1], [-10, -2], [-1000, -10], [-1, 1], [-0.01, 0.01], [-100, 100], [0, 0], [-65504.0, 65504.0], [-0.0078125, 0.0078125], [65504.0, 65504.0], [-65504.0, -65504.0], [-6.103515625e-05, -6.103515625e-05], [6.103515625e-05, 6.103515625e-05], ["inf", "inf"], ["-inf", "-inf"], ["nan", "nan"]]
3. 使用脚本自动提取测试因子
推荐方式：使用 generate_test_factors.py 脚本自动提取
python skills/ascendc-st-design/scripts/generate_test_factors.py <参数定义.yaml> <测试因子.yaml>
python skills/ascendc-st-design/scripts/generate_test_factors.py \
result/{operator_name}/03_参数定义.yaml \
result/{operator_name}/04_测试因子.yaml
脚本功能：
- ✅ 自动识别参数类型（aclTensor/aclScalar/int8_t等）
- ✅ 提取所有测试因子（存在性、格式、维度、数据类型、取值范围、特殊值等）
- ✅ 生成规范的YAML格式输出
4. 参数依赖关系分析
解析输入资料，理解算子的数学公式及计算逻辑，提取 GetWorkspaceSize 接口中950系列产品支持的参数、参数取值范围和参数依赖关系。
详细规范：参考 dependency-yaml-spec.md
4.1 约束分析维度（按优先级）
在识别因子依赖关系时，按以下优先级进行分析：
-
数据类型依赖
- 类型推导链、类型等价约束
- 类型可转换性、类型互斥规则
- 精度层级关系
-
形状依赖
- 维度数约束、维度大小计算
- Broadcast方向性和兼容性
- 指定维度值匹配
-
数值依赖
- 标量取值范围、枚举值定义域
- 特殊数值语义、数值精度影响
-
存在性依赖
4.2 约束定义文件规范
文件结构：
元信息
metadata:
operator: "{operator_name}"
version: "1.0"
description: "{operator_name}算子约束关系定义"
因子节点定义
factors:
{param}.{attribute}: {type: {type}, param: {param}, io_type: {io_type}}
...
约束定义
constraints:
- id: "C-XXX-001"
type: {constraint_type}
...
4.3 因子节点定义
因子节点是约束系统的基本单元，代表一个可测试的属性。
{id}: "{parameter}.{attribute}"
属性类型：
| 属性 | 说明 | 示例 |
|---|
dtype | 数据类型 | self.dtype |
dimensions | 维度 | self.dimensions |
shape | 张量形状 | batch1.shape |
value | 枚举值 | cubeMathType.value |
format | 数据格式 | input.format |
exist | 存在性 | bias.exist |
4.4 约束类型
| 类型 | 语义 | 表达式示例 | 说明 |
|---|
calculate | 计算约束 | target = expr(sources) | 通用计算，sources 不可为空 |
broadcast_dim | 指定维度广播 | 维度兼容性检查 | 单维度广播约束 |
broadcast_shape | 张量广播 | 形状兼容性检查 | 完整形状广播约束，支持单向/双向模式 |
conditional | 条件约束 | if-then-else 分支 | - |
match | 匹配约束 | 维度/属性匹配 | 双向约束，与 calculate 语义不同 |
existential | 存在性约束 | 可选参数联动 | - |
convertible | 可转换约束 | 类型兼容性检查 | - |
inferable_filter | 链式依赖约束 | 多Tensor类型互推导 | - |
inferable | 可推导约束 | 类型推导检查 | - |
约束类型设计原则：
calculate 是通用计算约束，等值场景使用 expression: "sources[0]"match 是双向约束，calculate 是单向计算，语义不同不应合并broadcast_dim 用于单维度广播，broadcast_shape 用于完整形状广播- 固定取值范围（如
cubeMathType.enum_values: [0, 1, 2, 3]）已在 04_测试因子.yaml 中定义，无需添加约束
重要限制：
broadcast_shape 不支持 source_shape_expr 字段（派生形状表达式）- 如需表达"广播到派生形状"的约束，应使用两步约束模式（详见示例）
4.5 约束定义示例
- id: "TYPE-002"
type: calculate
sources: ["self.dtype"]
target: "out.dtype"
expression: "sources[0]"
description: "输出类型等于self类型"
- id: "SHAPE-001"
type: calculate
sources: ["batch1.shape", "batch2.shape"]
target: "out.shape"
expression: "[sources[0][1], sources[1][2]]"
description: "out.shape = [M, N]"
- id: "BCAST-001"
type: broadcast_dim
sources: ["batch1.shape"]
source_index: 0
target: "batch2.shape"
target_index: 1
description: "batch1[0]与batch2[1]需满足广播关系"
- id: "BCAST-002"
type: broadcast_shape
sources: ["out.shape"]
target: "bias.shape"
mode: unidirectional
description: "bias.shape可广播到out.shape"
- id: "BCAST-003"
type: broadcast_shape
sources: ["x.shape"]
target: "y.shape"
mode: bidirectional
description: "x.shape和y.shape双向广播"
- id: "BCAST-004-CALC"
type: calculate
sources: ["batch1.shape", "batch2.shape"]
target: "_broadcast_target.shape"
expression: "[sources[0][1], sources[1][2]]"
description: "计算广播目标形状 [M, N]"
- id: "BCAST-004-BCAST"
type: broadcast_shape
sources: ["_broadcast_target.shape"]
target: "self.shape"
mode: unidirectional
description: "self.shape可广播到[M, N]"
- id: "MATCH-001"
type: match
sources: ["batch1.shape"]
source_index: 2
target: "batch2.shape"
target_index: 1
description: "K维度匹配: batch1[2] == batch2[1]"
- id: "C-TYPE-004"
type: convertible
sources: ["self.dtype"]
target: "beta.dtype"
target_domain: ["float32", "float16", "int32", "int64", "bool"]
description: "beta类型需要可转换成self类型"
- id: "C-TYPE-001"
type: inferable_filter
sources: ["batch1.dtype"]
target: "batch2.dtype"
target_domain: ["float32", "float16", "bfloat16"]
description: "batch2.dtype 需与 batch1.dtype 兼容"
- id: "C-TYPE-002"
type: inferable_filter
sources: ["batch1.dtype", "batch2.dtype"]
target: "self.dtype"
target_domain: ["float32", "float16", "bfloat16"]
description: "self.dtype 需与 (batch1, batch2) 的推导结果兼容"
4.6 检查清单
- 05_约束定义.yaml必须包含metadata、factors、constraints节点
- constraints节点中的sources不为[]；即：固定取值范围无需定义约束
5. 生成通用约束
推荐方式：使用 generate_implicit_constraints.py 脚本自动生成
python skills/ascendc-st-design/scripts/generate_implicit_constraints.py <测试因子.yaml> <约束定义.yaml>
python skills/ascendc-st-design/scripts/generate_implicit_constraints.py \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/05_约束定义.yaml \
--verbose
脚本功能：
- ✅ 自动识别需要生成隐式依赖的因子
- ✅ 生成三类通用隐式约束
- ✅ 避免重复约束（幂等性保证）
- ✅ 自动备份原有约束文件
通用依赖规则：
-
Tensor 输入：{param}.shape 依赖于 {param}.dimensions
- 根据 dimensions 推导具体的 shape 值
-
所有输入：{param}.value_range 依赖于 {param}.dtype
- 根据 dtype 选择对应的取值范围（如 float16 对应 [-65504.0, 65504.0]）
-
非 Tensor 且非枚举类型：{param}.value 依赖于 {param}.value_range
命令行参数：
usage: generate_implicit_constraints.py [-h] [--verbose]
factors_file constraints_file
参数说明:
factors_file 测试因子YAML文件（04_测试因子.yaml）
constraints_file 约束定义YAML文件（05_约束定义.yaml）
6. 构建测试因子依赖图
推荐方式：使用 generate_solver_config.py 脚本自动生成
python skills/ascendc-st-design/scripts/generate_solver_config.py <约束定义.yaml> <求解配置.yaml>
python skills/ascendc-st-design/scripts/generate_solver_config.py \
result/{operator_name}/05_约束定义.yaml \
result/{operator_name}/06_求解配置.yaml
脚本功能：
- ✅ 解析约束定义，构建因子依赖图
- ✅ 拓扑排序，确定求解层级
- ✅ 识别锚点因子（入度为0）
- ✅ 输出求解配置到YAML文件
输出示例：
solver:
strategy: topological
anchors:
- batch1.dtype
- batch1.shape
- self.dtype
derivation_order:
level_0: [batch1.dtype, batch1.shape, self.dtype, ...]
level_1: [alpha.dtype, batch2.shape, beta.dtype, out.dtype]
level_2: [out.shape]
7. 约束求解与测试因子值生成
推荐方式：使用 generate_factor_values.py 脚本自动生成满足约束的测试因子值
python skills/ascendc-st-design/scripts/generate_factor_values.py <求解配置.yaml> <约束定义.yaml> <测试因子.yaml> <输出.csv> [选项]
python skills/ascendc-st-design/scripts/generate_factor_values.py \
result/{operator_name}/06_求解配置.yaml \
result/{operator_name}/05_约束定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
--max-cases 10000
脚本功能：
- ✅ 基于拓扑排序的约束求解
- ✅ 锚点因子独立采样
- ✅ 逐层推导满足依赖关系
- ✅ 自动处理类型推导、形状约束、维度约束等
- ✅ 生成满足所有约束的测试因子组合
约束求解流程：
- 加载求解配置、约束定义和测试因子
- 识别锚点因子（Level 0），独立随机采样
- 按拓扑顺序逐层推导：
- Level 1：根据锚点推导
- Level 2：根据 Level 1 推导
- ... 以此类推
- 验证每个测试用例是否满足所有约束
- 输出满足约束的测试因子值到 CSV 文件
命令行参数：
usage: generate_factor_values.py [-h] [--max-cases N] [--seed N] [--verbose] solver_config constraints factors output
参数说明:
solver_config 求解配置YAML文件（06_求解配置.yaml）
constraints 约束定义YAML文件（05_约束定义.yaml）
factors 测试因子YAML文件（04_测试因子.yaml）
output 输出的CSV文件（07_因子值.csv）
--max-cases 最大用例数（默认10000）
--seed 随机数种子（用于复现结果）
--verbose 详细输出模式
输出示例：
case_id,batch1.dtype,batch1.shape,batch2.dtype,batch2.shape,self.dtype,self.shape,out.dtype,out.shape
0,float16,"[10, 3, 4]",float16,"[10, 4, 5]",float16,"[3, 5]",float16,"[3, 5]"
1,float32,"[5, 2, 3]",float32,"[5, 3, 4]",float32,"[2, 4]",float32,"[2, 4]"
2,bfloat16,"[1, 8, 16]",bfloat16,"[1, 16, 32]",bfloat16,"[8, 32]",bfloat16,"[8, 32]"
8. 测试用例生成（L0/L1）
推荐方式：使用统一的 generate_test_cases.py 脚本
python scripts/generate_test_cases.py <参数定义.yaml> <测试因子.yaml> <因子值.csv> <输出目录> --level <L0|L1> [选项]
测试用例生成示例（分步执行L0和L1）：
注意：由于 L0 和 L1 算法复杂度较高，建议分两步执行，并设置 5分钟超时。
python skills/ascendc-st-design/scripts/generate_test_cases.py \
result/{operator_name}/03_参数定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
result/{operator_name}/ \
--level L0 \
--verbose
python skills/ascendc-st-design/scripts/generate_test_cases.py \
result/{operator_name}/03_参数定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
result/{operator_name}/ \
--level L1 \
--target-count 500 \
--seed 42 \
--verbose
超时设置：在调用 Bash 工具时设置 timeout=300000（5分钟）
脚本功能：
- ✅ 支持L0和L1两种用例级别
- ✅ L0：覆盖所有单个因子值（≤200条）
- ✅ L1：覆盖所有因子值的两两组合（500~700条）
- ✅ 自动生成覆盖度报告
- ✅ 自动转换为标准格式
- ✅ 支持批量生成
- ✅ 严格的参数冲突检测
命令行参数：
必需:
--level {L0,L1} [...] 用例级别（必填，支持多个）
L0: 单因子覆盖（≤200条）
L1: 两两组合覆盖（500~700条）
可选:
--aclnn-name NAME 算子名称（默认从参数定义中提取）
--target-count N L1目标用例数量（默认500，仅L1有效）
【L0使用此参数会报错退出】
--seed N 随机数种子（用于复现L1补齐，仅L1有效）
【L0使用此参数会报错退出】
--report-output FILE 覆盖度报告文件名（默认: {level}_coverage_report.yaml）
批量生成时自动添加级别前缀（L0_, L1_）
--case-output FILE 测试用例文件名（默认: {level}_test_cases.csv）
批量生成时自动添加级别前缀（L0_, L1_）
--verbose 详细输出模式
用例生成流程：
L0流程：
- 加载参数定义、测试因子和因子值
- 提取所有需要覆盖的因子值
- 使用贪心算法选择覆盖所有因子值的最小用例集
- 生成覆盖度报告
- 转换为标准L0用例格式并输出
L1流程：
- 加载参数定义、测试因子和因子值
- 提取所有因子值，生成两两组合（笛卡尔积）
- 使用贪心算法选择覆盖所有两两组合的用例集
- 如果用例数 < 目标数量，从已选用例中随机补齐
- 生成两两组合覆盖度报告
- 转换为标准L1用例格式并输出
输出文件：
批量（--level L0 L1）：
L0_coverage_report.yaml, L0_test_cases.csvL1_coverage_report.yaml, L1_test_cases.csv
9. 测试设计结果总结
在 result 目录总结算子测试设计过程与结果：
- 算子参数定义
- 提取测试因子
- 参数依赖关系分析
- 生成隐式约束
- 构建测试因子依赖图
- 约束求解与测试因子值生成
- 测试用例生成（L0/L1）
参考文件
技能文档
自动化工具
工具使用示例
完整工作流程（推荐）
步骤1: 定义参数（03_参数定义.yaml）
参考官方文档和算子API说明，编写参数定义文件。
步骤2: 提取测试因子（自动化）
python skills/ascendc-st-design/scripts/generate_test_factors.py
result/{operator_name}/03_参数定义.yaml
result/{operator_name}/04_测试因子.yaml
步骤3: 生成隐式约束（自动化）
python skills/ascendc-st-design/scripts/generate_implicit_constraints.py
result/{operator_name}/04_测试因子.yaml
result/{operator_name}/05_约束定义.yaml
--verbose
步骤4: 定义约束关系
参考 dependency-yaml-spec.md 文档，生成算子特定的约束
自动生成隐式约束
步骤5: 生成求解配置（自动化）
python skills/ascendc-st-design/scripts/generate_solver_config.py
result/{operator_name}/05_约束定义.yaml
result/{operator_name}/06_求解配置.yaml
步骤6: 约束求解与测试因子值生成（自动化）
python skills/ascendc-st-design/scripts/generate_factor_values.py \
result/{operator_name}/06_求解配置.yaml \
result/{operator_name}/05_约束定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
--max-cases 10000 \
--seed 42
步骤7: 测试用例生成（分步执行，超时5分钟）
注意：建议分两步执行 L0 和 L1，避免超时
python skills/ascendc-st-design/scripts/generate_test_cases.py \
result/{operator_name}/03_参数定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
result/{operator_name}/ \
--level L0 \
--verbose
python skills/ascendc-st-design/scripts/generate_test_cases.py \
result/{operator_name}/03_参数定义.yaml \
result/{operator_name}/04_测试因子.yaml \
result/{operator_name}/07_因子值.csv \
result/{operator_name}/ \
--level L1 \
--target-count 500 \
--seed 42 \
--verbose
