trl README

The project's README from github.com/huggingface/trl. As one markdown file: README.md.

TRL - Transformers Reinforcement Learning

TRL Banner


A comprehensive library to post-train foundation models

License Documentation GitHub release Hugging Face Hub

🎉 What's New

📜 Training beyond 1M tokens: A new long context guide walks through the four things that break as sequences grow — the loss, the positions, the activations and the memory of a single GPU — and ends on an example that trains Qwen3-8B on million-token sequences on one 8-GPU node.

Overview

TRL is a cutting-edge library designed for post-training foundation models using advanced techniques like Supervised Fine-Tuning (SFT), Group Relative Policy Optimization (GRPO), and Direct Preference Optimization (DPO). Built on top of the 🤗 Transformers ecosystem, TRL supports a variety of model architectures and modalities, and can be scaled-up across various hardware setups.

Highlights

Installation

Python Package

Install the library using pip:

pip install trl

From source

If you want to use the latest features before an official release, you can install TRL from source:

pip install git+https://github.com/huggingface/trl.git

Repository

If you want to use the examples you can clone the repository with the following command:

git clone https://github.com/huggingface/trl.git

Quick Start

For more flexibility and control over training, TRL provides dedicated trainer classes to post-train language models or PEFT adapters on a custom dataset. Each trainer in TRL is a light wrapper around the 🤗 Transformers trainer and natively supports distributed training methods like DDP, DeepSpeed ZeRO, and FSDP.

SFTTrainer

Here is a basic example of how to use the SFTTrainer:

from trl import SFTTrainer
from datasets import load_dataset

dataset = load_dataset("trl-lib/Capybara", split="train")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset,
)
trainer.train()

GRPOTrainer

GRPOTrainer implements the Group Relative Policy Optimization (GRPO) algorithm that is more memory-efficient than PPO and was used to train Deepseek AI's R1.

from datasets import load_dataset
from trl import GRPOTrainer
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)
trainer.train()

[!NOTE] For reasoning models, use the reasoning_accuracy_reward() function for better results.

DPOTrainer

DPOTrainer implements the popular Direct Preference Optimization (DPO) algorithm that was used to post-train Llama 3 and many other models. Here is a basic example of how to use the DPOTrainer:

from datasets import load_dataset
from trl import DPOTrainer

dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = DPOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=dataset,
)
trainer.train()

KTOTrainer

KTOTrainer implements the Kahneman-Tversky Optimization (KTO) algorithm, which aligns models from simple binary (desirable / undesirable) feedback rather than paired preferences. Here is a basic example of how to use the KTOTrainer:

from datasets import load_dataset
from trl import KTOTrainer

dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

trainer = KTOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=dataset,
)
trainer.train()

RewardTrainer

Here is a basic example of how to use the RewardTrainer:

from trl import RewardTrainer
from datasets import load_dataset

dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = RewardTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    train_dataset=dataset,
)
trainer.train()

Command Line Interface (CLI)

You can use the TRL Command Line Interface (CLI) to quickly get started with post-training methods like Supervised Fine-Tuning (SFT) or Direct Preference Optimization (DPO):

SFT:

trl sft --model_name_or_path Qwen/Qwen2.5-0.5B \
    --dataset_name trl-lib/Capybara \
    --output_dir Qwen2.5-0.5B-SFT

DPO:

trl dpo --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --dataset_name argilla/Capybara-Preferences \
    --output_dir Qwen2.5-0.5B-DPO

KTO:

trl kto --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --dataset_name trl-lib/kto-mix-14k \
    --output_dir Qwen2.5-0.5B-KTO

Read more about CLI in the relevant documentation section or use --help for more details.

Development

If you want to contribute to trl or customize it to your needs make sure to read the contribution guide and make sure you make a dev install:

git clone https://github.com/huggingface/trl.git
cd trl/
pip install -e .[dev]

Experimental

A minimal incubation area is available under trl.experimental for unstable / fast-evolving features. Anything there may change or be removed in any release without notice.

Example:

from trl.experimental.new_trainer import NewTrainer

Read more in the Experimental docs.

Citation

@software{vonwerra2020trl,
  title   = {{TRL: Transformers Reinforcement Learning}},
  author  = {von Werra, Leandro and Belkada, Younes and Tunstall, Lewis and Beeching, Edward and Thrush, Tristan and Lambert, Nathan and Huang, Shengyi and Rasul, Kashif and Gallouédec, Quentin},
  license = {Apache-2.0},
  url     = {https://github.com/huggingface/trl},
  year    = {2020}
}

License

This repository's source code is available under the Apache-2.0 License.

trl (huggingface/trl)

Searching Database…

19.5K ·GitHub
Что это такое?TRL (Transformers Reinforcement Learning) — это библиотека от Hugging Face для пост-тренинга базовых моделей: дообучения с помощью таких техник, как SFT, GRPO и DPO, поверх стека Transformers.
Это Python-библиотека, которую я импортирую, или приложение, которое я запускаю?Это Python-библиотека: каждый тренер (SFTTrainer, DPOTrainer, GRPOTrainer и другие) — тонкая обёртка над стандартным Transformers Trainer, поэтому он встраивается в уже существующий рабочий процесс на Transformers.
Как установить её и запустить первый тренинг?Установите через pip install trl (или из исходников, если нужны возможности из пре-релиза); при желании склонируйте репозиторий с примерами, затем выберите тренер и укажите на свой датасет.
Тренинг идёт локально на моей машине, или нужны API-ключи для облака?Всё работает локально на вашем железе — API-ключи и аккаунты не нужны. Библиотека построена на стеке Hugging Face: Transformers, Accelerate для распределённых запусков, плюс опциональные PEFT и Unsloth.
Всё ли в библиотеке настолько стабильно, чтобы полагаться на это?Не совсем: код внутри trl.experimental — это площадка для нестабильных, быстро меняющихся функций. Любое из них может измениться или исчезнуть в любом релизе без предупреждения.
Мне обязательно нужен кластер с несколькими GPU, чтобы реально этим пользоваться?Не обязательно: библиотека масштабируется от одной GPU до многоузловых кластеров, а интеграция с PEFT (квантизация, LoRA/QLoRA) позволяет дообучать большие модели на скромном железе.
Что такое GRPO и почему его выбирают вместо PPO?GRPO (Group Relative Policy Optimization) — метод обучения с подкреплением, который расходует меньше памяти, чем PPO. Именно его DeepSeek использовала для обучения R1, а в TRL он доступен как GRPOTrainer.
Что такое KTO и когда его стоит использовать?KTO (Kahneman-Tversky Optimization) выравнивает модели по простым бинарным меткам «хороший/плохой» ответ, а не по парам предпочтений — это удобно, когда у вас есть только отметки «нравится/не нравится». В TRL для этого есть KTOTrainer.
Какие-нибудь известные модели обучались этими тренерами пост-тренингом?Да — в README отмечается, что GRPO использовался для обучения DeepSeek R1, а DPO — для пост-тренинга Llama 3 и многих других моделей.
А тренинг с очень длинным контекстом он поддерживает?Есть новый гайд по длинному контексту, который разбирает четыре вещи, ломающиеся при росте длины последовательностей, — loss, позиции, активации и память одной GPU, — и завершается примером обучения Qwen3-8B на последовательностях в миллион токенов на одном узле с 8 GPU.
Size
36.1 MB
Stars
19.5K
Age
6y
Commits · 90 Days