快速入门

文档版本：参见 changelog

本文档介绍如何使用评测工程进行算子代码生成评测。

前置条件

Python 3.10+
PyTorch 2.0+
torch_npu（NPU 模式）
CANN 环境（NPU 模式）

安装

仓内运行通常不需要安装本项目包，只需安装依赖并配置 PYTHONPATH：

pip install -r requirements.txt
export PYTHONPATH="$(pwd)/src:${PYTHONPATH}"

仓库根目录已提供 pyproject.toml，但推荐的仓内运行方式仍是 PYTHONPATH=src。若使用 pip install -e .，pip 会解析完整依赖（包括 torch / torch_npu），请确保当前 Python、CANN 和 NPU 依赖版本匹配。

评测命令

快速体验（评测任务样例）

项目提供了 Add/Sqrt 两个轻量评测任务 fixture，可用于快速验证评测流水线是否正常工作：

# 评测 add 算子
./scripts/run_evaluation.sh --source-dir examples/aclnn_launch_example \
    --task-dir examples/tasks/level2/add --no-perf

# 评测目录下所有 fixture 算子（add + sqrt）
./scripts/run_evaluation.sh --source-dir examples/aclnn_launch_example \
    --task-dir examples/tasks --no-perf

详见 examples/tasks/README.md。

从源码目录评测（推荐）

自动扫描、编译、安装 AI 生成的算子源码：

./scripts/run_evaluation.sh --source-dir /path/to/ai_ops

评测指定算子

# 评测指定目录
./scripts/run_evaluation.sh --task-dir tasks/level1

# 评测单个算子目录
./scripts/run_evaluation.sh --task-dir tasks/level1/exp

# 按算子名称筛选
./scripts/run_evaluation.sh --operator Exp

# 评测单个用例
./scripts/run_evaluation.sh --operator Exp --case-id 1

# 仅精度验证（不采集性能）
./scripts/run_evaluation.sh --operator Exp --no-perf

# 设置 warmup/repeat 参数
./scripts/run_evaluation.sh --operator Exp --warmup 5 --repeat 10

多卡并行评测

不指定 --device-id 时自动使用全部可用 NPU 卡：

# 多卡并行（自动检测）
./scripts/run_evaluation.sh --operator Exp

# 指定每卡进程数
./scripts/run_evaluation.sh --operator Exp --processes-per-card 4

# 指定进程超时
./scripts/run_evaluation.sh --operator Exp --timeout-per-process 600

单卡评测

# 单卡模式（指定设备 ID）
./scripts/run_evaluation.sh --device-id 0 --operator Exp

查看算子信息

# 列出所有算子
./scripts/run_evaluation.sh -a list

# 查看算子详情
./scripts/run_evaluation.sh -a info --operator Exp

# 查看配置
./scripts/run_evaluation.sh -a config

高级选项

./scripts/run_evaluation.sh 支持的参数：

参数	说明	默认值
`--device <type>`	设备类型 (cpu/npu)	npu
`--device-id <id>`	NPU 设备 ID（不指定则多卡并行）	None
`--processes-per-card <n>`	每卡进程数（多卡模式）	2
`--timeout-per-process <n>`	单进程超时（秒，等价于 cli `--timeout-per-operator`）	300
`--warmup <n>`	预热次数	3
`--repeat <n>`	采集次数	5
`--no-perf`	关闭性能采集（仅精度验证）	False
`--profiler-level <level>`	Profiler 级别 (Level1/Level2)	Level1

shell 暴露的是最常用子集。若需要 --op-timeout-sec / --no-iterative-compile / --eval-code / --eval-seed 等更精细控制，请直调 cli：
PYTHONPATH=src python -m kernel_eval.cli eval --source-dir /path/to/ai_ops \
    --op-timeout-sec 480
cli 完整参数表见 evaluator_design.md §3.3。

Golden 自验证

将 golden 函数打包成 cann_bench whl，通过 run_evaluation.sh 验证 golden(NPU) 与 golden(CPU fp64) 的精度一致性：

# 1. 构建 golden whl 并安装
./scripts/utils/build_golden_wheel.sh --install

# 2. 评测（golden 作为 AI 算子，golden(CPU fp64) 作为参考）
./scripts/run_evaluation.sh --task-dir tasks/level1/exp --no-perf

评测报告

评测完成后，报告输出到 reports/（其它评测集为 reports/<bench_name>/）目录。文件名由“语义前缀 + 阶段 + 时间戳”组成，形如 <bench>_<stage>_eval_<时间戳>.{json,md,html}（cann 分阶段评测会分别产出 cann_correctness_eval_*、cann_performance_eval_*、cann_final_eval_*）：

<...>.json：JSON 格式详细报告
<...>.md：Markdown 格式报告
<...>.html：HTML 格式报告
reports/prof_data/：性能采集数据

下一步

算子提交原则与禁止行为：哪些实现方式会被视为无效或作弊
贡献指南：如何提交新算子评测任务
评测基准规范：算子定义和精度标准
评测工程设计：评测器架构设计
性能采集设计：性能采集机制设计