# Trabalhando com modelos grandes

## Despacho e descarregamento

### init_empty_weights[[accelerate.init_empty_weights]]

#### accelerate.init_empty_weights[[accelerate.init_empty_weights]]

```python
accelerate.init_empty_weights(include_buffers: bool | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L57)

**Parâmetros:**

include_buffers (`bool`, *opcional*) : Se todos os buffers também devem ser colocados no dispositivo meta durante a inicialização.

Um gerenciador de contexto sob o qual os modelos são inicializados com todos os parâmetros no dispositivo meta, criando assim um modelo vazio. Útil quando apenas a inicialização do modelo estouraria a RAM disponível.

Exemplo:

```python
import torch.nn as nn
from accelerate import init_empty_weights

# Initialize a model with 100 billions parameters in no time and without using any RAM.
with init_empty_weights():
    tst = nn.Sequential(*[nn.Linear(10000, 10000) for _ in range(1000)])
```

Qualquer modelo criado sob este gerenciador de contexto não possui pesos. Dessa forma, você não pode fazer algo como `model.to(some_device)` com ele. Para carregar pesos dentro do seu modelo vazio, consulte [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.load_checkpoint_and_dispatch). Certifique-se de sobrescrever o parâmetro padrão device_map de [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.load_checkpoint_and_dispatch), caso contrário o dispatch não será chamado.

### cpu_offload[[accelerate.cpu_offload]]

#### accelerate.cpu_offload[[accelerate.cpu_offload]]

```python
accelerate.cpu_offload(model: Module, execution_device: torch.device | None = None, offload_buffers: bool = False, state_dict: dict[str, torch.Tensor] | None = None, preload_module_classes: list[str] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L175)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser descarregado.

execution_device (`torch.device`, *opcional*) : O dispositivo no qual a passagem direta do modelo será executado (deve ser uma GPU). O padrão será o dispositivo do primeiro parâmetro do modelo.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers devem ser descarregados junto com os parâmetros do modelo.

state_dict (`Dict[str, torch.Tensor]`, *opcional*) : O state dict do modelo que será mantido na CPU.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

Ativa o offload completo de CPU para um modelo. Como resultado, todos os parâmetros do modelo serão offloadados e apenas uma cópia do state dict do modelo será mantida. Durante o forward pass, os parâmetros serão extraídos desse state dict e colocados no dispositivo de execução passado à medida que forem necessários, e então offloadados novamente.

### cpu_offload_with_hook[[accelerate.cpu_offload_with_hook]]

#### accelerate.cpu_offload_with_hook[[accelerate.cpu_offload_with_hook]]

```python
accelerate.cpu_offload_with_hook(model: Module, execution_device: int | str | torch.device | None = None, prev_module_hook: accelerate.hooks.UserCpuOffloadHook | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L221)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser descarregado.

execution_device(`str`, `int` ou `torch.device`, *opcional*) : O dispositivo no qual o modelo deve ser executado. O padrão será o dispositivo MPS, se disponível; em seguida, o dispositivo 0, se houver um dispositivo de acelerador; e, por fim, a CPU.

prev_module_hook (`UserCpuOffloadHook`, *opcional*) : O hook retornado por esta função para um modelo anterior no pipeline que você está executando. Se fornecido, seu método de offload será chamado logo antes do forward do modelo ao qual este hook está anexado.

Desloca um modelo para a CPU e o retorna para o dispositivo de execução quando executado. A diferença em relação ao [cpu_offload()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.cpu_offload) é que o modelo permanece no dispositivo de execução após o forward e só é deslocado novamente quando o método `offload` do `hook` retornado é chamado. Útil para pipelines que executam um modelo em um loop.

Exemplo:

```py
model_1, hook_1 = cpu_offload_with_hook(model_1, device)
model_2, hook_2 = cpu_offload_with_hook(model_2, device, prev_module_hook=hook_1)
model_3, hook_3 = cpu_offload_with_hook(model_3, device, prev_module_hook=hook_2)

hid_1 = model_1(input)
for i in range(50):
    # model1 is offloaded on the CPU at the first iteration, model 2 stays on the GPU for this whole loop.
    hid_2 = model_2(hid_1)
# model2 is offloaded to the CPU just before this forward.
hid_3 = model_3(hid_3)

# For model3, you need to manually call the hook offload method.
hook_3.offload()
```

### disk_offload[[accelerate.disk_offload]]

#### accelerate.disk_offload[[accelerate.disk_offload]]

```python
accelerate.disk_offload(model: Module, offload_dir: str | os.PathLike, execution_device: torch.device | None = None, offload_buffers: bool = False, preload_module_classes: list[str] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L265)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser descarregado.

offload_dir (`str` ou `os.PathLike`) : A pasta em que os pesos do modelo serão descarregados (ou onde os pesos do modelo já foram descarregados).

execution_device (`torch.device`, *opcional*) : O dispositivo no qual a passagem direta do modelo será executado (deve ser uma GPU). O padrão será o dispositivo do primeiro parâmetro do modelo.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers devem ser descarregados junto com os parâmetros do modelo.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

Ativa o offload completo em disco para um modelo. Como resultado, todos os parâmetros do modelo serão offloadados como arrays mapeados em memória em uma pasta especificada. Durante a passagem de frente, os parâmetros serão acessados a partir dessa pasta e colocados no dispositivo de execução passado, conforme necessário, e offloadados novamente.

### dispatch_model[[accelerate.dispatch_model]]

#### accelerate.dispatch_model[[accelerate.dispatch_model]]

```python
accelerate.dispatch_model(model: Module, device_map: dict[str, str | int | torch.device], main_device: torch.device | None = None, state_dict: dict[str, torch.Tensor] | None = None, offload_dir: str | os.PathLike | None = None, offload_index: dict[str, str] | None = None, offload_buffers: bool = False, skip_keys: str | list[str] | None = None, preload_module_classes: list[str] | None = None, force_hooks: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L311)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser despachado.

device_map (`Dict[str, Union[str, int, torch.device]]`) : Um dicionário que mapeia os nomes dos módulos no `state_dict` dos modelos para o dispositivo em que devem ser colocados. Observe que `"disk"` é aceito, mesmo que não seja um valor adequado para `torch.device`.

main_device (`str`, `int` ou `torch.device`, *opcional*) : O dispositivo principal de execução. O padrão será o primeiro dispositivo no `device_map` diferente de `"cpu"` ou `"disk"`.

state_dict (`Dict[str, torch.Tensor]`, *opcional*) : O state dict da parte do modelo que será mantida na CPU.

offload_dir (`str` ou `os.PathLike`) : A pasta em que os pesos do modelo serão descarregados (ou onde os pesos do modelo já foram descarregados).

offload_index (`Dict`, *opcional*) : Um dicionário do nome do peso para suas informações (`dtype`/ `shape` ou nome do arquivo safetensors). O padrão será o índice salvo em `save_folder`.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers devem ser descarregados junto com os parâmetros do modelo.

skip_keys (`str` ou `List[str]`, *opcional*) : Uma lista de chaves para ignorar ao mover entradas ou saídas entre dispositivos.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

force_hooks (`bool`, *opcional*, padrão `False`) : Se os hooks de dispositivo devem ser forçados a serem anexados ao modelo, mesmo que todas as camadas sejam despachadas para um único dispositivo.

Despacha um modelo de acordo com um mapa de dispositivos dado. As camadas do modelo podem ser distribuídas entre GPUs, descarregadas na CPU ou até mesmo no disco.

### load_checkpoint_and_dispatch[[accelerate.load_checkpoint_and_dispatch]]

#### accelerate.load_checkpoint_and_dispatch[[accelerate.load_checkpoint_and_dispatch]]

```python
accelerate.load_checkpoint_and_dispatch(model: Module, checkpoint: str | os.PathLike, device_map: str | dict[str, int | str | torch.device] | None = None, max_memory: dict[int | str, int | str] | None = None, no_split_module_classes: list[str] | None = None, offload_folder: str | os.PathLike | None = None, offload_buffers: bool = False, dtype: str | torch.dtype | None = None, offload_state_dict: bool | None = None, skip_keys: str | list[str] | None = None, preload_module_classes: list[str] | None = None, force_hooks: bool = False, strict: bool = False, full_state_dict: bool = True, broadcast_from_rank0: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L500)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo no qual queremos carregar um checkpoint.

checkpoint (`str` ou `os.PathLike`) : O checkpoint de pasta a ser carregado. Pode ser: - um caminho para um arquivo contendo um state dict completo do modelo - um caminho para um arquivo `.json` contendo o índice de um checkpoint fragmentado - um caminho para uma pasta contendo um arquivo único `.index.json` e os fragmentos de um checkpoint.

device_map (`Dict[str, Union[int, str, torch.device]]`, *opcional*) : Um mapa que especifica para onde cada submódulo deve ser enviado. Não é necessário refinar para cada nome de parâmetro/buffer, pois, uma vez que um determinado nome de módulo está incluído, todos os seus submódulos serão enviados para o mesmo dispositivo. Para que o Accelerate calcule automaticamente o `device_map` mais otimizado, defina `device_map="auto"`. Para mais informações sobre cada opção, veja [aqui](../concept_guides/big_model_inference#designing-a-device-map). O padrão é None, o que significa que [dispatch_model()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.dispatch_model) não será chamado.

max_memory (`Dict`, *opcional*) : Um dicionário de identificador de dispositivo para memória máxima. Se não definido, o padrão será a memória máxima disponível para cada GPU e a RAM disponível da CPU.

no_split_module_classes (`List[str]`, *opcional*) : Uma lista de nomes de classes de camadas que nunca devem ser divididas entre dispositivos (por exemplo, qualquer camada que tenha uma conexão residual).

offload_folder (`str` ou `os.PathLike`, *opcional*) : Se o `device_map` contiver qualquer valor `"disk"`, a pasta onde os pesos serão descarregados.

offload_buffers (`bool`, *opcional*, padrão `False`) : Nas camadas que são descarregadas na CPU ou no disco rígido, se os buffers devem ser descarregados junto com os parâmetros.

dtype (`str` ou `torch.dtype`, *opcional*) : Se fornecido, os pesos serão convertidos para esse tipo ao serem carregados.

offload_state_dict (`bool`, *opcional*) : Se `True`, o state dict da CPU será temporariamente descarregado no disco rígido para evitar a falta de RAM na CPU caso o peso do state dict da CPU + o maior shard não caiba. O valor padrão será `True` se o device map selecionado contiver valores de `"disk"`.

skip_keys (`str` ou `List[str]`, *opcional*) : Uma lista de chaves para ignorar ao mover entradas ou saídas entre dispositivos.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

force_hooks (`bool`, *opcional*, padrão `False`) : Se os hooks de dispositivo devem ser forçados a serem anexados ao modelo, mesmo que todas as camadas sejam despachadas para um único dispositivo.

strict (`bool`, *opcional*, padrão `False`) : Se deve aplicar estritamente que as chaves no state_dict do checkpoint correspondam às chaves do state_dict do modelo.

full_state_dict (`bool`, *opcional*, padrão `True`) : se definido como `True`, todos os tensors no state_dict carregado serão reunidos. Não haverá ShardedTensor nem DTensor no state_dict carregado.

broadcast_from_rank0 (`False`, *opcional*, padrão `False`) : quando a opção é `True`, um `ProcessGroup` distribuído deve ser inicializado. O rank0 deve receber um state_dict completo e fará o broadcast dos tensors no state_dict um a um para os outros ranks. Os outros ranks receberão os tensors e farão o sharding (se aplicável) de acordo com os shards locais no modelo.

Carrega um checkpoint (possivelmente fragmentado) dentro de um modelo, potencialmente enviando os pesos para um dispositivo específico à medida que são carregados, e adiciona os diversos hooks que farão com que este modelo execute corretamente (mesmo que esteja dividido entre dispositivos).

Exemplo:

```python
>>> from accelerate import init_empty_weights, load_checkpoint_and_dispatch
>>> from huggingface_hub import hf_hub_download
>>> from transformers import AutoConfig, AutoModelForCausalLM

>>> # Download the Weights
>>> checkpoint = "EleutherAI/gpt-j-6B"
>>> weights_location = hf_hub_download(checkpoint, "pytorch_model.bin")

>>> # Create a model and initialize it with empty weights
>>> config = AutoConfig.from_pretrained(checkpoint)
>>> with init_empty_weights():
...     model = AutoModelForCausalLM.from_config(config)

>>> # Load the checkpoint and dispatch it to the right devices
>>> model = load_checkpoint_and_dispatch(
...     model, weights_location, device_map="auto", no_split_module_classes=["GPTJBlock"]
... )
```

### load_checkpoint_in_model[[accelerate.load_checkpoint_in_model]]

#### accelerate.load_checkpoint_in_model[[accelerate.load_checkpoint_in_model]]

```python
accelerate.load_checkpoint_in_model(model: Module, checkpoint: str | os.PathLike, device_map: dict[str, int | str | torch.device] | None = None, offload_folder: str | os.PathLike | None = None, dtype: str | torch.dtype | None = None, offload_state_dict: bool = False, offload_buffers: bool = False, keep_in_fp32_modules: list[str] | None = None, offload_8bit_bnb: bool = False, strict: bool = False, full_state_dict: bool = True, broadcast_from_rank0: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/modeling.py#L1786)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo no qual queremos carregar um checkpoint.

checkpoint (`str` ou `os.PathLike`) : O checkpoint de pasta a ser carregado. Pode ser: - um caminho para um arquivo contendo um state dict completo do modelo - um caminho para um arquivo `.json` contendo o índice de um checkpoint fragmentado - um caminho para uma pasta contendo um arquivo único `.index.json` e os fragmentos de um checkpoint. - um caminho para uma pasta contendo um arquivo único pytorch_model.bin ou model.safetensors.

device_map (`Dict[str, Union[int, str, torch.device]]`, *opcional*) : Um mapa que especifica para onde cada submódulo deve ser enviado. Não é necessário refinar para cada nome de parâmetro/buffer, pois, uma vez que um determinado nome de módulo está incluído, todos os seus submódulos serão enviados para o mesmo dispositivo.

offload_folder (`str` ou `os.PathLike`, *opcional*) : Se o `device_map` contiver qualquer valor `"disk"`, a pasta onde os pesos serão descarregados.

dtype (`str` ou `torch.dtype`, *opcional*) : Se fornecido, os pesos serão convertidos para esse tipo ao serem carregados.

offload_state_dict (`bool`, *opcional*, padrão `False`) : Se `True`, o state dict da CPU será temporariamente descarregado no disco rígido para evitar a falta de RAM na CPU caso o peso do state dict da CPU + o maior shard não caiba.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers devem ser incluídos nos pesos descarregados para o disco.

keep_in_fp32_modules(`List[str]`, *opcional*) : Uma lista dos módulos que mantemos no dtype `torch.float32`.

offload_8bit_bnb (`bool`, *opcional*) : Se deve ou não habilitar o offload de módulos de 8 bits para cpu/disco.

strict (`bool`, *opcional*, padrão `False`) : Se deve aplicar estritamente que as chaves no state_dict do checkpoint correspondam às chaves do state_dict do modelo.

full_state_dict (`bool`, *opcional*, padrão `True`) : se definido como `True`, todos os tensors no state_dict carregado serão reunidos. Não haverá ShardedTensor nem DTensor no state_dict carregado.

broadcast_from_rank0 (`False`, *opcional*, padrão `False`) : quando a opção é `True`, um `ProcessGroup` distribuído deve ser inicializado. O rank0 deve receber um state_dict completo e fará o broadcast dos tensors no state_dict um a um para os outros ranks. Os outros ranks receberão os tensors e farão o sharding (se aplicável) de acordo com os shards locais no modelo.

Carrega um checkpoint (possivelmente fragmentado) dentro de um modelo, enviando possivelmente os pesos para um dispositivo específico à medida que são carregados.

Depois de carregar em vários dispositivos, você ainda precisa chamar [dispatch_model()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.dispatch_model) no seu modelo para que ele possa ser executado. Para agrupar o carregamento do checkpoint e o despacho em uma única chamada, use [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/pt/package_reference/big_modeling#accelerate.load_checkpoint_and_dispatch).

### infer_auto_device_map[[accelerate.infer_auto_device_map]]

#### accelerate.infer_auto_device_map[[accelerate.infer_auto_device_map]]

```python
accelerate.infer_auto_device_map(model: Module, max_memory: dict[int | str, int | str] | None = None, no_split_module_classes: list[str] | None = None, dtype: str | torch.dtype | None = None, special_dtypes: dict[str, str | torch.dtype] | None = None, verbose: bool = False, clean_result: bool = True, offload_buffers: bool = False, fallback_allocation: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/modeling.py#L1278)

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser analisado.

max_memory (`Dict`, *opcional*) : Um dicionário de identificador de dispositivo para memória máxima. Se não definido, usará a memória máxima disponível por padrão. Exemplo: `max_memory={0: "1GB"}`.

no_split_module_classes (`List[str]`, *opcional*) : Uma lista de nomes de classes de camadas que nunca devem ser divididas entre dispositivos (por exemplo, qualquer camada que tenha uma conexão residual).

dtype (`str` ou `torch.dtype`, *opcional*) : Se fornecido, os pesos serão convertidos para esse tipo ao serem carregados.

special_dtypes (`Dict[str, Union[str, torch.device]]`, *opcional*) : Se fornecido, dtypes especiais a considerar para alguns pesos específicos (substituirá o dtype usado como padrão para todos os pesos).

verbose (`bool`, *opcional*, padrão `False`) : Se deve ou não fornecer declarações de depuração conforme a função constrói o device_map.

clean_result (`bool`, *opcional*, padrão `True`) : Limpa o device_map resultante, agrupando todos os submódulos que ficam no mesmo dispositivo.

offload_buffers (`bool`, *opcional*, padrão `False`) : Nas camadas que são descarregadas na CPU ou no disco rígido, se os buffers devem ser descarregados junto com os parâmetros.

fallback_allocation (`bool`, *opcional*, padrão `False`) : Quando a alocação regular falha, tenta alocar um módulo que caiba no limite de tamanho usando BFS.

Calcule um mapa de dispositivos para um modelo específico, dando prioridade às GPUs, depois faça o offload para a CPU e, por fim, para o disco, de modo que:
- não excedemos a memória disponível de nenhuma das GPUs.
- se o offload para a CPU for necessário, sempre haverá espaço disponível na GPU 0 para colocar de volta a camada offloadada na CPU que possui o maior tamanho.
- se o offload para a CPU for necessário, não excedemos a RAM disponível na CPU.
- se o offload para o disco for necessário, sempre haverá espaço disponível na CPU para colocar de volta a camada offloadada no disco que tiver o maior tamanho.

Todo o cálculo é realizado analisando os tamanhos e os dtypes dos parâmetros do modelo. Como resultado, o modelo pode estar no dispositivo meta (como estaria se fosse inicializado dentro do gerenciador de contexto `init_empty_weights`).

## Hooks

### ModelHook[[accelerate.hooks.ModelHook]]

#### accelerate.hooks.ModelHook[[accelerate.hooks.ModelHook]]

```python
accelerate.hooks.ModelHook()
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L51)

Um hook que contém callbacks para serem executados logo antes e depois do método forward de um modelo. A diferença em relação aos hooks existentes no PyTorch é que eles recebem os kwargs.

Atributo de classe:
- **no_grad** (`bool`, *opcional*, padrão `False`) -- Se a passagem de frente real deve ser executada sob o gerenciador de contexto `torch.no_grad()`.

#### detach_hook[[accelerate.hooks.ModelHook.detach_hook]]

```python
detach_hook(module)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L99)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo desconectado deste hook.

Para ser executado quando o hook é desconectado de um módulo.

#### init_hook[[accelerate.hooks.ModelHook.init_hook]]

```python
init_hook(module)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L63)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo anexado a este hook.

Para ser executado quando o hook for anexado ao módulo.

#### post_forward[[accelerate.hooks.ModelHook.post_forward]]

```python
post_forward(module, output)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L86)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo cuja passagem para frente foi executada logo antes deste evento.

output (`Any`) : A saída do módulo.

**Retorna:** `Any`

O `output` processado.

Para ser executado logo após o método forward do modelo.

#### pre_forward[[accelerate.hooks.ModelHook.pre_forward]]

```python
pre_forward(module, *args, **kwargs)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L72)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo cuja passagem para frente será executada logo após este evento.

args (`Tuple[Any]`) : Os argumentos posicionais passados para o módulo.

kwargs (`Dict[Str, Any]`) : Os argumentos de palavra-chave passados para o módulo.

**Retorna:** `Tuple[Tuple[Any], Dict[Str, Any]]`

Uma tupla com os `args` e `kwargs` tratados.

Para ser executado logo antes do método forward do modelo.

### AlignDevicesHook[[accelerate.hooks.AlignDevicesHook]]

#### accelerate.hooks.AlignDevicesHook[[accelerate.hooks.AlignDevicesHook]]

```python
accelerate.hooks.AlignDevicesHook(execution_device: int | str | torch.device | None = None, offload: bool = False, io_same_device: bool = False, weights_map: collections.abc.Mapping | None = None, offload_buffers: bool = False, place_submodules: bool = False, skip_keys: str | list[str] | None = None, tied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L238)

**Parâmetros:**

execution_device (`torch.device`, *opcional*) : O dispositivo em que as entradas e os pesos do modelo devem ser colocados antes da passagem para frente.

offload (`bool`, *opcional*, padrão `False`) : Se os pesos devem ser descarregados após a passagem de frente.

io_same_device (`bool`, *opcional*, padrão `False`) : Se a saída deve ou não ser colocada no mesmo dispositivo em que a entrada estava.

weights_map (`Mapping[str, torch.Tensor]`, *opcional*) : Quando os pesos do modelo são descarregados, um mapa (potencialmente preguiçoso) dos nomes dos parâmetros para os valores dos tensores.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers do módulo associado devem ser incluídos durante o offloading.

place_submodules (`bool`, *opcional*, padrão `False`) : Se os submódulos devem ser colocados em `execution_device` durante o evento `init_hook`.

Um `ModelHook` genérico que garante que as entradas e os pesos do modelo estejam no mesmo dispositivo para a passagem direta do módulo associado, potencialmente descarregando os pesos após a passagem direta.

### SequentialHook[[accelerate.hooks.SequentialHook]]

#### accelerate.hooks.SequentialHook[[accelerate.hooks.SequentialHook]]

```python
accelerate.hooks.SequentialHook(*hooks)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L109)

Um hook que pode conter vários hooks e itera por eles a cada evento.

### LayerwiseCastingHook[[accelerate.hooks.LayerwiseCastingHook]]

#### accelerate.hooks.LayerwiseCastingHook[[accelerate.hooks.LayerwiseCastingHook]]

```python
accelerate.hooks.LayerwiseCastingHook(storage_dtype: dtype, compute_dtype: dtype, non_blocking: bool)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L781)

Um hook que converte os pesos de um módulo para um dtype de alta precisão para o cálculo e para um dtype de baixa precisão para o armazenamento. Esse processo pode levar a uma perda de qualidade na saída, mas pode reduzir significativamente a pegada de memória.

## Adicionando Hooks

### add_hook_to_module[[accelerate.hooks.add_hook_to_module]]

#### accelerate.hooks.add_hook_to_module[[accelerate.hooks.add_hook_to_module]]

```python
accelerate.hooks.add_hook_to_module(module: Module, hook: ModelHook, append: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L140)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo ao qual o hook será anexado.

hook (`ModelHook`) : O hook a ser anexado.

append (`bool`, *opcional*, padrão `False`) : Se o hook deve ser encadeado com um existente (se o módulo já contém um hook) ou não.

**Retorna:** `torch.nn.Module`

O mesmo módulo, com o hook anexado (o módulo é modificado no local, portanto o resultado pode ser descartado).

Adiciona um hook a um módulo específico. Isso reescreve o método `forward` do módulo para incluir o hook. Para remover esse comportamento e restaurar o método `forward` original, use `remove_hook_from_module`.

Se o módulo já contém um hook, ele será substituído pelo novo hook passado por padrão. Para encadear dois hooks, passe `append=True`, de modo que o hook atual e o novo sejam encadeados em uma instância da classe `SequentialHook`.

### attach_execution_device_hook[[accelerate.hooks.attach_execution_device_hook]]

#### accelerate.hooks.attach_execution_device_hook[[accelerate.hooks.attach_execution_device_hook]]

```python
accelerate.hooks.attach_execution_device_hook(module: Module, execution_device: int | str | torch.device, skip_keys: str | list[str] | None = None, preload_module_classes: list[str] | None = None, tied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L440)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo onde queremos anexar os hooks.

execution_device (`int`, `str` ou `torch.device`) : O dispositivo no qual as entradas e os pesos do modelo devem ser colocados antes da passagem para frente.

skip_keys (`str` ou `List[str]`, *opcional*) : Uma lista de chaves para ignorar ao mover entradas ou saídas entre dispositivos.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *opcional*, padrão `None`) : Um mapa de ponteiros de dados para dicionários de dispositivos para pesos vinculados já despachados. Para um dispositivo de execução dado, este parâmetro é útil para reutilizar o primeiro ponteiro disponível de um peso compartilhado para todos os outros, em vez de duplicar a memória.

Anexa recursivamente `AlignDevicesHook` a todos os submódulos de um modelo específico para garantir que eles tenham o dispositivo de execução correto

### attach_align_device_hook[[accelerate.hooks.attach_align_device_hook]]

#### accelerate.hooks.attach_align_device_hook[[accelerate.hooks.attach_align_device_hook]]

```python
accelerate.hooks.attach_align_device_hook(module: Module, execution_device: torch.device | None = None, offload: bool = False, weights_map: collections.abc.Mapping | None = None, offload_buffers: bool = False, module_name: str = '', skip_keys: str | list[str] | None = None, preload_module_classes: list[str] | None = None, tied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L488)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo onde queremos anexar os hooks.

execution_device (`torch.device`, *opcional*) : O dispositivo em que as entradas e os pesos do modelo devem ser colocados antes da passagem para frente.

offload (`bool`, *opcional*, padrão `False`) : Se os pesos devem ser descarregados após a passagem de frente.

weights_map (`Mapping[str, torch.Tensor]`, *opcional*) : Quando os pesos do modelo são descarregados, um mapa (potencialmente preguiçoso) dos nomes dos parâmetros para os valores dos tensores.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers do módulo associado devem ser incluídos durante o offloading.

module_name (`str`, *opcional*, padrão `""`) : O nome do módulo.

skip_keys (`str` ou `List[str]`, *opcional*) : Uma lista de chaves para ignorar ao mover entradas ou saídas entre dispositivos.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *opcional*, padrão `None`) : Um mapa de ponteiros de dados para dicionários de dispositivos para pesos vinculados já despachados. Para um dispositivo de execução dado, este parâmetro é útil para reutilizar o primeiro ponteiro disponível de um peso compartilhado para todos os outros, em vez de duplicar a memória.

Anexa recursivamente `AlignDevicesHook` a todos os submódulos de um modelo dado que possuem parâmetros e/ou buffers diretos.

### attach_align_device_hook_on_blocks[[accelerate.hooks.attach_align_device_hook_on_blocks]]

#### accelerate.hooks.attach_align_device_hook_on_blocks[[accelerate.hooks.attach_align_device_hook_on_blocks]]

```python
accelerate.hooks.attach_align_device_hook_on_blocks(module: Module, execution_device: torch.device | dict[str, torch.device] | None = None, offload: bool | dict[str, bool] = False, weights_map: collections.abc.Mapping | None = None, offload_buffers: bool = False, module_name: str = '', skip_keys: str | list[str] | None = None, preload_module_classes: list[str] | None = None, tied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L583)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo onde queremos anexar os hooks.

execution_device (`torch.device` ou `Dict[str, torch.device]`, *opcional*) : O dispositivo em que as entradas e os pesos do modelo devem ser colocados antes da passagem para frente. Pode ser um único dispositivo para todo o módulo ou um dicionário que mapeia o nome do módulo para o dispositivo.

offload (`bool`, *opcional*, padrão `False`) : Indica se os pesos devem ser descarregados após a passagem de frente. Pode ser um único booleano para o módulo inteiro ou um dicionário que mapeia o nome do módulo para um booleano.

weights_map (`Mapping[str, torch.Tensor]`, *opcional*) : Quando os pesos do modelo são descarregados, um mapa (potencialmente preguiçoso) dos nomes dos parâmetros para os valores dos tensores.

offload_buffers (`bool`, *opcional*, padrão `False`) : Se os buffers do módulo associado devem ser incluídos durante o offloading.

module_name (`str`, *opcional*, padrão `""`) : O nome do módulo.

skip_keys (`str` ou `List[str]`, *opcional*) : Uma lista de chaves para ignorar ao mover entradas ou saídas entre dispositivos.

preload_module_classes (`List[str]`, *opcional*) : Uma lista de classes cujas instâncias devem carregar todos os seus pesos (mesmo nos submódulos) no início do forward. Isso deve ser usado apenas para classes que possuem submódulos registrados, mas que não são chamados diretamente durante o forward, por exemplo, se uma camada linear `dense` estiver registrada, mas, no forward, `dense.weight` e `dense.bias` forem usados em algumas operações em vez de chamar `dense` diretamente.

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *opcional*, padrão `None`) : Um mapa de ponteiros de dados para dicionários de dispositivos para pesos vinculados já despachados. Para um dispositivo de execução dado, este parâmetro é útil para reutilizar o primeiro ponteiro disponível de um peso compartilhado para todos os outros, em vez de duplicar a memória.

Anexa `AlignDevicesHook` a todos os blocos de um modelo específico, conforme necessário.

### attach_layerwise_casting_hooks[[accelerate.big_modeling.attach_layerwise_casting_hooks]]

#### accelerate.big_modeling.attach_layerwise_casting_hooks[[accelerate.big_modeling.attach_layerwise_casting_hooks]]

```python
accelerate.big_modeling.attach_layerwise_casting_hooks(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str | tuple[str, ...] | None = None, skip_modules_classes: tuple[type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/big_modeling.py#L641)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo cujos módulos folha serão convertidos para um dtype de alta precisão para computação e para um dtype de baixa precisão para armazenamento.

storage_dtype (`torch.dtype`) : O dtype para o qual o módulo deve ser convertido antes/depois da passagem de frente para armazenamento.

compute_dtype (`torch.dtype`) : O dtype para o qual o módulo deve ser convertido durante a passagem de frente para a computação.

skip_modules_pattern (`tuple[str, ...]`, padrão `None`) : Uma lista de padrões para corresponder aos nomes dos módulos a serem ignorados durante o processo de conversão por camada. Se definido como `None` junto com `skip_modules_classes` sendo `None`, a conversão por camada é aplicada diretamente ao módulo em vez de seus submódulos internos.

skip_modules_classes (`tuple[type[torch.nn.Module], ...]`, padrão `None`) : Uma lista de classes de módulos para ignorar durante o processo de conversão por camada.

non_blocking (`bool`, padrão `False`) : Se `True`, as operações de conversão de pesos são não bloqueantes.

Aplica o casting por camada a um módulo específico. O módulo esperado aqui é um `nn.Module` do PyTorch. Isso é útil para reduzir os requisitos de memória quando não se deseja quantizar completamente um modelo. Os parâmetros do modelo podem ser mantidos, por exemplo, em `torch.float8_e4m3fn` e convertidos para uma precisão maior, como `torch.bfloat16`, durante a passagem para frente e convertidos de volta para `torch.float8_e4m3fn` para realizar economias de memória.

Exemplo:

```python
>>> from accelerate.hooks import attach_layerwise_casting_hooks
>>> from transformers import AutoModelForCausalLM
>>> import torch

>>> # Model
>>> checkpoint = "EleutherAI/gpt-j-6B"
>>> model = AutoModelForCausalLM.from_pretrained(checkpoint)

>>> # Attach hooks and perform inference
>>> attach_layerwise_casting_hooks(model, storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)
>>> with torch.no_grad():
...     model(...)
```

Os usuários também podem passar os módulos que desejam evitar que sejam convertidos para um tipo de menor precisão.

```py
>>> attach_layerwise_casting_hooks(
...     model, storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16, skip_modules_pattern=["norm"]
... )
```

## Removendo Hooks

### remove_hook_from_module[[accelerate.hooks.remove_hook_from_module]]

#### accelerate.hooks.remove_hook_from_module[[accelerate.hooks.remove_hook_from_module]]

```python
accelerate.hooks.remove_hook_from_module(module: Module, recurse = False)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L198)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo ao qual o hook será anexado.

recurse (`bool`, **opcional**) : Se deve remover os hooks recursivamente

**Retorna:** `torch.nn.Module`

O mesmo módulo, com o hook desacoplado (o módulo é modificado no local, portanto o resultado pode ser descartado).

Remove qualquer hook anexado a um módulo por meio de `add_hook_to_module`.

### remove_hook_from_submodules[[accelerate.hooks.remove_hook_from_submodules]]

#### accelerate.hooks.remove_hook_from_submodules[[accelerate.hooks.remove_hook_from_submodules]]

```python
accelerate.hooks.remove_hook_from_submodules(module: Module)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/hooks.py#L571)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo no qual remover todos os hooks.

Remove recursivamente todos os hooks anexados aos submódulos de um modelo específico.

## Utilitários

### has_offloaded_params[[accelerate.utils.has_offloaded_params]]

#### accelerate.utils.has_offloaded_params[[accelerate.utils.has_offloaded_params]]

```python
accelerate.utils.has_offloaded_params(module: Module)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/modeling.py#L2119)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo a ser verificado em busca de um hook de offload.

**Retorna:** `bool`

`True` se o módulo possui um hook de offload e o offloading está habilitado, `False` caso contrário.

Verifica se um módulo possui parâmetros descarregados, verificando se o módulo fornecido tem um AlignDevicesHook anexado com o descarregamento ativado

### align_module_device[[accelerate.utils.align_module_device]]

#### accelerate.utils.align_module_device[[accelerate.utils.align_module_device]]

```python
accelerate.utils.align_module_device(module: Module, execution_device: torch.device | None = None)
```

[Fonte](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/modeling.py#L2135)

**Parâmetros:**

module (`torch.nn.Module`) : Módulo com parâmetros para alinhar.

execution_device (`torch.device`, *opcional*) : Se fornecido, substitui o dispositivo de execução do módulo dentro do contexto. Caso contrário, usa o dispositivo de execução do hook ou passa

Gerenciador de contexto que move os parâmetros de um módulo para o dispositivo de execução especificado.

