X-R1：在普通设备中低成本训练0.5B模型-首席AI分享圈

🚀 Invitation to Experience: China's First AI IDE Intelligent Programming Software Trae Chinese version downloadThe DeepSeek-R1 and Doubao-pro are available for unlimited use!

General Introduction

X-R1 是一个由 dhcode-cpp 团队在 GitHub 上开源的强化学习框架，旨在为开发者提供一个低成本、高效的工具，用于训练基于端到端强化学习的模型。该项目受到 DeepSeek-R1 和 open-r1 的启发，专注于构建一个易于上手且资源需求较低的训练环境。X-R1 的核心产品是 R1-Zero，一个参数量为 0.5B 的模型，号称能够在普通硬件上实现高效训练。它支持多种基础模型（0.5B、1.5B、3B），并通过强化学习提升模型的推理能力和格式遵循能力。项目使用 C++ 开发，结合 vLLM 推理引擎和 GRPO 算法，适用于数学推理、中文任务处理等场景。无论是个人开发者还是研究人员，X-R1 都提供了一个值得尝试的开源选择。

X-R1：在普通设备中低成本训练0.5B模型-1

Function List

低成本模型训练：支持在普通硬件（如 4 张 3090 GPU）上训练 0.5B 参数的 R1-Zero 模型。
Enhanced Learning Optimization：通过端到端强化学习（RL），提升模型的推理能力和输出格式准确性。
Multi-model support：兼容 0.5B、1.5B、3B 等多种基础模型，灵活适配不同任务需求。
GPU 加速采样：集成 vLLM 作为在线推理引擎，实现快速 GRPO 数据采样。
中文数学推理：支持中文环境下的数学推理任务，生成清晰的解答过程。
基准测试评估：提供 benchmark.py 脚本，用于评估模型的准确性和格式输出能力。
开源配置：提供详细的配置文件（如 zero3.yaml），便于用户自定义训练参数。

Using Help

X-R1 是一个基于 GitHub 的开源项目，用户需要一定的编程基础和硬件环境来安装和使用。以下是详细的安装与使用指南，帮助你快速上手。

Installation process

environmental preparation
- hardware requirement：至少 1 张 NVIDIA GPU（如 3090），推荐 4 张以获得最佳性能；CPU 支持 AVX/AVX2 指令集；至少 16GB 内存。
- operating system：Linux（如 Ubuntu 20.04+）、Windows（需 WSL2 支持）或 macOS。
- Dependent tools：安装 Git、Python 3.8+、CUDA Toolkit（与 GPU 匹配，如 11.8）、C++ 编译器（如 g++）。
```
sudo apt update
sudo apt install git python3 python3-pip build-essential
```
- GPU 驱动：确保已安装 NVIDIA 驱动并匹配 CUDA 版本，可通过 nvidia-smi Check.
cloning project
在终端中运行以下命令，将 X-R1 仓库下载到本地：
```
git clone https://github.com/dhcode-cpp/X-R1.git
cd X-R1
```
Installation of dependencies
- 安装 Python 依赖：
```
pip install -r requirements.txt
```
- 安装 Accelerate（用于分布式训练）：
```
pip install accelerate
```
Configuration environment
- 根据 GPU 数量编辑配置文件（如 recipes/zero3.yaml），设置 num_processes（如 3，表示 4 张 GPU 中 3 张用于训练，1 张用于 vLLM 推理）。
- 示例配置：
```
num_processes: 3
per_device_train_batch_size: 1
num_generations: 3
```
Verify Installation
Run the following command to check that the environment is properly configured:
```
accelerate config
```
根据提示选择硬件和分布式设置。

Main Functions

1. 模型训练

priming training：使用 GRPO 算法训练 R1-Zero 模型。运行以下命令：

ACCELERATE_LOG_LEVEL=info accelerate launch \
--config_file recipes/zero3.yaml \
--num_processes=3 \
src/x_r1/grpo.py \
--config recipes/X_R1_zero_0dot5B_config.yaml \
> ./output/x_r1_0dot5B_sampling.log 2>&1

Functional Description：此命令启动 0.5B 模型的训练，日志保存在 output 文件夹中。训练过程会利用强化学习优化模型推理能力。
caveat：确保全局批次大小（num_processes * per_device_train_batch_size）能被 num_generations 整除，否则会报错。

2. 中文数学推理

配置数学任务：使用专为中文设计的配置文件：

ACCELERATE_LOG_LEVEL=info accelerate launch \
--config_file recipes/zero3.yaml \
--num_processes=3 \
src/x_r1/grpo.py \
--config recipes/examples/mathcn_zero_3B_config.yaml \
> ./output/mathcn_3B_sampling.log 2>&1

workflow::
1. 准备中文数学问题数据集（如 JSON 格式）。
2. 修改配置文件中的数据集路径。
3. 运行上述命令，模型将生成推理过程并输出到日志。
Featured Functions：支持生成详细的中文解答步骤，适合教育场景。

3. 基准测试

Operational assessment: Use benchmark.py 测试模型性能：

CUDA_VISIBLE_DEVICES=0,1 python ./src/x_r1/benchmark.py \
--model_name='xiaodongguaAIGC/X-R1-0.5B' \
--dataset_name='HuggingFaceH4/MATH-500' \
--output_name='./output/result_benchmark_math500' \
--max_output_tokens=1024 \
--num_gpus=2

结果解读：脚本会输出准确性（accuracy-metric）和格式得分（format-metric），结果保存为 JSON 文件。
Usage Scenarios：验证模型在数学任务中的表现，优化训练参数。

operating skill

Log View：训练或测试完成后，查看日志文件（如 x_r1_0dot5B_sampling.log）以调试问题。
多 GPU 优化：若有更多 GPU，可调整 num_processes cap (a poem) num_gpus 参数，提升并行效率。
error detection：若遇到批次大小错误，调整 per_device_train_batch_size cap (a poem) num_generations 使之匹配。