# Serialisasi

`huggingface_hub` menyediakan helper untuk menyimpan dan memuat bobot model ML dengan cara yang terstandarisasi. Bagian pustaka ini masih dalam pengembangan dan akan ditingkatkan pada rilis mendatang. Tujuannya adalah untuk menyelaraskan cara bobot disimpan dan dimuat di seluruh Hub, baik untuk menghilangkan duplikasi kode antar pustaka maupun untuk menetapkan konvensi yang konsisten.

## Format file DDUF

DDUF adalah format file yang dirancang untuk model difusi. Format ini memungkinkan penyimpanan semua informasi yang diperlukan untuk menjalankan model dalam satu file. Pekerjaan ini terinspirasi oleh format [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md). `huggingface_hub` menyediakan helper untuk menyimpan dan memuat file DDUF, memastikan format file dipatuhi.

> [!WARNING]
> Ini adalah versi parser yang sangat awal. API dan implementasinya dapat berkembang dalam waktu dekat.
>
> Parser saat ini melakukan validasi yang sangat sedikit. Untuk detail lebih lanjut tentang format file, lihat https://github.com/huggingface/huggingface.js/tree/main/packages/dduf.

### Bagaimana cara menulis file DDUF?

Berikut cara mengekspor folder yang berisi berbagai bagian dari model difusi menggunakan [export_folder_as_dduf()](/docs/huggingface_hub/main/id/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")
```

Untuk fleksibilitas yang lebih besar, Anda dapat menggunakan [export_entries_as_dduf()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.export_entries_as_dduf) dan meneruskan daftar file yang akan disertakan dalam file DDUF akhir:

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

Parameter `entries` juga mendukung pengiriman iterable dari path atau bytes. Hal ini dapat berguna jika Anda memiliki model yang sudah dimuat dan ingin langsung mengserialisasikannya ke dalam file DDUF, alih-alih harus mengserialisasikan setiap komponen ke disk terlebih dahulu dan kemudian sebagai file DDUF. Berikut adalah contoh bagaimana `StableDiffusionPipeline` dapat diserialisasikan sebagai 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))
```

**Catatan:** dalam praktiknya, `diffusers` menyediakan metode untuk langsung melakukan serialisasi pipeline ke dalam file DDUF. Snippet di atas hanya dimaksudkan sebagai contoh.

### Bagaimana cara membaca file 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)
```

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L160)

**Parameter:**

dduf_path (`str` atau `os.PathLike`) : Path ke file DDUF yang akan ditulis.

entries (`Iterable[tuple[str, Union[str, Path, bytes]]]`) : Sebuah iterable berisi entri untuk ditulis ke dalam file DDUF. Setiap entri adalah tuple yang berisi nama file dan isinya. Nama file harus berupa path ke file dalam arsip DDUF. Isinya dapat berupa string atau pathlib.Path yang merepresentasikan path ke file di disk lokal, atau langsung berupa konten sebagai bytes.

**Mengangkat:** `-`

- - -- `DDUFExportError`: Jika terjadi kesalahan selama proses ekspor (misalnya nama entri tidak valid, 'model_index.json' tidak ditemukan, dll.).

Tulis file DDUF dari iterable entri.

Ini adalah helper tingkat yang lebih rendah daripada [export_folder_as_dduf()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.export_folder_as_dduf) yang memberikan fleksibilitas lebih besar saat melakukan serialisasi data. Secara khusus, Anda tidak perlu menyimpan data ke disk terlebih dahulu sebelum mengekspornya ke file DDUF.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L249)

**Parameter:**

dduf_path (`str` atau `os.PathLike`) : Path ke file DDUF yang akan ditulis.

folder_path (`str` atau `os.PathLike`) : Path ke folder yang berisi model difusi.

Ekspor folder sebagai file DDUF.

AMenggunakan [export_entries_as_dduf()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.export_entries_as_dduf) di balik layar.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L91)

**Parameter:**

dduf_path (`str` atau `os.PathLike`) : Path ke file DDUF yang akan dibaca.

**Mengembalikan:** `dict[str, DDUFEntry]`

Kamus [DDUFEntry](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.DDUFEntry) yang diindeks berdasarkan nama file.

**Mengangkat:** `-`

- - -- `DDUFCorruptedFileError`: Jika file DDUF rusak (yaitu tidak mengikuti format DDUF).

Baca file DDUF dan kembalikan kamus entri.

Hanya metadata yang dibaca, datanya tidak dimuat ke dalam memori.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L36)

**Parameter:**

filename (str) : Nama file dalam arsip DDUF.

offset (int) : Offset file dalam arsip DDUF.

length (int) : Panjang file dalam arsip DDUF.

dduf_path (str) : Jalur ke arsip DDUF (untuk penggunaan internal).

Objek yang merepresentasikan entri file dalam file DDUF.

Lihat [read_dduf_file()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.read_dduf_file) untuk cara membaca file DDUF.

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

```python
as_mmap()
```

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L58)

Buka file sebagai file yang dipetakan ke memori.

Berguna untuk memuat safetensors langsung dari file.

Contoh:
```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')
```

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_dduf.py#L75)

Baca file sebagai teks.

Berguna untuk entri '.txt' dan '.json'.

Contoh:
```py
>>> import json
>>> index = json.loads(entry.read_text())
```

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

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L521)

Pengecualian dasar untuk kesalahan yang terkait dengan format DDUF.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L525)

Pengecualian dilempar ketika file DDUF rusak.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L529)

Pengecualian dasar untuk kesalahan selama ekspor DDUF.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L533)

Exception dilempar ketika nama entri tidak valid.

## Menyimpan tensor

Helper utama dari modul `serialization` menerima torch `nn.Module` sebagai input dan menyimpannya ke disk. Helper ini menangani logika untuk menyimpan tensor bersama (lihat [penjelasan safetensors](https://huggingface.co/docs/safetensors/torch_shared_tensors)) serta logika untuk memecah state dictionary menjadi shard, menggunakan [split_torch_state_dict_into_shards()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) di baliknya. Saat ini, hanya framework `torch` yang didukung.

Jika Anda ingin menyimpan state dictionary (misalnya pemetaan antara nama layer dan tensor terkait) alih-alih `nn.Module`, Anda dapat menggunakan [save_torch_state_dict()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.save_torch_state_dict) yang menyediakan fitur yang sama. Ini berguna, misalnya, jika Anda ingin menerapkan logika kustom pada state dict sebelum menyimpannya.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L47)

**Parameter:**

model (`torch.nn.Module`) : Model yang akan disimpan ke disk.

save_directory (`str` atau `Path`) : Direktori tempat model akan disimpan.

filename_pattern (`str`, *opsional*) : Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat dengan `filename_pattern.format(suffix=...)` dan harus mengandung kata kunci `suffix`. Secara default menggunakan `"model{suffix}.safetensors"` atau `pytorch_model{suffix}.bin` tergantung pada parameter `safe_serialization`.

force_contiguous (`boolean`, *opsional*) : Memaksa state_dict disimpan sebagai tensor yang contiguous. Hal ini tidak memengaruhi kebenaran model, tetapi berpotensi mengubah kinerja jika tata letak tensor dipilih secara khusus untuk alasan tersebut. Nilainya secara default adalah `True`.

max_shard_size (`int` atau `str`, *opsional*) : Ukuran maksimum setiap shard, dalam byte. Bawaan adalah 5GB.

metadata (`dict[str, str]`, *opsional*) : Informasi tambahan untuk disimpan bersama model. Beberapa metadata akan ditambahkan untuk setiap tensor yang dihapus. Informasi ini tidak akan cukup untuk memulihkan struktur bersama secara keseluruhan, tetapi mungkin membantu dalam memahami hal-hal tersebut.

safe_serialization (`bool`, *opsional*) : Apakah akan menyimpan sebagai safetensors, yang merupakan perilaku bawaan. Jika `False`, shard disimpan sebagai pickle. Serialisasi aman direkomendasikan karena alasan keamanan. Menyimpan sebagai pickle sudah tidak didukung (deprecated) dan akan dihapus pada versi mendatang.

is_main_process (`bool`, *opsional*) : Apakah proses yang memanggil ini adalah proses utama atau tidak. Berguna saat pelatihan terdistribusi seperti TPU dan perlu memanggil fungsi ini dari semua proses. Dalam kasus ini, atur `is_main_process=True` hanya pada proses utama untuk menghindari kondisi balapan. Bawaan adalah True.

shared_tensors_to_discard (`list[str]`, *opsional*) : Daftar nama tensor yang akan dihapus saat menyimpan tensor bersama. Jika tidak disediakan dan tensor bersama terdeteksi, nama pertama secara alfabetis akan dihapus.

Menyimpan model torch tertentu ke disk, menangani masalah sharding dan tensor bersama.

Lihat juga [save_torch_state_dict()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.save_torch_state_dict) untuk menyimpan state dict dengan fleksibilitas yang lebih besar.

Untuk informasi lebih lanjut tentang berbagi tensor, lihat [panduan ini](https://huggingface.co/docs/safetensors/torch_shared_tensors).

Kamus state model dipecah menjadi beberapa shard sehingga setiap shard lebih kecil dari ukuran tertentu. Shard disimpan di `save_directory` dengan `filename_pattern` yang diberikan. Jika model terlalu besar untuk muat dalam satu shard, file indeks disimpan di `save_directory` untuk menunjukkan di mana setiap tensor disimpan. Helper ini menggunakan [split_torch_state_dict_into_shards()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) di baliknya. Jika `safe_serialization` adalah `True`, shard disimpan sebagai safetensors (default). Sebaliknya, shard disimpan sebagai pickle.

Sebelum menyimpan model, `save_directory` dibersihkan dari file shard sebelumnya.

> [!WARNING]
> Jika salah satu tensor model lebih besar dari `max_shard_size`, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar dari `max_shard_size`.

> [!WARNING]
> Jika model Anda adalah `transformers.PreTrainedModel`, Anda harus meneruskan `model._tied_weights_keys` sebagai `shared_tensors_to_discard` untuk menangani penyimpanan tensor bersama dengan benar. Hal ini memastikan tensor duplikat yang tepat dibuang selama penyimpanan.

Contoh:

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L141)

**Parameter:**

state_dict (`dict[str, torch.Tensor]`) : Kamus status yang akan disimpan.

save_directory (`str` atau `Path`) : Direktori tempat model akan disimpan.

filename_pattern (`str`, *opsional*) : Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat dengan `filename_pattern.format(suffix=...)` dan harus mengandung kata kunci `suffix`. Secara default menggunakan `"model{suffix}.safetensors"` atau `pytorch_model{suffix}.bin` tergantung pada parameter `safe_serialization`.

force_contiguous (`boolean`, *opsional*) : Memaksa state_dict disimpan sebagai tensor yang contiguous. Hal ini tidak memengaruhi kebenaran model, tetapi berpotensi mengubah kinerja jika tata letak tensor dipilih secara khusus untuk alasan tersebut. Nilainya secara default adalah `True`.

max_shard_size (`int` atau `str`, *opsional*) : Ukuran maksimum setiap shard, dalam byte. Bawaan adalah 5GB.

metadata (`dict[str, str]`, *opsional*) : Informasi tambahan untuk disimpan bersama model. Beberapa metadata akan ditambahkan untuk setiap tensor yang dihapus. Informasi ini tidak akan cukup untuk memulihkan struktur bersama secara keseluruhan, tetapi mungkin membantu dalam memahami hal-hal tersebut.

safe_serialization (`bool`, *opsional*) : Apakah akan menyimpan sebagai safetensors, yang merupakan perilaku bawaan. Jika `False`, shard disimpan sebagai pickle. Serialisasi aman direkomendasikan karena alasan keamanan. Menyimpan sebagai pickle sudah tidak didukung (deprecated) dan akan dihapus pada versi mendatang.

is_main_process (`bool`, *opsional*) : Apakah proses yang memanggil ini adalah proses utama atau tidak. Berguna saat pelatihan terdistribusi seperti TPU dan perlu memanggil fungsi ini dari semua proses. Dalam kasus ini, atur `is_main_process=True` hanya pada proses utama untuk menghindari kondisi balapan. Bawaan adalah True.

shared_tensors_to_discard (`list[str]`, *opsional*) : Daftar nama tensor yang akan dihapus saat menyimpan tensor bersama. Jika tidak disediakan dan tensor bersama terdeteksi, nama pertama secara alfabetis akan dihapus.

Simpan kamus status model ke disk, menangani masalah sharding dan tensor bersama.

Lihat juga [save_torch_model()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.save_torch_model) untuk menyimpan model PyTorch secara langsung.

Untuk informasi lebih lanjut tentang berbagi tensor, lihat [panduan ini](https://huggingface.co/docs/safetensors/torch_shared_tensors).

Kamus state model dipecah menjadi beberapa shard sehingga setiap shard lebih kecil dari ukuran tertentu. Shard disimpan di `save_directory` dengan `filename_pattern` yang diberikan. Jika model terlalu besar untuk muat dalam satu shard, file indeks disimpan di `save_directory` untuk menunjukkan di mana setiap tensor disimpan. Helper ini menggunakan [split_torch_state_dict_into_shards()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) di baliknya. Jika `safe_serialization` adalah `True`, shard disimpan sebagai safetensors (default). Sebaliknya, shard disimpan sebagai pickle.

Sebelum menyimpan model, `save_directory` dibersihkan dari file shard sebelumnya.

> [!WARNING]
> Jika salah satu tensor model lebih besar dari `max_shard_size`, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar dari `max_shard_size`.

> [!WARNING]
> Jika model Anda adalah `transformers.PreTrainedModel`, Anda harus meneruskan `model._tied_weights_keys` sebagai `shared_tensors_to_discard` untuk menangani penyimpanan tensor bersama dengan benar. Hal ini memastikan tensor duplikat yang tepat dibuang selama penyimpanan.

Contoh:

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

Modul `serialization` juga berisi helper tingkat rendah untuk memecah state dictionary menjadi beberapa shard, sambil membuat indeks yang tepat dalam prosesnya. Helper ini tersedia untuk tensor `torch` dan dirancang agar mudah diperluas ke framework ML lainnya.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L302)

**Parameter:**

state_dict (`dict[str, torch.Tensor]`) : Kamus status yang akan disimpan.

filename_pattern (`str`, *opsional*) : Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat dengan `filename_pattern.format(suffix=...)` dan harus mengandung kata kunci `suffix`. Bawaan adalah `"model{suffix}.safetensors"`.

max_shard_size (`int` atau `str`, *opsional*) : Ukuran maksimum setiap shard, dalam byte. Bawaan adalah 5GB.

**Mengembalikan:** `StateDictSplit`

Objek `StateDictSplit` yang berisi shard dan indeks untuk mengambilnya.

Pisahkan kamus status model menjadi beberapa fragmen agar setiap fragmen lebih kecil dari ukuran tertentu.

Shard ditentukan dengan mengiterasi `state_dict` sesuai urutan kuncinya. Tidak ada optimasi yang dilakukan untuk membuat setiap shard sedekat mungkin dengan ukuran maksimum yang diberikan. Misalnya, jika batasnya adalah 10GB dan kita memiliki tensor dengan ukuran [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], mereka akan di-shard menjadi [6GB], [6+2GB], [6+2+2GB] dan bukan [6+2+2GB], [6+2GB], [6GB].

> [!TIP]
> Untuk menyimpan kamus status model ke disk, lihat [save_torch_state_dict()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.save_torch_state_dict). Helper ini menggunakan `split_torch_state_dict_into_shards` di baliknya.

> [!WARNING]
> Jika salah satu tensor model lebih besar dari `max_shard_size`, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar dari `max_shard_size`.

Contoh:
```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]]

Ini adalah pabrik dasar yang menjadi asal turunan setiap helper yang spesifik untuk framework tertentu. Dalam praktiknya, Anda tidak diharapkan untuk menggunakan pabrik ini secara langsung, kecuali jika Anda perlu menyesuaikannya dengan framework yang belum didukung. Jika demikian, silakan beri tahu kami dengan [membuka issue baru](https://github.com/huggingface/huggingface_hub/issues/new) di 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 0x7f56f657d510>, max_shard_size: int | str = '5GB')
```

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_base.py#L50)

**Parameter:**

state_dict (`dict[str, Tensor]`) : Kamus status yang akan disimpan.

get_storage_size (`Callable[[Tensor], int]`) : Fungsi yang mengembalikan ukuran tensor saat disimpan di disk dalam byte.

get_storage_id (`Callable[[Tensor], Optional[Any]]`, *opsional*) : Fungsi yang mengembalikan pengidentifikasi unik untuk penyimpanan tensor. Beberapa tensor yang berbeda dapat berbagi penyimpanan dasar yang sama. Pengidentifikasi ini dijamin unik dan konstan untuk penyimpanan tensor ini selama masa hidupnya. Dua penyimpanan tensor dengan masa hidup yang tidak tumpang tindih dapat memiliki id yang sama.

filename_pattern (`str`, *opsional*) : Pola untuk menghasilkan nama file tempat model akan disimpan. Pola harus berupa string yang dapat diformat dengan `filename_pattern.format(suffix=...)` dan harus mengandung kata kunci `suffix`

max_shard_size (`int` atau `str`, *opsional*) : Ukuran maksimum setiap shard, dalam byte. Bawaan adalah 5GB.

**Mengembalikan:** `StateDictSplit`

Objek `StateDictSplit` yang berisi shard dan indeks untuk mengambilnya.

Pisahkan kamus status model menjadi beberapa fragmen agar setiap fragmen lebih kecil dari ukuran tertentu.

Shard ditentukan dengan mengiterasi `state_dict` sesuai urutan kuncinya. Tidak ada optimasi yang dilakukan untuk membuat setiap shard sedekat mungkin dengan ukuran maksimum yang diberikan. Misalnya, jika batasnya adalah 10GB dan kita memiliki tensor dengan ukuran [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], mereka akan di-shard menjadi [6GB], [6+2GB], [6+2+2GB] dan bukan [6+2+2GB], [6+2GB], [6GB].

> [!WARNING]
> Jika salah satu tensor model lebih besar dari `max_shard_size`, tensor tersebut akan berakhir di shard tersendiri yang ukurannya lebih besar dari `max_shard_size`.

## Memuat tensor

Helper pemuatan mendukung checkpoint tunggal dan terpecah dalam format safetensors atau pickle. [load_torch_model()](/docs/huggingface_hub/main/id/package_reference/serialization#huggingface_hub.load_torch_model) menerima `nn.Module` dan path checkpoint (baik file tunggal maupun direktori) sebagai input, lalu memuat bobot ke dalam model.

> [!WARNING]
> Kedua helper ini secara default menggunakan `safe=True`, yang berarti checkpoint selalu dideserialisasi dengan loader safetensors — apa pun nama filenya. Memuat checkpoint pickle memerlukan opt-in secara eksplisit, karena unpickling mengeksekusi kode arbitrer saat pemuatan:
> ```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)
> ```
> Jalur pickle secara default juga menggunakan `weights_only=True`, yaitu unpickler terbatas dari torch. Checkpoint yang berisi objek non-tensor (state optimizer, seluruh model, ...) memerlukan `weights_only=False` di samping `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)
```

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L375)

**Parameter:**

model (`torch.nn.Module`) : Model tempat checkpoint dimuat.

checkpoint_path (`str` atau `os.PathLike`) : Path ke file checkpoint atau direktori yang berisi checkpoint.

strict (`bool`, *opsional*, defaultnya `False`) : Apakah akan secara ketat menegakkan bahwa kunci dalam state dict model harus cocok dengan kunci dalam checkpoint. Sama seperti `torch.nn.Module.load_state_dict`, pemeriksaan dilakukan setelah checkpoint dimuat, sehingga model mungkin sudah diperbarui sebagian ketika error muncul.

safe (`bool`, *opsional*, defaultnya `True`) : Jika `safe` adalah True, file safetensors akan dimuat. Jika `safe` adalah False, fungsi akan terlebih dahulu mencoba memuat file safetensors jika tersedia, jika tidak, akan beralih ke memuat file pickle. `filename_pattern` yang tidak menggambarkan file safetensors akan ditolak ketika `safe=True`.

weights_only (`bool`, *opsional*, defaultnya `True`) : Jika True, hanya memuat bobot model tanpa status optimizer dan metadata lainnya, menggunakan unpickler terbatas dari torch. Atur ke False untuk mengizinkan objek Python arbitrer dalam checkpoint pickle (hal ini mengeksekusi kode arbitrer saat pemuatan). Tidak berdampak pada PyTorch < 1.13, yang tidak memiliki unpickler terbatas dan selalu melakukan unpickle tanpa batasan.

map_location (`str` atau `torch.device`, *opsional*) : Objek `torch.device`, string, atau dict yang menentukan cara memetakan ulang lokasi penyimpanan. Ini menunjukkan lokasi di mana semua tensor harus dimuat.

mmap (`bool`, *opsional*, defaultnya `False`) : Apakah akan menggunakan pemuatan file memory-mapped. Pemetaan memori dapat meningkatkan kinerja pemuatan untuk model besar di PyTorch >= 2.1.0 dengan checkpoint berbasis zipfile.

filename_pattern (`str`, *opsional*) : Pola untuk mencari file indeks. Pola harus berupa string yang dapat diformat dengan `filename_pattern.format(suffix=...)` dan harus mengandung kata kunci `suffix`. Bawaan adalah `"model{suffix}.safetensors"`.

**Mengembalikan:** `NamedTuple`

Named tuple dengan field `missing_keys` dan `unexpected_keys`.
- `missing_keys` adalah daftar str yang berisi kunci yang hilang, yaitu kunci yang ada di model tetapi tidak ada di checkpoint.
- `unexpected_keys` adalah daftar str yang berisi kunci yang tidak terduga, yaitu kunci yang ada di checkpoint tetapi tidak ada di model.

**Mengangkat:** ``FileNotFoundError`` atau ``ImportError`` atau ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Jika file atau direktori checkpoint tidak ada.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Jika safetensors atau torch tidak terpasang saat mencoba memuat file .safetensors atau checkpoint PyTorch, masing-masing.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Jika format checkpoint tidak dapat ditentukan.

Muat checkpoint ke dalam model, menangani checkpoint yang terpecah (sharded) maupun yang tidak terpecah.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L633)

**Parameter:**

checkpoint_file (`str` atau `os.PathLike`) : Path ke file checkpoint yang akan dimuat. Bisa berupa checkpoint safetensors atau pickle (`.bin`).

map_location (`str` atau `torch.device`, *opsional*) : Objek `torch.device`, string, atau dict yang menentukan cara memetakan ulang lokasi penyimpanan. Ini menunjukkan lokasi di mana semua tensor harus dimuat.

weights_only (`bool`, *opsional*, defaultnya `True`) : Jika True, hanya memuat bobot model tanpa status optimizer dan metadata lainnya, menggunakan unpickler terbatas dari torch. Atur ke False untuk mengizinkan objek Python arbitrer dalam checkpoint pickle (hal ini mengeksekusi kode arbitrer saat pemuatan). Tidak berpengaruh saat memuat file safetensors, maupun pada PyTorch < 1.13 yang tidak memiliki unpickler terbatas — versi-versi tersebut selalu melakukan unpickle tanpa pembatasan dan sebuah peringatan dicatat.

mmap (`bool`, *opsional*, defaultnya `False`) : Apakah akan menggunakan pemuatan file berbasis memory-mapped. Pemetaan memori dapat meningkatkan kinerja pemuatan untuk model besar di PyTorch >= 2.1.0 dengan checkpoint berbasis zipfile. Tidak berpengaruh saat memuat file safetensors, karena pustaka `safetensors` menggunakan pemetaan memori secara default.

safe (`bool`, *opsional*, defaultnya `True`) : Jika True, checkpoint selalu dimuat sebagai safetensors, apa pun namanya. Format lain (misalnya file pickle `.bin`) akan memicu `ValueError` alih-alih dideserialisasi: checkpoint pickle dapat mengeksekusi kode arbitrer saat dimuat. Jika False, file dimuat sebagai safetensors jika namanya mengindikasikan demikian, dan dengan `torch.load` jika tidak.

**Mengembalikan:** `Union[dict[str, "torch.Tensor"], Any]`

Checkpoint yang dimuat.
- Untuk file safetensors: selalu mengembalikan kamus yang memetakan nama parameter ke tensor.
- Untuk file pickle: mengembalikan objek Python apa pun yang di-pickle (umumnya state dict, tetapi bisa juga seluruh model, state optimizer, atau objek Python lainnya).

**Mengangkat:** ``FileNotFoundError`` atau ``ImportError`` atau ``OSError`` atau ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Jika file checkpoint tidak ada.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Jika safetensors atau torch tidak terpasang saat mencoba memuat file .safetensors atau checkpoint PyTorch, masing-masing.
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- Jika format file checkpoint tidak valid atau jika file git-lfs tidak diunduh dengan benar.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Jika jalur file checkpoint kosong atau tidak valid, atau jika file tersebut tidak dapat dideserialisasi sebagai safetensors saat `safe=True` (lalu `safe=False` untuk mengizinkan checkpoint pickle).

Memuat file checkpoint, menangani format checkpoint safetensors dan pickle.

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

## Helper tensor

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L878)

Kembalikan pengenal unik ke penyimpanan tensor.

Beberapa tensor yang berbeda dapat berbagi penyimpanan (storage) yang sama. Identifikasi ini dijamin unik dan konstan untuk penyimpanan tensor ini selama masa hidupnya. Dua penyimpanan tensor dengan masa hidup yang tidak tumpang tindih dapat memiliki id yang sama. Dalam kasus tensor meta, kami mengembalikan None karena kami tidak dapat menentukan apakah mereka berbagi penyimpanan yang sama.

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

[Sumber](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/serialization/_torch.py#L895)

Diambil dari https://github.com/huggingface/safetensors/blob/08db34094e9e59e2f9218f2df133b7b4aaff5a99/bindings/python/py_src/safetensors/torch.py#L31C1-L41C59