Accelerate documentation

Acelerador

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Acelerador

La clase Accelerator es la principal para habilitar el entrenamiento distribuido en cualquier tipo de configuración de entrenamiento. Lea el tutorial Add Accelerator to your code para aprender más sobre cómo agregar Accelerator a su script.

Acelerador

clase 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, valor predeterminado True) — Indica si el acelerador debe colocar los objetos en el dispositivo (tensores generados por el dataloader, modelo, etc…).
  • mixed_precision (str, opcional) — Indica si se debe usar entrenamiento con precisión mixta. Elija entre ‘no’,‘fp16’,‘bf16’ o ‘fp8’. Por defecto, se usará el valor de la variable de entorno ACCELERATE_MIXED_PRECISION, que a su vez usará el valor predeterminado de la configuración de accelerate del sistema actual o la bandera pasada con el comando accelerate.launch. ‘fp8’ requiere la instalación de transformers-engine.
  • gradient_accumulation_steps (int, opcional, valor predeterminado 1) — El número de pasos que deben transcurrir antes de que se acumulen los gradientes. Un número > 1 debe combinarse con Accelerator.accumulate. Si no se especifica, se usará el valor de la variable de entorno ACCELERATE_GRADIENT_ACCUMULATION_STEPS. También puede configurarse mediante un GradientAccumulationPlugin.
  • cpu (bool, opcional) — Indica si se debe forzar la ejecución del script en la CPU. Si se establece en True, se ignorará cualquier GPU disponible y se forzará la ejecución en un solo proceso.
  • dataloader_config (DataLoaderConfiguration, opcional) — Una configuración para cómo deben manejarse los dataloaders en escenarios distribuidos.
  • deepspeed_plugin (DeepSpeedPlugin o dict de str — DeepSpeedPlugin, opcional): Ajusta tus argumentos relacionados con DeepSpeed mediante este argumento. Este argumento es opcional y se puede configurar directamente usando accelerate config. Si se utilizan varios plugins, usa la propiedad key configurada de cada plugin para acceder a ellos desde accelerator.state.get_deepspeed_plugin(key). Alias de deepspeed_plugins.
  • fsdp_plugin (FullyShardedDataParallelPlugin, opcional) — Ajusta los argumentos relacionados con FSDP mediante este argumento. Este argumento es opcional y se puede configurar directamente usando accelerate config
  • torch_tp_plugin (TorchTensorParallelPlugin, opcional) — No recomendado: usa parallelism_config con tp_size en su lugar.
  • megatron_lm_plugin (MegatronLMPlugin, opcional) — Ajusta los argumentos relacionados con MegatronLM mediante este argumento. Este argumento es opcional y se puede configurar directamente usando accelerate config
  • rng_types (lista de str o RNGType) — La lista de generadores de números aleatorios que se deben sincronizar al inicio de cada iteración en tus dataloaders preparados. Debe ser uno o varios de los siguientes:
    • "torch": el generador de números aleatorios base de torch
    • "cuda": el generador de números aleatorios de CUDA (solo GPU)
    • El tipo de dispositivo de cualquier acelerador de PyTorch registrado: su generador de números aleatorios de dispositivo.
    • "xla": el generador de números aleatorios de XLA (solo TPU)
    • "generator": el torch.Generator del sampler (o del batch sampler si no hay sampler en su dataloader) o del dataset iterable (si existe) si el dataset subyacente es de ese tipo.

    Por defecto será ["torch"] para versiones de PyTorch <=1.5.1 y ["generator"] para versiones de PyTorch >= 1.6.

  • log_with (lista de str, LoggerType o GeneralTracker, opcional) — Una lista de registradores para configurar el seguimiento de experimentos. Debe ser uno o varios de:
    • "all"
    • "tensorboard"
    • "wandb"
    • "trackio"
    • "aim"
    • "comet_ml"
    • "mlflow"
    • "dvclive"
    • "swanlab" Si se selecciona "all", se detectarán todos los trackers disponibles en el entorno y se inicializarán. También puede aceptar implementaciones de GeneralTracker para trackers personalizados, y puede combinarse con "all".
  • project_config (ProjectConfiguration, opcional) — Una configuración para cómo se puede manejar el guardado del estado.
  • project_dir (str, os.PathLike, opcional) — Una ruta a un directorio para almacenar datos, como registros de registradores compatibles localmente y, potencialmente, puntos de control guardados.
  • step_scheduler_with_optimizer (bool, opcional, valor predeterminado True) — Establezca True si el programador de la tasa de aprendizaje se actualiza al mismo tiempo que el optimizador, o False si solo se hace en ciertas circunstancias (al final de cada época, por ejemplo).
  • kwargs_handlers (lista de KwargsHandler, opcional) — Una lista de KwargsHandler para personalizar cómo se crean los objetos relacionados con el entrenamiento distribuido, el perfilado o la precisión mixta. Consulte kwargs para obtener más información.
  • dynamo_backend (str o DynamoBackend, opcional, valor predeterminado "no") — Establezca uno de los backends de dynamo posibles para optimizar su entrenamiento con torch dynamo.
  • dynamo_plugin (TorchDynamoPlugin, opcional) — Una configuración para cómo debe manejarse torch dynamo, si se necesita más ajuste que solo el backend o el mode.
  • gradient_accumulation_plugin (GradientAccumulationPlugin, opcional) — Una configuración para cómo debe manejarse la acumulación de gradientes, si se necesita más ajuste que solo el de gradient_accumulation_steps.

Crea una instancia de un acelerador para el entrenamiento distribuido o el entrenamiento con precisión mixta.

Attributos disponibles:

  • device (torch.device) — El dispositivo a utilizar.
  • distributed_type (DistributedType) — La configuración de entrenamiento distribuido.
  • local_process_index (int) — El índice del proceso en la máquina actual.
  • mixed_precision (str) — El modo de precisión mixta configurado.
  • num_processes (int) — El número total de procesos utilizados para el entrenamiento.
  • optimizer_step_was_skipped (bool) — Indica si la actualización del optimizador se omitió (debido a un desbordamiento de gradientes en precisión mixta), en cuyo caso no se debe cambiar la tasa de aprendizaje.
  • process_index (int) — El índice general del proceso actual entre todos los procesos.
  • state (AcceleratorState) — El estado de la configuración distribuida.
  • sync_gradients (bool) — Indica si los gradientes se están sincronizando actualmente entre todos los procesos.
  • use_distributed (bool) — Indica si la configuración actual es para entrenamiento distribuido.

accumulate

< >

( *models )

Parámetros

  • *models (lista de torch.nn.Module) — Módulos de PyTorch que se prepararon con Accelerator.prepare. Los modelos pasados a accumulate() omitirán la sincronización de gradientes durante la propagación inversa en el entrenamiento distribuido

Un administrador de contexto que envolverá ligeramente y realizará la acumulación de gradientes automáticamente

Ejemplo:

>>> 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á la precisión mixta automática dentro del bloque dentro de este administrador de contexto, si está habilitada. De lo contrario, no ocurrirá nada diferente.

Se puede pasar un autocast_handler diferente para anular el establecido en el objeto Accelerator. Esto es útil en bloques bajo autocast donde se desea volver a fp32.

Ejemplo:

>>> from accelerate import Accelerator

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

backward

< >

( loss**kwargs )

Escala los gradientes de acuerdo con GradientAccumulationPlugin y llama al backward() correcto según la configuración.

Debe usarse en lugar de loss.backward().

Ejemplo:

>>> from accelerate import Accelerator

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

check_trigger

< >

( )

Comprueba si el tensor de activación interno se ha establecido en 1 en alguno de los procesos. Si es así, devuelve True y restablece el tensor de activación a 0.

Nota: No requiere wait_for_everyone()

Ejemplo:

>>> 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

clear

< >

( *objects )

Alias de Accelerate.free_memory, libera todas las referencias a los objetos internos almacenados y llama al recolector de basura. Debería llamar a este método entre dos entrenamientos con modelos/optimizadores diferentes.

Ejemplo:

>>> 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

Devuelve

torch.Tensor

Norma total de los gradientes de los parámetros (considerados como un único vector).

Debe usarse en lugar de torch.nn.utils.clip_grad_norm_.

Ejemplo:

>>> 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 )

Debe usarse en lugar de torch.nn.utils.clip_grad_value_.

Ejemplo:

>>> 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 )

esto normalmente se llama como parte de prepare, pero cuando el dataloader se preparó por separado del modelo (para la llamada externa a accelerator.prepare), se debe realizar esta llamada adicional después de prepare(model) (vea HF Trainer como caso de uso)

end_training

< >

( )

Ejecuta comportamientos especiales de finalización del entrenamiento, como detener los trackers solo en el proceso principal o destruir el grupo de procesos. Debe llamarse siempre al final de su script si está usando seguimiento de experimentos.

Ejemplo:

>>> from accelerate import Accelerator

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

free_memory

< >

( *objects )

Liberará todas las referencias a los objetos internos almacenados y llamará al recolector de basura. Debería llamar a este método entre dos entrenamientos con modelos/optimizadores diferentes. También restablecerá Accelerator.step a 0.

Ejemplo:

>>> 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, o una tupla/lista/diccionario anidado de torch.Tensor) — Los tensores que se deben recopilar en todos los procesos.

Devuelve

torch.Tensor, o una tupla/lista/diccionario anidado de torch.Tensor

El (los) tensor(es) recopilado(s). Tenga en cuenta que la primera dimensión del resultado es num_processes multiplicado por la primera dimensión de los tensores de entrada.

Reúne los valores de tensor en todos los procesos y concátalos en la primera dimensión. Útil para reagrupar las predicciones de todos los procesos al realizar la evaluación.

Nota: Esta operación de recolección se realiza en todos los procesos.

Ejemplo:

>>> # 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, una tupla/lista/diccionario anidado de torch.Tensor, o una tupla/lista/diccionario anidado de object) — Los tensores u objetos para calcular métricas en todos los procesos
  • use_gather_object(bool) — Si se debe usar forzosamente gather_object en lugar de gather (esto ya se hace si todos los objetos pasados no contienen tensores). Esta bandera puede ser útil para reunir tensores de diferentes tamaños que no queremos rellenar y concatenar a lo largo de la primera dimensión. Su uso con tensores de GPU no está bien soportado y es ineficiente, ya que implica una transferencia de GPU -> CPU, dado que los tensores se serializarían.

Reúne input_data y, en un sistema distribuido, elimina posibles duplicados en el último lote. Debe usarse para reunir las entradas y los objetivos para el cálculo de métricas.

Ejemplo:

>>> # 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) — Un modelo de PyTorch enviado a través de Accelerator.prepare()
  • unwrap (bool, opcional, valor predeterminado True) — Si se devuelve el state_dict original subyacente de model o el state_dict envuelto

Devuelve

dict

El diccionario de estado del modelo, posiblemente sin precisión completa.

Devuelve el diccionario de estado de un modelo enviado a través de Accelerator.prepare(), posiblemente sin precisión completa.

Ejemplo:

>>> 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) — El nombre de un tracker, que corresponde a la propiedad .name.
  • unwrap (bool) — Si se debe devolver el mecanismo de seguimiento interno o el tracker envuelto en su lugar (recomendado).

Devuelve

GeneralTracker

El tracker correspondiente a name si existe.

Devuelve un tracker de self.trackers en función de name solo en el proceso principal.

Ejemplo:

>>> 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]) — Una lista de modelos u optimizadores que heredan de torch.distributed.algorithms.Joinable. Lo más habitual es un PyTorch Module preparado con Accelerator.prepare para el entrenamiento con DistributedDataParallel.
  • even_batches (bool, opcional) — Si se establece, este valor anulará el de even_batches configurado en el Accelerator. Si no se proporciona, se utilizará el valor predeterminado de Accelerator.

Un gestor de contexto que facilita el entrenamiento o la evaluación distribuidos con entradas desiguales, que actúa como un envoltorio alrededor de torch.distributed.algorithms.join. Esto es útil cuando el tamaño total del lote no divide uniformemente la longitud del conjunto de datos.

join_uneven_inputs solo se admite para el entrenamiento con Distributed Data Parallel en varias GPU. En cualquier otra configuración, este método no tendrá efecto.

La sobrescritura de even_batches no afectará a los cargadores de datos de estilo iterable.

Ejemplo:

>>> 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()

cargar_state

< >

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

Parámetros

  • input_dir (str o os.PathLike) — El nombre de la carpeta en la que se guardaron todos los pesos y estados relevantes. Puede ser None si se usa automatic_checkpoint_naming, y tomará el último punto de control disponible.
  • load_kwargs (dict, opcional) — Argumentos de palabra clave adicionales para la función load subyacente, como los argumentos opcionales para state_dict y optimizer.
  • load_model_func_kwargs (dict, opcional) — Argumentos de palabra clave adicionales para cargar el modelo que pueden pasarse a la función de carga subyacente, como los argumentos opcionales de la función load_checkpoint de DeepSpeed o un map_location para cargar el modelo y el optimizador.

Carga los estados actuales del modelo, el optimizador, el escalador, los generadores de RNG y los objetos registrados.

Debe usarse únicamente en conjunto con Accelerator.save_state(). Si un archivo no está registrado para el checkpointing, no se cargará si se encuentra almacenado en el directorio.

Ejemplo:

>>> 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 el proceso principal local entre en un bloque with.

Los demás procesos entrarán en el bloque with después de que el proceso principal finalice.

Ejemplo:

>>> 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 )

Ejecuta la propagación hacia atrás en los optimizadores LOMO.

main_process_first

< >

( )

Permite que el proceso principal vaya primero dentro de un bloque with.

Los demás procesos entrarán en el bloque with después de que el proceso principal finalice.

Ejemplo:

>>> 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}")

maybe_context_parallel

< >

( 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 se van a fragmentar a lo largo de la dimensión de secuencia. Ejemplos comunes son inputs, labels o buffers de positional embedding. Este context manager modificará estos buffers in-place, y después de salir del contexto, los buffers se restaurarán a su estado original. Para evitar restauraciones innecesarias, puedes usar no_restore_buffers para especificar qué buffers no necesitan ser restaurados.
  • buffer_seq_dims (list[int], optional) — Dimensiones de secuencia de buffers.
  • no_restore_buffers (set[torch.Tensor], optional) — Este conjunto debe ser un subconjunto de buffers. Especifica qué buffers del argumento buffers no se restaurarán después de que el contexto finalice. Estos buffers se mantendrán entonces en estado fragmentado.

Un administrador de contexto que permite el entrenamiento paralelo de contexto.

context_parallel es compatible actualmente con FSDP2 y requiere parallelism_config.cp_size >

  1. Si alguna de estas condiciones no se cumple, este administrador de contexto no tendrá ningún efecto, aunque para permitir menos cambios en el código no lanzará una Exception.

Este gestor de contexto debe recrearse en cada paso de entrenamiento, como se muestra en el ejemplo siguiente.

Ejemplo:

>>> 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 de PyTorch preparado con Accelerator.prepare

Un gestor de contexto para deshabilitar las sincronizaciones de gradientes entre procesos DDP mediante la llamada a torch.nn.parallel.DistributedDataParallel.no_sync.

Si model no está en DDP, este administrador de contexto no hace nada

Ejemplo:

>>> 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) — La función a decorar.

Un decorador que ejecutará la función decorada solo en el último proceso. También se puede llamar usando la clase PartialState.

Ejemplo:

# 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) — La función a decorar.

Un decorador que ejecutará la función decorada solo en el proceso principal local. También se puede llamar usando la clase PartialState.

Ejemplo:

# 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) — La función a decorar.
  • local_process_index (int, opcional) — El índice del proceso local en el que se ejecutará la función.

Un decorador que ejecutará la función decorada solo en un índice de proceso local dado. También se puede llamar usando la clase PartialState.

Ejemplo:

# 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) — La función a decorar.

Un decorador que ejecutará la función decorada solo en el proceso principal. También se puede llamar usando la clase PartialState.

Ejemplo:

>>> 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) — La función a decorar.
  • process_index (int, optional) — El índice del proceso en el que se ejecutará la función.

Un decorador que ejecutará la función decorada solo en un índice de proceso dado. También se puede llamar usando la clase PartialState.

Ejemplo:

# 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/diccionario anidado de torch.Tensor) — Los datos que se deben recopilar.
  • dim (int, opcional, valor predeterminado 0) — La dimensión sobre la que se debe rellenar.
  • pad_index (int, opcional, valor predeterminado 0) — El valor con el que se rellena.
  • pad_first (bool, opcional, valor predeterminado False) — Si se debe rellenar al principio o al final.

Devuelve

torch.Tensor, o una tupla/lista/diccionario anidado de torch.Tensor

El/los tensor(es) rellenos.

Rellena recursivamente los tensores en una lista/tupla/diccionario anidado de tensores de todos los dispositivos hasta el mismo tamaño para que puedan recopilarse de forma segura.

Ejemplo:

>>> # 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) — Cualquiera de los siguientes tipos de objetos:
    • torch.utils.data.DataLoader: Dataloader de PyTorch
    • torch.nn.Module: Módulo de PyTorch
    • torch.optim.Optimizer: Optimizador de PyTorch
    • torch.optim.lr_scheduler.LRScheduler: Programador de tasa de aprendizaje de PyTorch
  • device_placement (list[bool], opcional) — Se utiliza para personalizar si se debe realizar la colocación automática de dispositivos para cada objeto pasado. Debe ser una lista de la misma longitud que args. No es compatible con DeepSpeed ni con FSDP.

Prepara todos los objetos pasados en args para el entrenamiento distribuido y la precisión mixta, y luego los devuelve en el mismo orden.

No es necesario preparar un modelo si solo se utiliza para inferencia sin ningún tipo de precisión mixta

Ejemplos:

>>> 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) — Un DataLoader de PyTorch estándar para preparar
  • device_placement (bool, opcional) — Indica si se deben colocar los lotes en el dispositivo adecuado en el dataloader preparado. El valor predeterminado es 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 un DataLoader de PyTorch para el entrenamiento en cualquier configuración distribuida. Se recomienda usar Accelerator.prepare() en su lugar.

Ejemplo:

>>> 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) — Un modelo de PyTorch que se va a preparar. No es necesario preparar un modelo si solo se utiliza para inferencia sin ningún tipo de precisión mixta
  • device_placement (bool, opcional) — Indica si se debe colocar el modelo en el dispositivo adecuado. El valor predeterminado es self.device_placement.
  • evaluation_mode (bool, opcional, valor predeterminado False) — Indica si se debe configurar el modelo solo para evaluación, aplicando únicamente precisión mixta y torch.compile (si está configurado en el objeto Accelerator).

Prepara un modelo de PyTorch para el entrenamiento en cualquier configuración distribuida. Se recomienda usar Accelerator.prepare() en su lugar.

Ejemplo:

>>> 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) — Un optimizador de PyTorch estándar para preparar
  • device_placement (bool, opcional) — Indica si se debe colocar el optimizador en el dispositivo adecuado. El valor predeterminado es self.device_placement.

Prepara un optimizador de PyTorch para el entrenamiento en cualquier configuración distribuida. Se recomienda usar Accelerator.prepare() en su lugar.

Ejemplo:

>>> 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) — Un programador de PyTorch estándar para preparar

Prepara un programador de PyTorch para el entrenamiento en cualquier configuración distribuida. Se recomienda usar Accelerator.prepare() en su lugar.

Ejemplo:

>>> 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 )

Sustituto directo de print() para imprimir solo una vez por servidor.

Ejemplo:

>>> from accelerate import Accelerator

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

perfil

< >

( profile_handler: ProfileKwargs | None = None )

Parámetros

  • profile_handler (ProfileKwargs, opcional) — El profile handler a utilizar para este context manager. Si no se pasa, se utilizará el establecido en el objeto Accelerator.

Perfilará el código dentro del gestor de contexto. El perfil se guardará en un archivo de Chrome Trace si profile_handler.output_trace_dir está configurado.

Se puede pasar un profile_handler diferente para reemplazar el establecido en el objeto Accelerator.

Ejemplo:

# 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, o una tupla/lista/diccionario anidado de torch.Tensor) — Los tensores que se van a reducir entre todos los procesos.
  • reduction (str, opcional, valor predeterminado “sum”) — Un tipo de reducción, puede ser ‘sum’, ‘mean’, ‘max’ o ‘none’. Si es ‘none’, no se realizará ninguna operación.
  • scale (float, opcional, valor predeterminado 1.0) — Un valor de escala predeterminado que se aplica después de la reducción, válido solo en XLA.

Devuelve

torch.Tensor, o una tupla/lista/diccionario anidado de torch.Tensor

El/los tensor(es) reducido(s).

Reduce los valores en tensor entre todos los procesos en función de reduction.

Nota: Todos los procesos obtienen el valor reducido.

Ejemplo:

>>> # 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 )

Toma nota de objects y los guardará o cargará durante save_state o load_state.

Deben utilizarse cuando el estado se carga o se guarda en el mismo script. No están diseñados para usarse en scripts diferentes.

Todo object debe tener una función load_state_dict y una función state_dict para poder almacenarse.

Ejemplo:

>>> 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

Devuelve

torch.utils.hooks.RemovableHandle

un identificador que se puede usar para eliminar el hook añadido llamando a handle.remove()

Registra un pre hook que se ejecutará antes de que se llame a load_checkpoint en Accelerator.load_state().

El hook debe tener la siguiente firma:

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

El argumento models son los modelos tal como se guardan en el estado del acelerador bajo accelerator._models, y el argumento input_dir es el argumento input_dir pasado a Accelerator.load_state().

Debe usarse únicamente en conjunto con Accelerator.register_save_state_pre_hook(). Puede ser útil para cargar configuraciones además de los pesos del modelo. También puede usarse para sobrescribir la carga del modelo con un método personalizado. En este caso, asegúrese de eliminar los modelos ya cargados de la lista de modelos.

register_save_state_pre_hook

< >

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

Parámetros

Devuelve

torch.utils.hooks.RemovableHandle

un identificador que se puede usar para eliminar el hook añadido llamando a handle.remove()

Registra un pre hook que se ejecutará antes de que se llame a save_checkpoint en Accelerator.save_state().

El hook debe tener la siguiente firma:

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

El argumento models son los modelos tal y como se guardan en el estado del acelerador bajo accelerator._models, el argumento weights son los state dicts de los models, y el argumento input_dir es el argumento input_dir pasado a Accelerator.load_state().

Debe usarse únicamente en conjunto con Accelerator.register_load_state_pre_hook(). Puede ser útil para guardar configuraciones además de los pesos del modelo. También puede usarse para sobrescribir el guardado del modelo con un método personalizado. En este caso, asegúrese de eliminar los pesos ya cargados de la lista de pesos.

save

< >

( objfsafe_serialization = False )

Parámetros

  • obj (object) — El objeto a guardar.
  • f (str o os.PathLike) — Dónde guardar el contenido de obj.
  • safe_serialization (bool, opcional, valor predeterminado False) — Si se guarda obj usando safetensors

Guarde el objeto pasado en el disco una vez por máquina. Úselo en lugar de torch.save.

Nota: Si save_on_each_node se pasó como un ProjectConfiguration, se guardará el objeto una vez por nodo, en lugar de solo una vez en el nodo principal.

Ejemplo:

>>> 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 que se va a guardar. El modelo puede estar envuelto o no.
  • save_directory (str o os.PathLike) — Directorio en el que se guardará. Se creará si no existe.
  • max_shard_size (int o str, opcional, por defecto "10GB") — El tamaño máximo de un checkpoint antes de ser fragmentado. Los fragmentos del checkpoint tendrán cada uno un tamaño inferior a este valor. Si se expresa como una cadena, debe consistir en dígitos seguidos de una unidad (como "5MB").

    Si un solo peso del modelo es mayor que max_shard_size, se encontrará en su propia partición de checkpoint, que será mayor que max_shard_size.

  • safe_serialization (bool, opcional, valor predeterminado True) — Si se guarda el modelo usando safetensors o de la forma tradicional de PyTorch (que usa pickle).

Guardar un modelo para que pueda recargarse usando load_checkpoint_in_model

Ejemplo:

>>> 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 o os.PathLike) — El nombre de la carpeta donde se guardarán todos los pesos y estados relevantes.
  • safe_serialization (bool, opcional, valor predeterminado True) — Si se guarda el modelo usando safetensors o de la forma tradicional de PyTorch (que usa pickle).
  • save_model_func_kwargs (dict, opcional) — Argumentos de palabra clave adicionales para guardar el modelo que pueden pasarse a la función de guardado subyacente, como los argumentos opcionales de la función save_checkpoint de DeepSpeed.

Guarda los estados actuales del modelo, el optimizador, el escalador, los generadores de RNG y los objetos registrados en una carpeta.

Si se pasó una ProjectConfiguration al objeto Accelerator con automatic_checkpoint_naming habilitado, los checkpoints se guardarán en self.project_dir/checkpoints. Si el número de guardados actuales es mayor que total_limit, se elimina el guardado más antiguo. Cada checkpoint se guarda en carpetas separadas llamadas checkpoint_<iteration>.

En caso contrario, simplemente se guardan en output_dir.

Debe usarse únicamente cuando se desea guardar un punto de control durante el entrenamiento y restaurar el estado en el mismo entorno.

Ejemplo:

>>> 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

< >

( )

Establece el tensor de disparo interno en 1 en el proceso actual. Debe seguirse una comprobación posterior que utilice esto para verificar en todos los procesos.

Nota: No requiere wait_for_everyone()

Ejemplo:

>>> 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) — El cargador de datos en el que se omitirán los lotes.
  • num_batches (int, opcional, valor predeterminado 0) — El número de lotes a omitir

Crea un nuevo torch.utils.data.DataLoader que omitirá eficientemente los primeros num_batches.

Ejemplo:

>>> 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 o dict de list/tuple/torch.Tensor) — La entrada que se dividirá entre los procesos.
  • apply_padding (bool, optional, por defecto False) — Si se aplica relleno repitiendo el último elemento de la entrada para que todos los procesos tengan el mismo número de elementos. Útil al intentar realizar acciones como Accelerator.gather() en las salidas o al pasar menos entradas que procesos. Si es así, recuerda eliminar los elementos rellenados después.

Divide input entre self.num_processes de forma rápida y luego puede usarse en ese proceso. Útil al realizar inferencia distribuida, por ejemplo, con diferentes prompts.

Tenga en cuenta que al usar un dict, todas las claves deben tener el mismo número de elementos.

Ejemplo:

# 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) — El modelo para el que se debe activar la sincronización de gradientes.

Disparar la sincronización de los gradientes en la siguiente pasada hacia atrás del modelo después de varias pasadas hacia adelante bajo Accelerator.no_sync (solo aplicable en escenarios multi-GPU).

Si el script no se inicia en modo distribuido, este administrador de contexto no hace nada.

Ejemplo:

>>> 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 o list[torch.optim.Optimizer], opcional) — El o los optimizadores para los que se debe desescalar los gradientes. Si no se establece, se desescalarán los gradientes en todos los optimizadores que se hayan pasado a prepare().

Desescala los gradientes en el entrenamiento de precisión mixta con AMP. En todas las demás configuraciones, esta operación no tiene efecto.

Probablemente debería llamarse a través de Accelerator.clipgrad_norm() o Accelerator.clipgrad_value()

Ejemplo:

>>> 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) — El modelo que se debe desenrollar.
  • keep_fp32_wrapper (bool, opcional, valor predeterminado True) — Si no se debe eliminar el hook de precisión mixta si se añadió.
  • keep_torch_compile (bool, opcional, valor predeterminado True) — Si se debe o no desenvolver el modelo compilado si está compilado.

Devuelve

torch.nn.Module

El modelo sin envolver.

Desenvuelve el model de la capa adicional que pudo haber sido añadida por prepare(). Útil antes de guardar el modelo.

Ejemplo:

>>> # 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 no se haya preparado para la inferencia de modelos grandes con un device-map que se asemeje a auto.

wait_for_everyone

< >

( )

Detendrá la ejecución del proceso actual hasta que todos los demás procesos hayan alcanzado ese punto (por lo que no hace nada cuando el script se ejecuta en un solo proceso). Útil para hacerlo antes de guardar un modelo.

Ejemplo:

>>> # 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")

Utilidades

accelerate.utils.gather_object

< >

( object: Any )

Parámetros

  • object (lista/tupla/diccionario anidado de objetos serializables) — Los datos que se deben recopilar.

Recolectar recursivamente un objeto en una lista/tupla/diccionario anidado de objetos desde todos los dispositivos.

Update on GitHub