APITest 测试优化：🔧 补齐运行脚本参数说明并新增 run.py YAML 任务启动器

[cangtianhuang]

🧭 背景

• engineV4.py 已兼容 engineV2.py 的主要调用方式，并额外支持 compute-sanitizer 参数
• 原有 shell 脚本未覆盖全部 engine 参数，V4-only 参数缺少明确说明，Paddle Flags 缺少集中解释；直接编辑脚本切换参数容易出错
• 需要一个支持 YAML 配置的统一启动入口，满足多场景任务管理、内置多轮复测、CLI 临时覆盖等需求
• 新增 FLAGS_use_accuracy_compatible_kernel，默认关闭

🔧 主要变更

1. run.py — YAML 配置驱动的任务启动器

新增 run.py 作为主要任务入口，取代直接调用 shell 脚本的方式。

基本用法：

# 使用默认配置（test_pipeline/run_config.yaml）
python run.py --dry-run           # 预览最终命令
python run.py                     # 后台启动
python run.py --foreground        # 前台运行（调试）
python run.py --stop              # 终止后台任务
python run.py --status            # 查看运行状态

# 指定配置文件
python run.py -c test_pipeline/V4_configs/run_gpu_accuracy_full.yaml

# 临时覆盖配置，不修改 YAML 文件
python run.py --api-config-file tester/api_config/5_accuracy/accuracy_1.txt
python run.py --gpu-ids 0-3 --num-workers-per-gpu 2
python run.py --log-dir /tmp/mytest --timeout 300
python run.py --set-env FLAGS_check_nan_inf=true
python run.py --engine-arg atol=1e-3 --engine-arg rtol=1e-3

# 向 engine 透传原始参数（-- 之后的内容原样传递）
python run.py -- --accuracy=True --gpu_ids=0

YAML 配置结构：

name: run_config          # 任务名，用于 PID 文件

runner:
  engine: engineV4        # engineV2 | engineV4
  foreground: false       # true=前台运行
  dry_run: false

env:                      # Paddle Flags 和其他环境变量
  FLAGS_use_system_allocator: "true"
  FLAGS_use_accuracy_compatible_kernel: "false"

input:
  api_config_file: "tester/api_config/5_accuracy/accuracy_1.txt"
  # 三选一：api_config / api_config_file / api_config_file_pattern

output:
  log_dir: "tester/api_config/test_log"

retest:                   # 内置多轮复测
  enabled: false
  rounds: 3               # 总轮数（含第 1 轮）

engine_args:              # engine CLI 参数，注释掉的使用 engine 默认值
  accuracy: true
  num_gpus: -1
  timeout: 600
  # use_compute_sanitizer: true   # engineV4 only

多轮复测（retest）： 开启后 run.py 自动读取上一轮 log_dir 中的失败配置文件（api_config_accuracy_error.txt 等）作为下一轮输入，无需手动编写复测命令。

2. 预置场景配置文件

新增 test_pipeline/V4_configs/ 目录，提供开箱即用的任务配置：

文件	测试模式	主要特性
run_gpu_accuracy_full.yaml	accuracy	bitwise_alignment，atol/rtol=0
run_gpu_0size_full.yaml	accuracy	random_seed=2025，10 workers
run_cpu_0size_full.yaml	accuracy	test_cpu=true
run_gpu_bigtensor_full.yaml	accuracy	use_cached_numpy=true
run_dsv4_0size_accuracy.yaml	accuracy_stable	use_cached_numpy，4 workers
run_dsv4_0size_paddleonly.yaml	paddle_only	use_compute_sanitizer，1 worker
run_dsv4_1M_accuracy.yaml	accuracy_stable	timeout=1200，1 worker
run_dsv4_1M_paddleonly.yaml	paddle_only	use_compute_sanitizer，全量 Paddle Flags
run_v2_0size_accuracy.yaml	accuracy_stable	v2 输入文件
run_v2_1M_paddleonly.yaml	paddle_only	v2 输入文件

3. 补齐 shell 模板参数和说明

• run-example.sh（engineV2 示例）和 run-v4.sh 补充全部 engine 参数注释，包含 custom_device_vs_gpu、manual_threshold_config_file、random_seed、show_runtime_status 等
• compute-sanitizer 参数明确标注为 engineV4 only；run-v4.sh 在 ENGINE=engineV2 时跳过 sanitizer 参数传递
• 两个脚本新增 Paddle Flags 集中说明，并导出 FLAGS_use_accuracy_compatible_kernel=false
• 提示信息中的脚本名改为动态读取 ${BASH_SOURCE[0]##*/}，支持用户复制脚本为不同任务名

4. 修正 runner 参数白名单和 schema

• run.py ENGINE_ARG_TYPES 补齐 manual_threshold_config_file、use_gpu_cache_mode
• run_config.schema.json 补齐缺失字段并为所有 engine 参数添加对应 CLI 参数描述

📁 改动文件

PaddleAPITest/
├── run.py                                    # 新增：YAML 配置驱动的任务启动器
├── run-example.sh                            # 补齐参数注释，动态脚本名
├── run-v4.sh                                 # 补齐参数注释，动态脚本名，sanitizer 按引擎条件传递
└── test_pipeline/
    ├── run_config.yaml                       # 默认配置模板，补齐全部 engine 参数示例
    ├── run_config.schema.json                # 补齐字段定义和参数描述
    └── V4_configs/                           # 预置场景配置（10 个任务模板）
        ├── run_gpu_accuracy_full.yaml
        ├── run_gpu_0size_full.yaml
        ├── run_cpu_0size_full.yaml
        ├── run_gpu_bigtensor_full.yaml
        ├── run_dsv4_0size_accuracy.yaml
        ├── run_dsv4_0size_paddleonly.yaml
        ├── run_dsv4_1M_accuracy.yaml
        ├── run_dsv4_1M_paddleonly.yaml
        ├── run_v2_0size_accuracy.yaml
        └── run_v2_1M_paddleonly.yaml