# 대형 모델 작업

## Dispatch 및 offload

### 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 device에 초기화되어 빈 모델이 생성되는 컨텍스트 매니저입니다. 모델 초기화만으로도 사용 가능한 RAM이 부족해지는 경우에 유용합니다.

예:

```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/ko/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/ko/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`, *선택 사항*) : 모델의 forward pass가 실행될 장치입니다 (GPU여야 합니다). 기본값은 모델의 첫 번째 파라미터 장치가 됩니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 모델 파라미터와 함께 버퍼를 오프로드할지 여부.

state_dict (`Dict[str, torch.Tensor]`, *선택 사항*) : CPU에 유지될 모델의 state dict입니다.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

모델에 대한 전체 CPU 오프로드를 활성화합니다. 그 결과, 모델의 모든 파라미터가 오프로드되고 모델의 state dict는 단 하나의 복사본만 유지됩니다. forward pass 동안에는 파라미터가 해당 state dict에서 추출되어 필요할 때 전달된 실행 장치에 그대로 배치된 후, 다시 오프로드됩니다.

### 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 장치를 사용하고, 가속기 장치가 있으면 device 0을, 그 외에는 CPU를 사용합니다.

prev_module_hook (`UserCpuOffloadHook`, *선택 사항*) : 실행 중인 파이프라인의 이전 모델에 대해 이 함수가 반환한 훅입니다. 전달되면, 이 훅이 연결된 모델의 forward가 실행되기 직전에 해당 offload 메서드가 호출됩니다.

모델을 CPU로 오프로드한 후 실행 시 실행 장치로 다시 올립니다. [cpu_offload()](/docs/accelerate/v1.16.0/ko/package_reference/big_modeling#accelerate.cpu_offload)와의 차이는 forward 이후에도 모델이 실행 장치에 남아 있으며, 반환된 `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`, *선택 사항*) : 모델의 forward pass가 실행될 장치(GPU여야 합니다). 기본값은 모델의 첫 번째 파라미터 장치가 됩니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 모델 파라미터와 함께 버퍼를 오프로드할지 여부.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

모델에 대한 전체 디스크 오프로드를 활성화합니다. 그 결과, 모델의 모든 파라미터가 지정된 폴더에 메모리 매핑된 배열로 오프로드됩니다. 포워드 패스 동안 파라미터는 해당 폴더에서 접근되어 필요할 때 실행 장치로 전달되며, 사용 후 다시 오프로드됩니다.

### 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]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

force_hooks (`bool`, *선택 사항*, 기본값 `False`) : 모든 레이어가 단일 디바이스에 배치된 경우에도 모델에 디바이스 훅을 강제 연결할지 여부.

device map에 따라 모델을 배포합니다. 모델의 레이어는 여러 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/ko/package_reference/big_modeling#accelerate.dispatch_model)이 호출되지 않음을 의미합니다.

max_memory (`Dict`, *선택 사항*) : 디바이스 식별자를 최대 메모리로 매핑한 사전입니다. 설정되지 않으면 각 GPU의 사용 가능한 최대 메모리와 사용 가능한 CPU RAM이 기본값으로 사용됩니다.

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 RAM에 맞지 않을 때 CPU RAM 부족을 방지하기 위해 CPU 상태 사전을 하드 드라이브로 일시적으로 오프로드합니다. 선택된 디바이스 맵에 `"disk"` 값이 포함된 경우 기본값은 `True`입니다.

skip_keys (`str` 또는 `List[str]`, *선택 사항*) : 디바이스 간에 입력 또는 출력을 이동할 때 무시할 키 목록.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

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 RAM에 맞지 않을 때 CPU RAM 부족을 방지하기 위해 CPU 상태 사전을 하드 드라이브에 일시적으로 오프로드합니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 디스크로 오프로드된 가중치에 버퍼를 포함할지 여부입니다.

keep_in_fp32_modules(`List[str]`, *선택 사항*) : `torch.float32` dtype로 유지할 모듈 목록입니다.

offload_8bit_bnb (`bool`, *선택 사항*) : 8비트 모듈의 cpu/disk 오프로딩을 활성화할지 여부.

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/ko/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/ko/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로의 offload가 필요한 경우, GPU 0에는 항상 CPU에 offload된 레이어 중 가장 큰 크기의 레이어를 다시 올릴 수 있는 여유 공간이 있습니다.
- CPU로 offload가 필요한 경우, CPU에서 사용 가능한 RAM을 초과하지 않습니다.
- 디스크 오프로딩이 필요한 경우에도, 디스크에 오프로드된 레이어 중 가장 큰 크기의 레이어를 CPU로 다시 올릴 수 있는 공간이 항상 남아 있습니다.

모든 계산은 모델 파라미터의 크기와 dtype를 분석하여 수행됩니다. 따라서 모델은 `init_empty_weights` 컨텍스트 매니저 내에서 초기화된 경우와 마찬가지로 meta 디바이스에 있을 수 있습니다.

## Hooks

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

모델의 forward 메서드 실행 직전과 직후에 실행될 콜백을 포함하는 훅입니다. PyTorch의 기존 훅과의 차이점은 kwargs가 함께 전달된다는 것입니다.

클래스 속성:
- **no_grad** (`bool`, *선택 사항*, 기본값 `False`) -- `torch.no_grad()` 컨텍스트 매니저 아래에서 실제 forward pass를 실행할지 여부.

#### 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`) : 이 훅에서 분리된 모듈입니다.

hook가 모듈에서 분리될 때 실행됩니다.

#### 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`) : 이 훅에 연결된 모듈입니다.

hook이 모듈에 연결될 때 실행됩니다.

#### 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`) : 이 이벤트 바로 전에 forward pass가 실행된 모듈입니다.

output (`Any`) : 모듈의 출력입니다.

**반환값:** `Any`

처리된 `output`.

모델의 forward 메서드 바로 다음에 실행됩니다.

#### 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`) : 이 이벤트 직후 forward pass가 실행될 모듈입니다.

args (`Tuple[Any]`) : 모듈에 전달된 위치 인자.

kwargs (`Dict[Str, Any]`) : 모듈에 전달되는 키워드 인자입니다.

**반환값:** `Tuple[Tuple[Any], Dict[Str, Any]]`

처리된 `args`와 `kwargs`로 구성된 튜플입니다.

모델의 forward 메서드가 실행되기 직전에 실행됩니다.

### 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`, *선택 사항*) : forward pass 전에 입력과 모델 가중치를 배치할 장치입니다.

offload (`bool`, *선택 사항*, 기본값 `False`) : forward pass 이후에 가중치를 offload할지 여부입니다.

io_same_device (`bool`, *선택 사항*, 기본값 `False`) : 출력이 입력이 있던 동일한 디바이스에 배치될지 여부입니다.

weights_map (`Mapping[str, torch.Tensor]`, *선택 사항*) : 모델 가중치가 오프로드된 경우, 파라미터 이름에서 텐서 값으로의 (지연된) 맵입니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 오프로딩 시 관련 모듈의 버퍼를 포함할지 여부.

place_submodules (`bool`, *선택 사항*, 기본값 `False`) : `init_hook` 이벤트 동안 서브모듈을 `execution_device`에 배치할지 여부.

해당 모듈의 forward pass에서 입력과 모델 가중치가 동일한 device에 있도록 보장하는 범용 `ModelHook`입니다. forward pass 이후 가중치를 offload할 수 있습니다.

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

모듈의 가중치를 계산 시에는 높은 정밀도의 dtype으로, 저장 시에는 낮은 정밀도의 dtype으로 변환하는 훅입니다. 이 과정은 출력의 품질 저하를 초래할 수 있지만, 메모리 사용량을 크게 줄일 수 있습니다.

## 훅 추가

### 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`) : forward pass 전에 입력과 모델 가중치를 배치할 장치.

skip_keys (`str` 또는 `List[str]`, *선택 사항*) : 디바이스 간에 입력 또는 출력을 이동할 때 무시할 키 목록.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

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`, *선택 사항*) : forward pass 전에 입력과 모델 가중치를 배치할 장치입니다.

offload (`bool`, *선택 사항*, 기본값 `False`) : forward pass 이후에 가중치를 offload할지 여부입니다.

weights_map (`Mapping[str, torch.Tensor]`, *선택 사항*) : 모델 가중치가 오프로드된 경우, 파라미터 이름에서 텐서 값으로의 (지연된) 맵입니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 오프로딩 시 관련 모듈의 버퍼를 포함할지 여부.

module_name (`str`, *선택 사항*, 기본값 `""`) : 모듈의 이름.

skip_keys (`str` 또는 `List[str]`, *선택 사항*) : 디바이스 간에 입력 또는 출력을 이동할 때 무시할 키 목록.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], *선택 사항*, 기본값은 `None`) : 데이터 포인터를 디바이스별 이미 디스패치된 타이드 웨이트 사전으로 매핑하는 맵입니다. 주어진 실행 디바이스에 대해, 이 매개변수는 메모리를 중복하는 대신 공유된 웨이트의 첫 번째 사용 가능한 포인터를 나머지 모든 웨이트에 재사용하는 데 유용합니다.

`AlignDevicesHook`을 주어진 모델의 직접적인 파라미터와/또는 버퍼를 가진 모든 서브모듈에 재귀적으로 연결합니다.

### 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]`, *선택 사항*) : forward pass 전에 입력과 모델 가중치를 배치할 장치입니다. 모듈 전체에 하나의 장치를 사용할 수도 있고, 모듈 이름을 장치로 매핑하는 사전(dictionary)을 사용할 수도 있습니다.

offload (`bool`, *선택 사항*, 기본값 `False`) : forward pass 이후에 가중치를 offload할지 여부입니다. 모듈 전체에 대해 하나의 boolean 값을 사용할 수도 있고, 모듈 이름을 boolean 값으로 매핑하는 dictionary를 사용할 수도 있습니다.

weights_map (`Mapping[str, torch.Tensor]`, *선택 사항*) : 모델 가중치가 오프로드된 경우, 파라미터 이름에서 텐서 값으로의 (지연된) 맵입니다.

offload_buffers (`bool`, *선택 사항*, 기본값 `False`) : 오프로딩 시 관련 모듈의 버퍼를 포함할지 여부.

module_name (`str`, *선택 사항*, 기본값 `""`) : 모듈의 이름.

skip_keys (`str` 또는 `List[str]`, *선택 사항*) : 디바이스 간에 입력 또는 출력을 이동할 때 무시할 키 목록.

preload_module_classes (`List[str]`, *선택 사항*) : forward의 시작 시 모든 가중치(서브모듈의 가중치를 포함하여)를 로드해야 하는 클래스 인스턴스의 목록입니다. 이는 forward 중에 직접 호출되지 않지만 등록되어 있는 서브모듈을 가진 클래스에만 사용해야 합니다. 예를 들어, `dense` 선형 레이어가 등록되어 있지만 forward에서 `dense`를 직접 호출하는 대신 `dense.weight`와 `dense.bias`가 일부 연산에 사용되는 경우입니다.

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`) : 계산 시 리프 모듈을 고정밀 dtype으로, 저장 시 저정밀 dtype으로 캐스팅할 모듈입니다.

storage_dtype (`torch.dtype`) : 저장하기 위해 forward pass 전/후에 모듈을 캐스팅할 dtype.

compute_dtype (`torch.dtype`) : forward pass에서 계산을 위해 모듈을 캐스트할 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`인 경우, 가중치 캐스팅 작업이 비차단(non-blocking) 방식으로 수행됩니다.

주어진 모듈에 레이어별 캐스팅을 적용합니다. 여기서 기대하는 모듈은 PyTorch `nn.Module`입니다. 이는 모델을 완전히 양자화하지 않고도 메모리 요구량을 줄이는 데 유용합니다. 모델 파라미터를 `torch.float8_e4m3fn`과 같은 형식으로 유지하고, forward pass 동안 `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 hook이 있고 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`) : 정렬할 매개변수를 가진 Module

execution_device (`torch.device`, *선택 사항*) : 지정된 경우, 컨텍스트 내에서 모듈의 실행 장치를 재정의합니다. 그렇지 않으면, 훅 실행 장치 또는 패스

지정된 실행 장치로 모듈의 매개변수를 이동하는 컨텍스트 매니저입니다.

