# 处理大型模型

## 分发与卸载

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

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

**参数：**

include_buffers (`bool`, *可选*) : 初始化时是否将所有缓冲区也放置在 meta 设备上。

一个上下文管理器，在该管理器下，模型的所有参数都会在 meta 设备上初始化，从而创建一个空模型。当仅初始化模型就会耗尽可用内存时，此功能非常有用。

示例：

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

Any model created under this context manager has no weights. As such you can't do something like `model.to(some_device)` with it. To load weights inside your empty model, see [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/zh/package_reference/big_modeling#accelerate.load_checkpoint_and_dispatch). Make sure to overwrite the default device_map param for [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/zh/package_reference/big_modeling#accelerate.load_checkpoint_and_dispatch), otherwise dispatch is not called.

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

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

**参数：**

model (`torch.nn.Module`)：要卸载的模型。

execution_device (`torch.device`, *可选*) : 模型前向传播将执行所在的设备（应为 GPU）。默认值为模型第一个参数的设备。

offload_buffers (`bool`，*可选*，默认为 `False`)：是否将缓冲区与模型参数一起卸载。

state_dict (`Dict[str, torch.Tensor]`, *可选*) : 将保留在 CPU 上的模型状态字典。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

为模型启用完整的 CPU 卸载。因此，模型的所有参数都将被卸载，并且仅保留一份模型状态字典的副本。在前向传播过程中，参数将从该状态字典中提取出来，并在需要时以原样放置到传入的执行设备上，随后再次被卸载。

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

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

**参数：**

model (`torch.nn.Module`)：要卸载的模型。

execution_device(`str`, `int` 或 `torch.device`, *可选*) : 模型应执行所在的设备。如果可用，默认使用 MPS 设备；否则，如果存在加速器设备，则使用设备 0；最后回退到 CPU。

prev_module_hook (`UserCpuOffloadHook`, *可选*) : 此函数为流水线中前一个模型返回的钩子。如果传入，其 offload 方法将在挂载此钩子的模型执行 forward 之前被调用。

将模型卸载到 CPU，并在执行时将其放回执行设备。与 [cpu_offload()](/docs/accelerate/v1.16.0/zh/package_reference/big_modeling#accelerate.cpu_offload) 的区别在于，前向传播后模型会保留在执行设备上，只有当调用返回的 `hook` 的 `offload` 方法时才会再次卸载。适用于在循环中运行模型的流水线。

示例：

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

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

**参数：**

model (`torch.nn.Module`)：要卸载的模型。

offload_dir (`str` 或 `os.PathLike`)：用于卸载模型权重的文件夹（或模型权重已卸载的位置）。

execution_device (`torch.device`, *可选*) : 模型前向传播将执行所在的设备（应为 GPU）。默认使用模型第一个参数的设备。

offload_buffers (`bool`，*可选*，默认为 `False`)：是否将缓冲区与模型参数一起卸载。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

为模型启用完整的磁盘卸载。因此，模型的所有参数都将作为内存映射数组卸载到指定文件夹中。在前向传播过程中，参数将从该文件夹中读取，并在需要时以原样放置到传入的执行设备上，随后再次被卸载。

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

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

**参数：**

model (`torch.nn.Module`)：要分发的模型。

device_map (`Dict[str, Union[str, int, torch.device]]`) : 一个字典，将模型 `state_dict` 中的模块名称映射到它们应放置的设备。请注意，即使 `"disk"` 不是 `torch.device` 的有效值，它也是被接受的。

main_device (`str`、`int` 或 `torch.device`，*可选*)：主要执行设备。默认值为 `device_map` 中第一个不同于 `"cpu"` 或 `"disk"` 的设备。

state_dict (`Dict[str, torch.Tensor]`, *可选*) : 将保留在 CPU 上的模型部分的 state dict。

offload_dir (`str` 或 `os.PathLike`)：用于卸载模型权重的文件夹（或模型权重已卸载的位置）。

offload_index (`Dict`, *可选*) : 从权重名称到其信息（`dtype`/ `shape` 或 safetensors 文件名）的字典。默认使用保存在 `save_folder` 中的索引。

offload_buffers (`bool`，*可选*，默认为 `False`)：是否将缓冲区与模型参数一起卸载。

skip_keys (`str` 或 `List[str]`，*可选*)：在设备之间移动输入或输出时需要忽略的键列表。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

force_hooks (`bool`，*可选*，默认为 `False`)：是否强制将设备钩子附加到模型上，即使所有层都已调度到单个设备上。

根据给定的设备映射来调度模型。模型的层可能分布在多个 GPU 上，卸载到 CPU 上，甚至卸载到磁盘上。

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

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

**参数：**

model (`torch.nn.Module`)：要加载检查点的模型。

checkpoint (`str` 或 `os.PathLike`) : 要加载的文件夹检查点。它可以是： - 包含完整模型状态字典的文件路径 - 包含分片检查点索引的 `.json` 文件路径 - 包含唯一的 `.index.json` 文件和检查点分片的文件夹路径。

device_map (`Dict[str, Union[int, str, torch.device]]`, *可选*) : 一个映射，用于指定每个子模块应放置的位置。它无需细化到每个参数/缓冲区名称，只要某个模块名称包含在内，其所有子模块都将被发送到同一设备。 若要让 Accelerate 自动计算最优化的 `device_map`，请设置 `device_map="auto"`。有关每个选项的更多信息，请参阅 [此处](../concept_guides/big_model_inference#designing-a-device-map)。默认为 None，这意味着不会调用 [dispatch_model()](/docs/accelerate/v1.16.0/zh/package_reference/big_modeling#accelerate.dispatch_model)。

max_memory (`Dict`, *可选*) : 一个从设备标识符到最大内存的字典。如果未设置，将默认为每个 GPU 的最大可用内存和可用的 CPU 内存。

no_split_module_classes (`List[str]`, *可选*) : 一个层类名列表，这些层不应跨设备拆分（例如任何具有残差连接的层）。

offload_folder (`str` 或 `os.PathLike`，*可选*) : 如果 `device_map` 包含任何值为 `"disk"` 的项，则指定用于卸载权重的文件夹。

offload_buffers (`bool`，*可选*，默认为 `False`)：对于卸载到 CPU 或硬盘的层，是否同时卸载缓冲区以及参数。

dtype (`str` 或 `torch.dtype`，*可选*)：如果提供，加载时权重将被转换为该类型。

offload_state_dict (`bool`, *可选*) : 如果为 `True`，当 CPU 状态字典的权重加上最大分片无法放入 CPU 内存时，会临时将 CPU 状态字典卸载到硬盘上，以避免 CPU 内存不足。如果所选的设备映射包含 `"disk"` 值，则默认设为 `True`。

skip_keys (`str` 或 `List[str]`，*可选*)：在设备之间移动输入或输出时需要忽略的键列表。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

force_hooks (`bool`，*可选*，默认为 `False`)：是否强制将设备钩子附加到模型上，即使所有层都已调度到单个设备上。

strict (`bool`，*可选*，默认为 `False`)：是否严格强制检查点 state_dict 中的键与模型 state_dict 的键相匹配。

full_state_dict (`bool`，*可选*，默认为 `True`)：如果设置为 `True`，则加载的 state_dict 中的所有张量都会被收集。加载的 state_dict 中不会包含 ShardedTensor 和 DTensor。

broadcast_from_rank0 (`False`，*可选*，默认为 `False`)：当该选项为 `True` 时，必须初始化一个分布式 `ProcessGroup`。rank0 应接收完整的 state_dict，并将 state_dict 中的张量逐个广播到其他 rank。其他 rank 将接收这些张量，并根据模型中的本地分片进行分片（如适用）。

在模型内部加载（可能分片的）检查点，在加载过程中可能将权重发送到指定设备，并添加各种钩子，以确保该模型能够正常运行（即使其被拆分到多个设备上）。

示例：

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

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

**参数：**

model (`torch.nn.Module`)：要加载检查点的模型。

checkpoint (`str` 或 `os.PathLike`) : 要加载的文件夹检查点。它可以是： - 包含完整模型状态字典的文件路径 - 包含分片检查点索引的 `.json` 文件路径 - 包含唯一的 `.index.json` 文件和检查点分片的文件夹路径。 - 包含唯一的 pytorch_model.bin 或 model.safetensors 文件的文件夹路径。

device_map (`Dict[str, Union[int, str, torch.device]]`, *可选*) : 一个映射，用于指定每个子模块应放置的位置。它无需细化到每个参数/缓冲区名称，只要某个模块名称包含在内，其所有子模块都将被发送到同一设备。

offload_folder (`str` 或 `os.PathLike`，*可选*) : 如果 `device_map` 包含任何值为 `"disk"` 的项，则指定用于卸载权重的文件夹。

dtype (`str` 或 `torch.dtype`，*可选*)：如果提供，加载时权重将被转换为该类型。

offload_state_dict (`bool`，*可选*，默认为 `False`)：如果为 `True`，当 CPU 状态字典的权重加上最大分片无法放入 CPU 内存时，会临时将 CPU 状态字典卸载到硬盘上，以避免 CPU 内存不足。

offload_buffers (`bool`, *可选*, 默认为 `False`) : 是否将缓冲区包含在卸载到磁盘的权重中。

keep_in_fp32_modules(`List[str]`, *可选*) : 一个模块列表，这些模块将保持为 `torch.float32` 数据类型。

offload_8bit_bnb (`bool`, *可选*) : 是否启用将 8 位模块卸载到 CPU/磁盘。

strict (`bool`，*可选*，默认为 `False`)：是否严格强制检查点 state_dict 中的键与模型 state_dict 的键相匹配。

full_state_dict (`bool`，*可选*，默认为 `True`)：如果设置为 `True`，则加载的 state_dict 中的所有张量都会被收集。加载的 state_dict 中不会包含 ShardedTensor 和 DTensor。

broadcast_from_rank0 (`False`，*可选*，默认为 `False`)：当该选项为 `True` 时，必须初始化一个分布式 `ProcessGroup`。rank0 应接收完整的 state_dict，并将 state_dict 中的张量逐个广播到其他 rank。其他 rank 将接收这些张量，并根据模型中的本地分片进行分片（如适用）。

在模型内部加载（可能分片的）检查点，并在加载时将权重发送到指定设备。

Once loaded across devices, you still need to call [dispatch_model()](/docs/accelerate/v1.16.0/zh/package_reference/big_modeling#accelerate.dispatch_model) on your model to make it able to run. To group the checkpoint loading and dispatch in one single call, use [load_checkpoint_and_dispatch()](/docs/accelerate/v1.16.0/zh/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)
```

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

**参数：**

model (`torch.nn.Module`)：要分析的模型。

max_memory (`Dict`, *可选*) : 一个从设备标识符到最大内存的字典。如果未设置，则默认为可用的最大内存。示例：`max_memory={0: "1GB"}`。

no_split_module_classes (`List[str]`, *可选*) : 一个层类名列表，这些层不应跨设备拆分（例如任何具有残差连接的层）。

dtype (`str` 或 `torch.dtype`，*可选*)：如果提供，加载时权重将被转换为该类型。

special_dtypes (`Dict[str, Union[str, torch.device]]`，*可选*)：如果提供，则为某些特定权重考虑的特殊 dtype（将覆盖用于所有权重的默认 dtype）。

verbose (`bool`，*可选*，默认为 `False`)：在函数构建 device_map 时，是否提供调试语句。

clean_result (`bool`，*可选*，默认为 `True`)：通过将所有位于同一设备上的子模块归为一组，来清理生成的 device_map。

offload_buffers (`bool`，*可选*，默认为 `False`)：对于卸载到 CPU 或硬盘的层，是否同时卸载缓冲区以及参数。

fallback_allocation (`bool`，*可选*，默认为 `False`)：当常规分配失败时，尝试使用 BFS 分配一个符合大小限制的模块。

为给定模型计算设备映射，优先分配给 GPU，然后卸载到 CPU，最后卸载到磁盘，使得：
- 我们不会超出任何 GPU 的可用内存。
- 如果需要将层卸载到 CPU，那么 GPU 0 上始终会预留足够的空间，以便将 CPU 上占用空间最大的已卸载层重新放回。
- 如果需要将数据卸载到 CPU，我们不会超出 CPU 上可用的 RAM。
- 如果需要将层卸载到磁盘，CPU 上始终会保留足够的空间，以便将已卸载到磁盘的层中体积最大的那一层重新加载回 CPU。

所有计算都是通过分析模型参数的大小和数据类型来完成的。因此，模型可以位于 meta 设备上（例如，在 `init_empty_weights` 上下文管理器内初始化时即为如此）。

## 钩子

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

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

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

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

一个包含回调的钩子，这些回调将在模型的前向方法执行之前和之后运行。与 PyTorch 中现有的钩子不同，这些回调会接收 kwargs 参数。

类属性：
- **no_grad** (`bool`，*可选*，默认为 `False`) -- 是否在 `torch.no_grad()` 上下文管理器下执行实际的前向传播。

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

```python
detach_hook(module)
```

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

**参数：**

module (`torch.nn.Module`)：从此钩子中分离的模块。

在钩子从模块上分离时执行。

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

```python
init_hook(module)
```

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

**参数：**

module (`torch.nn.Module`)：附加到此钩子的模块。

在钩子附加到模块时执行。

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

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

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

**参数：**

module (`torch.nn.Module`)：在此事件之前刚刚执行了前向传播的模块。

output (`Any`)：模块的输出。

**返回：** `Any`

处理后的`output`。

在模型的前向方法执行后立即执行。

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

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

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

**参数：**

module (`torch.nn.Module`)：将在该事件之后立即执行前向传播的模块。

args (`Tuple[Any]`) : 传递给模块的位置参数。

kwargs (`Dict[Str, Any]`) : 传递给模块的关键字参数。

**返回：** `Tuple[Tuple[Any], Dict[Str, Any]]`

一个包含经过处理的 `args` 和 `kwargs` 的元组。

在模型的前向方法执行之前立即执行。

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

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

**参数：**

execution_device (`torch.device`, *可选*) : 在前向传播之前，输入和模型权重应放置的设备。

offload (`bool`, *可选*, 默认为 `False`) : 是否在前向传播后卸载权重。

io_same_device (`bool`，*可选*，默认为 `False`)：是否应将输出放置在输入所在的同一设备上。

weights_map (`Mapping[str, torch.Tensor]`, *可选*) : 当模型权重被卸载时，一个（可能是惰性的）从参数名称到张量值的映射。

offload_buffers (`bool`, *可选*, 默认为 `False`) : 在卸载时是否包含关联模块的缓冲区。

place_submodules (`bool`, *可选*, 默认为 `False`) : 是否在 `init_hook` 事件期间将子模块放置在 `execution_device` 上。

一个通用的 `ModelHook`，用于确保在关联模块的前向传播过程中，输入和模型权重位于同一设备上，并可能在前向传播结束后将权重卸载。

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

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

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

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

一个可以包含多个钩子并在每个事件时遍历它们的钩子。

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

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

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

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

一个钩子，用于将模块的权重转换为高精度数据类型以进行计算，并转换为低精度数据类型以进行存储。此过程可能会导致输出质量下降，但可以显著减少内存占用。

## 添加钩子

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

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

**参数：**

module (`torch.nn.Module`)：要挂载钩子的模块。

hook (`ModelHook`)：要附加的钩子。

append (`bool`，*可选*，默认为 `False`)：是否应将钩子与现有钩子（如果模块已包含钩子）进行链式连接。

**返回：** `torch.nn.Module`

相同的模块，已附加钩子（模块会被就地修改，因此可以丢弃返回结果）。

为指定模块添加一个钩子。这将重写该模块的 `forward` 方法以包含该钩子。若要移除此行为并恢复原始的 `forward` 方法，请使用 `remove_hook_from_module`。

如果模块中已存在一个钩子，默认情况下会用传入的新钩子将其替换。若要串联两个钩子，请传入 `append=True`，这样会将当前钩子与新钩子串联为 `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)
```

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

**参数：**

module (`torch.nn.Module`)：要挂载钩子的模块。

execution_device (`int`、`str` 或 `torch.device`)：在前向传播之前，输入和模型权重应放置的设备。

skip_keys (`str` 或 `List[str]`，*可选*)：在设备之间移动输入或输出时需要忽略的键列表。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *可选*，默认为 `None`)：一个从数据指针映射到设备字典的映射，其中设备字典包含已分发的绑定权重。对于给定的执行设备，此参数可用于复用共享权重的第一个可用指针，供其他所有设备使用，从而避免内存重复。

递归地将 `AlignDevicesHook` 附加到给定模型的所有子模块，以确保它们具有正确的执行设备

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

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

**参数：**

module (`torch.nn.Module`)：要挂载钩子的模块。

execution_device (`torch.device`, *可选*) : 在前向传播之前，输入和模型权重应放置的设备。

offload (`bool`, *可选*, 默认为 `False`) : 是否在前向传播后卸载权重。

weights_map (`Mapping[str, torch.Tensor]`, *可选*) : 当模型权重被卸载时，一个（可能是惰性的）从参数名称到张量值的映射。

offload_buffers (`bool`, *可选*, 默认为 `False`) : 在卸载时是否包含关联模块的缓冲区。

module_name (`str`，*可选*，默认为 `""`)：模块的名称。

skip_keys (`str` 或 `List[str]`，*可选*)：在设备之间移动输入或输出时需要忽略的键列表。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *可选*，默认为 `None`)：一个从数据指针映射到设备字典的映射，其中设备字典包含已分发的绑定权重。对于给定的执行设备，此参数可用于复用共享权重的第一个可用指针，供其他所有设备使用，从而避免内存重复。

递归地将 `AlignDevicesHook` 附加到给定模型中所有具有直接参数和/或缓冲区（buffers）的子模块。

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

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

**参数：**

module (`torch.nn.Module`)：要挂载钩子的模块。

execution_device (`torch.device` 或 `Dict[str, torch.device]`，*可选*) : 在前向传播之前，输入和模型权重应放置的设备。它可以是整个模块使用的单一设备，也可以是模块名称到设备的映射字典。

offload (`bool`，*可选*，默认为 `False`)：是否应在前向传播后卸载权重。它可以是用于整个模块的一个布尔值，也可以是映射模块名称到布尔值的字典。

weights_map (`Mapping[str, torch.Tensor]`, *可选*) : 当模型权重被卸载时，一个（可能是惰性的）从参数名称到张量值的映射。

offload_buffers (`bool`, *可选*, 默认为 `False`) : 在卸载时是否包含关联模块的缓冲区。

module_name (`str`，*可选*，默认为 `""`)：模块的名称。

skip_keys (`str` 或 `List[str]`，*可选*)：在设备之间移动输入或输出时需要忽略的键列表。

preload_module_classes (`List[str]`, *可选*) : 一个类列表，其实例应在前向传播开始时加载所有权重（包括子模块中的权重）。此参数仅应用于那些在子模块中注册了但未在前向传播中直接调用的类，例如，如果注册了一个 `dense` 线性层，但在前向传播中，某些操作直接使用 `dense.weight` 和 `dense.bias`，而不是直接调用 `dense`。

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *可选*，默认为 `None`)：一个从数据指针映射到设备字典的映射，其中设备字典包含已分发的绑定权重。对于给定的执行设备，此参数可用于复用共享权重的第一个可用指针，供其他所有设备使用，从而避免内存重复。

根据需要在给定模型的所有块上附加 `AlignDevicesHook`。

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

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

**参数：**

module (`torch.nn.Module`)：其叶子模块将在计算时转换为高精度数据类型，在存储时转换为低精度数据类型的模块。

storage_dtype (`torch.dtype`)：在存储之前/之后，用于将模块转换到的数据类型。

compute_dtype (`torch.dtype`)：在前向传播计算期间，将模块转换到的数据类型。

skip_modules_pattern (`tuple[str, ...]`，默认为 `None`) : 用于匹配在逐层转换过程中需要跳过的模块名称的模式列表。如果设置为 `None` 且 `skip_modules_classes` 也为 `None`，则逐层转换将直接应用于该模块，而不是其内部子模块。

skip_modules_classes (`tuple[type[torch.nn.Module], ...]`，默认为 `None`)：在逐层转换过程中需要跳过的模块类列表。

non_blocking (`bool`，默认为 `False`)：如果为 `True`，则权重转换操作为非阻塞的。

对给定模块应用逐层类型转换。此处期望的模块是 PyTorch `nn.Module`。当不希望完全量化模型时，这有助于降低内存需求。可以将模型参数保留为例如 `torch.float8_e4m3fn`，在前向传播期间上转换为更高精度（如 `torch.bfloat16`），然后再下转换回 `torch.float8_e4m3fn` 以实现内存节省。

示例：

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

用户还可以传入希望避免被降级的模块。

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

## 移除钩子

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

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

**参数：**

module (`torch.nn.Module`)：要挂载钩子的模块。

recurse (`bool`, **可选**) : 是否递归地移除钩子

**返回：** `torch.nn.Module`

相同的模块，但已分离钩子（该模块会被就地修改，因此可以丢弃返回结果）。

移除通过 `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)
```

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

**参数：**

module (`torch.nn.Module`)：要移除所有钩子的模块。

递归移除给定模型的所有子模块上附加的所有钩子。

## 实用工具

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

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

**参数：**

module (`torch.nn.Module`)：要检查是否存在 offload hook 的模块。

**返回：** `bool`

如果模块具有 offload 钩子且 offloading 已启用，则返回 `True`，否则返回 `False`。

通过检查给定模块是否附加了启用卸载的 AlignDevicesHook，来检查该模块是否具有已卸载的参数

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

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

**参数：**

module (`torch.nn.Module`)：包含用于对齐的参数的模块。

execution_device (`torch.device`，*可选*)：如果提供，则覆盖上下文中的模块执行设备。否则，使用钩子执行设备或传递

上下文管理器，用于将模块的参数移动到指定的执行设备。

