# Công cụ Fully Sharded Data Parallel

## enable_fsdp_ram_efficient_loading[[accelerate.utils.enable_fsdp_ram_efficient_loading]]

#### accelerate.utils.enable_fsdp_ram_efficient_loading[[accelerate.utils.enable_fsdp_ram_efficient_loading]]

```python
accelerate.utils.enable_fsdp_ram_efficient_loading()
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L40)

Cho phép tải các mô hình Hugging Face một cách hiệu quả về RAM cho FSDP trong môi trường.

## disable_fsdp_ram_efficient_loading[[accelerate.utils.disable_fsdp_ram_efficient_loading]]

#### accelerate.utils.disable_fsdp_ram_efficient_loading[[accelerate.utils.disable_fsdp_ram_efficient_loading]]

```python
accelerate.utils.disable_fsdp_ram_efficient_loading()
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L50)

Tắt tính năng nạp hiệu quả RAM cho các mô hình Hugging Face dành cho FSDP trong môi trường.

## merge_fsdp_weights[[accelerate.utils.merge_fsdp_weights]]

#### accelerate.utils.merge_fsdp_weights[[accelerate.utils.merge_fsdp_weights]]

```python
accelerate.utils.merge_fsdp_weights(checkpoint_dir: str, output_path: str, safe_serialization: bool = True, remove_checkpoint_dir: bool = False)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L486)

**Tham số:**

checkpoint_dir (`str`) : Thư mục chứa các checkpoint FSDP (có thể là của model hoặc optimizer).

output_path (`str`) : Đường dẫn để lưu checkpoint đã hợp nhất.

safe_serialization (`bool`, *tùy chọn*, mặc định là `True`) : Có lưu trọng số đã hợp nhất với safetensors (được khuyến nghị) hay không.

remove_checkpoint_dir (`bool`, *tùy chọn*, mặc định là `False`) : Có xóa thư mục checkpoint sau khi gộp hay không.

Gộp các trọng số từ các checkpoint mô hình FSDP dạng phân mảnh (sharded) thành một checkpoint kết hợp duy nhất. Nên sử dụng nếu `SHARDED_STATE_DICT` đã được dùng cho mô hình. Các trọng số sẽ được lưu vào `{output_path}/model.safetensors` nếu `safe_serialization`, ngược lại là `pytorch_model.bin`.

Lưu ý: đây là một quy trình bị giới hạn bởi CPU.

## FullyShardedDataParallelPlugin[[accelerate.FullyShardedDataParallelPlugin]]

#### accelerate.FullyShardedDataParallelPlugin[[accelerate.FullyShardedDataParallelPlugin]]

```python
accelerate.FullyShardedDataParallelPlugin(fsdp_version: int = None, sharding_strategy: str | ForwardRef('torch.distributed.fsdp.ShardingStrategy') = None, reshard_after_forward: str | ForwardRef('torch.distributed.fsdp.ShardingStrategy') | bool = None, backward_prefetch: str | ForwardRef('torch.distributed.fsdp.BackwardPrefetch') | None = None, mixed_precision_policy: dict | str | ForwardRef('torch.distributed.fsdp.MixedPrecision') | ForwardRef('torch.distributed.fsdp.MixedPrecisionPolicy') | None = None, auto_wrap_policy: typing.Callable | typing.Literal['transformer_based_wrap', 'size_based_wrap', 'no_wrap'] | None = None, cpu_offload: bool | ForwardRef('torch.distributed.fsdp.CPUOffload') | ForwardRef('torch.distributed.fsdp.CPUOffloadPolicy') = None, ignored_modules: collections.abc.Iterable[torch.nn.Module] | str | None = None, state_dict_type: str | ForwardRef('torch.distributed.fsdp.StateDictType') = None, state_dict_config: ForwardRef('torch.distributed.fsdp.FullStateDictConfig') | ForwardRef('torch.distributed.fsdp.ShardedStateDictConfig') | None = None, optim_state_dict_config: ForwardRef('torch.distributed.fsdp.FullOptimStateDictConfig') | ForwardRef('torch.distributed.fsdp.ShardedOptimStateDictConfig') | None = None, limit_all_gathers: bool = True, use_orig_params: bool | None = None, param_init_fn: typing.Callable[[torch.nn.Module], NoneType] | None = None, sync_module_states: bool | None = None, forward_prefetch: bool = None, activation_checkpointing: bool = None, activation_checkpointing_offload: bool = None, cpu_ram_efficient_loading: bool = None, transformer_cls_names_to_wrap: list[str] | None = None, min_num_params: int | None = None)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1465)

**Tham số:**

fsdp_version (`int`, mặc định là `1`) : Phiên bản của FSDP cần sử dụng. Mặc định là 1. Nếu đặt thành 2, trình khởi chạy sẽ kỳ vọng cấu hình đã được chuyển đổi sang định dạng FSDP2.

sharding_strategy (`Union[str, torch.distributed.fsdp.ShardingStrategy]`, mặc định là `'FULL_SHARD'`) : Chiến lược sharding cần sử dụng. Phải là một `str` hoặc một instance của `torch.distributed.fsdp.fully_sharded_data_parallel.ShardingStrategy`. Đã bị thay thế bởi `reshard_after_forward`.

reshard_after_forward (`Union[str, torch.distributed.fsdp.ShardingStrategy, bool]`, mặc định là `'FULL_SHARD'` cho `fsdp_version=1` và `True` cho `fsdp_version=2`) : Chiến lược sharding cần sử dụng. Phải là một bool nếu `fsdp_version` được đặt thành 2, ngược lại phải là một `str` hoặc một instance của `torch.distributed.fsdp.fully_sharded_data_parallel.ShardingStrategy`.

backward_prefetch (`Union[str, torch.distributed.fsdp.BackwardPrefetch]`, mặc định là `'NO_PREFETCH'`) : Chiến lược prefetch ngược (backward prefetch) cần sử dụng. Phải là một `str` hoặc một instance của `torch.distributed.fsdp.fully_sharded_data_parallel.BackwardPrefetch`.

mixed_precision_policy (`Optional[Union[dict, str, torch.distributed.fsdp.MixedPrecision, torch.distributed.fsdp.MixedPrecisionPolicy]]`, mặc định là `None`) : Cấu hình để bật huấn luyện độ chính xác hỗn hợp với FullyShardedDataParallel. Nếu truyền vào một `dict`, nó phải có các khóa sau: `param_dtype`, `reduce_dtype` và `buffer_dtype`, có thể là một instance của `torch.distributed.fsdp.MixedPrecisionPolicy` nếu `fsdp_version` được đặt thành 2. Nếu truyền vào một `str`, nó phải là một trong các giá trị sau: fp8, fp16, bf16, fp32, và được dùng để đặt `param_dtype`, `reduce_dtype` và `buffer_dtype`.

auto_wrap_policy (`Optional(Union[Callable, Literal["transformer_based_wrap", "size_based_wrap", "no_wrap"]]), defaults to `NO_WRAP`) : A callable or string specifying a policy to recursively wrap layers with FSDP. If a string, it must be one of `transformer_based_wrap`, `size_based_wrap`, or `no_wrap`. See `torch.distributed.fsdp.wrap.size_based_wrap_policy` for a direction on what it should look like.

cpu_offload (`Union[bool, torch.distributed.fsdp.CPUOffload, torch.distributed.fsdp.CPUOffloadPolicy]`, mặc định là `False`) : Có nên offload tham số sang CPU hay không. Giá trị phải là `bool` hoặc một instance của `torch.distributed.fsdp.fully_sharded_data_parallel.CPUOffload` hoặc `torch.distributed.fsdp.fully_sharded_data_parallel.CPUOffloadPolicy` nếu `fsdp_version` được đặt thành 2.

ignored_modules (`Optional[Union[Iterable[torch.nn.Module], str]]`, mặc định là `None`) : Một danh sách các module cần bỏ qua khi bọc bằng FSDP. Khi truyền một chuỗi, các module sẽ được khớp theo tên bằng regex fullmatch. Nếu `fsdp_version` được đặt thành 2, các module sẽ được chuyển thành các tham số và được sử dụng.

state_dict_type (`Union[str, torch.distributed.fsdp.StateDictType]`, mặc định là `'FULL_STATE_DICT'`) : Kiểu state dict cần sử dụng. Nếu là chuỗi, nó phải là một trong `full_state_dict`, `local_state_dict`, hoặc `sharded_state_dict`.

state_dict_config (`Optional[Union[torch.distributed.fsdp.FullStateDictConfig, torch.distributed.fsdp.ShardedStateDictConfig]`, mặc định là `None`) : Cấu hình state dict cần sử dụng. Nếu không được truyền vào, giá trị này sẽ được xác định dựa trên `state_dict_type`.

optim_state_dict_config (`Optional[Union[torch.distributed.fsdp.FullOptimStateDictConfig, torch.distributed.fsdp.ShardedOptimStateDictConfig]`, mặc định là `None`) : Cấu hình state dict của optimizer cần sử dụng. Được xác định dựa trên `state_dict_type` nếu không được truyền vào.

limit_all_gathers (`bool`, mặc định là `True`) : Xác định có để FSDP đồng bộ hóa rõ ràng luồng CPU để ngăn quá nhiều all-gather đang chạy hay không. Giá trị bool này chỉ ảnh hưởng đến các chiến lược phân mảnh (sharded) có lịch trình all-gather. Bật tùy chọn này có thể giúp giảm số lần thử lại (retries) của CUDA malloc.

use_orig_params (`bool`, mặc định là `False`) : Có sử dụng các tham số gốc cho bộ tối ưu hay không.

param_init_fn (`Optional[Callable[[torch.nn.Module], None]`, mặc định là `None`) : Một `Callable[torch.nn.Module] -> None` quy định cách khởi tạo các module hiện đang trên thiết bị meta lên một thiết bị thực. Chỉ áp dụng khi `sync_module_states` là `True`. Mặc định là một `lambda` gọi `to_empty` trên module.

sync_module_states (`bool`, mặc định là `False`) : Xác định xem mỗi đơn vị FSDP được bọc riêng lẻ có nên phát trực tiếp (broadcast) các tham số module từ rank 0 để đảm bảo chúng giống nhau trên tất cả các rank sau khi khởi tạo hay không. Mặc định là `False` trừ khi `cpu_ram_efficient_loading` là `True`, khi đó tùy chọn này sẽ được bật bắt buộc.

forward_prefetch (`bool`, mặc định là `False`) : Xác định việc FSDP có lấy trước (prefetch) thao tác all-gather tiếp theo trong khi thực hiện bước truyền xuôi (forward pass) hay không. Chỉ sử dụng với đồ thị tĩnh (Static graphs).

activation_checkpointing (`bool`, mặc định là `False`) : Một kỹ thuật để giảm mức sử dụng bộ nhớ bằng cách xóa các kích hoạt của một số lớp nhất định và tính toán lại chúng trong quá trình truyền ngược. Về cơ bản, kỹ thuật này đánh đổi thêm thời gian tính toán để giảm mức sử dụng bộ nhớ.

cpu_ram_efficient_loading (`bool`, mặc định là `None`) : Nếu là True, chỉ tiến trình đầu tiên tải checkpoint mô hình được huấn luyện trước, trong khi tất cả các tiến trình khác có trọng số rỗng. Chỉ áp dụng cho Transformers. Khi sử dụng điều này, `sync_module_states` cần phải là `True`.

transformer_cls_names_to_wrap (`Optional[List[str]]`, mặc định là `None`) : Một danh sách tên lớp của các tầng transformer cần bọc. Chỉ áp dụng khi `auto_wrap_policy` là `transformer_based_wrap`.

min_num_params (`Optional[int]`, mặc định là `None`) : Số lượng tham số tối thiểu mà một module phải có để được bọc. Chỉ áp dụng khi `auto_wrap_policy` là `size_based_wrap`.

Plugin này được sử dụng để bật song song dữ liệu phân mảnh hoàn toàn.

#### set_auto_wrap_policy[[accelerate.FullyShardedDataParallelPlugin.set_auto_wrap_policy]]

```python
set_auto_wrap_policy(model)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1941)

Với `model`, tạo một `auto_wrap_policy` dựa trên chính sách được truyền vào và nếu chúng ta có thể sử dụng `transformer_cls_to_wrap`

#### set_mixed_precision[[accelerate.FullyShardedDataParallelPlugin.set_mixed_precision]]

```python
set_mixed_precision(mixed_precision, buffer_autocast = False, override = False)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1981)

Đặt chính sách độ chính xác hỗn hợp cho FSDP

#### set_state_dict_type[[accelerate.FullyShardedDataParallelPlugin.set_state_dict_type]]

```python
set_state_dict_type(state_dict_type = None)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L1896)

Đặt cấu hình state dict dựa trên `StateDictType`.

#### validate_mixed_precision_policy[[accelerate.FullyShardedDataParallelPlugin.validate_mixed_precision_policy]]

```python
validate_mixed_precision_policy()
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/dataclasses.py#L2029)

Kiểm tra chính sách độ chính xác hỗn hợp, được trừu tượng hóa để không đưa các lệnh import vào nếu không cần thiết.

## fsdp2_load_full_state_dict[[accelerate.utils.fsdp2_load_full_state_dict]]

#### accelerate.utils.fsdp2_load_full_state_dict[[accelerate.utils.fsdp2_load_full_state_dict]]

```python
accelerate.utils.fsdp2_load_full_state_dict(accelerator, model: Module, full_sd: dict, cpu_offload: bool = False)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L584)

**Tham số:**

accelerator (`Accelerator`) : Bản thể accelerator

model (`torch.nn.Module`) : Mô hình để nạp state dict vào, được kỳ vọng nằm trên meta device, nếu không có thể xảy ra hiện tượng tăng đột biến VRAM

full_sd (`dict`) : Toàn bộ state dict cần nạp, chỉ có thể nằm trên rank 0

cpu_offload (`bool`, mặc định là `False`) : Nếu là True, di chuyển các tham số phân mảnh sang CPU sau khi phân phối. Bắt buộc khi FSDP CPU offloading được bật. Các buffer và tham số bị bỏ qua vẫn nằm trên thiết bị accelerator.

Tải toàn bộ state dict (chỉ có thể nằm trên rank 0) vào mô hình đã chia shard. Việc này được thực hiện bằng cách phát trực tiếp (broadcast) các tham số từ rank 0 đến tất cả các rank khác. Hàm này sửa đổi mô hình tại chỗ (in-place).

## fsdp2_switch_optimizer_parameters[[accelerate.utils.fsdp2_switch_optimizer_parameters]]

#### accelerate.utils.fsdp2_switch_optimizer_parameters[[accelerate.utils.fsdp2_switch_optimizer_parameters]]

```python
accelerate.utils.fsdp2_switch_optimizer_parameters(optimizer: Optimizer, mapping: dict)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L658)

**Tham số:**

optimizer (`torch.optim.Optimizer`) : Đối tượng Optimizer chứa các tham số của mô hình gốc

mapping (`dict`) : Ánh xạ từ con trỏ dữ liệu của tham số gốc (hoặc danh tính đối với tham số meta) đến tham số đã phân mảnh.

**Lỗi:** ``KeyError``

- ``KeyError`` -- Nếu một tham số trong optimizer không thể được chuyển sang phiên bản sharded. Điều này không bao giờ xảy ra và cho thấy có lỗi. Nếu chúng ta giữ nguyên các tham số gốc thay vì ném ngoại lệ, quá trình huấn luyện sẽ không chính xác về mặt số học và trọng số sẽ không được cập nhật.

Chuyển các tham số của bộ tối ưu sang các tham số mới (tham số phân mảnh trong trường hợp thông thường). Hàm này sửa đổi bộ tối ưu tại chỗ.

## fsdp2_prepare_model[[accelerate.utils.fsdp2_prepare_model]]

#### accelerate.utils.fsdp2_prepare_model[[accelerate.utils.fsdp2_prepare_model]]

```python
accelerate.utils.fsdp2_prepare_model(accelerator, model: Module)
```

[Nguồn](https://github.com/huggingface/accelerate/blob/v1.16.0/src/accelerate/utils/fsdp_utils.py#L740)

**Tham số:**

accelerator (`Accelerator`) : Bản thể accelerator

model (`torch.nn.Module`) : Mô hình cần chuẩn bị

**Trả về:** `torch.nn.Module`

Mô hình đã được chuẩn bị

Chuẩn bị mô hình cho FSDP2 tại chỗ. Đồng thời trả về mô hình để tránh việc sử dụng sai mô hình gốc.

## fsdp2_prepare_auto_wrap_policy

