Skip to content

[BIT] Update readme #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wanghuancoder merged 1 commit into from
Jun 5, 2025
Merged

[BIT] Update readme #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 66 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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）结果。
Expand All @@ -58,7 +55,6 @@ engineV2.py 及配合的 run-example.sh 是目前运行本项目的主要工具
- cinn 存放 paddle 静态编译器与动态图方式进行精度对比测试结果。
- fresh_report 存放引擎补齐（paddle_only）和精度转换（accuracy）两个任务中，出现的内核报错或者精度报错。


2. tester 介绍

* api_config 目录存放配置目录的管理情况和相关脚本工具，各配置目录下的文本命名语义一致，参考 5_accuracy 中的 txt 命名含义：
Expand Down Expand Up @@ -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*** 润色
24 changes: 12 additions & 12 deletions engineV2-README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 脚本**：
Expand Down