Accelerate documentation

Acelerador

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Acelerador

O Accelerator é a classe principal para habilitar o treinamento distribuído em qualquer tipo de configuração de treinamento. Leia o tutorial Adicione o Accelerator ao seu código para saber mais sobre como adicionar o Accelerator ao seu script.

Acelerador

classe accelerate.Accelerator

< >

( device_placement: bool = Truesplit_batches: bool = <object object at 0x7f7bf6a755a0>mixed_precision: PrecisionType | str | None = Nonegradient_accumulation_steps: int = 1cpu: bool = Falsedataloader_config: DataLoaderConfiguration | None = Nonedeepspeed_plugin: DeepSpeedPlugin | dict[str, DeepSpeedPlugin] | None = Nonefsdp_plugin: FullyShardedDataParallelPlugin | None = Nonetorch_tp_plugin: TorchTensorParallelPlugin | None = Nonemegatron_lm_plugin: MegatronLMPlugin | None = Nonerng_types: list[str | RNGType] | None = Nonelog_with: str | LoggerType | GeneralTracker | list[str | LoggerType | GeneralTracker] | None = Noneproject_dir: str | os.PathLike | None = Noneproject_config: ProjectConfiguration | None = Nonegradient_accumulation_plugin: GradientAccumulationPlugin | None = Nonestep_scheduler_with_optimizer: bool = Truekwargs_handlers: list[KwargsHandler] | None = Nonedynamo_backend: DynamoBackend | str | None = Nonedynamo_plugin: TorchDynamoPlugin | None = Nonedeepspeed_plugins: DeepSpeedPlugin | dict[str, DeepSpeedPlugin] | None = Noneparallelism_config: ParallelismConfig | None = None )

Parâmetros

  • device_placement (bool, opcional, padrão True) — Se o acelerador deve ou não colocar objetos no dispositivo (tensores gerados pelo dataloader, modelo, etc…).
  • mixed_precision (str, opcional) — Se deve ou não usar treinamento com precisão mista. Escolha entre ‘no’,‘fp16’,‘bf16’ ou ‘fp8’. O valor padrão será o da variável de ambiente ACCELERATE_MIXED_PRECISION, que usará o valor padrão na configuração do accelerate do sistema atual ou a flag passada com o comando accelerate.launch. ‘fp8’ requer a instalação do transformers-engine.
  • gradient_accumulation_steps (int, opcional, padrão 1) — O número de passos que devem passar antes que os gradientes sejam acumulados. Um número > 1 deve ser combinado com Accelerator.accumulate. Se não for passado, o valor padrão será o da variável de ambiente ACCELERATE_GRADIENT_ACCUMULATION_STEPS. Também pode ser configurado por meio de um GradientAccumulationPlugin.
  • cpu (bool, opcional) — Se deve forçar o script a ser executado na CPU. Se definido como True, ignorará a GPU disponível e forçará a execução em apenas um processo.
  • dataloader_config (DataLoaderConfiguration, opcional) — Uma configuração para como os dataloaders devem ser tratados em cenários distribuídos.
  • deepspeed_plugin (DeepSpeedPlugin ou dict de str — DeepSpeedPlugin, opcional): Ajuste seus argumentos relacionados ao DeepSpeed usando este argumento. Este argumento é opcional e pode ser configurado diretamente usando accelerate config. Se estiver usando vários plugins, use a propriedade key configurada de cada plugin para acessá-los a partir de accelerator.state.get_deepspeed_plugin(key). Alias para deepspeed_plugins.
  • fsdp_plugin (FullyShardedDataParallelPlugin, opcional) — Ajuste os argumentos relacionados ao FSDP usando este argumento. Este argumento é opcional e pode ser configurado diretamente usando accelerate config
  • torch_tp_plugin (TorchTensorParallelPlugin, opcional) — Descontinuado: use parallelism_config com tp_size em vez disso.
  • megatron_lm_plugin (MegatronLMPlugin, opcional) — Ajuste seus argumentos relacionados ao MegatronLM usando este argumento. Este argumento é opcional e pode ser configurado diretamente usando accelerate config
  • rng_types (lista de str ou RNGType) — A lista de geradores de números aleatórios a serem sincronizados no início de cada iteração nos seus dataloaders preparados. Deve ser um ou vários dos seguintes:
    • "torch": o gerador de números aleatórios base do torch
    • "cuda": o gerador de números aleatórios CUDA (somente GPU)
    • O tipo de dispositivo de qualquer acelerador registrado do PyTorch: seu gerador de números aleatórios de dispositivo.
    • "xla": o gerador de números aleatórios do XLA (somente TPU)
    • "generator": o torch.Generator do sampler (ou do batch sampler, se não houver sampler no seu dataloader) ou do dataset iterável (se existir), caso o dataset subjacente seja desse tipo.

    O padrão será ["torch"] para versões do PyTorch <=1.5.1 e ["generator"] para versões do PyTorch >= 1.6.

  • log_with (lista de str, LoggerType ou GeneralTracker, opcional) — Uma lista de loggers a serem configurados para o rastreamento de experimentos. Deve ser um ou vários dos seguintes:
    • "all"
    • "tensorboard"
    • "wandb"
    • "trackio"
    • "aim"
    • "comet_ml"
    • "mlflow"
    • "dvclive"
    • "swanlab" Se "all" for selecionado, todos os trackers disponíveis no ambiente serão coletados e inicializados. Também pode aceitar implementações de GeneralTracker para trackers personalizados e pode ser combinado com "all".
  • project_config (ProjectConfiguration, opcional) — Uma configuração para como o salvamento do estado pode ser tratado.
  • project_dir (str, os.PathLike, opcional) — Um caminho para um diretório para armazenar dados, como logs de loggers compatíveis localmente e, potencialmente, checkpoints salvos.
  • step_scheduler_with_optimizer (bool, opcional, padrão True) — Defina como True se o agendador de taxa de aprendizado for atualizado ao mesmo tempo que o otimizador, ou False se isso for feito apenas em certas circunstâncias (por exemplo, no final de cada época).
  • kwargs_handlers (lista de KwargsHandler, opcional) — Uma lista de KwargsHandler para personalizar como os objetos relacionados ao treinamento distribuído, ao profiling ou à precisão mista são criados. Veja kwargs para mais informações.
  • dynamo_backend (str ou DynamoBackend, opcional, padrão "no") — Defina como um dos backends dynamo possíveis para otimizar seu treinamento com torch dynamo.
  • dynamo_plugin (TorchDynamoPlugin, opcional) — Uma configuração para como o torch dynamo deve ser tratado, caso seja necessário mais ajuste do que apenas o backend ou o mode.
  • gradient_accumulation_plugin (GradientAccumulationPlugin, opcional) — Uma configuração para como a acumulação de gradientes deve ser tratada, caso seja necessário mais ajuste do que apenas o gradient_accumulation_steps.

Cria uma instância de um acelerador para treinamento distribuído ou treinamento com precisão mista.

Atributos disponíveis:

  • device (torch.device) — O dispositivo a ser utilizado.
  • distributed_type (DistributedType) — A configuração de treinamento distribuído.
  • local_process_index (int) — O índice do processo na máquina atual.
  • mixed_precision (str) — O modo de precisão mista configurado.
  • num_processes (int) — O número total de processos usados para o treinamento.
  • optimizer_step_was_skipped (bool) — Indica se a atualização do otimizador foi ignorada (devido a estouro de gradiente em precisão mista), caso em que a taxa de aprendizado não deve ser alterada.
  • process_index (int) — O índice geral do processo atual entre todos os processos.
  • state (AcceleratorState) — O estado da configuração distribuída.
  • sync_gradients (bool) — Indica se os gradientes estão atualmente sendo sincronizados entre todos os processos.
  • use_distributed (bool) — Indica se a configuração atual é para treinamento distribuído.

accumulate

< >

( *models )

Parâmetros

  • *models (lista de torch.nn.Module) — Módulos do PyTorch que foram preparados com Accelerator.prepare. Os modelos passados para accumulate() pularão a sincronização de gradientes durante a passagem reversa no treinamento distribuído

Um gerenciador de contexto que envolve levemente e executa o acúmulo de gradientes automaticamente

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=1)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, output in dataloader:
...     with accelerator.accumulate(model):
...         outputs = model(input)
...         loss = loss_func(outputs)
...         loss.backward()
...         optimizer.step()
...         scheduler.step()
...         optimizer.zero_grad()

autocast

< >

( autocast_handler: AutocastKwargs = None )

Aplicará a precisão mista automática dentro do bloco dentro deste gerenciador de contexto, se estiver habilitado. Caso contrário, nada diferente acontecerá.

É possível passar um autocast_handler diferente para substituir o definido no objeto Accelerator. Isso é útil em blocos sob autocast onde você deseja reverter para fp32.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(mixed_precision="fp16")
>>> with accelerator.autocast():
...     train()

backward

< >

( loss**kwargs )

Escala os gradientes de acordo com o GradientAccumulationPlugin e chama o backward() correto com base na configuração.

Deve ser usado em vez de loss.backward().

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> outputs = model(inputs)
>>> loss = loss_fn(outputs, labels)
>>> accelerator.backward(loss)

check_trigger

< >

( )

Verifica se o tensor de gatilho interno foi definido como 1 em qualquer um dos processos. Se for o caso, retorna True e reinicia o tensor de gatilho para 0.

Observação: Não requer wait_for_everyone()

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume later in the training script
>>> # `should_do_breakpoint` is a custom function to monitor when to break,
>>> # e.g. when the loss is NaN
>>> if should_do_breakpoint(loss):
...     accelerator.set_trigger()
>>> # Assume later in the training script
>>> if accelerator.check_trigger():
...     break

limpar

< >

( *objects )

Alias para Accelerate.free_memory, libera todas as referências aos objetos internos armazenados e chama o coletor de lixo. Você deve chamar este método entre dois treinos com modelos/otimizadores diferentes.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, scheduler = ...
>>> model, optimizer, scheduler = accelerator.prepare(model, optimizer, scheduler)
>>> model, optimizer, scheduler = accelerator.clear(model, optimizer, scheduler)

clip_grad_norm_

< >

( parametersmax_normnorm_type = 2 ) → torch.Tensor

Retorna

torch.Tensor

Norma total dos gradientes dos parâmetros (considerados como um único vetor).

Deve ser usado no lugar de torch.nn.utils.clip_grad_norm_.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     if accelerator.sync_gradients:
...         accelerator.clip_grad_norm_(model.parameters(), max_grad_norm)
...     optimizer.step()

clip_grad_value_

< >

( parametersclip_value )

Deve ser usado no lugar de torch.nn.utils.clip_grad_value_.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(gradient_accumulation_steps=2)
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)

>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     if accelerator.sync_gradients:
...         accelerator.clip_grad_value_(model.parameters(), clip_value)
...     optimizer.step()

deepspeed_ulysses_dl_adapter

< >

( dlmodel )

isso normalmente é chamado como parte de prepare, mas quando o dataloader foi preparado separadamente do modelo (para a chamada externa accelerator.prepare), essa chamada adicional precisa ser feita após prepare(model) (veja o HF Trainer como caso de uso)

end_training

< >

( )

Executa comportamentos especiais de encerramento do treinamento, como parar rastreadores apenas no processo principal ou destruir o grupo de processos. Deve ser chamado sempre no final do seu script ao usar rastreamento de experimentos.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(log_with="tensorboard")
>>> accelerator.init_trackers("my_project")
>>> # Do training
>>> accelerator.end_training()

free_memory

< >

( *objects )

Liberará todas as referências aos objetos internos armazenados e chamará o coletor de lixo. Você deve chamar este método entre dois treinos com modelos/otimizadores diferentes. Também redefinirá Accelerator.step para 0.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, scheduler = ...
>>> model, optimizer, scheduler = accelerator.prepare(model, optimizer, scheduler)
>>> model, optimizer, scheduler = accelerator.free_memory(model, optimizer, scheduler)

gather

< >

( tensor ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Parâmetros

  • tensor (torch.Tensor, ou uma tupla/lista/dicionário aninhado de torch.Tensor) — Os tensores a serem reunidos em todos os processos.

Retorna

torch.Tensor, ou uma tupla/lista/dicionário aninhado de torch.Tensor

O(s) tensor(es) coletado(s). Observe que a primeira dimensão do resultado é num_processes multiplicado pela primeira dimensão dos tensores de entrada.

Reúna os valores em tensor entre todos os processos e concatene-os na primeira dimensão. Útil para reagrupar as previsões de todos os processos ao realizar a avaliação.

Nota: Esse gather ocorre em todos os processos.

Exemplo:

>>> # Assuming four processes
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.tensor([accelerator.process_index], device=accelerator.device)
>>> gathered_tensor = accelerator.gather(process_tensor)
>>> gathered_tensor
tensor([0, 1, 2, 3])

gather_for_metrics

< >

( input_datause_gather_object = False )

Parâmetros

  • input_data (torch.Tensor, object, uma tupla/lista/dicionário aninhado de torch.Tensor, ou uma tupla/lista/dicionário aninhado de object) — Os tensores ou objetos para calcular métricas em todos os processos
  • use_gather_object(bool) — Se deve forçar o uso de gather_object em vez de gather (o que já é feito se todos os objetos passados não contiverem tensores). Essa flag pode ser útil para reunir tensores de tamanhos diferentes que não queremos preencher e concatenar ao longo da primeira dimensão. O uso com tensores de GPU não é bem suportado e é ineficiente, pois implica transferência de GPU -> CPU, já que os tensores seriam serializados.

Reúne input_data e, potencialmente, remove duplicatas no último lote em um sistema distribuído. Deve ser usado para reunir as entradas e os alvos para o cálculo de métricas.

Exemplo:

>>> # Assuming two processes, with a batch size of 5 on a dataset with 9 samples
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader = torch.utils.data.DataLoader(range(9), batch_size=5)
>>> dataloader = accelerator.prepare(dataloader)
>>> batch = next(iter(dataloader))
>>> gathered_items = accelerator.gather_for_metrics(batch)
>>> len(gathered_items)
9

get_state_dict

< >

( modelunwrap = True ) → dict

Parâmetros

  • model (torch.nn.Module) — Um modelo do PyTorch enviado por meio de Accelerator.prepare()
  • unwrap (bool, opcional, padrão True) — Se deve retornar o state_dict original subjacente de model ou o state_dict encapsulado

Retorna

dict

O dicionário de estado do modelo, potencialmente sem precisão total.

Retorna o dicionário de estado de um modelo enviado por Accelerator.prepare(), potencialmente sem precisão total.

Exemplo:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> net = torch.nn.Linear(2, 2)
>>> net = accelerator.prepare(net)
>>> state_dict = accelerator.get_state_dict(net)

get_tracker

< >

( name: strunwrap: bool = False ) → GeneralTracker

Parâmetros

  • name (str) — O nome de um tracker, correspondente à propriedade .name.
  • unwrap (bool) — Se deve retornar o mecanismo de rastreamento interno ou o rastreador envolvido (recomendado).

Retorna

GeneralTracker

O tracker correspondente a name, se existir.

Retorna um tracker de self.trackers com base em name apenas no processo principal.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(log_with="tensorboard")
>>> accelerator.init_trackers("my_project")
>>> tensorboard_tracker = accelerator.get_tracker("tensorboard")

join_uneven_inputs

< >

( joinableseven_batches = None )

Parâmetros

  • joinables (list[torch.distributed.algorithms.Joinable]) — Uma lista de modelos ou otimizadores que são subclasses de torch.distributed.algorithms.Joinable. Mais comumente, um PyTorch Module que foi preparado com Accelerator.prepare para treinamento com DistributedDataParallel.
  • even_batches (bool, opcional) — Se definido, isso substituirá o valor de even_batches definido no Accelerator. Se não for fornecido, o valor padrão do Accelerator será usado.

Um gerenciador de contexto que facilita o treinamento ou a avaliação distribuídos em entradas desiguais, que atua como um wrapper ao redor de torch.distributed.algorithms.join. Isso é útil quando o tamanho total do lote não divide uniformemente o comprimento do conjunto de dados.

join_uneven_inputs é suportado apenas para treinamento com Distributed Data Parallel em múltiplas GPUs. Para qualquer outra configuração, este método não terá efeito.

A sobrescrita de even_batches não afetará carregadores de dados do estilo iterável.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator(even_batches=True)
>>> ddp_model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)

>>> with accelerator.join_uneven_inputs([ddp_model], even_batches=False):
...     for input, output in dataloader:
...         outputs = model(input)
...         loss = loss_func(outputs)
...         loss.backward()
...         optimizer.step()
...         optimizer.zero_grad()

load_state

< >

( input_dir: str | None = Noneload_kwargs: dict | None = None**load_model_func_kwargs )

Parâmetros

  • input_dir (str ou os.PathLike) — O nome da pasta em que todos os pesos e estados relevantes foram salvos. Pode ser None se automatic_checkpoint_naming for usado, e recuperará a partir do checkpoint mais recente.
  • load_kwargs (dict, opcional) — Argumentos de palavra-chave adicionais para a função load subjacente, como argumentos opcionais para state_dict e optimizer.
  • load_model_func_kwargs (dict, opcional) — Argumentos de palavra-chave adicionais para carregar o modelo que podem ser passados para a função de carregamento subjacente, como argumentos opcionais para a função load_checkpoint do DeepSpeed ou um map_location para carregar o modelo e o otimizador.

Carrega os estados atuais do modelo, otimizador, scaler, geradores de RNG e objetos registrados.

Deve ser usado apenas em conjunto com Accelerator.save_state(). Se um arquivo não estiver registrado para checkpointing, ele não será carregado se estiver armazenado no diretório.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, lr_scheduler = ...
>>> model, optimizer, lr_scheduler = accelerator.prepare(model, optimizer, lr_scheduler)
>>> accelerator.load_state("my_checkpoint")

local_main_process_first

< >

( )

Permite que o processo principal local entre em um bloco with.

Os outros processos entrarão no bloco with após o processo principal sair.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> with accelerator.local_main_process_first():
...     # This will be printed first by local process 0 then in a seemingly
...     # random order by the other processes.
...     print(f"This will be printed by process {accelerator.local_process_index}")

lomo_backward

< >

( loss: torch.Tensorlearning_rate: float )

Executa a passagem reversa nos otimizadores LOMO.

main_process_first

< >

( )

Permite que o processo principal execute primeiro dentro de um bloco with.

Os outros processos entrarão no bloco with após o processo principal sair.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> with accelerator.main_process_first():
...     # This will be printed first by process 0 then in a seemingly
...     # random order by the other processes.
...     print(f"This will be printed by process {accelerator.process_index}")

talvez_contexto_paralelo

< >

( buffers: list[torch.Tensor] | None = Nonebuffer_seq_dims: list[int] | None = Noneno_restore_buffers: set[torch.Tensor] | None = None )

Parâmetros

  • buffers (list[torch.Tensor], optional) — Buffers que serão fragmentados ao longo da dimensão da sequência. Exemplos comuns são buffers de entradas, rótulos ou embeddings posicionais. Este gerenciador de contexto modificará esses buffers in-place e, após sair do contexto, os buffers serão restaurados ao seu estado original. Para evitar restaurações desnecessárias, você pode usar no_restore_buffers para especificar quais buffers não precisam ser restaurados.
  • buffer_seq_dims (list[int], optional) — Dimensões de sequência dos buffers.
  • no_restore_buffers (set[torch.Tensor], optional) — Este conjunto deve ser um subconjunto de buffers. Especifica quais buffers do argumento buffers não serão restaurados após a saída do contexto. Esses buffers serão então mantidos em estado particionado.

Um gerenciador de contexto que permite o treinamento paralelo de contexto.

context_parallel é atualmente suportado com FSDP2 e requer parallelism_config.cp_size >

  1. Se nenhuma dessas condições for atendida, este gerenciador de contexto não terá efeito, embora, para permitir menos alterações no código, ele não lance uma Exception.

Este gerenciador de contexto precisa ser recriado a cada etapa de treinamento, conforme mostrado no exemplo abaixo.

Exemplo:

>>> for batch in dataloader:
...     with accelerator.maybe_context_parallel(
...         buffers=[batch["input_ids"], batch["attention_mask"]],
...         buffer_seq_dims=[1, 1],
...         no_restore_buffers={batch["input_ids"]},
...     ):
...         outputs = model(batch)
...         ...

no_sync

< >

( model )

Parâmetros

  • model (torch.nn.Module) — Módulo do PyTorch que foi preparado com Accelerator.prepare

Um gerenciador de contexto para desabilitar a sincronização de gradientes entre processos DDP, chamando torch.nn.parallel.DistributedDataParallel.no_sync.

Se model não estiver em DDP, este gerenciador de contexto não faz nada

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader, model, optimizer = accelerator.prepare(dataloader, model, optimizer)
>>> input_a = next(iter(dataloader))
>>> input_b = next(iter(dataloader))

>>> with accelerator.no_sync():
...     outputs = model(input_a)
...     loss = loss_func(outputs)
...     accelerator.backward(loss)
...     # No synchronization across processes, only accumulate gradients
>>> outputs = model(input_b)
>>> accelerator.backward(loss)
>>> # Synchronization across all processes
>>> optimizer.step()
>>> optimizer.zero_grad()

on_last_process

< >

( function: Callable[..., Any] )

Parâmetros

  • function (Callable) — A função a ser decorada.

Um decorador que executa a função decorada apenas no último processo. Também pode ser chamado usando a classe PartialState.

Exemplo:

# Assume we have 4 processes.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_last_process
def print_something():
    print(f"Printed on process {accelerator.process_index}")


print_something()
"Printed on process 3"

on_local_main_process

< >

( function: Callable[..., Any] | None = None )

Parâmetros

  • function (Callable) — A função a ser decorada.

Um decorador que executa a função decorada apenas no processo principal local. Também pode ser chamado usando a classe PartialState.

Exemplo:

# Assume we have 2 servers with 4 processes each.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_local_main_process
def print_something():
    print("This will be printed by process 0 only on each server.")


print_something()
# On server 1:
"This will be printed by process 0 only"
# On server 2:
"This will be printed by process 0 only"

on_local_process

< >

( function: Callable[..., Any] | None = Nonelocal_process_index: int | None = None )

Parâmetros

  • function (Callable, opcional) — A função a ser decorada.
  • local_process_index (int, opcional) — O índice do processo local no qual executar a função.

Um decorador que executa a função decorada apenas em um índice de processo local específico. Também pode ser chamado usando a classe PartialState.

Exemplo:

# Assume we have 2 servers with 4 processes each.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_local_process(local_process_index=2)
def print_something():
    print(f"Printed on process {accelerator.local_process_index}")


print_something()
# On server 1:
"Printed on process 2"
# On server 2:
"Printed on process 2"

on_main_process

< >

( function: Callable[..., Any] | None = None )

Parâmetros

  • function (Callable) — A função a ser decorada.

Um decorador que executa a função decorada apenas no processo principal. Também pode ser chamado usando a classe PartialState.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()


>>> @accelerator.on_main_process
... def print_something():
...     print("This will be printed by process 0 only.")


>>> print_something()
"This will be printed by process 0 only"

on_process

< >

( function: Callable[..., Any] | None = Noneprocess_index: int | None = None )

Parâmetros

  • function (Callable, optional) — A função a ser decorada.
  • process_index (int, optional) — O índice do processo no qual a função será executada.

Um decorador que executa a função decorada apenas em um índice de processo específico. Também pode ser chamado usando a classe PartialState.

Exemplo:

# Assume we have 4 processes.
from accelerate import Accelerator

accelerator = Accelerator()


@accelerator.on_process(process_index=2)
def print_something():
    print(f"Printed on process {accelerator.process_index}")


print_something()
"Printed on process 2"

pad_across_processes

< >

( tensordim = 0pad_index = 0pad_first = False ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Parâmetros

  • tensor (lista/tupla/dicionário aninhado de torch.Tensor) — Os dados a serem coletados.
  • dim (int, opcional, padrão 0) — A dimensão na qual aplicar o preenchimento.
  • pad_index (int, opcional, padrão 0) — O valor usado para o preenchimento.
  • pad_first (bool, opcional, padrão False) — Se o preenchimento deve ser feito no início ou no final.

Retorna

torch.Tensor, ou uma tupla/lista/dicionário aninhado de torch.Tensor

O(s) tensor(es) com preenchimento.

Preencha recursivamente os tensores em uma lista/tupla/dicionário aninhado de tensores de todos os dispositivos até o mesmo tamanho para que possam ser coletados com segurança.

Exemplo:

>>> # Assuming two processes, with the first processes having a tensor of size 1 and the second of size 2
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.arange(accelerator.process_index + 1).to(accelerator.device)
>>> padded_tensor = accelerator.pad_across_processes(process_tensor)
>>> padded_tensor.shape
torch.Size([2])

prepare

< >

( *argsdevice_placement = None )

Parâmetros

  • *args (lista de objetos) — Qualquer um dos seguintes tipos de objetos:
    • torch.utils.data.DataLoader: Dataloader do PyTorch
    • torch.nn.Module: Módulo do PyTorch
    • torch.optim.Optimizer: Otimizador do PyTorch
    • torch.optim.lr_scheduler.LRScheduler: Agendador de taxa de aprendizado do PyTorch
  • device_placement (list[bool], opcional) — Usado para personalizar se a colocação automática de dispositivos deve ser realizada para cada objeto passado. Precisa ser uma lista do mesmo comprimento que args. Não compatível com DeepSpeed ou FSDP.

Prepare todos os objetos passados em args para treinamento distribuído e precisão mista, em seguida, retorne-os na mesma ordem.

Você não precisa preparar um modelo se for usá-lo apenas para inferência, sem nenhum tipo de precisão mista

Exemplos:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model, optimizer, data_loader and scheduler are defined
>>> model, optimizer, data_loader, scheduler = accelerator.prepare(model, optimizer, data_loader, scheduler)
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model, optimizer, data_loader and scheduler are defined
>>> device_placement = [True, True, False, False]
>>> # Will place the first two items passed in automatically to the right device but not the last two.
>>> model, optimizer, data_loader, scheduler = accelerator.prepare(
...     model, optimizer, data_loader, scheduler, device_placement=device_placement
... )

prepare_data_loader

< >

( data_loader: torch.utils.data.DataLoaderdevice_placement = Noneslice_fn_for_dispatch = None )

Parâmetros

  • data_loader (torch.utils.data.DataLoader) — Um DataLoader do PyTorch puro para preparar
  • device_placement (bool, opcional) — Indica se os lotes devem ser colocados no dispositivo adequado no dataloader preparado. O valor padrão é self.device_placement.
  • slice_fn_for_dispatch (Callable, optional) -- If passed, this function will be used to slice tensors across num_processes. Will default to [slice_tensors()](/docs/accelerate/v1.16.0/en/package_reference/utilities#accelerate.utils.slice_tensors). This argument is used only when dispatch_batchesis set toTrue` and will be ignored otherwise.

Prepara um PyTorch DataLoader para treinamento em qualquer configuração distribuída. É recomendado usar Accelerator.prepare() em vez disso.

Exemplo:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> data_loader = torch.utils.data.DataLoader(...)
>>> data_loader = accelerator.prepare_data_loader(data_loader, device_placement=True)

prepare_model

< >

( model: torch.nn.Moduledevice_placement: bool | None = Noneevaluation_mode: bool = False )

Parâmetros

  • model (torch.nn.Module) — Um modelo do PyTorch a ser preparado. Você não precisa preparar um modelo se ele for usado apenas para inferência, sem nenhum tipo de precisão mista
  • device_placement (bool, opcional) — Se o modelo deve ou não ser colocado no dispositivo adequado. O valor padrão é self.device_placement.
  • evaluation_mode (bool, opcional, padrão False) — Se o modelo deve ser configurado apenas para avaliação, aplicando somente precisão mista e torch.compile (se configurado no objeto Accelerator).

Prepara um modelo do PyTorch para treinamento em qualquer configuração distribuída. É recomendado usar Accelerator.prepare() em vez disso.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume a model is defined
>>> model = accelerator.prepare_model(model)

prepare_optimizer

< >

( optimizer: torch.optim.Optimizerdevice_placement = None )

Parâmetros

  • optimizer (torch.optim.Optimizer) — Um otimizador PyTorch padrão para preparar
  • device_placement (bool, opcional) — Se o otimizador deve ou não ser colocado no dispositivo adequado. O valor padrão é self.device_placement.

Prepara um otimizador do PyTorch para treinamento em qualquer configuração distribuída. É recomendado usar Accelerator.prepare() em vez disso.

Exemplo:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> optimizer = torch.optim.Adam(...)
>>> optimizer = accelerator.prepare_optimizer(optimizer, device_placement=True)

prepare_scheduler

< >

( scheduler: LRScheduler )

Parâmetros

  • scheduler (torch.optim.lr_scheduler.LRScheduler) — Um agendador PyTorch puro para preparar

Prepara um agendador do PyTorch para treinamento em qualquer configuração distribuída. É recomendado usar Accelerator.prepare() em vez disso.

Exemplo:

>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> optimizer = torch.optim.Adam(...)
>>> scheduler = torch.optim.lr_scheduler.LambdaLR(optimizer, ...)
>>> scheduler = accelerator.prepare_scheduler(scheduler)

print

< >

( *args**kwargs )

Substituição direta de print() para imprimir apenas uma vez por servidor.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> accelerator.print("Hello world!")

perfil

< >

( profile_handler: ProfileKwargs | None = None )

Parâmetros

  • profile_handler (ProfileKwargs, opcional) — O profile handler a ser usado para este context manager. Se não for passado, será usado o definido no objeto Accelerator.

Fará o perfil do código dentro do gerenciador de contexto. O perfil será salvo em um arquivo Chrome Trace se profile_handler.output_trace_dir estiver definido.

Um profile_handler diferente pode ser passado para substituir o definido no objeto Accelerator.

Exemplo:

# Profile with default settings
from accelerate import Accelerator
from accelerate.utils import ProfileKwargs

accelerator = Accelerator()
with accelerator.profile() as prof:
    train()
accelerator.print(prof.key_averages().table())


# Profile with the custom handler
def custom_handler(prof):
    print(prof.key_averages().table(sort_by="self_cpu_time_total", row_limit=10))


kwargs = ProfileKwargs(schedule_option=dict(wait=1, warmup=1, active=1), on_trace_ready=custom_handler)
accelerator = Accelerator(kwarg_handler=[kwargs])
with accelerator.profile() as prof:
    for _ in range(10):
        train_iteration()
        prof.step()


# Profile and export to Chrome Trace
kwargs = ProfileKwargs(output_trace_dir="output_trace")
accelerator = Accelerator(kwarg_handler=[kwargs])
with accelerator.profile():
    train()

reduce

< >

( tensorreduction = 'sum'scale = 1.0 ) → torch.Tensor, or a nested tuple/list/dictionary of torch.Tensor

Parâmetros

  • tensor (torch.Tensor, ou uma tupla/lista/dicionário aninhado de torch.Tensor) — Os tensores a serem reduzidos entre todos os processos.
  • reduction (str, opcional, padrão “sum”) — Um tipo de redução, pode ser um de ‘sum’, ‘mean’, ‘max’ ou ‘none’. Se ‘none’, nenhuma operação será executada.
  • scale (float, opcional, padrão 1.0) — Um valor de escala padrão a ser aplicado após o reduce, válido apenas no XLA.

Retorna

torch.Tensor, ou uma tupla/lista/dicionário aninhado de torch.Tensor

O(s) tensor(es) reduzido(s).

Reduza os valores em tensor entre todos os processos com base em reduction.

Nota: Todos os processos recebem o valor reduzido.

Exemplo:

>>> # Assuming two processes
>>> import torch
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> process_tensor = torch.arange(accelerator.num_processes) + 1 + (2 * accelerator.process_index)
>>> process_tensor = process_tensor.to(accelerator.device)
>>> reduced_tensor = accelerator.reduce(process_tensor, reduction="sum")
>>> reduced_tensor
tensor([4, 6])

register_for_checkpointing

< >

( *objects )

Faz anotação dos objects e os salva ou carrega durante o save_state ou load_state.

Esses devem ser utilizados quando o estado está sendo carregado ou salvo no mesmo script. Não foram projetados para serem usados em scripts diferentes.

Todo object deve ter uma função load_state_dict e uma função state_dict para ser armazenado.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume `CustomObject` has a `state_dict` and `load_state_dict` function.
>>> obj = CustomObject()
>>> accelerator.register_for_checkpointing(obj)
>>> accelerator.save_state("checkpoint.pt")

register_load_state_pre_hook

< >

( hook: Callable[..., None] ) → torch.utils.hooks.RemovableHandle

Parâmetros

Retorna

torch.utils.hooks.RemovableHandle

um identificador que pode ser usado para remover o hook adicionado chamando handle.remove()

Registra um pré-gancho para ser executado antes de load_checkpoint ser chamado em Accelerator.load_state().

O hook deve ter a seguinte assinatura:

hook(models: list[torch.nn.Module], input_dir: str) -> None

O argumento models são os modelos conforme salvos no estado do acelerador sob accelerator._models, e o argumento input_dir é o argumento input_dir passado para Accelerator.load_state().

Deve ser usado apenas em conjunto com Accelerator.register_save_state_pre_hook(). Pode ser útil para carregar configurações além dos pesos do modelo. Também pode ser usado para sobrescrever o carregamento do modelo com um método personalizado. Nesse caso, certifique-se de remover os modelos já carregados da lista de modelos.

register_save_state_pre_hook

< >

( hook: Callable[..., None] ) → torch.utils.hooks.RemovableHandle

Parâmetros

Retorna

torch.utils.hooks.RemovableHandle

um identificador que pode ser usado para remover o hook adicionado chamando handle.remove()

Registra um pré-gancho para ser executado antes de save_checkpoint ser chamado em Accelerator.save_state().

O hook deve ter a seguinte assinatura:

hook(models: list[torch.nn.Module], weights: list[dict[str, torch.Tensor]], input_dir: str) -> None

O argumento models são os modelos salvos no estado do acelerador sob accelerator._models, o argumento weights são os state dicts dos models e o argumento input_dir é o argumento input_dir passado para Accelerator.load_state().

Deve ser usado apenas em conjunto com Accelerator.register_load_state_pre_hook(). Pode ser útil para salvar configurações além dos pesos do modelo. Também pode ser usado para sobrescrever o salvamento do modelo com um método personalizado. Nesse caso, certifique-se de remover os pesos já carregados da lista de pesos.

salvar

< >

( objfsafe_serialization = False )

Parâmetros

  • obj (object) — O objeto a ser salvo.
  • f (str ou os.PathLike) — Onde salvar o conteúdo de obj.
  • safe_serialization (bool, opcional, padrão False) — Se salvar obj usando safetensors

Salve o objeto passado no disco uma vez por máquina. Use no lugar de torch.save.

Nota: Se save_on_each_node foi passado como um ProjectConfiguration, o objeto será salvo uma vez por nó, em vez de apenas uma vez no nó principal.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> arr = [0, 1, 2, 3]
>>> accelerator.save(arr, "array.pkl")

save_model

< >

( model: torch.nn.Modulesave_directory: Union[str, os.PathLike]max_shard_size: Union[int, str] = '10GB'safe_serialization: bool = True )

Parâmetros

  • model — (torch.nn.Module): Modelo a ser salvo. O modelo pode estar envolto ou não.
  • save_directory (str ou os.PathLike) — Diretório para o qual salvar. Será criado se não existir.
  • max_shard_size (int ou str, opcional, padrão é "10GB") — O tamanho máximo de um checkpoint antes de ser dividido em shards. Os shards do checkpoint terão, então, cada um um tamanho menor que esse valor. Se expresso como uma string, deve ser composto por dígitos seguidos de uma unidade (como "5MB").

    Se um único peso do modelo for maior que max_shard_size, ele ficará em seu próprio shard de checkpoint, que será maior que max_shard_size.

  • safe_serialization (bool, opcional, padrão True) — Se o modelo deve ser salvo usando safetensors ou da maneira tradicional do PyTorch (que usa pickle).

Salve um modelo para que ele possa ser recarregado usando load_checkpoint_in_model

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model = ...
>>> accelerator.save_model(model, save_directory)

save_state

< >

( output_dir: str | None = Nonesafe_serialization: bool = True**save_model_func_kwargs )

Parâmetros

  • output_dir (str ou os.PathLike) — O nome da pasta para salvar todos os pesos e estados relevantes.
  • safe_serialization (bool, opcional, padrão True) — Se o modelo deve ser salvo usando safetensors ou da maneira tradicional do PyTorch (que usa pickle).
  • save_model_func_kwargs (dict, opcional) — Argumentos de palavra-chave adicionais para salvar o modelo que podem ser passados para a função de salvamento subjacente, como argumentos opcionais para a função save_checkpoint do DeepSpeed.

Salva os estados atuais do modelo, otimizador, scaler, geradores de RNG e objetos registrados em uma pasta.

Se um ProjectConfiguration foi passado para o objeto Accelerator com automatic_checkpoint_naming habilitado, os checkpoints serão salvos em self.project_dir/checkpoints. Se o número de salvamentos atuais for maior que total_limit, o salvamento mais antigo será excluído. Cada checkpoint é salvo em pastas separadas nomeadas checkpoint_<iteration>.

Caso contrário, eles são apenas salvos em output_dir.

Deve ser usado apenas quando se deseja salvar um checkpoint durante o treinamento e restaurar o estado no mesmo ambiente.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer, lr_scheduler = ...
>>> model, optimizer, lr_scheduler = accelerator.prepare(model, optimizer, lr_scheduler)
>>> accelerator.save_state(output_dir="my_checkpoint")

set_trigger

< >

( )

Define o tensor de gatilho interno como 1 no processo atual. Uma verificação posterior deve ser feita usando este, que verificará em todos os processos.

Observação: Não requer wait_for_everyone()

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> # Assume later in the training script
>>> # `should_do_breakpoint` is a custom function to monitor when to break,
>>> # e.g. when the loss is NaN
>>> if should_do_breakpoint(loss):
...     accelerator.set_trigger()
>>> # Assume later in the training script
>>> if accelerator.check_breakpoint():
...     break

skip_first_batches

< >

( dataloadernum_batches: int = 0 )

Parâmetros

  • dataloader (torch.utils.data.DataLoader) — O carregador de dados no qual os lotes devem ser ignorados.
  • num_batches (int, opcional, padrão 0) — O número de lotes a serem ignorados

Cria um novo torch.utils.data.DataLoader que ignorará eficientemente as primeiras num_batches.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader, model, optimizer, scheduler = accelerator.prepare(dataloader, model, optimizer, scheduler)
>>> skipped_dataloader = accelerator.skip_first_batches(dataloader, num_batches=2)
>>> # for the first epoch only
>>> for input, target in skipped_dataloader:
...     optimizer.zero_grad()
...     output = model(input)
...     loss = loss_func(output, target)
...     accelerator.backward(loss)
...     optimizer.step()

>>> # subsequent epochs
>>> for input, target in dataloader:
...     optimizer.zero_grad()
...     ...

split_between_processes

< >

( inputs: list | tuple | dict | torch.Tensorapply_padding: bool = False )

Parâmetros

  • inputs (list, tuple, torch.Tensor ou dict de list/tuple/torch.Tensor) — A entrada a ser dividida entre os processos.
  • apply_padding (bool, optional, padrão False) — Se deve aplicar padding repetindo o último elemento da entrada para que todos os processos tenham o mesmo número de elementos. Útil ao tentar executar ações como Accelerator.gather() nas saídas ou ao passar menos entradas do que o número de processos. Se for o caso, lembre-se de descartar os elementos de padding depois.

Divide input entre self.num_processes rapidamente e pode ser usado em seguida nesse processo. Útil ao realizar inferência distribuída, como com diferentes prompts.

Observe que, ao usar um dict, todas as chaves precisam ter o mesmo número de elementos.

Exemplo:

# Assume there are two processes
from accelerate import Accelerator

accelerator = Accelerator()
with accelerator.split_between_processes(["A", "B", "C"]) as inputs:
    print(inputs)
# Process 0
["A", "B"]
# Process 1
["C"]

with accelerator.split_between_processes(["A", "B", "C"], apply_padding=True) as inputs:
    print(inputs)
# Process 0
["A", "B"]
# Process 1
["C", "C"]

trigger_sync_in_backward

< >

( model )

Parâmetros

  • model (torch.nn.Module) — O modelo para o qual acionar a sincronização de gradientes.

Dispare a sincronização dos gradientes na próxima passagem de retropropagação do modelo após várias passagens de propagação direta sob Accelerator.no_sync (aplicável apenas em cenários multi-GPU).

Se o script não for iniciado em modo distribuído, este gerenciador de contexto não faz nada.

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> dataloader, model, optimizer = accelerator.prepare(dataloader, model, optimizer)

>>> with accelerator.no_sync():
...     loss_a = loss_func(model(input_a))  # first forward pass
...     loss_b = loss_func(model(input_b))  # second forward pass
>>> accelerator.backward(loss_a)  # No synchronization across processes, only accumulate gradients
>>> with accelerator.trigger_sync_in_backward(model):
...     accelerator.backward(loss_b)  # Synchronization across all processes
>>> optimizer.step()
>>> optimizer.zero_grad()

unscale_gradients

< >

( optimizer = None )

Parâmetros

  • optimizer (torch.optim.Optimizer ou list[torch.optim.Optimizer], opcional) — O(s) otimizador(es) para os quais as gradientes devem ser desescaladas. Se não definido, as gradientes serão desescaladas em todos os otimizadores que foram passados para prepare().

Desescala os gradientes no treinamento de precisão mista com AMP. Isso é um noop em todos os outros cenários.

Provavelmente deve ser chamado por meio de Accelerator.clipgrad_norm() ou Accelerator.clipgrad_value()

Exemplo:

>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model, optimizer = accelerator.prepare(model, optimizer)
>>> outputs = model(inputs)
>>> loss = loss_fn(outputs, labels)
>>> accelerator.backward(loss)
>>> accelerator.unscale_gradients(optimizer=optimizer)

unwrap_model

< >

( modelkeep_fp32_wrapper: bool = Truekeep_torch_compile: bool = True ) → torch.nn.Module

Parâmetros

  • model (torch.nn.Module) — O modelo a ser desembrulhado.
  • keep_fp32_wrapper (bool, opcional, padrão True) — Se o hook de precisão mista adicionado deve ser mantido.
  • keep_torch_compile (bool, opcional, padrão True) — Se deve ou não desembrulhar o modelo compilado, caso ele esteja compilado.

Retorna

torch.nn.Module

O modelo sem embrulho.

Desfaz a camada adicional que pode ter sido adicionada ao model pelo prepare(). Útil antes de salvar o modelo.

Exemplo:

>>> # Assuming two GPU processes
>>> from torch.nn.parallel import DistributedDataParallel
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> model = accelerator.prepare(MyModel())
>>> print(model.__class__.__name__)
DistributedDataParallel

>>> model = accelerator.unwrap_model(model)
>>> print(model.__class__.__name__)
MyModel

verify_device_map

< >

( model: torch.nn.Module )

Verifica que model não foi preparado para inferência de modelos grandes com um device-map semelhante a auto.

wait_for_everyone

< >

( )

Interromperá a execução do processo atual até que todos os outros processos tenham alcançado esse ponto (portanto, isso não faz nada quando o script é executado em apenas um processo). Útil para fazer antes de salvar um modelo.

Exemplo:

>>> # Assuming two GPU processes
>>> import time
>>> from accelerate import Accelerator

>>> accelerator = Accelerator()
>>> if accelerator.is_main_process:
...     time.sleep(2)
>>> else:
...     print("I'm waiting for the main process to finish its sleep...")
>>> accelerator.wait_for_everyone()
>>> # Should print on every process at the same time
>>> print("Everyone is here")

Utilitários

accelerate.utils.gather_object

< >

( object: Any )

Parâmetros

  • object (lista/tupla/dicionário aninhado de objetos picklable) — Os dados a serem reunidos.

Recolher recursivamente um objeto em uma lista/tupela/dicionário aninhado de objetos de todos os dispositivos.

Update on GitHub