已关闭

RFC：Autofuse 真实设备验证机制（Device Validation） #281

Jett_Woo创建于 12 天前关闭于 11 天前

12 天前创建

Autofuse 真实设备验证机制（Device Validation）设计文档

简介

目的

本文档描述 Autofuse 真实设备验证机制（device_validation）的需求与设计，覆盖 case contract、SoC profile、codegen/JIT、真机执行、精度校验、性能采集（msprof）、fused/unfused 收益对比、开发阶段自验证与故障定位。目标是让开发者能够新增或迁移用例、在开发阶段以本仓库最新 autofuse 源码完成自验证，并为 CI 提供可分层执行的验证门禁。

目标读者：Autofuse Codegen/Backend 开发者、测试框架维护者、Ascend 950/910 上板验证开发者。期望输出：可直接指导用例开发与框架维护的实现方案和验证标准。

范围

本设计包含：

Case Contract v1 与 per-case（backend + SoC）支持矩阵；
Python 编排层 + 薄 C++ Device Executor 的分层架构；
双 ABI（AutofuseLaunch / AutofuseLaunchV2）动态库执行与校验；
unfused 多步骤分解（steps + $previous 数据流）与 fused/unfused 收益对比；
应用内 ACL Profiling + CANN analysis 离线导出的设备端性能（device_kernel_duration，timing_source=msprof）；
SoC profile（Ascend950 / Ascend910_9362）与仓库内置 JIT 适配器；
无设备降级路径（host fake、profiler 失败诚实标注）与 CTest 分层；
README 开发者指南（含最新源码自验证流程）与用例开发教程。
首个迁移用例 isinf_maskedfill_fusion（fused + unfused，多 shape，含 512x512）。

本设计不包含：

修改 Autofuse optimize/codegen 生产算法、ASCIR 注册或 ATT 模板；
修改 SuperKernel；
新增第二套 simulator（沿用 backend_e2e_v2）；
将 AscendCL/runtime/profiler 依赖加入 Autofuse 生产库与安装包；
修改 pyautofuse 对外接口。

涉及组件：Autofuse 测试框架、Autofuse Codegen/Backend 测试与测试文档；不涉及 SuperKernel、生产打包逻辑与 Python 对外接口。

总体概述

软件概述

项目介绍

仓库已有 autofuse/tests/v35/st/backend_e2e_v2 通过 tikicpulib 验证 Codegen 生成 kernel 的编译与执行（simulator 路径）。本需求新增面向真实 Ascend 设备的验证层：

flowchart LR
    A[backend_e2e_v2] --> B[Ascend950 simulator] --> C[Codegen/kernel 执行正确性]
    D[device_validation] --> E[Ascend950/910 真机] --> F[Python 构图/JIT/runtime ABI/精度/性能]

最终形态为"Python 编排框架 + 薄 C++ Device Executor"：

flowchart TB
    subgraph Python["Python Orchestration (device_validation/tools + python/)"]
        P1[case contract / support matrix / matrix]
        P2[fused/unfused 执行与收益对比 p50_speedup / kernel_reduction]
        P3[input/reference 生成、精度验证、性能汇总]
        P4[report / JIT 编排 / profiler 导出]
    end
    subgraph CPP["Thin C++ Device Executor (device_validation/runner + backend/)"]
        C1[ACL 生命周期 / Device 内存 / tiling / workspace]
        C2[AutofuseLaunch / AutofuseLaunchV2 ABI 分发]
        C3[warmup/measure 采样、D2H 原始输出、runtime timing]
    end
    P1 --> P2 --> P3 --> P4
    P4 --> C1
    C1 --> C2 --> C3

Python 是 case、SoC、shape、dtype、variant、精度与报告的唯一编排层；C++ 只接收扁平化执行请求（flat request）并返回原始输出、实际 ABI、runtime timing 与采样统计，不解析完整 Case Contract、不决定 SoC 支持策略、不计算融合加速比。

产品环境介绍

CANN Toolkit（AscendCL 公共接口、Ascend runtime 公共接口、msprof）；
Autofuse Python 编译接口（autofuse.pyautofuse：ascir/Autofuser）与生成的 host/device 代码；
生成含 AutofuseTiling / AutofuseLaunch / AutofuseLaunchV2 的动态库；
真机（Ascend950PR / Ascend910_9362）与对应 device id；
JIT 编译依赖 bisheng 编译器与 CANN 头文件/库（路径由编译适配器基于包位置推算或 ASCEND_HOME_PATH 回退）。

软件功能

用例契约与支持矩阵驱动执行（compile/functional/precision/performance 能力门）；
fused 单图 / unfused 多步骤（$previous 串接；steps 支持 ASCIR codegen 与 aclnn 双模式）两条执行路径；
精度校验（NaN/Inf 统计、首个 mismatch、atol/rtol）与结构化 report.json；
msprof 设备端内核时长与 host 墙钟两类性能指标、收益对比与诚实降级；
仓库内置 JIT 适配器与多 SoC profile；
无设备 host 验证层（fake executor、host CTest）与三层 opt-in CTest；
开发阶段最新源码自验证（.dev_env + pyautofuse 构建 + 来源自检）。

设计约束

不绑定任何固定安装路径/环境路径；CANN 路径一律经 ASCEND_HOME_PATH 或包相对推算；
不硬编码芯片类型判断；SoC 能力全部经 profile 与 support matrix 声明；
不修改生产 Autofuse/SuperKernel/simulator 与 pyautofuse 对外接口；
不把 host 墙钟或 launch 时长冒充设备端内核时长；profiler 失败必须显式标注；
测试产物（jit 临时目录、profiler 输出、xlsx、build 产物）不得入库；
所有构建命令限制并行度（-j 8）。

假设和依赖关系

真机验证需要装有 CANN Toolkit 且具备对应 NPU 的环境（待确认：CI 硬件池按调度提供）；
构建仓库最新 pyautofuse 需要开发者本地 .dev_env（第三方依赖配置，不入库；无 .dev_env 的 CI 回落到 CANN 包内 autofuse 作基线验证）；
JIT 编译需要 bisheng 编译器可达（CANN 包布局满足；仓库构建布局需按文档镜像依赖目录）。

需求分析与设计

整体介绍

数据流：

flowchart TD
    A[case.json 契约 + support matrix + variants] --> B[Python 编排 run_device_validation]
    C[profiles/&lt;soc&gt;.json soc_version/ABI/dtype/资源/ascir 平台] --> B
    B --> D{support 决策 / 能力门}
    D -->|required 缺失| E[required_capability_failed exit 3 不发卡]
    D -->|gen_input/golden| F1[fused: input_ascir Autofuser codegen JIT kernel_module.so]
    D -->|steps 分解| F2[unfused: steps 每步独立 codegen+JIT+runner, $previous 串接]
    F1 --> G[C++ runner flat request 校验]
    F2 --> G
    G --> H[AscendCBackend: tiling H2D warmup/launch D2H]
    H --> I[精度验证 同一 golden atol/rtol]
    I --> J[性能汇总 wall_clock / msprof]
    J --> K[report.json schema v2 + EXIT_CODES]
    K --> L[matrix 模式 p50_speedup / kernel_reduction]

关键模块边界：

tools/：CLI 编排、JIT 适配器、预检脚本（入口层，无设备逻辑）；
python/：契约解析、support 决策、矩阵、验证、性能、报告（纯逻辑，可 host 测试）；
runner/：C++ runner 与 flat request/contract 校验；
backend/：ACL/AscendC 真实执行、kernel module、tensor、clock、in-process profiler；
cases/、profiles/：用例与设备能力声明；
根目录：README（中英）、CMake、pytest 基础设施。

功能需求

功能需求 1：用例契约与支持矩阵（case.json）

介绍：每个用例以 schema v1 case.json 声明 inputs/outputs（dtype/shape/dynamic）、verification（atol/rtol）、performance 声明、support_matrix（backend+soc 能力级别与 shapes）、variants（fused codegen 入口；unfused steps 分解）。
输入：--case 指向用例目录；--soc-profile 必须与 support_matrix 的 soc 精确一致；--shape 必须命中 shapes。
处理：resolve_support 按（case, backend, soc, shape, dtype）匹配；compile/functional/precision/performance 的 required/optional/unsupported 决定阻断、跳过或执行；required 失败返回 required_capability_failed（exit 3）不发设备任务。
输出：support 决策进入 report 的 support_decisions；未声明的（variant/shape/soc）组合得到 not_applicable。

功能需求 2：fused 单图执行

介绍：variants.fused.codegen_entry（默认 input_ascir.py）经 --rows/--cols/--profile/--output-dir 被调用，产出 tiling.h / host_impl.cpp / device_impl.cpp。
输入：shape、profile（ascir 平台参数）、dtype 集合。
处理：Autofuser schedule+codegen -> JIT 适配器读 profile soc_version 编译 kernel_module.so（单算子 6 参 tiling 自动转发为 runner 4 参 ABI）-> C++ runner 执行；_ensure_abi_metadata 从 device_impl.cpp 提取 launch 签名。
输出：<artifact>/kernel_module.so + 精度/性能 report；失败按 codegen/JIT/launch 阶段区分 error_code。

功能需求 3：unfused 多步骤执行（steps + $previous）

介绍：variants.unfused.steps 声明有序步骤（name/graph/script/inputs/outputs）；"$previous" 引用上一步输出文件。
输入：每步的 inputs 文件与 dtype/shape 声明；首个步骤不得使用 $previous（校验报错）。
处理：每步独立 codegen + JIT + runner 调用（独立 flat request 与 contract_schema，runner 端校验步骤错位/ABI 不匹配）；输出文件写入 step_N_<name>/ 并传递为下一步输入；三步采样求和为 unfused 总时长，另存逐算子分解。
可选 aclnn 模式：step 条目可声明 "aclnn": "<OpName>"（如 IsInf/LogicalOr/MaskedFillScalar/MaskedFillTensor）绕过 ASCIR/Autofuser/JIT，由 runner 的 aclnn step executor 直接经 CANN 原生 aclnn 算子接口执行（GetWorkspaceSize -> workspace -> Create/SetTensor -> Execute -> 同步 -> 释放），warmup/repeat 采样与 msprof 采集和 ASCIR 步骤一致；未知算子报 unknown_aclnn_op；aclnn 步骤与 ASCIR 步骤可在同一 steps 列表并存。
输出：最终步输出与 golden 比对（与 fused 同一 golden）；performance.actual.samples 为三步求和，msprof 模式含 steps 分解。

功能需求 4：精度与报告

介绍：verify_outputs 逐元素比较（支持 float16 解码、整数精确、NaN/Inf 统计、首个 mismatch 定位）。
输入：实际输出（runner decode 后）+ golden（reference.py 独立实现）；atol/rtol 来自 case.json。
处理：mismatch_count>0 或 NaN/Inf 异常 -> precision_failed（exit 5）；prepare_only/skipped/not_applicable 不计入通过。
输出：report.json（schema v2）：stage、support_decisions、precision、performance.actual（metric/unit/timing_source/samples/分位数/kernel_count）、run_parameters、error_code、artifact 目录清单。

功能需求 5：性能与收益对比

介绍：runner_wall_clock（host 墙钟，ms，粗粒度）与 device_kernel_duration（msprof AI Core 时长，us，收益主指标）；--metric device_kernel_duration 时自动请求 profiler。
输入：--warmup/--repeat（warmup 必须小于 repeat 才产生生效样本；wall-clock 采样数恒等于 repeat）；profiler 需要 msprof 与 libsqlite3.so 可达。
处理：应用内 ACL Profiling 采集 -> CANN analysis 离线导出 task_time_*.csv -> 解析 AIV_SQE 记录 -> 按 kernel 名过滤、warmup 剔除、对齐 repeat；导出失败时 profiler_export_failed 且 samples 回退 host_rdtsc，timing_source 同步标注（不冒充设备时长）。
输出：fused/unfused 的 p50/mean/p90/p99 与 timing_source=msprof；matrix 模式在两侧精度通过后计算 p50_speedup、kernel_reduction（3→1 即 2）。

功能需求 6：无设备降级与 CTest 分层

介绍：无 NPU/CI 场景仍可 host 验证编排与契约逻辑。
处理：RunnerHostFakeFlat/fake executor 生成确定性输出并明确标注；CTest 分 device_validation（纯 host）/real_codegen/hardware 三层 opt-in。
输出：host 结果不得当作硬件通过。

功能需求 7：开发阶段最新源码自验证

介绍：开发者在仓库修改 autofuse 源码后，以本仓库最新构建产物跑用例自验证。
处理：.dev_env（本地）启用 OPEN_SRC -> 构建 pyautofuse -> 与 autofuse/compiler/python/*.py 组装运行时包 -> PYTHONPATH 前置与 LD_LIBRARY_PATH 指向 build 产物 -> 来源自检（import autofuse.pyautofuse; print(__file__)）；JIT 编译依赖的 bisheng/include/pkg_inc 等按文档镜像。
输出：import 指向 build 产物即最新源码路径；无 .dev_env 的 CI 回落到 CANN 包基线并可在报告中区分。

非功能需求

可维护性

目录按场景归组：runner/（C++ runner 与 contract）、backend/（ACL/AscendC 执行）、tools/（编排/JIT/预检）、python/（纯逻辑库）、cases/、profiles/；
Python 执行链用 frozen dataclass 收敛参数（MatrixSpec/MatrixRunConfig/CliReportOptions/CodegenOptions 等），C++ 校验函数按职责拆分且错误码字符串逐字保持；
新用例开发遵循 README 五步教程（case.json -> fused/steps -> input/reference -> profile 关联 -> 验证顺序）。

可测试性

host pytest（175 用例）覆盖契约/support/matrix/JIT 适配器/profiler 解析；
C++ gtest（136 用例，12 suites）覆盖 runner contract、backend、kernel module、support matrix；
真机 functional/perf 回归命令见"测试命令"。

可移植性

平台信息（soc_version、ascir platform、资源上限、allowed_abi）全部在 profile 声明，无核心逻辑硬编码芯片型号；
CANN 路径经 ASCEND_HOME_PATH；新 SoC 步骤：新增 profiles/<soc>.json + support_matrix 条目 + aclrtGetSocName() 确认变体。

可靠性

runner 错误码 2/3/4 与编排层 0/3/4/5 语义稳定；异常路径写结构化 report；
ACL 异步生命周期：launch 后 D2H 前同步，stream 顺序固定；资源随 RAII/异常分支释放；
profiler 失败显式标注，不伪造通过；JIT 产物写独立临时目录。

特性交叉影响

按 cross_feature_check.md 逐项结论：

场景	适用性	结论
SuperKernel Python 接口	不适用	零改动，仅测试组件新增
SuperKernel C++/AOT 接口	不适用	零改动，不触碰 `libascendsk` 与 AOT
Autofuse 图优化	不适用	不改 optimize pass；用例经 AUTOFUSE_DEVICE_JIT/pyautofuse 消费既有优化
Autofuse Codegen/Backend	不适用（加分项）	不改 codegen；用例验证既有的 codegen 产物；`backend_e2e_v2` simulator 保持不变
AscendC API / Runtime 交互	适用	新增 aclrt/runtime 调用集中在 `backend/`；遵守同步/内存生命周期与 size>0 检查（见安全检查）
Python/C++ 混合绑定	不适用	不修改 pyautofuse 绑定；仅消费其接口
构建与打包	适用	仅 `autofuse/tests/` 下 CMake 增量；生产 CMake/install/build.sh 未触碰；`-j 8` 限并行
测试与覆盖率	适用	pytest 175 + gtest 136 + 真机 ST；见测试设计
性能与日志	适用	见"性能"章节
兼容性	适用	新增测试组件，无既有 API/产物破坏；README 路径与环境变量无绑定

性能

编译时长

用例首次 JIT 编译（每 step 一次）约数十秒（bisheng 编译），为预期开销；多 step 并行编译已用线程池；
host pytest/gtest 为秒级；不影响生产构建时长。

执行性能

真机测量本身即性能验证对象：fused p50 约 7.2us（Ascend950）/ 4.72us（Ascend910_9362），unfused 约 9.6us / 15.52us（当前环境实测）；
profiler 采集为应用内 ACL Profiling + 离线导出，不改变 kernel launch 语义；warmup 剔除避免首轮抖动；
日志默认关闭诊断（codegen_compile_debug 开关），高频路径无默认海量日志。

内存和产物大小

每次运行在 --output-dir/<case_id>-*/ 产生 codegen/JIT/报告/输入输出（MB 级）；
无新增运行包/wheel/动态库（全部为测试目录内容）。

接口设计

新增/修改接口描述

接口	类型	说明
`device_validation.tools.run_device_validation` CLI	新增（测试内）	`--case/--backend/--soc-profile/--device/--mode{functional,performance,run,prepare}/--warmup/--repeat/--profiler/--metric{runner_wall_clock,device_kernel_duration}/--variant{fused,unfused}/--output-dir/--profile/--shape R C`；退出码 0/3/4/5
`case.json` schema v1	新增（测试内）	support_matrix/variants/verification/performance 契约
`profiles/<soc>.json`	新增（测试内）	soc_version/allowed_abi/dtypes/resources/ascir/tools
`jit_adapter.py`（`AUTOFUSE_DEVICE_JIT`）	新增（测试内）	codegen 产物 -> `kernel_module.so`；`--codegen-dir/--output/--rows/--cols/--profile/--graph-name/--soc-version`
`device_validation_runner --request <json>`	新增（测试内）	flat request：case/tensor/ABI/contract/采样参数；aclnn 步骤携带 `aclnn_op` 字段；误差码见软件设计
report schema v2	新增（测试内）	stage/support/precision/performance/run_parameters/error_code
环境变量	新增（测试内）	`DEVICE_VALIDATION_RUNNER`、`AUTOFUSE_DEVICE_JIT`、`DEVICE_VALIDATION_SQLITE_LIB_PATH`

接口检查项

检查项	子检查项	是否涉及	说明
接口说明	是否需要接口评审	否	全部为测试组件内部接口
接口说明	是否需要补充文档	是	README（中英）含参数速查与用例开发指南
接口兼容	行为是否兼容	是	不改变既有测试/工具行为；simulator/生产接口零触碰
接口兼容	ABI/API 是否兼容	是	runner 仅消费 `AutofuseLaunch`/`AutofuseLaunchV2`（实际生成并校验），无新增生产 ABI
接口约束	约束不满足时是否清晰报错	是	flat request 校验 error_code、support 决策 reason、JIT/编译异常上抛
接口测试	是否需要独立接口用例	是	pytest+gtest 覆盖契约/请求/报告 schema

软件设计

关键数据结构

CaseConfig（python/case.py）：inputs/outputs/variants/support_matrix 的 typed 视图；
SupportDecision（python/support_matrix.py）：capabilities + reason + profile 关联；
MatrixSpec / MatrixRunConfig（python/matrix.py）：矩阵维度与执行配置（frozen dataclass）；
ExecutionContext 族（tools/run_device_validation.py）：UnfusedContext/FusedContext 承载执行状态（previous 输出、step_samples、goldens）；
ExecutorRequest/FlatRequest（C++ FlatRequest，runner/device_validation_runner.cpp）：扁平执行请求；
ReportDocument/CliReportOptions：报告组装参数对象；
声明周期：Python 对象随编排函数栈管理；C++ 资源经 RAII（TemporaryDirectory/unique_ptr），ACL 资源随 backend 生命周期。

关键技术/算法

flat request 校验链（runner/device_validation_runner.cpp）：ValidateFlatRequest 拆分为 tensor 数组/identity/contract/ABI/形状溢出/profile 检查，错误码逐字稳定；
msprof 设备时长：应用内 ACL Profiling -> msprof 离线导出 task_time_*.csv -> 解析 AIV_SQE 行 -> kernel 名过滤与 warmup 剔除 -> 与 repeat 对齐（不足时按 required 判定报错）；
单算子 6 参 tiling 转发：JIT 适配器把 codegen 的单算子 6 参 AutofuseTiling(s0,s1,...) 重写为 4 参入口并绑定 --rows/--cols；
aclnn 调用序列（aclnn step executor，backend/aclnn_executor.cpp）：按算子分发表（IsInf/LogicalOr/MaskedFillScalar/MaskedFillTensor）执行统一序列 aclnnXxxGetWorkspaceSize（查询 workspace 需求）-> aclrtMalloc（分配 workspace）-> aclCreateTensor（以设备内存视图描述输入/输出，ACL_FORMAT_ND）-> aclnnCreateXxx + Set 输入输出 -> aclnnXxx（异步入队）-> aclrtSynchronizeStream（同步完成）-> aclDestroyTensor/aclrtFree（同步后释放，与运行时异步生命周期约束一致）；输入 H2D/输出 D2H 与 decode/精度/采样复用既有 ASCIR 步骤流程，msprof kernel 名过滤用 aclnn 算子名；
收益对比：p50_speedup = unfused_p50 / fused_p50、kernel_reduction = steps - 1；仅两侧精度通过后计算。

流程设计

主流程（run()，tools/run_device_validation.py:1930）：

flowchart LR
    A[load_case + load_typed_case] --> B{variant == all?}
    B -->|yes| C[matrix 模式]
    B -->|no| D[shapes 循环 _run args shape]
    D --> E[_prepare_run support 决策 + artifact + 输入/golden/manifest]
    E --> F{variant 含 steps?}
    F -->|yes| G[unfused: 步骤循环 _run_unfused_mode]
    F -->|no| H[fused: _run_fused codegen JIT runner payload]
    G --> I[汇总 report]
    H --> I
    I --> J[report 落盘 + EXIT_CODES 0/3/4/5]

异常/回滚：任何阶段失败写结构化 report（stage/error_code/reason）并返回对应退出码；临时目录（jit/profiler 导出）经 TemporaryDirectory 自动清理；JIT 产物输出到独立目录避免覆盖冲突。

对子模块的修改

autofuse/tests/st/device_validation/：新增（CMake、README 中英、pytest.ini、conftest、cases、profiles）；
- runner/：runner 主流程、flat request 校验、flat output 原子写出、（测试）step contract 校验；
- backend/：ACL runtime（公开接口）、tensor buffer、kernel module（V2/legacy ABI 分发）、host clock、in-process profiler、AscendCBackend、aclnn step executor（aclnn_executor.cpp：分发表 GetWorkspaceSize/Create/SetTensor/Execute、workspace/tensor 生命周期、warmup/repeat 采样复用）；
- tools/：CLI 编排、JIT 适配器、real-codegen 预检/runner、hardware 预检包装；
- python/：契约/support/matrix/验证/性能/报告/ABI/benchmark 与全部测试；
autofuse/tests/framework/device_validation/：契约解析、report 序列化、support matrix、结果类型定义（TensorView/PrecisionReport，精度验证由 Python 执行）；
autofuse/tests/ut/device_validation/：C++ gtest（11 suites，136 用例）；
autofuse/tests/CMakeLists.txt、autofuse/tests/{st,framework,ut}/device_validation/CMakeLists.txt：新测试目标注册；
.gitignore：测试临时产物路径。

错误处理

系统错误

文件/编译/runtime 失败：统一转 StructuredReport（stage/error_code/reason），JIT/编译错误透传 stderr 摘要；
profiler 导出失败：profiler_export_failed/profiler_export_unavailable，数据回退并标注，不阻断 functional；
内存/buffer 异常：backend 校验 size>0 与返回码，RAII 保证释放。

接口错误

runner 错误码：step_contract/selected_shape/input_specs/output_specs/abi_metadata/input_count/output_count/profile_dir/fake_execution/unknown_aclnn_op 等；exit 2/3/4；
编排层退出码：0（通过/跳过/not_applicable）、3（required 不可用）、4（执行失败）、5（精度失败）；
用户可见提示：结构化 report.json（indent=2）+ stdout 摘要。

安全检查

按编码红线.md 逐条核对：

敏感信息/公网地址：无硬编码密钥/账号/地址（xlsx/临时产物不入库）；
外部输入校验：flat request 的 shape/dtype/count 全部先校验再使用；shape 溢出与元素数乘法防溢出；
整数运算：shape 元素数、字节数、索引均有边界检查（max_shape_elements、size_t 溢出检查）；
除 0：rdtsc 时长换算按表达式内三目防护（ticks_per_us > 0 ? ... : 0）；
资源释放：临时目录/文件句柄/ACL 资源覆盖异常分支；
ABI/API 兼容：不修改生产接口；runner 仅消费实际生成并校验的 AutofuseLaunch/AutofuseLaunchV2；
图改写等价性/确定性：本需求不改图；codegen 消费既有实现；
runtime/aclrt 生命周期：launch 后同步再 D2H；克隆/资源释放顺序固定；只用 CANN 公开头文件接口。

兼容性检查

既有脚本/配置/产物：零破坏（新增独立测试目录与 target）；
backend_e2e_v2 simulator、SuperKernel、pyautofuse、生产 package 均未改动；
新 SoC 为纯声明式扩展；环境路径无绑定；README 命令可从仓库根目录执行。

测试设计

测试边界

入口：CLI（run_device_validation）、pytest（device_validation/）、CTest label、gtest 二进制；
出口：report.json、退出码、CTest 结果、真机 functional/perf 数据；
打桩：host 场景用 fake executor / RunHostFakeFlat；profiler 用伪造 collect/export 目录；runner 契约不依赖设备。

测试用例设计

测试类别	关键测试项	测试方法	用例类型
功能	case/profile/support 契约解析、支持矩阵决策	pytest	UT
功能	flat request 校验（缺失字段/类型错误/溢出/ABI arity/dtype）	gtest	UT
功能	fused/unfused 真机 functional+precision（Ascend950 多 shape、Ascend910_9362 多 shape）	真机 ST	RDV/ST
异常	JIT 失败、profiler 导出失败、warmup>=repeat、step 无 `$previous` 非法引用、未知 aclnn op	pytest+gtest	UT
性能	`runner_wall_clock` 与 `device_kernel_duration`（timing_source=msprof）采样	真机 ST	Benchmark/ST
兼容性	双 ABI 分发（V2 优先、legacy 3 输入 1 输出）	gtest+真机	UT/ST
特性交叉	host CTest 分层；无设备 CI 路径	pytest+CTest	UT/ST

测试命令

# host 全量
PYTHONPATH=autofuse/tests/st:$PYTHONPATH python3 -m pytest autofuse/tests/st/device_validation -q   # 175 passed
cmake --build build -j 8 --target device_validation_ut device_validation_runner
./build/autofuse/tests/ut/device_validation/device_validation_ut                                      # 136 passed

# 真机（Ascend950）
export PYTHONPATH=autofuse/tests/st:$PYTHONPATH
export DEVICE_VALIDATION_RUNNER=$PWD/build/autofuse/tests/st/device_validation/device_validation_runner
export AUTOFUSE_DEVICE_JIT=$PWD/autofuse/tests/st/device_validation/tools/jit_adapter.py
python3 -m device_validation.tools.run_device_validation --case autofuse/tests/st/device_validation/cases/isinf_maskedfill_fusion \
  --soc-profile ascend950 --profile autofuse/tests/st/device_validation/profiles/ascend950.json \
  --backend ascendc_real_device --device 0 --variant all --mode functional --shape 128 128 --warmup 0
python3 -m device_validation.tools.run_device_validation ... --variant fused --mode performance --profiler \
  --metric device_kernel_duration --warmup 1 --repeat 3

# 最新源码自验证（开发阶段）
cmake --build build --target pyautofuse -j 8
python3 -c "import autofuse.pyautofuse; print(autofuse.pyautofuse.__file__)"   # 应指向 build 产物

验收标准

case.json/profile 契约校验、support 决策与错误码行为有 pytest/gtest 覆盖（175 + 136 全绿）；
Ascend950 真机 fused/unfused functional+precision 多 shape（含 512x512）通过（mismatch=0、NaN/Inf=0）；
device_kernel_duration 链路可用（timing_source=msprof、fused/unfused 样本与 p50_speedup/kernel_reduction 有效）；
profiler 失败时报告显式标注且不冒充设备时长（profiler_export_failed）；
无设备环境 host pytest/CTest 全绿且不伪造硬件通过；
新增 SoC 仅需声明（profile + support_matrix），无核心逻辑改动；
README（中英）无路径绑定，按文档可完成用例开发与最新源码自验证；
codecheck/SCA/precommit/compile/llt 门禁通过，测试产物不入库。

用例执行情况（实测，2026-08-25）

用例：`isinf_maskedfill_fusion`（Ascend950PR_9579，CANN 9.2.0）

功能与精度（fused / unfused(ASCIR) / unfused(aclnn) 三模式）

shape	fused	unfused(ASCIR)	unfused(aclnn)
[128,128]	✅ passed，mismatch=0	✅ passed，mismatch=0	✅ passed，mismatch=0
[128,130]	✅ passed，mismatch=0	✅ passed，mismatch=0	✅ passed，mismatch=0
[127,129]	✅ passed，mismatch=0	✅ passed，mismatch=0	✅ passed，mismatch=0
[512,512]	✅ passed，mismatch=0	✅ passed（平台一致）	✅ passed，mismatch=0

（unfused(aclnn) 使用 --variant unfused_aclnn：IsInf + LogicalOr + MaskedFillScalar，全 aclnn 步骤无需 AUTOFUSE_DEVICE_JIT；MaskedFillTensor 变体亦通过）

性能（device_kernel_duration，timing_source=msprof，warmup=1 repeat=3）

shape	fused p50	unfused(ASCIR) p50	unfused(aclnn) p50	kernel_reduction
[128,128]	7.22 us（1 kernel）	9.57 us（3 kernels）	4.15 us（3 kernels）	3→1
[512,512]	100.05 us（1 kernel）	—	5.72 us（3 kernels）	3→1

host 墙钟（runner_wall_clock，[128,128]）：fused p50≈12.7 us vs unfused(aclnn) p50≈34.6 us——融合在端到端（含 host 调度）维度快约 2.7 倍；设备端纯 kernel 时长维度 unfused(aclnn) 更快（当前用例的 fused kernel tiling 仍待优化，尤其 512x512 单 kernel ~100us 异常偏高）。

其它环境

Ascend910_9362：既有 shape fused/unfused functional/precision 通过（mismatch=0）；profiler 实测 fused p50≈4.72 us、unfused(ASCIR) p50≈15.52 us；512x512 声明已扩展（该 shape 尚未在 9362 实测）。
自动化基线：host pytest 175 passed、C++ gtest 136 passed；CI 流水线全绿（codecheck/SCA/precommit/compile/llt）。

Jett_Woo成员

12 天前评论：

需求开发

J Jett_Woo成员

12 天前修改标题为 “RFC：Autofuse 真实设备验证机制（Device Validation）”，原标题为“设计文档：Autofuse 真实设备验证机制（Device Validation）”

J Jett_Woo成员

12 天前修改了issue 的描述

朱朱珉成员

12 天前将 Jett_Woo 设为负责人

J Jett_Woo成员

11 天前修改了issue 的描述

J Jett_Woo成员

11 天前 issue状态由进行中改变为已完成

J Jett_Woo成员

11 天前关闭了 issue

CANN-robot成员

11 天前添加了label：resolved

Autofuse 真实设备验证机制（Device Validation）设计文档

简介

目的

范围

总体概述

软件概述

项目介绍

产品环境介绍

软件功能

设计约束

假设和依赖关系

需求分析与设计

整体介绍

功能需求

功能需求 1：用例契约与支持矩阵（case.json）

功能需求 2：fused 单图执行

功能需求 3：unfused 多步骤执行（steps + $previous）

功能需求 4：精度与报告

功能需求 5：性能与收益对比

功能需求 6：无设备降级与 CTest 分层

功能需求 7：开发阶段最新源码自验证

非功能需求

可维护性

可测试性

可移植性

可靠性

特性交叉影响

性能

编译时长

执行性能

内存和产物大小

接口设计

新增/修改接口描述

接口检查项

软件设计

关键数据结构

关键技术/算法

流程设计

对子模块的修改

错误处理

系统错误

接口错误

安全检查

兼容性检查

测试设计

测试边界

测试用例设计

测试命令

验收标准

用例执行情况（实测，2026-08-25）

用例：isinf_maskedfill_fusion（Ascend950PR_9579，CANN 9.2.0）

其它环境

用例：`isinf_maskedfill_fusion`（Ascend950PR_9579，CANN 9.2.0）