This folder contains actively maintained examples of use of πŸ€— Transformers organized along NLP tasks. If you are looking for an example that used to be in this folder, it may have moved to our research projects subfolder (which contains frozen snapshots of research projects).

Important noteΒΆ


To make sure you can successfully run the latest versions of the example scripts, you have to install the library from source and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:

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

Then cd in the example folder of your choice and run

pip install -r requirements.txt

Alternatively, you can run the version of the examples as they were for your current version of Transformers via (for instance with v3.5.1):

git checkout tags/v3.5.1

The Big Table of TasksΒΆ

Here is the list of all our examples:

  • with information on whether they are built on top of Trainer/TFTrainer (if not, they still work, they might just lack some features),

  • whether or not they leverage the πŸ€— Datasets library.

  • links to Colab notebooks to walk through the scripts and run them easily,

Task Example datasets Trainer support TFTrainer support πŸ€— Datasets Colab
language-modeling Raw text βœ… - βœ… Open In Colab
multiple-choice SWAG, RACE, ARC βœ… βœ… - Open In Colab
question-answering SQuAD βœ… βœ… βœ… Open In Colab
summarization CNN/Daily Mail βœ… - - -
text-classification GLUE, XNLI βœ… βœ… βœ… Open In Colab
text-generation - n/a n/a - Open In Colab
token-classification CoNLL NER βœ… βœ… βœ… Open In Colab
translation WMT βœ… - - -

Running on TPUsΒΆ

When using Tensorflow, TPUs are supported out of the box as a tf.distribute.Strategy.

When using PyTorch, we support TPUs thanks to pytorch/xla. For more context and information on how to setup your TPU environment refer to Google’s documentation and to the very detailed pytorch/xla README.

In this repo, we provide a very simple launcher script named xla_spawn.py that lets you run our example scripts on multiple TPU cores without any boilerplate. Just pass a --num_cores flag to this script, then your regular training script with its arguments (this is similar to the torch.distributed.launch helper for torch.distributed). Note that this approach does not work for examples that use pytorch-lightning.

For example for run_glue:

python examples/xla_spawn.py --num_cores 8 \
	examples/text-classification/run_glue.py \
	--model_name_or_path bert-base-cased \
	--task_name mnli \
	--data_dir ./data/glue_data/MNLI \
	--output_dir ./models/tpu \
	--overwrite_output_dir \
	--do_train \
	--do_eval \
	--num_train_epochs 1 \
	--save_steps 20000

Feedback and more use cases and benchmarks involving TPUs are welcome, please share with the community.

Logging & Experiment trackingΒΆ

You can easily log and monitor your runs code. The following are currently supported:

Weights & BiasesΒΆ

To use Weights & Biases, install the wandb package with:

pip install wandb

Then log in the command line:

wandb login

If you are in Jupyter or Colab, you should login with:

import wandb

Whenever you use Trainer or TFTrainer classes, your losses, evaluation metrics, model topology and gradients (for Trainer only) will automatically be logged.

When using πŸ€— Transformers with PyTorch Lightning, runs can be tracked through WandbLogger. Refer to related documentation & examples.


To use comet_ml, install the Python package with:

pip install comet_ml

or if in a Conda environment:

conda install -c comet_ml -c anaconda -c conda-forge comet_ml