experimental/cpu/: trl-0.7.11 metadata and description

Homepage Simple index

Train transformer language models with reinforcement learning.

author Leandro von Werra
author_email leandro.vonwerra@gmail.com
  • Development Status :: 2 - Pre-Alpha
  • Intended Audience :: Developers
  • Intended Audience :: Science/Research
  • License :: OSI Approved :: Apache Software License
  • Natural Language :: English
  • Operating System :: OS Independent
  • Programming Language :: Python :: 3
  • Programming Language :: Python :: 3.7
  • Programming Language :: Python :: 3.8
  • Programming Language :: Python :: 3.9
  • Programming Language :: Python :: 3.10
description_content_type text/markdown
keywords ppo,transformers,huggingface,gpt2,language modeling,rlhf
license Apache 2.0
provides_extras test
  • torch >=1.4.0
  • transformers >=4.31.0
  • numpy >=1.18.2
  • accelerate
  • datasets
  • tyro >=0.5.11
  • wandb ; extra == 'benchmark'
  • ghapi ; extra == 'benchmark'
  • openrlbenchmark ==0.2.1a5 ; extra == 'benchmark'
  • requests ; extra == 'benchmark'
  • deepspeed ; extra == 'benchmark'
  • deepspeed >=0.9.5 ; extra == 'deepspeed'
  • parameterized ; extra == 'dev'
  • pytest ; extra == 'dev'
  • pytest-xdist ; extra == 'dev'
  • accelerate ; extra == 'dev'
  • pytest-cov ; extra == 'dev'
  • peft >=0.4.0 ; extra == 'dev'
  • diffusers >=0.18.0 ; extra == 'dev'
  • deepspeed >=0.9.5 ; extra == 'dev'
  • wandb ; extra == 'dev'
  • ghapi ; extra == 'dev'
  • openrlbenchmark ==0.2.1a5 ; extra == 'dev'
  • requests ; extra == 'dev'
  • deepspeed ; extra == 'dev'
  • bitsandbytes <=0.41.1 ; extra == 'dev'
  • diffusers >=0.18.0 ; extra == 'diffusers'
  • peft >=0.4.0 ; extra == 'peft'
  • bitsandbytes <=0.41.1 ; extra == 'quantization'
  • parameterized ; extra == 'test'
  • pytest ; extra == 'test'
  • pytest-xdist ; extra == 'test'
  • accelerate ; extra == 'test'
  • pytest-cov ; extra == 'test'
requires_python >=3.7
File Tox results History
152 KB
Python Wheel

TRL - Transformer Reinforcement Learning

Full stack transformer language models with reinforcement learning.

License Documentation GitHub release

What is it?

trl is a full stack library where we provide a set of tools to train transformer language models and stable diffusion models with Reinforcement Learning, from the Supervised Fine-tuning step (SFT), Reward Modeling step (RM) to the Proximal Policy Optimization (PPO) step. The library is built on top of the transformers library by 🤗 Hugging Face. Therefore, pre-trained language models can be directly loaded via transformers. At this point, most of decoder architectures and encoder-decoder architectures are supported. Refer to the documentation or the examples/ folder for example code snippets and how to run these tools.


How PPO works

Fine-tuning a language model via PPO consists of roughly three steps:

  1. Rollout: The language model generates a response or continuation based on query which could be the start of a sentence.
  2. Evaluation: The query and response are evaluated with a function, model, human feedback or some combination of them. The important thing is that this process should yield a scalar value for each query/response pair.
  3. Optimization: This is the most complex part. In the optimisation step the query/response pairs are used to calculate the log-probabilities of the tokens in the sequences. This is done with the model that is trained and a reference model, which is usually the pre-trained model before fine-tuning. The KL-divergence between the two outputs is used as an additional reward signal to make sure the generated responses don't deviate too far from the reference language model. The active language model is then trained with PPO.

This process is illustrated in the sketch below:

Figure: Sketch of the workflow.


Python package

Install the library with pip:

pip install trl

From source

If you want to run the examples in the repository a few additional libraries are required. Clone the repository and install it with pip:

git clone https://github.com/huggingface/trl.git
cd trl/
pip install .

If you wish to develop TRL, you should install in editable mode:

pip install -e .

How to use


This is a basic example on how to use the SFTTrainer from the library. The SFTTrainer is a light wrapper around the transformers Trainer to easily fine-tune language models or adapters on a custom dataset.

# imports
from datasets import load_dataset
from trl import SFTTrainer

# get dataset
dataset = load_dataset("imdb", split="train")

# get trainer
trainer = SFTTrainer(

# train


This is a basic example on how to use the RewardTrainer from the library. The RewardTrainer is a wrapper around the transformers Trainer to easily fine-tune reward models or adapters on a custom preference dataset.

# imports
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from trl import RewardTrainer

# load model and dataset - dataset needs to be in a specific format
model = AutoModelForSequenceClassification.from_pretrained("gpt2", num_labels=1)
tokenizer = AutoTokenizer.from_pretrained("gpt2")


# load trainer
trainer = RewardTrainer(

# train


This is a basic example on how to use the PPOTrainer from the library. Based on a query the language model creates a response which is then evaluated. The evaluation could be a human in the loop or another model's output.

# imports
import torch
from transformers import AutoTokenizer
from trl import PPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead, create_reference_model
from trl.core import respond_to_batch

# get models
model = AutoModelForCausalLMWithValueHead.from_pretrained('gpt2')
model_ref = create_reference_model(model)

tokenizer = AutoTokenizer.from_pretrained('gpt2')

# initialize trainer
ppo_config = PPOConfig(

# encode a query
query_txt = "This morning I went to the "
query_tensor = tokenizer.encode(query_txt, return_tensors="pt")

# get model response
response_tensor  = respond_to_batch(model, query_tensor)

# create a ppo trainer
ppo_trainer = PPOTrainer(ppo_config, model, model_ref, tokenizer)

# define a reward for response
# (this could be any reward such as human feedback or output from another model)
reward = [torch.tensor(1.0)]

# train model for one step with ppo
train_stats = ppo_trainer.step([query_tensor[0]], [response_tensor[0]], reward)


Proximal Policy Optimisation

The PPO implementation largely follows the structure introduced in the paper "Fine-Tuning Language Models from Human Preferences" by D. Ziegler et al. [paper, code].

Language models

The language models utilize the transformers library by 🤗 Hugging Face. Currently, trl only supports transformers models for text.


  author = {Leandro von Werra and Younes Belkada and Lewis Tunstall and Edward Beeching and Tristan Thrush and Nathan Lambert and Shengyi Huang},
  title = {TRL: Transformer Reinforcement Learning},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/huggingface/trl}}