# Chuẩn hóa

`huggingface_hub` cung cấp các hàm trợ giúp để lưu và nạp trọng số mô hình ML theo cách chuẩn hóa. Phần này của thư viện vẫn đang trong quá trình phát triển và sẽ được cải thiện trong các bản phát hành tương lai. Mục tiêu là hài hòa hóa cách lưu và nạp trọng số trên Hub, vừa để loại bỏ sự trùng lặp mã giữa các thư viện, vừa để thiết lập các quy ước nhất quán.

## Định dạng tệp DDUF

DDUF là định dạng tệp được thiết kế cho các mô hình khuếch tán. Định dạng này cho phép lưu trữ toàn bộ thông tin cần thiết để chạy một mô hình trong một tệp duy nhất. Công việc này được lấy cảm hứng từ định dạng [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md). `huggingface_hub` cung cấp các hàm hỗ trợ để lưu và nạp tệp DDUF, đảm bảo tuân thủ đúng định dạng tệp.

> [!WARNING]
> Đây là một phiên bản rất sơ khai của trình phân tích cú pháp. API và cách triển khai có thể thay đổi trong tương lai gần.
>
> Trình phân tích hiện thực hiện rất ít kiểm tra xác thực. Để biết thêm chi tiết về định dạng tệp, hãy xem https://github.com/huggingface/huggingface.js/tree/main/packages/dduf.

### Cách viết một tệp DDUF?

Dưới đây là cách xuất một thư mục chứa các phần khác nhau của một mô hình khuếch tán bằng [export_folder_as_dduf()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.export_folder_as_dduf):

```python
# Export a folder as a DDUF file
>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")
```

Để có nhiều linh hoạt hơn, bạn có thể sử dụng [export_entries_as_dduf()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.export_entries_as_dduf) và truyền vào một danh sách các tệp cần bao gồm trong tệp DDUF cuối cùng:

```python
# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
...     dduf_path="stable-diffusion-v1-4-FP16.dduf",
...     entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
...         ("model_index.json", "path/to/model_index.json"),
...         ("vae/config.json", "path/to/vae/config.json"),
...         ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
...         ("text_encoder/config.json", "path/to/text_encoder/config.json"),
...         ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
...         # ... add more entries here
...     ]
... )
```

Tham số `entries` cũng hỗ trợ truyền vào một đối tượng lặp được chứa các đường dẫn hoặc bytes. Điều này có thể hữu ích nếu bạn đã tải một model và muốn serialize nó trực tiếp vào một tệp DDUF thay vì phải serialize từng thành phần ra đĩa trước rồi mới tạo tệp DDUF. Dưới đây là một ví dụ về cách một `StableDiffusionPipeline` có thể được serialize dưới dạng DDUF:

```python
# Export state_dicts one by one from a loaded pipeline 
>>> from diffusers import DiffusionPipeline
>>> from typing import Generator, Tuple
>>> import safetensors.torch
>>> from huggingface_hub import export_entries_as_dduf
>>> pipe = DiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")
... # ... do some work with the pipeline

>>> def as_entries(pipe: DiffusionPipeline) -> Generator[Tuple[str, bytes], None, None]:
...     # Build a generator that yields the entries to add to the DDUF file.
...     # The first element of the tuple is the filename in the DDUF archive (must use UNIX separator!). The second element is the content of the file.
...     # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
...     yield "vae/config.json", pipe.vae.to_json_string().encode()
...     yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
...     yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
...     yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
...     # ... add more entries here

>>> export_entries_as_dduf(dduf_path="stable-diffusion-v1-4.dduf", entries=as_entries(pipe))
```

**Lưu ý:** trên thực tế, `diffusers` cung cấp một phương thức để trực tiếp serialize một pipeline trong một tệp DDUF. Đoạn mã ở trên chỉ mang tính chất minh họa.

### Cách đọc tệp DDUF?

```python
>>> import json
>>> import safetensors.torch
>>> from huggingface_hub import read_dduf_file

# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")

# Returns a mapping filename <> DDUFEntry
>>> dduf_entries["model_index.json"]
DDUFEntry(filename='model_index.json', offset=66, length=587)

# Load model index as JSON
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', 'scheduler': ['diffusers', 'FlowMatchEulerDiscreteScheduler'], 'text_encoder': ['transformers', 'CLIPTextModel'], 'text_encoder_2': ['transformers', 'T5EncoderModel'], 'tokenizer': ['transformers', 'CLIPTokenizer'], 'tokenizer_2': ['transformers', 'T5TokenizerFast'], 'transformer': ['diffusers', 'FluxTransformer2DModel'], 'vae': ['diffusers', 'AutoencoderKL']}

# Load VAE weights using safetensors
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
...     state_dict = safetensors.torch.load(mm)
```

### Trợ lý[[huggingface_hub.export_entries_as_dduf]]

#### huggingface_hub.export_entries_as_dduf[[huggingface_hub.export_entries_as_dduf]]

```python
huggingface_hub.export_entries_as_dduf(dduf_path: str | os.PathLike, entries: Iterable)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L160)

**Tham số:**

dduf_path (`str` hoặc `os.PathLike`) : Đường dẫn đến tệp DDUF cần ghi.

entries (`Iterable[tuple[str, Union[str, Path, bytes]]]`) : Một iterable chứa các mục cần ghi vào tệp DDUF. Mỗi mục là một tuple gồm tên tệp và nội dung. Tên tệp phải là đường dẫn đến tệp trong kho lưu trữ DDUF. Nội dung có thể là một chuỗi hoặc một pathlib.Path đại diện cho đường dẫn đến tệp trên đĩa cục bộ, hoặc trực tiếp là nội dung dưới dạng bytes.

**Lỗi:** `-`

- - -- `DDUFExportError`: Nếu có bất kỳ sự cố nào xảy ra trong quá trình xuất (ví dụ: tên mục không hợp lệ, thiếu 'model_index.json', v.v.).

Viết một tệp DDUF từ một đối tượng lặp được các mục nhập.

Đây là một hàm trợ giúp ở cấp độ thấp hơn so với [export_folder_as_dduf()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.export_folder_as_dduf), cho phép linh hoạt hơn khi thực hiện chuỗi hóa dữ liệu. Cụ thể, bạn không cần phải lưu dữ liệu xuống đĩa trước khi xuất nó vào tệp DDUF.

Ví dụ:
```python
# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
...     dduf_path="stable-diffusion-v1-4-FP16.dduf",
...     entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
...         ("model_index.json", "path/to/model_index.json"),
...         ("vae/config.json", "path/to/vae/config.json"),
...         ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
...         ("text_encoder/config.json", "path/to/text_encoder/config.json"),
...         ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
...         # ... add more entries here
...     ]
... )
```

```python
# Export state_dicts one by one from a loaded pipeline
>>> from diffusers import DiffusionPipeline
>>> from typing import Generator, Tuple
>>> import safetensors.torch
>>> from huggingface_hub import export_entries_as_dduf
>>> pipe = DiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")
... # ... do some work with the pipeline

>>> def as_entries(pipe: DiffusionPipeline) -> Generator[tuple[str, bytes], None, None]:
...     # Build a generator that yields the entries to add to the DDUF file.
...     # The first element of the tuple is the filename in the DDUF archive (must use UNIX separator!). The second element is the content of the file.
...     # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
...     yield "vae/config.json", pipe.vae.to_json_string().encode()
...     yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
...     yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
...     yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
...     # ... add more entries here

>>> export_entries_as_dduf(dduf_path="stable-diffusion-v1-4.dduf", entries=as_entries(pipe))
```

#### huggingface_hub.export_folder_as_dduf[[huggingface_hub.export_folder_as_dduf]]

```python
huggingface_hub.export_folder_as_dduf(dduf_path: str | os.PathLike, folder_path: str | os.PathLike)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L249)

**Tham số:**

dduf_path (`str` hoặc `os.PathLike`) : Đường dẫn đến tệp DDUF cần ghi.

folder_path (`str` hoặc `os.PathLike`) : Đường dẫn đến thư mục chứa mô hình khuếch tán.

Xuất một thư mục dưới dạng tệp DDUF.

ADùng [export_entries_as_dduf()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.export_entries_as_dduf) bên trong.

Ví dụ:
```python
>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf(dduf_path="FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")
```

#### huggingface_hub.read_dduf_file[[huggingface_hub.read_dduf_file]]

```python
huggingface_hub.read_dduf_file(dduf_path: os.PathLike | str)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L91)

**Tham số:**

dduf_path (`str` hoặc `os.PathLike`) : Đường dẫn đến tệp DDUF cần đọc.

**Trả về:** `dict[str, DDUFEntry]`

Một từ điển của [DDUFEntry](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.DDUFEntry) được chỉ mục theo tên tệp.

**Lỗi:** `-`

- - -- `DDUFCorruptedFileError`: Nếu tệp DDUF bị hỏng (tức là không tuân theo định dạng DDUF).

Đọc tệp DDUF và trả về một từ điển các mục nhập.

Chỉ metadata được đọc, dữ liệu không được nạp vào bộ nhớ.

Ví dụ:
```python
>>> import json
>>> import safetensors.torch
>>> from huggingface_hub import read_dduf_file

# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")

# Returns a mapping filename <> DDUFEntry
>>> dduf_entries["model_index.json"]
DDUFEntry(filename='model_index.json', offset=66, length=587)

# Load model index as JSON
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', ...

# Load VAE weights using safetensors
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
...     state_dict = safetensors.torch.load(mm)
```

#### huggingface_hub.DDUFEntry[[huggingface_hub.DDUFEntry]]

```python
huggingface_hub.DDUFEntry(filename: str, length: int, offset: int, dduf_path: Path)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L36)

**Tham số:**

filename (str) : Tên của tệp trong kho lưu trữ DDUF.

offset (int) : Độ lệch của tệp trong kho lưu trữ DDUF.

length (int) : Độ dài của tệp trong kho lưu trữ DDUF.

dduf_path (str) : Đường dẫn đến tệp lưu trữ DDUF (dùng nội bộ).

Đối tượng đại diện cho một mục tệp trong tệp DDUF.

Xem [read_dduf_file()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.read_dduf_file) để biết cách đọc tệp DDUF.

#### as_mmap[[huggingface_hub.DDUFEntry.as_mmap]]

```python
as_mmap()
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L58)

Mở tệp dưới dạng tệp ánh xạ bộ nhớ.

Có ích để nạp trực tiếp safetensors từ tệp.

Ví dụ:
```py
>>> import safetensors.torch
>>> with entry.as_mmap() as mm:
...     tensors = safetensors.torch.load(mm)
```

#### read_text[[huggingface_hub.DDUFEntry.read_text]]

```python
read_text(encoding: str = 'utf-8')
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_dduf.py#L75)

Đọc tệp dưới dạng văn bản.

Có ích cho các mục '.txt' và '.json'.

Ví dụ:
```py
>>> import json
>>> index = json.loads(entry.read_text())
```

### Lỗi[[huggingface_hub.errors.DDUFError]]

#### huggingface_hub.errors.DDUFError[[huggingface_hub.errors.DDUFError]]

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L521)

Ngoại lệ cơ bản cho các lỗi liên quan đến định dạng DDUF.

#### huggingface_hub.errors.DDUFCorruptedFileError[[huggingface_hub.errors.DDUFCorruptedFileError]]

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L525)

Lỗi ngoại lệ được ném ra khi tệp DDUF bị hỏng.

#### huggingface_hub.errors.DDUFExportError[[huggingface_hub.errors.DDUFExportError]]

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L529)

Ngoại lệ cơ bản cho các lỗi trong quá trình xuất DDUF.

#### huggingface_hub.errors.DDUFInvalidEntryNameError[[huggingface_hub.errors.DDUFInvalidEntryNameError]]

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L533)

Ngoại lệ được ném ra khi tên mục không hợp lệ.

## Lưu tensor

Hàm trợ giúp chính của module `serialization` nhận một `nn.Module` của torch làm đầu vào và lưu nó xuống đĩa. Hàm này xử lý logic để lưu các tensor dùng chung (xem [giải thích về safetensors](https://huggingface.co/docs/safetensors/torch_shared_tensors)) cũng như logic để chia state dictionary thành các shard, sử dụng [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) bên trong. Hiện tại, chỉ hỗ trợ framework `torch`.

Nếu bạn muốn lưu một state dictionary (ví dụ: ánh xạ giữa tên các layer và các tensor liên quan) thay vì một `nn.Module`, bạn có thể sử dụng [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.save_torch_state_dict) cung cấp các tính năng tương tự. Điều này hữu ích, chẳng hạn, nếu bạn muốn áp dụng logic tùy chỉnh cho state dict trước khi lưu nó.

### save_torch_model[[huggingface_hub.save_torch_model]]

#### huggingface_hub.save_torch_model[[huggingface_hub.save_torch_model]]

```python
huggingface_hub.save_torch_model(model: torch.nn.Module, save_directory: str | pathlib.Path, filename_pattern: str | None = None, force_contiguous: bool = True, max_shard_size: int | str = '5GB', metadata: dict[str, str] | None = None, safe_serialization: bool = True, is_main_process: bool = True, shared_tensors_to_discard: list[str] | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L47)

**Tham số:**

model (`torch.nn.Module`) : Mô hình cần lưu trên đĩa.

save_directory (`str` hoặc `Path`) : Thư mục mà mô hình sẽ được lưu vào.

filename_pattern (`str`, *tùy chọn*) : Mẫu để tạo tên tệp mà mô hình sẽ được lưu vào. Mẫu phải là một chuỗi có thể được định dạng bằng `filename_pattern.format(suffix=...)` và phải chứa từ khóa `suffix`. Mặc định là `"model{suffix}.safetensors"` hoặc `pytorch_model{suffix}.bin` tùy thuộc vào tham số `safe_serialization`.

force_contiguous (`boolean`, *tùy chọn*) : Buộc state_dict được lưu dưới dạng các tensor liên tục. Điều này không ảnh hưởng đến tính chính xác của mô hình, nhưng có thể thay đổi hiệu năng nếu bố cục của tensor được chọn đặc biệt vì lý do đó. Mặc định là `True`.

max_shard_size (`int` hoặc `str`, *tùy chọn*) : Kích thước tối đa của mỗi shard, tính bằng byte. Mặc định là 5GB.

metadata (`dict[str, str]`, *tùy chọn*) : Thông tin bổ sung để lưu cùng với mô hình. Một số metadata sẽ được thêm cho mỗi tensor bị loại bỏ. Thông tin này sẽ không đủ để khôi phục toàn bộ cấu trúc được chia sẻ nhưng có thể giúp hiểu rõ hơn.

safe_serialization (`bool`, *optional*) : Xác định có lưu dưới dạng safetensors hay không, đây là hành vi mặc định. Nếu `False`, các shard sẽ được lưu dưới dạng pickle. Việc serialize an toàn được khuyến nghị vì lý do bảo mật. Việc lưu dưới dạng pickle đã bị ngừng hỗ trợ và sẽ bị loại bỏ trong một phiên bản tương lai.

is_main_process (`bool`, *tuỳ chọn*) : Xác định xem tiến trình gọi hàm này có phải là tiến trình chính hay không. Hữu ích khi huấn luyện phân tán như trên TPU và cần gọi hàm này từ tất cả các tiến trình. Trong trường hợp này, chỉ đặt `is_main_process=True` trên tiến trình chính để tránh điều kiện đua. Mặc định là True.

shared_tensors_to_discard (`list[str]`, *tùy chọn*) : Danh sách tên tensor cần loại bỏ khi lưu các tensor dùng chung. Nếu không được cung cấp và phát hiện có tensor dùng chung, tên đầu tiên theo thứ tự bảng chữ cái sẽ bị loại bỏ.

Lưu một mô hình torch đã cho xuống đĩa, xử lý các vấn đề về phân mảnh và tensor dùng chung.

Xem thêm [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.save_torch_state_dict) để lưu state dict với nhiều sự linh hoạt hơn.

Để biết thêm thông tin về việc chia sẻ tensor, hãy xem [hướng dẫn này](https://huggingface.co/docs/safetensors/torch_shared_tensors).

Từ điển trạng thái mô hình được chia thành các phần (shards) sao cho mỗi phần nhỏ hơn một kích thước cho trước. Các phần này được lưu trong `save_directory` với `filename_pattern` đã chỉ định. Nếu mô hình quá lớn để chứa trong một phần duy nhất, một tệp chỉ mục sẽ được lưu trong `save_directory` để chỉ ra vị trí lưu trữ của từng tensor. Tiện ích này sử dụng [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) bên trong. Nếu `safe_serialization` là `True`, các phần sẽ được lưu dưới dạng safetensors (mặc định). Ngược lại, các phần sẽ được lưu dưới dạng pickle.

Trước khi lưu mô hình, `save_directory` sẽ được dọn sạch khỏi các tệp shard trước đó.

> [!WARNING]
> Nếu một trong các tensor của model có kích thước lớn hơn `max_shard_size`, tensor đó sẽ nằm trong một shard riêng có kích thước lớn hơn `max_shard_size`.

> [!WARNING]
> Nếu model của bạn là `transformers.PreTrainedModel`, bạn nên truyền `model._tied_weights_keys` vào `shared_tensors_to_discard` để xử lý việc lưu các tensor dùng chung một cách chính xác. Điều này đảm bảo các tensor trùng lặp đúng sẽ bị loại bỏ trong quá trình lưu.

Ví dụ:

```py
>>> from huggingface_hub import save_torch_model
>>> model = ... # A PyTorch model

# Save state dict to "path/to/folder". The model will be split into shards of 5GB each and saved as safetensors.
>>> save_torch_model(model, "path/to/folder")

# Load model back
>>> from huggingface_hub import load_torch_model  # TODO
>>> load_torch_model(model, "path/to/folder")
>>>
```

### save_torch_state_dict[[huggingface_hub.save_torch_state_dict]]

#### huggingface_hub.save_torch_state_dict[[huggingface_hub.save_torch_state_dict]]

```python
huggingface_hub.save_torch_state_dict(state_dict: dict, save_directory: str | pathlib.Path, filename_pattern: str | None = None, force_contiguous: bool = True, max_shard_size: int | str = '5GB', metadata: dict[str, str] | None = None, safe_serialization: bool = True, is_main_process: bool = True, shared_tensors_to_discard: list[str] | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L141)

**Tham số:**

state_dict (`dict[str, torch.Tensor]`) : Từ điển trạng thái cần lưu.

save_directory (`str` hoặc `Path`) : Thư mục mà mô hình sẽ được lưu vào.

filename_pattern (`str`, *tùy chọn*) : Mẫu để tạo tên tệp mà mô hình sẽ được lưu vào. Mẫu phải là một chuỗi có thể được định dạng bằng `filename_pattern.format(suffix=...)` và phải chứa từ khóa `suffix`. Mặc định là `"model{suffix}.safetensors"` hoặc `pytorch_model{suffix}.bin` tùy thuộc vào tham số `safe_serialization`.

force_contiguous (`boolean`, *tùy chọn*) : Buộc state_dict được lưu dưới dạng các tensor liên tục. Điều này không ảnh hưởng đến tính chính xác của mô hình, nhưng có thể thay đổi hiệu năng nếu bố cục của tensor được chọn đặc biệt vì lý do đó. Mặc định là `True`.

max_shard_size (`int` hoặc `str`, *tùy chọn*) : Kích thước tối đa của mỗi shard, tính bằng byte. Mặc định là 5GB.

metadata (`dict[str, str]`, *tùy chọn*) : Thông tin bổ sung để lưu cùng với mô hình. Một số metadata sẽ được thêm cho mỗi tensor bị loại bỏ. Thông tin này sẽ không đủ để khôi phục toàn bộ cấu trúc được chia sẻ nhưng có thể giúp hiểu rõ hơn.

safe_serialization (`bool`, *optional*) : Xác định có lưu dưới dạng safetensors hay không, đây là hành vi mặc định. Nếu `False`, các shard sẽ được lưu dưới dạng pickle. Việc serialize an toàn được khuyến nghị vì lý do bảo mật. Việc lưu dưới dạng pickle đã bị ngừng hỗ trợ và sẽ bị loại bỏ trong một phiên bản tương lai.

is_main_process (`bool`, *tuỳ chọn*) : Xác định xem tiến trình gọi hàm này có phải là tiến trình chính hay không. Hữu ích khi huấn luyện phân tán như trên TPU và cần gọi hàm này từ tất cả các tiến trình. Trong trường hợp này, chỉ đặt `is_main_process=True` trên tiến trình chính để tránh điều kiện đua. Mặc định là True.

shared_tensors_to_discard (`list[str]`, *tùy chọn*) : Danh sách tên tensor cần loại bỏ khi lưu các tensor dùng chung. Nếu không được cung cấp và phát hiện có tensor dùng chung, tên đầu tiên theo thứ tự bảng chữ cái sẽ bị loại bỏ.

Lưu từ điển trạng thái mô hình xuống đĩa, xử lý các vấn đề về phân mảnh và tensor dùng chung.

Xem thêm [save_torch_model()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.save_torch_model) để lưu trực tiếp một mô hình PyTorch.

Để biết thêm thông tin về việc chia sẻ tensor, hãy xem [hướng dẫn này](https://huggingface.co/docs/safetensors/torch_shared_tensors).

Từ điển trạng thái mô hình được chia thành các phần (shards) sao cho mỗi phần nhỏ hơn một kích thước cho trước. Các phần này được lưu trong `save_directory` với `filename_pattern` đã chỉ định. Nếu mô hình quá lớn để chứa trong một phần duy nhất, một tệp chỉ mục sẽ được lưu trong `save_directory` để chỉ ra vị trí lưu trữ của từng tensor. Tiện ích này sử dụng [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) bên trong. Nếu `safe_serialization` là `True`, các phần sẽ được lưu dưới dạng safetensors (mặc định). Ngược lại, các phần sẽ được lưu dưới dạng pickle.

Trước khi lưu mô hình, `save_directory` sẽ được dọn sạch khỏi các tệp shard trước đó.

> [!WARNING]
> Nếu một trong các tensor của model có kích thước lớn hơn `max_shard_size`, tensor đó sẽ nằm trong một shard riêng có kích thước lớn hơn `max_shard_size`.

> [!WARNING]
> Nếu model của bạn là `transformers.PreTrainedModel`, bạn nên truyền `model._tied_weights_keys` vào `shared_tensors_to_discard` để xử lý việc lưu các tensor dùng chung một cách chính xác. Điều này đảm bảo các tensor trùng lặp đúng sẽ bị loại bỏ trong quá trình lưu.

Ví dụ:

```py
>>> from huggingface_hub import save_torch_state_dict
>>> model = ... # A PyTorch model

# Save state dict to "path/to/folder". The model will be split into shards of 5GB each and saved as safetensors.
>>> state_dict = model_to_save.state_dict()
>>> save_torch_state_dict(state_dict, "path/to/folder")
```

Module `serialization` cũng chứa các hàm trợ giúp cấp thấp để chia một state dictionary thành nhiều shard, đồng thời tạo một index phù hợp trong quá trình đó. Các hàm trợ giúp này có sẵn cho tensor `torch` và được thiết kế để dễ dàng mở rộng sang bất kỳ framework ML nào khác.

### split_torch_state_dict_into_shards[[huggingface_hub.split_torch_state_dict_into_shards]]

#### huggingface_hub.split_torch_state_dict_into_shards[[huggingface_hub.split_torch_state_dict_into_shards]]

```python
huggingface_hub.split_torch_state_dict_into_shards(state_dict: dict, filename_pattern: str = 'model{suffix}.safetensors', max_shard_size: int | str = '5GB')
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L302)

**Tham số:**

state_dict (`dict[str, torch.Tensor]`) : Từ điển trạng thái cần lưu.

filename_pattern (`str`, *tùy chọn*) : Mẫu để tạo tên tệp mà mô hình sẽ được lưu vào. Mẫu phải là một chuỗi có thể được định dạng bằng `filename_pattern.format(suffix=...)` và phải chứa từ khóa `suffix`. Mặc định là `"model{suffix}.safetensors"`.

max_shard_size (`int` hoặc `str`, *tùy chọn*) : Kích thước tối đa của mỗi shard, tính bằng byte. Mặc định là 5GB.

**Trả về:** `StateDictSplit`

Một đối tượng `StateDictSplit` chứa các shard và chỉ mục để truy xuất chúng.

Tách từ điển trạng thái của mô hình thành các phần sao cho mỗi phần nhỏ hơn một kích thước cho trước.

Các shard được xác định bằng cách lặp qua `state_dict` theo thứ tự các key của nó. Không có tối ưu hóa nào được thực hiện để đảm bảo mỗi shard gần nhất có thể với kích thước tối đa được truyền vào. Ví dụ, nếu giới hạn là 10GB và chúng ta có các tensor với kích thước [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], chúng sẽ được chia shard thành [6GB], [6+2GB], [6+2+2GB] chứ không phải [6+2+2GB], [6+2GB], [6GB].

> [!TIP]
> Để lưu state dictionary của mô hình xuống đĩa, hãy xem [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.save_torch_state_dict). Hàm trợ giúp này sử dụng `split_torch_state_dict_into_shards` bên trong.

> [!WARNING]
> Nếu một trong các tensor của model có kích thước lớn hơn `max_shard_size`, tensor đó sẽ nằm trong một shard riêng có kích thước lớn hơn `max_shard_size`.

Ví dụ:
```py
>>> import json
>>> import os
>>> from safetensors.torch import save_file as safe_save_file
>>> from huggingface_hub import split_torch_state_dict_into_shards

>>> def save_state_dict(state_dict: dict[str, torch.Tensor], save_directory: str):
...     state_dict_split = split_torch_state_dict_into_shards(state_dict)
...     for filename, tensors in state_dict_split.filename_to_tensors.items():
...         shard = {tensor: state_dict[tensor] for tensor in tensors}
...         safe_save_file(
...             shard,
...             os.path.join(save_directory, filename),
...             metadata={"format": "pt"},
...         )
...     if state_dict_split.is_sharded:
...         index = {
...             "metadata": state_dict_split.metadata,
...             "weight_map": state_dict_split.tensor_to_filename,
...         }
...         with open(os.path.join(save_directory, "model.safetensors.index.json"), "w") as f:
...             f.write(json.dumps(index, indent=2))
```

### split_state_dict_into_shards_factory[[huggingface_hub.split_state_dict_into_shards_factory]]

Đây là nhà máy cơ bản mà từ đó mỗi trình trợ giúp cụ thể cho từng framework được dẫn xuất. Trên thực tế, bạn không được kỳ vọng sử dụng trực tiếp nhà máy này, trừ khi bạn cần điều chỉnh nó cho một framework chưa được hỗ trợ. Nếu trường hợp đó xảy ra, vui lòng cho chúng tôi biết bằng cách [mở một issue mới](https://github.com/huggingface/huggingface_hub/issues/new) trên repo `huggingface_hub`.

#### huggingface_hub.split_state_dict_into_shards_factory[[huggingface_hub.split_state_dict_into_shards_factory]]

```python
huggingface_hub.split_state_dict_into_shards_factory(state_dict: dict, get_storage_size: Callable, filename_pattern: str, get_storage_id: Callable = <function <lambda> at 0x7f9673968670>, max_shard_size: int | str = '5GB')
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_base.py#L50)

**Tham số:**

state_dict (`dict[str, Tensor]`) : Từ điển trạng thái cần lưu.

get_storage_size (`Callable[[Tensor], int]`) : Một hàm trả về kích thước của một tensor khi được lưu trên đĩa, tính bằng byte.

get_storage_id (`Callable[[Tensor], Optional[Any]]`, *tuỳ chọn*) : Một hàm trả về định danh duy nhất cho bộ nhớ lưu trữ của tensor. Nhiều tensor khác nhau có thể chia sẻ cùng một bộ nhớ lưu trữ cơ bản. Định danh này được đảm bảo là duy nhất và không đổi cho bộ nhớ lưu trữ của tensor này trong suốt vòng đời của nó. Hai bộ nhớ lưu trữ tensor có vòng đời không chồng lấn có thể có cùng id.

filename_pattern (`str`, *tùy chọn*) : Mẫu để tạo tên tệp mà mô hình sẽ được lưu vào. Mẫu phải là một chuỗi có thể được định dạng bằng `filename_pattern.format(suffix=...)` và phải chứa từ khóa `suffix`

max_shard_size (`int` hoặc `str`, *tùy chọn*) : Kích thước tối đa của mỗi shard, tính bằng byte. Mặc định là 5GB.

**Trả về:** `StateDictSplit`

Một đối tượng `StateDictSplit` chứa các shard và chỉ mục để truy xuất chúng.

Tách từ điển trạng thái của mô hình thành các phần sao cho mỗi phần nhỏ hơn một kích thước cho trước.

Các shard được xác định bằng cách lặp qua `state_dict` theo thứ tự các key của nó. Không có tối ưu hóa nào được thực hiện để đảm bảo mỗi shard gần nhất có thể với kích thước tối đa được truyền vào. Ví dụ, nếu giới hạn là 10GB và chúng ta có các tensor với kích thước [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], chúng sẽ được chia shard thành [6GB], [6+2GB], [6+2+2GB] chứ không phải [6+2+2GB], [6+2GB], [6GB].

> [!WARNING]
> Nếu một trong các tensor của model có kích thước lớn hơn `max_shard_size`, tensor đó sẽ nằm trong một shard riêng có kích thước lớn hơn `max_shard_size`.

## Tải tensor

Các hàm hỗ trợ tải hỗ trợ cả checkpoint dạng tệp đơn và dạng phân mảnh ở định dạng safetensors hoặc pickle. [load_torch_model()](/docs/huggingface_hub/v2.4.0/vi/package_reference/serialization#huggingface_hub.load_torch_model) nhận một `nn.Module` và đường dẫn checkpoint (một tệp đơn hoặc một thư mục) làm đầu vào và tải trọng số vào mô hình.

> [!WARNING]
> Cả hai hàm trợ giúp đều mặc định là `safe=True`, có nghĩa là checkpoint luôn được giải chuỗi hóa bằng trình nạp safetensors — bất kể tên tệp là gì. Việc nạp checkpoint pickle yêu cầu phải chọn bật tính năng này một cách rõ ràng, vì quá trình unpickle sẽ thực thi mã tùy ý tại thời điểm nạp:
> ```py
> >>> from huggingface_hub import load_state_dict_from_file, load_torch_model
>
> # Raises: the file is not safetensors
> >>> load_state_dict_from_file("path/to/pytorch_model.bin")
> >>> load_torch_model(model, "path/to/pytorch_model.bin")
>
> # Explicit opt-in
> >>> load_state_dict_from_file("path/to/pytorch_model.bin", safe=False)
> >>> load_torch_model(model, "path/to/pytorch_model.bin", safe=False)
> ```
> Đường dẫn pickle mặc định thêm `weights_only=True`, tức là bộ unpickler bị hạn chế của torch. Một checkpoint chứa các đối tượng không phải tensor (trạng thái optimizer, toàn bộ model, ...) cần `weights_only=False` bên cạnh `safe=False`.

### load_torch_model[[huggingface_hub.load_torch_model]]

#### huggingface_hub.load_torch_model[[huggingface_hub.load_torch_model]]

```python
huggingface_hub.load_torch_model(model: torch.nn.Module, checkpoint_path: str | os.PathLike, strict: bool = False, safe: bool = True, weights_only: bool = True, map_location: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, mmap: bool = False, filename_pattern: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L375)

**Tham số:**

model (`torch.nn.Module`) : Mô hình để nạp checkpoint.

checkpoint_path (`str` hoặc `os.PathLike`) : Đường dẫn đến tệp checkpoint hoặc thư mục chứa các checkpoint.

strict (`bool`, *tùy chọn*, mặc định là `False`) : Có nên thực thi nghiêm ngặt việc các khóa trong model state dict phải khớp với các khóa trong checkpoint hay không. Tương tự như `torch.nn.Module.load_state_dict`, việc kiểm tra được thực hiện sau khi checkpoint đã được tải, do đó model có thể đã được cập nhật một phần khi lỗi được ném ra.

safe (`bool`, *tùy chọn*, mặc định là `True`) : Nếu `safe` là True, các tệp safetensors sẽ được tải. Nếu `safe` là False, hàm sẽ trước tiên cố gắng tải các tệp safetensors nếu chúng có sẵn, nếu không sẽ chuyển sang tải các tệp pickle. Một `filename_pattern` không mô tả các tệp safetensors sẽ bị từ chối khi `safe=True`.

weights_only (`bool`, *tuỳ chọn*, mặc định là `True`) : Nếu là True, chỉ tải trọng số của mô hình mà không tải trạng thái optimizer và các metadata khác, sử dụng unpickler bị hạn chế của torch. Đặt thành False để cho phép các đối tượng Python tùy ý trong checkpoint pickle (điều này sẽ thực thi mã tùy ý khi tải). Không có tác dụng với PyTorch < 1.13, vốn không có unpickler bị hạn chế và luôn unpickle mà không có hạn chế.

map_location (`str` hoặc `torch.device`, *tuỳ chọn*) : Một đối tượng `torch.device`, chuỗi hoặc dict chỉ định cách ánh xạ lại các vị trí lưu trữ. Nó cho biết vị trí mà tất cả các tensor nên được nạp vào.

mmap (`bool`, *tùy chọn*, mặc định là `False`) : Có sử dụng chế độ nạp tệp ánh xạ bộ nhớ (memory-mapped file loading) hay không. Ánh xạ bộ nhớ có thể cải thiện hiệu suất nạp cho các mô hình lớn trong PyTorch >= 2.1.0 với các checkpoint dựa trên zipfile.

filename_pattern (`str`, *tùy chọn*) : Mẫu để tìm tệp chỉ mục. Mẫu phải là chuỗi có thể được định dạng bằng `filename_pattern.format(suffix=...)` và phải chứa từ khóa `suffix`. Mặc định là `"model{suffix}.safetensors"`.

**Trả về:** `NamedTuple`

Một named tuple có các trường `missing_keys` và `unexpected_keys`.
- `missing_keys` là một danh sách str chứa các khóa bị thiếu, tức là các khóa có trong model nhưng không có trong checkpoint.
- `unexpected_keys` là một danh sách str chứa các khóa không mong đợi, tức là các khóa có trong checkpoint nhưng không có trong model.

**Lỗi:** ``FileNotFoundError`` hoặc ``ImportError`` hoặc ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Nếu tệp hoặc thư mục checkpoint không tồn tại.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Nếu safetensors hoặc torch chưa được cài đặt khi cố gắng tải một tệp .safetensors hoặc một checkpoint PyTorch tương ứng.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Nếu không thể xác định được định dạng checkpoint.

Tải checkpoint vào mô hình, xử lý cả checkpoint dạng phân mảnh và không phân mảnh.

Ví dụ:
```python
>>> from huggingface_hub import load_torch_model
>>> model = ... # A PyTorch model
>>> load_torch_model(model, "path/to/checkpoint")
```

### load_state_dict_from_file[[huggingface_hub.load_state_dict_from_file]]

#### huggingface_hub.load_state_dict_from_file[[huggingface_hub.load_state_dict_from_file]]

```python
huggingface_hub.load_state_dict_from_file(checkpoint_file: str | os.PathLike, map_location: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, weights_only: bool = True, mmap: bool = False, safe: bool = True)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L633)

**Tham số:**

checkpoint_file (`str` hoặc `os.PathLike`) : Đường dẫn đến tệp checkpoint cần tải. Có thể là checkpoint dạng safetensors hoặc pickle (`.bin`).

map_location (`str` hoặc `torch.device`, *tuỳ chọn*) : Một đối tượng `torch.device`, chuỗi hoặc dict chỉ định cách ánh xạ lại các vị trí lưu trữ. Nó cho biết vị trí mà tất cả các tensor nên được nạp vào.

weights_only (`bool`, *tuỳ chọn*, mặc định là `True`) : Nếu là True, chỉ tải trọng số của mô hình mà không tải trạng thái optimizer và các metadata khác, sử dụng restricted unpickler của torch. Đặt thành False để cho phép các đối tượng Python tùy ý trong checkpoint pickle (điều này sẽ thực thi mã tùy ý khi tải). Không có hiệu ứng khi tải các tệp safetensors, cũng như trên PyTorch < 1.13 vốn không có restricted unpickler — các phiên bản đó luôn unpickle không có ràng buộc và một cảnh báo sẽ được ghi log.

mmap (`bool`, *tùy chọn*, mặc định là `False`) : Có sử dụng nạp tệp theo bản đồ bộ nhớ (memory-mapped file loading) hay không. Bản đồ bộ nhớ có thể cải thiện hiệu suất nạp cho các mô hình lớn trong PyTorch >= 2.1.0 với các checkpoint dựa trên zipfile. Không có tác dụng khi nạp các tệp safetensors, vì thư viện `safetensors` sử dụng bản đồ bộ nhớ theo mặc định.

safe (`bool`, *optional*, mặc định là `True`) : Nếu là True, checkpoint luôn được nạp dưới dạng safetensors, bất kể tên của nó là gì. Mọi định dạng khác (ví dụ: tệp pickle `.bin`) sẽ gây ra `ValueError` thay vì được khử chuỗi hóa: các checkpoint pickle có thể thực thi mã tùy ý khi nạp. Nếu là False, tệp sẽ được nạp dưới dạng safetensors nếu tên của nó cho thấy điều đó, và bằng `torch.load` trong các trường hợp còn lại.

**Trả về:** `Union[dict[str, "torch.Tensor"], Any]`

Checkpoint đã được tải.
- Đối với các tệp safetensors: luôn trả về một từ điển ánh xạ tên tham số tới các tensor.
- Đối với tệp pickle: trả về bất kỳ đối tượng Python nào đã được pickle (thường là state dict, nhưng cũng có thể là toàn bộ model, trạng thái optimizer, hoặc bất kỳ đối tượng Python nào khác).

**Gây ra:** ``FileNotFoundError`` hoặc ``ImportError`` hoặc ``OSError`` hoặc ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Nếu tệp checkpoint không tồn tại.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Nếu safetensors hoặc torch chưa được cài đặt khi cố gắng tải một tệp .safetensors hoặc một checkpoint PyTorch tương ứng.
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- Nếu định dạng tệp checkpoint không hợp lệ hoặc các tệp git-lfs không được tải xuống đúng cách.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Nếu đường dẫn tệp checkpoint trống hoặc không hợp lệ, hoặc nếu tệp không thể được khử chuỗi hóa dưới dạng safetensors khi `safe=True` (truyền `safe=False` để cho phép các checkpoint pickle).

Tải tệp checkpoint, xử lý cả định dạng checkpoint safetensors và pickle.

Ví dụ:
```python
>>> from huggingface_hub import load_state_dict_from_file

# Load a safetensors checkpoint (safe by default)
>>> state_dict = load_state_dict_from_file("path/to/model.safetensors", safe=True)
>>> model.load_state_dict(state_dict)

# Load a pickle checkpoint. `safe=False` is required: pickle files can execute arbitrary code.
>>> state_dict = load_state_dict_from_file("path/to/model.bin", safe=False, map_location="cpu")
>>> model.load_state_dict(state_dict)
```

## Trợ lý Tensors

### get_torch_storage_id[[huggingface_hub.get_torch_storage_id]]

#### huggingface_hub.get_torch_storage_id[[huggingface_hub.get_torch_storage_id]]

```python
huggingface_hub.get_torch_storage_id(tensor: torch.Tensor)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L878)

Trả về định danh duy nhất cho bộ nhớ tensor.

Nhiều tensor khác nhau có thể chia sẻ cùng một bộ nhớ lưu trữ (storage) cơ bản. Định danh này được đảm bảo là duy nhất và không đổi đối với storage của tensor này trong suốt vòng đời của nó. Hai storage của tensor có vòng đời không chồng lấn có thể có cùng id. Trong trường hợp của meta tensors, chúng tôi trả về None vì không thể xác định xem chúng có chia sẻ cùng một storage hay không.

Trích từ https://github.com/huggingface/transformers/blob/1ecf5f7c982d761b4daaa96719d162c324187c64/src/transformers/pytorch_utils.py#L278.

### get_torch_storage_size[[huggingface_hub.get_torch_storage_size]]

#### huggingface_hub.get_torch_storage_size[[huggingface_hub.get_torch_storage_size]]

```python
huggingface_hub.get_torch_storage_size(tensor: torch.Tensor)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/serialization/_torch.py#L895)

Trích từ https://github.com/huggingface/safetensors/blob/08db34094e9e59e2f9218f2df133b7b4aaff5a99/bindings/python/py_src/safetensors/torch.py#L31C1-L41C59

