Merge pull request #225 from cangtianhuang/develop

[BIT] Update readme

Author: wanghuancoder

README.md

@@ -1,53 +1,50 @@
 # PaddleAPITest
 
-******
-
 ## 1. 项目背景
 
-正确性是Paddle质量的基石，影响业务训练、推理，影响用户对Paddle的信赖。至关重要。
-如何主动发现Paddle存在的质量问题，给予修复。而不是被动等用户反馈后，再修复。是一个质量上的难题。
-API是Paddle的“窗口”，PaddleAPITest通过整理API级的300余万条case（本项目称之为配置 / api config），使用case驱动Paddle不同内核机制执行API，可成为Paddle内核机制、算子正确性的“扫描仪”。
+正确性是 PaddlePaddle 框架质量的基石，影响业务训练、推理的效果，影响用户对 Paddle 的信赖。如何主动发现 Paddle 存在的质量问题并及时修复，而不是被动等用户反馈后再修复，是一个亟待解决的质量难题。
 
-PaddleAPITest主要工作思路如下：
+API 是 Paddle 的 “窗口”，PaddleAPITest 通过整理超过 300 万条 API 级别的测试用例（本项目称为配置 / api config），利用这些用例驱动 Paddle 的不同内核机制执行 API，从而成为 Paddle 内核机制和算子正确性的 “扫描仪”。
 
-1. 在Paddle开发Trace API机制，具体见 https://github.com/PaddlePaddle/Paddle/pull/70752 ，用于抓取API调用配置，下面是一个配置例子：
+PaddleAPITest 主要工作思路如下：
 
+1. 在 Paddle 中开发 Trace API 机制（具体实现见 [PR#70752](https://github.com/PaddlePaddle/Paddle/pull/70752)），用于抓取 API 调用配置。以下是一个配置示例：
 ```
 paddle.concat(tuple(Tensor([31376, 768],"float32"),Tensor([1, 768],"float32"),), axis=0, )
 ```
 
-2. 在所有Paddle单元测试（CI）、集成测试（CE）流水线中，抓取所有Paddle API的调用配置，形成了PaddleAPITest/tester/api_config下以 "CI_CE_config" 的配置集。对以上配置集进行去重、排序并对测试结果进行梳理得到了 api_config 下各个目录的配置集。
+2. 在所有 Paddle 单元测试（CI）和集成测试（CE）流水线中，抓取所有 Paddle API 的调用配置，形成了 `PaddleAPITest/tester/api_config` 下的 `CI_CE_config` 的配置集。对配置集进行去重、排序，并对测试结果进行梳理，得到了 `api_config` 下各个目录的配置集。
 
-3. 在 PaddleAPITest 中开发一套**引擎**，加载配置集，初始化相应Tensor，调用相应API执行前/反向测试。
+3. 在 PaddleAPITest 中开发一套 **引擎**，用于加载配置集，初始化相应 Tensor，并调用相应的 API 执行前/反向测试。
 
-4. 对采集到的配置集进行shape篡改，得到了 "big_tensor"、"0_size" 开头的配置集。
+4. 对采集到的配置集进行 shape 篡改，生成了以 `"big_tensor"` 和 `"0_size"` 开头的配置集。
 
-5. 对于精度正确性，在 PaddleAPITest 中开发一套**转换工具**，在调用Paddle API测试的同时，等同的调用Torch API，做精度对比测试。
+5. 对于精度正确性，在 PaddleAPITest 中开发一套 **转换工具**，在调用 Paddle API 测试的同时，等效地调用 Torch API，进行精度对比测试。
 
-6. 对于内核测试，可通过继承APITestBase，开发针对某内核的测试引擎。被测对象可以是：Kernel精度、Kernel性能、Kernel显存、动态图、静态图、动转静、组合算子、CINN、Paddle2ONNX、GPU、CPU、XPU、NPU、OneDNN、TRT等等。
+6. 对于内核测试，可通过继承 `APITestBase`，开发针对特定内核的测试引擎。测试对象包括：Kernel 精度、Kernel 性能、Kernel 显存、动态图、静态图、动转静、组合算子、CINN、Paddle2ONNX、GPU、CPU、XPU、NPU、OneDNN、TRT 等等。
 
 ## 2. 项目结构
 
-```python
+```bash
 ├── tester
-│   ├── accuracy.py
 │   ├── api_config
+│   ├── paddle_to_torch
 │   ├── base.py
-│   ├── paddle_cinn_vs_dygraph.py
 │   ├── paddle_only.py
-│   └── paddle_to_torch
+│   ├── accuracy.py
+│   └── paddle_cinn_vs_dygraph.py
+├── report
 ├── test_pipline
 ├── tools
 ├── engine.py
 ├── engineV2.py
 ├── engineV3.py
-├── report
 └── run-example.sh
 ```
 
-目前项目结构主要分为 report 和 tester 文件夹，report 用于储存内核报错的 api 信息，tester 用于测试配置的正确性和存放配置测试结果。
+项目结构主要分为 `report` 和 `tester` 文件夹，`report` 用于存储内核报错的 api 信息，`tester` 用于测试配置的正确性和存放配置测试结果。
 
-engineV2.py 及配合的 run-example.sh 是目前运行本项目的主要工具，engineV3.py 目前由百度内部开发测试使用，engine.py 是最早的引擎，相较 engineV2.py 吞吐量低，在少量配置时可使用。
+**engineV2.py** 及配套的 `run-example.sh` 是目前运行本项目的主要工具；**engineV3.py** 目前由百度内部开发测试使用；**engine.py** 是最早的引擎，相较 `engineV2.py` 吞吐量低，在少量配置时可使用。
 
 1. report 介绍
    - 0size_tensor_cpu 存放进行在 cpu 上进行精度测试/引擎解析能力测试（accuracy / paddle_only）结果。
@@ -58,7 +55,6 @@ engineV2.py 及配合的 run-example.sh 是目前运行本项目的主要工具
    - cinn 存放 paddle 静态编译器与动态图方式进行精度对比测试结果。
    - fresh_report 存放引擎补齐（paddle_only）和精度转换（accuracy）两个任务中，出现的内核报错或者精度报错。
 
-
 2. tester 介绍
 
    * api_config 目录存放配置目录的管理情况和相关脚本工具，各配置目录下的文本命名语义一致，参考 5_accuracy 中的 txt 命名含义：
@@ -86,133 +82,127 @@ engineV2.py 及配合的 run-example.sh 是目前运行本项目的主要工具
        * to_0_size*.py 是篡改为 0-size 配置的工具
        * to_big_size\*.py 是篡改为大形状张量的配置的工具。 
 
-   * tester/paddle2torch/是转换能力的核心代码。介绍详见 [4.paddle2torch转换](#4-paddle2torch转换)
+   * tester/paddle2torch/ 是转换能力的核心代码。介绍详见 [4.paddle2torch转换](#4-paddle2torch转换)
 
-3. tools文件夹中存放了一些实用的工具，例如move_config可以用来批量的移动配置，详见[move_config-README.md](./tools/move_config-README.md)。
+3. tools 文件夹中存放了一些实用的工具，例如 move_config.py 可以用来批量的移动配置，error_stat.py 可以一键解析错误日志等。
 
 ## 3. 使用介绍
 
 ### 环境配置
 
-运行环境分为**cpu**环境与**gpu**环境，cpu和gpu上运行的结果**可能存在差异**，即存在cpu上能够正确运行，但gpu上报错的情况。因此需要根据需求正确安装环境。
-
-[PaddlePaddle 安装链接](https://www.paddlepaddle.org.cn/install/quick)
-
-若需要本地编译paddle，可参考链接：https://www.paddlepaddle.org.cn/documentation/docs/zh/install/compile/linux-compile-by-make.html
-
-测试CPU除了通过上述链接安装CPU的最新develop包之外，还可使用如下指令设置Paddle工作在CPU模式：
+建议在虚拟环境或 docker 中进行开发，并正确安装 python 与 nvidia 驱动。
 
+PaddlePaddle 框架运行环境分为 **CPU** 环境与 **GPU** 环境，CPU 和 GPU 上运行的结果 **可能存在差异**，即存在 GPU 上能够正确运行，但 CPU 上报错的情况。请正确安装 *paddlepaddle-gpu* 环境，选择 develop 版本：
+- [使用 pip 快速安装 paddle](https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html)
+- 或者运行命令（cuda>=11.8）：
+```bash
+pip install --pre paddlepaddle-gpu -i https://www.paddlepaddle.org.cn/packages/nightly/cu118/
 ```
-paddle.device.set_device("cpu")
+- 若需要本地编译 Paddle，可参考链接：[Linux 下使用 ninja 从源码编译](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/install/compile/linux-compile-by-ninja.html)
+
+安装 PaddleAPITest 项目其他依赖项：
+- [使用 pip 快速安装 torch](https://pytorch.org/get-started/locally/)
+```bash
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+pip install func_timeout pebble pynvml
 ```
 
-### 使用说明
+paddle 与 torch 的部分依赖项可能发生冲突，请先安装 paddlepaddle-gpu 再安装 torch。重新安装请添加 `--force-reinstall` 参数。
 
-#### A. engine v1
+### 使用说明
 
-所有测试前，**必须创建**一个目录：PaddleAPITest/tester/api_config/test_log/，用于存放测试所产生的测试结果和checkpoint。
+#### A. engineV1
 
-PaddleAPITest目前支持paddle_only、accuracy、paddle_cinn三种测试：
+测试时，`tester/api_config/test_log` 文件夹用于存放测试所产生的测试结果和 checkpoint。
 
->paddle_only，用于单纯把配置在Paddle动态图跑一遍，验证PaddleAPITest 引擎**是否支持**该配置。
->
->accuracy，用于将Paddle API的前反向与**Torch**的前反向做精度对比测试。
->
->paddle_cinn，用于Paddle动态图与Paddle静态图编译器做精度对比测试。
+PaddleAPITest 目前支持 `paddle_only`、`accuracy`、`paddle_cinn` 三种测试：
 
-当测试**单个配置**时，可使用下面的代码，--api_config中输入待测试的配置内容：
+- **paddle_only**，用于单独将 Paddle 动态图跑一遍，验证 paddle 框架以及 PaddleAPITest 引擎**是否支持**该配置。
+- **accuracy**，用于将 Paddle API 的前反向与 **Torch** 的前反向做精度对比测试。
+- **paddle_cinn**，用于将 Paddle 动态图与 Paddle 静态图编译器做精度对比测试。
 
-仅测试paddle**是否支持**：
+当测试**单个配置**时，可使用下面的代码，`--api_config` 中输入待测试的配置内容：
 
-```
+- 仅测试 paddle **是否支持**：
+```bash
 python engine.py --paddle_only=True --api_config='paddle.abs(Tensor([1, 100],"float64"), )'
 ```
 
-测试输出**是否准确**：
-
-```
+- 测试输出**是否准确**：
+```bash
 python engine.py --accuracy=True --api_config='paddle.abs(Tensor([1, 100],"float64"), )'
 ```
+- 动态图和静态图测试：
 
-动态图和静态图测试：
-
-```
+```bash
 python engine.py --paddle_cinn=True --api_config='paddle.abs(Tensor([1, 100],"float64"), )'
 ```
 
-**值得注意**的是配置txt中统一使用双引号"，因此建议--api_config=''使用单引号，或在配置中手动添加转义斜杠\
+> [!NOTE]
+>**注意**: 配置 txt 中统一使用双引号 `"`，因此建议 `--api_config=''` 使用单引号，或在配置中手动添加转义斜杠 `\`。
 
-当需要测试的配置数目较多时，手动单次输入将**非常低效**，这种情况下可以使用如下所示的**批量测试**指令，将配置保存在一个txt中，并将指令中的路径设置为txt的路径即可：
-
-```
+当需要测试的配置数目较多时，手动单次输入将**非常低效**，这种情况下可以使用如下所示的**批量测试**指令，将配置保存在一个 txt 中，并将指令中的路径设置为 txt 的路径即可：
+```bash
 python engine.py --api_config_file=/host_home/wanghuan29/PaddleAPITest/tester/api_config/api_config.txt --accuracy=True > tester/api_config/test_log/log.log 2>&1
 
 python engine.py --api_config_file=/host_home/wanghuan29/PaddleAPITest/tester/api_config/api_config.txt --paddle_only=True > tester/api_config/test_log/log.log 2>&1
 
 python engine.py --api_config_file=/host_home/wanghuan29/PaddleAPITest/tester/api_config/api_config.txt --paddle_cinn=True > tester/api_config/test_log/log.log 2>&1
 ```
 
-当测试配置中有**精度不统一**的情况，需要精度转换时，直接运行测试可能会报错，可加入--test_amp=True
-
+当测试配置中有**精度不统一**的情况，需要精度转换时，直接运行测试可能会报错，可加入`--test_amp=True`。
 
-#### B. engine v2
+#### B. engineV2
 
 `engineV2.py` 是为 PaddleAPITest 项目设计的高性能测试框架，支持多 GPU 并行执行，具备负载均衡、超时处理和崩溃恢复能力。相比原始的 `engine.py` 实现，它能显著提升 Paddle API 配置测试效率，加速比约为 5-10 倍。
 
 功能特性:
-
 - **多 GPU 并行**：拥有灵活的 *gpus 相关参数*，可配置多 GPU 并行测试，支持任务跨 GPU 动态分发
 - **进程级并行**：基于 Pebble 库的 ProcessPool 进程池实现，支持进程的高效并行，每张 GPU 可拥有多个 worker
 - **动态负载均衡**：新的子进程自动分配至负载最轻 GPU，计算资源最优利用
 - **超时/崩溃恢复**：由张量大小推断执行时限（梯度阈值），主动杀死 coredump 进程，自动检测并重启死亡进程
 
-以精度测试为例，配置文件路径为 `tester/api_config/api_config_temp.txt`，输出日志路径为 `tester/api_config/test_log`：
-
-**多进程多 GPU 模式**：
+以精度测试为例，配置文件路径为 `tester/api_config/api_config_tmp.txt`，输出日志路径为 `tester/api_config/test_log`：
 
+**多 GPU 多进程模式**：
 ```bash
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=8 --num_workers_per_gpu=1 >> "tester/api_config/test_log/log.log" 2>&1
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=8 --num_workers_per_gpu=-1 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
-**单进程多 GPU 模式**：
-
+**多 GPU 单进程模式**：
 ```bash
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=8 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
-**单进程单 GPU 模式**：
-
+**单 GPU 单进程模式**：
 ```bash
-export CUDA_VISIBLE_DEVICES=""
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
+export CUDA_VISIBLE_DEVICES="0"
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
 **使用 run.sh 脚本**：
-
 ```bash
 # chmod +x run.sh
 ./run.sh
 ```
+该脚本使用参数：`NUM_GPUS=-1, NUM_WORKERS_PER_GPU=-1`，在后台运行程序，可在修改 `run.sh` 参数后使用。说明文档详见：[engineV2-README.md](engineV2-README.md)
 
-该脚本使用参数：NUM_GPUS=-1, NUM_WORKERS_PER_GPU=-1，在后台运行程序，可在修改 `run.sh` 参数后使用
-
-其说明文档详见 [engineV2.md](./engineV2.md)
+#### C. engineV3
 
+暂无介绍
 
 ## 4. paddle2torch转换
 
 Paddle2Torch 是一个专注于将 PaddlePaddle API 转换为 PyTorch 对应实现的知识工具库，属于 [PaddleAPITest](https://github.com/PFCCLab/PaddleAPITest) 项目的核心组成模块。本模块通过解析 PaddlePaddle API 调用，使用预定义的转换规则与动态代码生成，实现从 PaddlePaddle 到 PyTorch 的自动转换。转换过程将确保代码的语义一致性。
 
 本模块具有精简强悍的架构，仅由三个组件构成：
-
 - *转换引擎 converter.py*
 - *转换配置 mapping.json*
 - *转换规则 rules.py*
 
 代码已完全进行解耦，可以非常容易地迁移至其他代码中。本模块通过 **转换配置** 与 **转换规则** 管理 API 映射关系，因此支持开发者灵活扩展新的 API 转换能力。
 
-本模块的典型应用场景包括：模型迁移、跨框架验证、混合编程等，可为深度学习开发者提供跨框架的互操作性解决方案。
-
-现在转换工具已基本完成对PaddleAPI的转换。
+本模块的典型应用场景包括：模型迁移、跨框架验证、混合编程等，可为深度学习开发者提供跨框架的互操作性解决方案。现在转换工具已基本完成对PaddleAPI的转换。说明文档详见：[paddle_to_torch/README.md](tester/paddle_to_torch/README.md)
 
-其说明文档详见 [paddle2torch.md](./tester/paddle_to_torch/paddle2torch.md)
+> [!TIP]
+>本 README 已经过 ***文心一言 4.5 Turbo*** 润色

engineV2-README.md

@@ -40,36 +40,36 @@
 | `--api_config`              | str   | API 配置字符串（单条测试）                                           |
 | `--api_config_file`         | str   | API 配置文件路径（如`tester/api_config/5_accuracy/accuracy_1.txt`）  |
 | `--api_config_file_pattern` | str   | API 配置文件模式（如 `tester/api_config/5_accuracy/accuracy_*.txt`） |
-| `--paddle_only`             | bool  | 仅运行 Paddle 测试（默认 False）                                     |
-| `--accuracy`                | bool  | 启用精度测试（默认 False）                                           |
+| `--paddle_only`             | bool  | 运行 Paddle 测试（默认 False）                                       |
+| `--accuracy`                | bool  | 运行 Paddle vs Torch 精度测试（默认 False）                          |
 | `--paddle_cinn`             | bool  | 运行 CINN vs Dygraph 对比测试（默认 False）                          |
 | `--num_gpus`                | int   | 使用的 GPU 数量（默认 0，-1 动态最大）                               |
 | `--num_workers_per_gpu`     | int   | 每 GPU 的 worker 进程数（默认 1，-1 动态最大）                       |
-| `--gpu_ids`                 | str   | 使用的 GPU 序号，以逗号分隔（默认 ""，"-1" 动态最大）                 |
-| `--required_memory`         | float | 每 worker 进程预估使用显存（默认 10.0）                              |
+| `--gpu_ids`                 | str   | 使用的 GPU 序号，以逗号分隔（默认 ""，"-1" 动态最大）                |
+| `--required_memory`         | float | 每 worker 进程预估使用显存 GB（默认 10.0）                           |
 | `--test_amp`                | bool  | 启用自动混合精度测试（默认 False）                                   |
 | `--test_cpu`                | bool  | 启用 Paddle CPU 模式测试（默认 False）                               |
 | `--use_cached_numpy`        | bool  | 启用 Numpy 缓存（默认 False）                                        |
 | `--log_dir`                 | str   | 日志输出路径（默认 "tester/api_config/test_log"）                    |
 
 ### 示例命令
 
-以精度测试为例，配置文件路径为 `tester/api_config/api_config_temp.txt`，输出日志路径为 `tester/api_config/test_log`：
+以精度测试为例，配置文件路径为 `tester/api_config/api_config_tmp.txt`，输出日志路径为 `tester/api_config/test_log`：
 
-**多进程多 GPU 模式**：
+**多 GPU 多进程模式**：
 ```bash
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=8 --num_workers_per_gpu=1 >> "tester/api_config/test_log/log.log" 2>&1
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=8 --num_workers_per_gpu=-1 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
-**单进程多 GPU 模式**：
+**多 GPU 单进程模式**：
 ```bash
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=8 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
-**单进程单 GPU 模式**：
+**单 GPU 单进程模式**：
 ```bash
-export CUDA_VISIBLE_DEVICES=""
-python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_temp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
+export CUDA_VISIBLE_DEVICES="0"
+python engineV2.py --accuracy=True --api_config_file="tester/api_config/api_config_tmp.txt" --num_gpus=0 >> "tester/api_config/test_log/log.log" 2>&1
 ```
 
 **使用 run.sh 脚本**：