APITest 测试基建：新增 Operator Compare 多实现对比工具

[cangtianhuang]

背景

tester/operator_compare 复用 PaddleAPITest config、TensorConfig 和 Paddle→Torch converter，对指定算子 config 进行 Paddle / Torch / custom 多实现数值对比，并生成结构化结果与报告。

使用场景

用于在开发、调试或扩展算子时，对单个或少量 API config 做多实现数值对比、误差分析和报告归档。

功能简介

执行流程

PaddleAPITest config txt
        │
        ▼
APIConfig / TensorConfig 解析输入
        │
        ▼
CompareSuite 展开 implementation × dtype × precision
        │
        ▼
runner 执行 paddle / torch / custom 实现
        │
        ▼
metrics 计算 standard 与 pairwise 误差
        │
        ▼
artifacts / report 写出 JSON、CSV、Markdown 和 figures

核心能力

• 复用 config：直接读取 PaddleAPITest config 行或 config txt 文件。
• 复用输入生成：通过 APIConfig / TensorConfig 构造 Paddle 和 Torch 共用输入。
• 复用 Torch reference：通过 Paddle2TorchConverter 将 Paddle API 映射到 Torch 实现。
• 多实现对比：支持 paddle、torch 和注册的 custom implementation。
• 矩阵展开：支持按 implementation、dtype、precision 展开比较。
• 统一输出：生成 results.json、summary.csv、pairwise CSV、report.md 和可选图示。

开发指南摘要

优先方式：只增加 config

当 Paddle API 能直接执行、Torch reference 已在 mapping.json / rules.py 中支持、输出可由通用逻辑转换为 torch.Tensor 时，只需要增加或复用 config：

python tools/operator_compare.py \
  --case 'paddle.add(Tensor([2], "float32"), Tensor([2], "float32"), )' \
  --implementations paddle,torch \
  --standard 'torch|config|default' \
  --output-dir test_log_operator_compare/add_smoke

Torch reference 不存在：补充 converter rule

如果 Paddle2TorchConverter.convert(api_name) 不支持目标 API，在 tester/paddle_to_torch/mapping.json 增加映射；简单映射优先使用 GenericRule 字段，复杂逻辑在 tester/paddle_to_torch/rules.py 中增加专用 rule。

_C_ops 无签名算子：补充参数名绑定

部分 _C_ops 没有 Python signature，而 converter rule 需要通过命名变量取参数。此时在 tester/operator_compare/implementations.py 的 MANUAL_ARGUMENT_NAMES 中补充位置参数名：

MANUAL_ARGUMENT_NAMES: dict[str, tuple[str, ...]] = {
    "paddle._C_ops.fused_linear_param_grad_add": (
        "x",
        "dout",
        "dweight",
        "dbias",
        "multi_precision",
        "has_bias",
    ),
}

通用实现无法表达：注册 custom implementation

当 paddle / torch 通用路径无法表达某个实验实现时，在 tester/operator_compare/implementations.py 中注册 custom runner，并通过 --implementations paddle,torch,my_impl 使用。

主要文件

tools/operator_compare.py
tools/operator_compare_profile_worker.py

tester/operator_compare/
├── DESIGN.md
├── README.md
├── spec.py
├── config_loader.py
├── implementations.py
├── runner.py
├── metrics.py
├── artifacts.py
├── report.py
└── profile.py

测试指南摘要

新增算子时建议覆盖：

1. config 能被 APIConfig 正确解析。
2. build_compare_suite() 能生成预期 implementation id。
3. Paddle / Torch 两个实现都能运行成功。
4. target 相对 standard 的误差符合预期。
5. 如果新增 _C_ops 参数绑定，使用对应 _C_ops config 做 CLI smoke。
6. 如果新增 custom implementation，使用包含 custom implementation id 的 CLI smoke 验证。

本 PR 已通过 CLI smoke 覆盖：

• add 通用路径。
• fused_linear_param_grad_add _C_ops 参数绑定与真实执行路径。

使用示例

单条 config

python tools/operator_compare.py \
  --case 'paddle.Tensor.__abs__(Tensor([], "float32"), )' \
  --implementations paddle,torch \
  --standard 'torch|config|default' \
  --output-dir test_log_operator_compare/abs_smoke

add smoke

python tools/operator_compare.py \
  --case 'paddle.add(Tensor([2], "float32"), Tensor([2], "float32"), )' \
  --implementations paddle,torch \
  --standard 'torch|config|default' \
  --output-dir test_log_operator_compare/add_smoke_flat

fused_linear_param_grad_add smoke

python tools/operator_compare.py \
  --case 'paddle._C_ops.fused_linear_param_grad_add(Tensor([8, 4], "float32"), Tensor([8, 4], "float32"), Tensor([4, 4], "float32"), None, False, False, )' \
  --implementations paddle,torch \
  --standard 'torch|config|default' \
  --output-dir test_log_operator_compare/fused_linear_param_grad_add_smoke_flat