accelerate

A simple way to train and use NLP models with multi-GPU, TPU, mixed-precision.

Easy to integrate

🤗 Accelerate was created for PyTorch users who like to write the training loop of PyTorch models but are reluctant to write and maintain the boiler code needed to use multi-GPUs/TPU/fp16.

🤗 Accelerate abstracts exactly and only the boiler code related to multi-GPUs/TPU/fp16 and let the rest of your code unchanged.

Here is an example:

Original training code
(CPU or mono-GPU only)
With Accelerate
(CPU/GPU/multi-GPUs/TPUs/fp16)
import torch
import torch.nn.functional as F
from datasets import load_dataset



device = 'cpu'

model = torch.nn.Transformer().to(device)
optim = torch.optim.Adam(
    model.parameters()
)

dataset = load_dataset('my_dataset')
data = torch.utils.data.Dataloader(
    dataset
)





model.train()
for epoch in range(10):
    for source, targets in data:
        source = source.to(device)
        targets = targets.to(device)

        optimizer.zero_grad()

        output = model(source, targets)
        loss = F.cross_entropy(
            output, targets
        )

        loss.backward()

        optimizer.step()
  import torch
  import torch.nn.functional as F
  from datasets import load_dataset

+ from accelerate import Accelerator
+ accelerator = Accelerator()
+ device = accelerator.device

  model = torch.nn.Transformer().to(device)
  optim = torch.optim.Adam(
      model.parameters()
  )

  dataset = load_dataset('my_dataset')
  data = torch.utils.data.Dataloader(
      dataset
  )

+ model, optim, data = accelerator.prepare(
+     model, optim, data
+ )

  model.train()
  for epoch in range(10):
      for source, targets in data:
          source = source.to(device)
          targets = targets.to(device)

          optimizer.zero_grad()

          output = model(source, targets)
          loss = F.cross_entropy(
              output, targets
          )

+         accelerate.backward(loss)

          optimizer.step()

As you can see on this example, by adding 5-lines to any standard PyTorch training script you can now run on any kind of single or distributed node setting (single CPU, single GPU, multi-GPUs and TPUs) as well as with or without mixed precision (fp16).

The same code can then in particular run without modification on your local machine for debugging or your training environment.

🤗 Accelerate even handles the device placement for you (a bit more changes to your code but safer in general), so you can even simplify your training loop further:

Original training code
(CPU or mono-GPU only)
With Accelerate
(CPU/GPU/multi-GPUs/TPUs/fp16)
import torch
import torch.nn.functional as F
from datasets import load_dataset



device = 'cpu'

model = torch.nn.Transformer().to(device)
optim = torch.optim.Adam(
    model.parameters()
)

dataset = load_dataset('my_dataset')
data = torch.utils.data.Dataloader(
    dataset
)





model.train()
for epoch in range(10):
    for source, targets in data:
        source = source.to(device)
        targets = targets.to(device)

        optimizer.zero_grad()

        output = model(source, targets)
        loss = F.cross_entropy(
            output, targets
        )

        loss.backward()

        optimizer.step()
  import torch
  import torch.nn.functional as F
  from datasets import load_dataset

+ from accelerate import Accelerator
+ accelerator = Accelerator()
+ device = accelerator.device

+ model = torch.nn.Transformer()
  optim = torch.optim.Adam(
      model.parameters()
  )

  dataset = load_dataset('my_dataset')
  data = torch.utils.data.Dataloader(
      dataset
  )

+ model, optim, data = accelerator.prepare(
+     model, optim, data
+ )

  model.train()
  for epoch in range(10):
      for source, targets in data:
-
-

          optimizer.zero_grad()

          output = model(source, targets)
          loss = F.cross_entropy(
              output, targets
          )

+         accelerate.backward(loss)

          optimizer.step()

Launching script

🤗 Accelerate also provides an optional CLI tool that allows you to quickly configure and test your training environment then launch the scripts. No need to remember how to use torch.distributed.launch or to write a specific launcher for TPU training!
On your machine(s) just run:

accelerate config

and answer the questions asked. This will generate a config file that will be used automatically to properly set the default options when doing

accelerate launch my_script.py --args_to_my_script

For instance, here is how you would run the GLUE example on the MRPC task (from the root of the repo):

accelerate launch examples/nlp_example.py

Why should I use 🤗 Accelerate?

You should use 🤗 Accelerate when you want to easily run your training scripts in a distributed environment without having to renounce full control over your training loop. This is not a high-level framework above PyTorch, just a thin wrapper so you don't have to learn a new library, In fact the whole API of 🤗 Accelerate is in one class, the Accelerator object.

Why shouldn't use 🤗 Accelerate?

You shouldn't use 🤗 Accelerate if you don't want to write a training loop yourself. There are plenty of high-level libraries above PyTorch that will offer you that, 🤗 Accelerate is not one of them.

Installation

This repository is tested on Python 3.6+ and PyTorch 1.4.0+

You should install 🤗 Accelerate in a virtual environment. If you're unfamiliar with Python virtual environments, check out the user guide.

First, create a virtual environment with the version of Python you're going to use and activate it.

Then, you will need to install PyTorch: refer to the official installation page regarding the specific install command for your platform. Then 🤗 Accelerate can be installed using pip as follows:

pip install accelerate

Supported integrations

  • CPU only
  • single GPU
  • multi-GPU on one node (machine)
  • multi-GPU on several nodes (machines)
  • TPU
  • FP16 with native AMP (apex on the roadmap)

GitHub