README.md

# RCCL Auto-Tuning

自动化 RCCL 性能调优工具，通过测试不同算法和协议组合，自动选择最优配置并修改 RCCL 源码。

## 简介

RCCL (ROCm Communication Collectives Library) 是 AMD 为 GPU 提供的标准集合通信库，实现了 all-reduce、all-gather、reduce、broadcast、reduce-scatter、gather、scatter 和 all-to-all 等通信原语。本项目通过自动化测试和性能分析，为特定硬件配置和通信模式找到最优的算法和协议组合，并自动修改 RCCL 源码以应用这些优化。

## 参考链接

- [RCCL 官方仓库](http://112.11.119.99:10068/dcutoolkit/deeplearing/rccl)
- [RCCL-Tests 官方仓库](http://112.11.119.99:10068/dcutoolkit/deeplearing/rccl-tests)
- [RCCL 官方文档](https://rocm.docs.amd.com/projects/rccl/en/latest/)

## 项目结构

```
rccl_packages/
├── rccl-dtk-25.04/          # RCCL 通信库源代码
## 环境要求

### 硬件要求
- ROCm 支持的 AMD GPU
- 支持 PCIe、xGMI 或 InfiniBand 互连的多 GPU 系统

### 软件要求
- ROCm 软件栈 (包含 HIP runtime 和 HIP-Clang)
## 快速开始

### 1. 克隆仓库

```bash
git clone <repository-url>
cd rccl_packages
```

### 2. 编译 RCCL

使用快速编译脚本（推荐）：

```bash
cd rccl-dtk-25.04
./install.sh -i -j 16
```

或手动编译：

```bash
cd rccl-dtk-25.04
rm -rf build
mkdir build
cd build
CXX=/opt/rocm/bin/hipcc cmake -DCMAKE_PREFIX_PATH=/opt/rocm/ ..
make -j 16
```

编译选项说明：
- `-j 16`: 使用 16 个并行编译任务
- `-i`: 安装到系统目录 (需要 sudo)
- `-l`: 仅为本地 GPU 架构编译
- `-f`: 快速编译模式
- `--static`: 编译静态库

### 3. 编译 RCCL-Test

```bash
cd rccl-test
make MPI=1 MPI_HOME=/path/to/mpi
```

编译完成后，测试程序会生成在 `rccl-test/build/` 目录下，包括：
- `all_reduce_perf`
- `all_gather_perf`
- `broadcast_perf`
- `reduce_scatter_perf`
- 等其他通信原语测试程序

### 4. 启用 Peer-to-Peer 传输

对于 PCIe 连接的 GPU，需要设置环境变量：

```bash
export HSA_FORCE_FINE_GRAIN_PCIE=1
```

此设置需要 GPU 支持 peer-to-peer 访问和正确的 Large BAR 地址支持。

### 1. 编译 RCCL

```bash
cd rccl-dtk-25.04
rm -rf build
mkdir build
cd build
CXX=hipcc cmake ..
make -j
```

### 2. 编译 RCCL-Test

```bash
cd rccl-test
make MPI=1
```

编译完成后，测试程序会生成在 `rccl-test/build/` 目录下。

## 使用方法

### 1. 配置主机列表

编辑 `rccl-test-sh_wh/hosts` 文件，添加你的计算节点：

```
node1
node2
node3
```

### 2. 配置拓扑文件（可选）

根据你的硬件拓扑修改 `rccl-test-sh_wh/topo-input.xml`。

### 3. 运行自动调优

```bash
cd rccl-test-sh_wh
./run.sh hosts 100
```

参数说明：
- `hosts`: 主机列表文件
- `100`: 迭代次数（可选）

### 4. 脚本执行流程

1. **性能测试**: 对每个 nRanks 配置，测试 Default、TREE+LL、TREE+SIMPLE、RING+LL、RING+SIMPLE 五种组合
2. **数据分析**: `panduan.py` 分析测试结果，找出性能提升超过 3.5% 的配置
3. **代码修改**: `parse_qz_and_modify_tuning.py` 自动修改 `rccl-dtk-25.04/src/graph/tuning.cc`
4. **重新编译**: 自动重新编译 RCCL 库
5. **循环优化**: 对不同的 nRanks（进程数）重复上述步骤

## 输出文件

- `shuju.txt`: 性能测试数据
- `qz.txt`: 性能分析结果和优化建议

## 核心脚本说明

### run.sh
## 运行 RCCL 单元测试（可选）

RCCL 包含基于 Google Test 的单元测试：

```bash
cd rccl-dtk-25.04/build/test
# 运行所有测试
./rccl-UnitTests
## 高级功能

### NPKit 性能分析

RCCL 集成了 [NPKit](https://github.com/microsoft/npkit) 性能分析框架，可以收集细粒度的跟踪事件。

编译启用 NPKit：
```bash
cd rccl-dtk-25.04/build
CXX=hipcc cmake -DNPKIT_FLAGS="-DENABLE_NPKIT -DENABLE_NPKIT_EVENT_TIME_SYNC_CPU" ..
make -j
```

运行时启用 NPKit：
```bash
export NPKIT_DUMP_DIR=/path/to/dump/directory
# 运行你的 RCCL 程序
```

分析 NPKit 结果：
```bash
python3 npkit_trace_generator.py --npkit_dump_dir /path/to/dump/directory
```

### 自定义安装路径

```bash
cd rccl-dtk-25.04/build
CXX=hipcc cmake -DCMAKE_PREFIX_PATH=/opt/rocm/ -DCMAKE_INSTALL_PREFIX=/custom/path ..
make -j
make install
```

### 构建静态库

```bash
cd rccl-dtk-25.04
./install.sh --static -j 16
```

## 文档

### 在线文档
- [RCCL 官方文档](https://rocm.docs.amd.com/projects/rccl/en/latest/)

### 本地构建文档

```bash
cd rccl-dtk-25.04/docs
pip3 install -r sphinx/requirements.txt
python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
```

生成的文档位于 `_build/html/index.html`。

## 许可证

请参考各子项目的许可证文件：
- RCCL: `rccl-dtk-25.04/LICENSE.txt`
- RCCL-Test: `rccl-test/LICENSE.txt`

原始 RCCL 代码版权归 NVIDIA CORPORATION (2015-2022) 所有。
AMD 修改部分版权归 Advanced Micro Devices, Inc. (2019-2022) 所有。

## 贡献

欢迎提交 Issue 和 Pull Request。

## 相关资源

- [ROCm 官方网站](https://www.amd.com/en/graphics/servers-solutions-rocm)
- [RCCL GitHub](https://github.com/ROCmSoftwarePlatform/rccl)
- [RCCL-Tests GitHub](https://github.com/ROCmSoftwarePlatform/rccl-tests)
- [NPKit 性能分析工具](https://github.com/microsoft/npkit)
- `UT_DATATYPES`: 数据类型 (ncclFloat16, ncclFloat32, ncclBfloat16 等)
- `UT_REDOPS`: 归约操作 (sum, prod, min, max 等)
- `UT_COLLS`: 通信原语 (AllReduce, AllGather, Broadcast 等)

## 性能优化原理

### 算法类型
- **RING**: 环形算法，适合大数据量传输
- **TREE**: 树形算法，适合小数据量和低延迟场景

### 协议类型
- **SIMPLE**: 简单协议，适合大数据量
- **LL (Low Latency)**: 低延迟协议，适合小数据量（通常 < 512KB）
- **LL128**: LL 协议的 128 位变体

### 自动调优策略
1. 测试所有算法和协议组合
2. 对比 Default 配置的性能
3. 识别性能提升超过 3.5% 的配置
4. 根据数据大小范围自动调整优化区间
5. 修改 `tuning.cc` 中的执行时间估算逻辑
6. 重新编译应用优化









## 贡献

欢迎提交 Issue 和 Pull Request。