# Serialização

`huggingface_hub` fornece auxiliares para salvar e carregar pesos de modelos de ML de uma maneira padronizada. Esta parte da biblioteca ainda está em desenvolvimento e será aprimorada em versões futuras. O objetivo é harmonizar como os pesos são salvos e carregados no Hub, tanto para eliminar a duplicação de código entre as bibliotecas quanto para estabelecer convenções consistentes.

## Formato de arquivo DDUF

DDUF é um formato de arquivo projetado para modelos de difusão. Ele permite salvar todas as informações necessárias para executar um modelo em um único arquivo. Este trabalho é inspirado no formato [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md). O `huggingface_hub` fornece auxiliares para salvar e carregar arquivos DDUF, garantindo que o formato do arquivo seja respeitado.

> [!WARNING]
> Esta é uma versão muito inicial do parser. A API e a implementação podem evoluir em um futuro próximo.
>
> O parser atualmente realiza muito pouca validação. Para mais detalhes sobre o formato do arquivo, consulte https://github.com/huggingface/huggingface.js/tree/main/packages/dduf.

### Como escrever um arquivo DDUF?

Aqui está como exportar uma pasta contendo diferentes partes de um modelo de difusão usando [export_folder_as_dduf()](/docs/huggingface_hub/v2.4.0/pt/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")
```

Para mais flexibilidade, você pode usar [export_entries_as_dduf()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.export_entries_as_dduf) e passar uma lista de arquivos para incluir no arquivo DDUF final:

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

O parâmetro `entries` também suporta a passagem de um iterável de caminhos ou bytes. Isso pode ser útil se você tiver um modelo carregado e quiser serializá-lo diretamente em um arquivo DDUF, em vez de precisar serializar cada componente para o disco primeiro e, em seguida, como um arquivo DDUF. Aqui está um exemplo de como um `StableDiffusionPipeline` pode ser serializado como 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))
```

**Observação:** na prática, o `diffusers` fornece um método para serializar diretamente um pipeline em um arquivo DDUF. O trecho acima é apenas um exemplo.

### Como ler um arquivo 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)
```

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

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

**Parâmetros:**

dduf_path (`str` ou `os.PathLike`) : O caminho para o arquivo DDUF a ser escrito.

entries (`Iterable[tuple[str, Union[str, Path, bytes]]]`) : Um iterável de entradas para gravar no arquivo DDUF. Cada entrada é uma tupla com o nome do arquivo e o conteúdo. O nome do arquivo deve ser o caminho para o arquivo no arquivo DDUF. O conteúdo pode ser uma string ou um pathlib.Path representando um caminho para um arquivo no disco local ou diretamente o conteúdo como bytes.

**Exceções:** `-`

- - -- `DDUFExportError`: Se algo der errado durante a exportação (por exemplo, nome de entrada inválido, 'model_index.json' ausente, etc.).

Escreva um arquivo DDUF a partir de um iterável de entradas.

Este é um auxiliar de nível inferior em relação ao [export_folder_as_dduf()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.export_folder_as_dduf) que permite mais flexibilidade ao serializar dados. Em particular, você não precisa salvar os dados em disco antes de exportá-los no arquivo DDUF.

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

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

**Parâmetros:**

dduf_path (`str` ou `os.PathLike`) : O caminho para o arquivo DDUF a ser escrito.

folder_path (`str` ou `os.PathLike`) : O caminho para a pasta que contém o modelo de difusão.

Exporte uma pasta como um arquivo DDUF.

AUtiliza [export_entries_as_dduf()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.export_entries_as_dduf) por baixo dos panos.

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

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

**Parâmetros:**

dduf_path (`str` ou `os.PathLike`) : O caminho para o arquivo DDUF a ser lido.

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

Um dicionário de [DDUFEntry](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.DDUFEntry) indexado pelo nome do arquivo.

**Exceções:** `-`

- - -- `DDUFCorruptedFileError`: Se o arquivo DDUF estiver corrompido (ou seja, não seguir o formato DDUF).

Lê um arquivo DDUF e retorna um dicionário de entradas.

Apenas os metadados são lidos; os dados não são carregados na memória.

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

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

**Parâmetros:**

filename (str) : O nome do arquivo no arquivo DDUF.

offset (int) : O deslocamento do arquivo no arquivo DDUF.

length (int) : O comprimento do arquivo no arquivo DDUF.

dduf_path (str) : O caminho para o arquivo DDUF (para uso interno).

Objeto que representa uma entrada de arquivo em um arquivo DDUF.

Veja [read_dduf_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.read_dduf_file) para saber como ler um arquivo DDUF.

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

```python
as_mmap()
```

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

Abra o arquivo como um arquivo mapeado em memória.

Útil para carregar safetensors diretamente do arquivo.

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

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

Leia o arquivo como texto.

Útil para entradas '.txt' e '.json'.

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

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

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

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

Exceção base para erros relacionados ao formato DDUF.

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

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

Exceção lançada quando o arquivo DDUF está corrompido.

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

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

Exceção base para erros durante a exportação do DDUF.

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

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

Exceção lançada quando o nome da entrada é inválido.

## Salvando tensores

O principal auxiliar do módulo `serialization` recebe um `nn.Module` do torch como entrada e o salva em disco. Ele trata a lógica para salvar tensores compartilhados (veja [explicação do safetensors](https://huggingface.co/docs/safetensors/torch_shared_tensors)) e a lógica para dividir o dicionário de estado em fragmentos, usando [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) por baixo dos panos. No momento, apenas o framework `torch` é suportado.

Se você deseja salvar um dicionário de estado (por exemplo, um mapeamento entre nomes de camadas e os tensores relacionados) em vez de um `nn.Module`, você pode usar [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.save_torch_state_dict), que oferece os mesmos recursos. Isso é útil, por exemplo, se você quiser aplicar uma lógica personalizada ao dicionário de estado antes de salvá-lo.

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

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

**Parâmetros:**

model (`torch.nn.Module`) : O modelo a ser salvo no disco.

save_directory (`str` ou `Path`) : O diretório no qual o modelo será salvo.

filename_pattern (`str`, *opcional*) : O padrão para gerar os nomes dos arquivos nos quais o modelo será salvo. O padrão deve ser uma string que pode ser formatada com `filename_pattern.format(suffix=...)` e deve conter a palavra-chave `suffix`. O padrão é `"model{suffix}.safetensors"` ou `pytorch_model{suffix}.bin`, dependendo do parâmetro `safe_serialization`.

force_contiguous (`boolean`, *opcional*) : Força o state_dict a ser salvo como tensores contíguos. Isso não afeta a correção do modelo, mas pode potencialmente alterar o desempenho se o layout do tensor foi escolhido especificamente por esse motivo. O valor padrão é `True`.

max_shard_size (`int` ou `str`, *opcional*) : O tamanho máximo de cada shard, em bytes. O padrão é 5GB.

metadata (`dict[str, str]`, *opcional*) : Informações extras para salvar junto com o modelo. Algumas metadados serão adicionados para cada tensor descartado. Essas informações não serão suficientes para recuperar toda a estrutura compartilhada, mas podem ajudar a entender as coisas.

safe_serialization (`bool`, *opcional*) : Se deve salvar como safetensors, que é o comportamento padrão. Se `False`, os shards são salvos como pickle. A serialização segura é recomendada por motivos de segurança. Salvar como pickle está obsoleto e será removido em uma versão futura.

is_main_process (`bool`, *opcional*) : Indica se o processo que está chamando esta função é o processo principal ou não. Útil em treinamento distribuído, como em TPUs, quando é necessário chamar esta função a partir de todos os processos. Nesse caso, defina `is_main_process=True` apenas no processo principal para evitar condições de corrida. O valor padrão é True.

shared_tensors_to_discard (`list[str]`, *opcional*) : Lista de nomes de tensores a serem descartados ao salvar tensores compartilhados. Se não for fornecida e tensores compartilhados forem detectados, o primeiro nome em ordem alfabética será descartado.

Salva um modelo torch específico no disco, lidando com problemas de sharding e tensores compartilhados.

Veja também [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.save_torch_state_dict) para salvar um state dict com mais flexibilidade.

Para mais informações sobre compartilhamento de tensores, consulte [este guia](https://huggingface.co/docs/safetensors/torch_shared_tensors).

O dicionário de estado do modelo é dividido em fragmentos para que cada fragmento seja menor que um tamanho dado. Os fragmentos são salvos no `save_directory` com o `filename_pattern` fornecido. Se o modelo for grande demais para caber em um único fragmento, um arquivo de índice é salvo no `save_directory` para indicar onde cada tensor é salvo. Este helper usa [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) por baixo dos panos. Se `safe_serialization` for `True`, os fragmentos são salvos como safetensors (o padrão). Caso contrário, os fragmentos são salvos como pickle.

Antes de salvar o modelo, o `save_directory` é limpo de quaisquer arquivos de shard anteriores.

> [!WARNING]
> Se um dos tensores do modelo for maior que `max_shard_size`, ele ficará em seu próprio shard, que terá um tamanho maior que `max_shard_size`.

> [!WARNING]
> Se o seu modelo for um `transformers.PreTrainedModel`, você deve passar `model._tied_weights_keys` como `shared_tensors_to_discard` para lidar corretamente com o salvamento de tensores compartilhados. Isso garante que os tensores duplicados corretos sejam descartados durante o salvamento.

Exemplo:

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

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

**Parâmetros:**

state_dict (`dict[str, torch.Tensor]`) : O dicionário de estado a ser salvo.

save_directory (`str` ou `Path`) : O diretório no qual o modelo será salvo.

filename_pattern (`str`, *opcional*) : O padrão para gerar os nomes dos arquivos nos quais o modelo será salvo. O padrão deve ser uma string que pode ser formatada com `filename_pattern.format(suffix=...)` e deve conter a palavra-chave `suffix`. O padrão é `"model{suffix}.safetensors"` ou `pytorch_model{suffix}.bin`, dependendo do parâmetro `safe_serialization`.

force_contiguous (`boolean`, *opcional*) : Força o state_dict a ser salvo como tensores contíguos. Isso não afeta a correção do modelo, mas pode potencialmente alterar o desempenho se o layout do tensor foi escolhido especificamente por esse motivo. O valor padrão é `True`.

max_shard_size (`int` ou `str`, *opcional*) : O tamanho máximo de cada shard, em bytes. O padrão é 5GB.

metadata (`dict[str, str]`, *opcional*) : Informações extras para salvar junto com o modelo. Algumas metadados serão adicionados para cada tensor descartado. Essas informações não serão suficientes para recuperar toda a estrutura compartilhada, mas podem ajudar a entender as coisas.

safe_serialization (`bool`, *opcional*) : Se deve salvar como safetensors, que é o comportamento padrão. Se `False`, os shards são salvos como pickle. A serialização segura é recomendada por motivos de segurança. Salvar como pickle está obsoleto e será removido em uma versão futura.

is_main_process (`bool`, *opcional*) : Indica se o processo que está chamando esta função é o processo principal ou não. Útil em treinamento distribuído, como em TPUs, quando é necessário chamar esta função a partir de todos os processos. Nesse caso, defina `is_main_process=True` apenas no processo principal para evitar condições de corrida. O valor padrão é True.

shared_tensors_to_discard (`list[str]`, *opcional*) : Lista de nomes de tensores a serem descartados ao salvar tensores compartilhados. Se não for fornecida e tensores compartilhados forem detectados, o primeiro nome em ordem alfabética será descartado.

Salve um dicionário de estado de modelo no disco, lidando com problemas de sharding e tensores compartilhados.

Veja também [save_torch_model()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.save_torch_model) para salvar diretamente um modelo do PyTorch.

Para mais informações sobre compartilhamento de tensores, consulte [este guia](https://huggingface.co/docs/safetensors/torch_shared_tensors).

O dicionário de estado do modelo é dividido em fragmentos para que cada fragmento seja menor que um tamanho dado. Os fragmentos são salvos no `save_directory` com o `filename_pattern` fornecido. Se o modelo for grande demais para caber em um único fragmento, um arquivo de índice é salvo no `save_directory` para indicar onde cada tensor é salvo. Este helper usa [split_torch_state_dict_into_shards()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.split_torch_state_dict_into_shards) por baixo dos panos. Se `safe_serialization` for `True`, os fragmentos são salvos como safetensors (o padrão). Caso contrário, os fragmentos são salvos como pickle.

Antes de salvar o modelo, o `save_directory` é limpo de quaisquer arquivos de shard anteriores.

> [!WARNING]
> Se um dos tensores do modelo for maior que `max_shard_size`, ele ficará em seu próprio shard, que terá um tamanho maior que `max_shard_size`.

> [!WARNING]
> Se o seu modelo for um `transformers.PreTrainedModel`, você deve passar `model._tied_weights_keys` como `shared_tensors_to_discard` para lidar corretamente com o salvamento de tensores compartilhados. Isso garante que os tensores duplicados corretos sejam descartados durante o salvamento.

Exemplo:

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

O módulo `serialization` também contém auxiliares de baixo nível para dividir um dicionário de estado em vários shards, criando um índice adequado no processo. Esses auxiliares estão disponíveis para tensores `torch` e foram projetados para serem facilmente estendidos a qualquer outro framework de ML.

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

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

**Parâmetros:**

state_dict (`dict[str, torch.Tensor]`) : O dicionário de estado a ser salvo.

filename_pattern (`str`, *opcional*) : O padrão para gerar os nomes dos arquivos nos quais o modelo será salvo. O padrão deve ser uma string que pode ser formatada com `filename_pattern.format(suffix=...)` e deve conter a palavra-chave `suffix`. O padrão padrão é `"model{suffix}.safetensors"`.

max_shard_size (`int` ou `str`, *opcional*) : O tamanho máximo de cada shard, em bytes. O padrão é 5GB.

**Retorna:** `StateDictSplit`

Um objeto `StateDictSplit` contendo os shards e o índice para recuperá-los.

Divida o dicionário de estado de um modelo em fragmentos para que cada fragmento seja menor que um tamanho dado.

Os shards são determinados iterando pelo `state_dict` na ordem de suas chaves. Não há otimização para tornar cada shard o mais próximo possível do tamanho máximo definido. Por exemplo, se o limite for 10GB e tivermos tensores de tamanhos [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], eles serão divididos em [6GB], [6+2GB], [6+2+2GB] e não em [6+2+2GB], [6+2GB], [6GB].

> [!TIP]
> Para salvar um dicionário de estado de modelo no disco, consulte [save_torch_state_dict()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.save_torch_state_dict). Este helper usa `split_torch_state_dict_into_shards` por baixo dos panos.

> [!WARNING]
> Se um dos tensores do modelo for maior que `max_shard_size`, ele ficará em seu próprio shard, que terá um tamanho maior que `max_shard_size`.

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

Esta é a fábrica subjacente a partir da qual cada helper específico de framework é derivado. Na prática, não se espera que você use esta fábrica diretamente, exceto se precisar adaptá-la a um framework que ainda não é suportado. Se esse for o caso, por favor, nos avise [abrindo uma nova issue](https://github.com/huggingface/huggingface_hub/issues/new) no repositório `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')
```

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

**Parâmetros:**

state_dict (`dict[str, Tensor]`) : O dicionário de estado a ser salvo.

get_storage_size (`Callable[[Tensor], int]`) : Uma função que retorna o tamanho de um tensor quando salvo em disco, em bytes.

get_storage_id (`Callable[[Tensor], Optional[Any]]`, *opcional*) : Uma função que retorna um identificador único para o armazenamento de um tensor. Vários tensores diferentes podem compartilhar o mesmo armazenamento subjacente. Esse identificador é garantido como único e constante para o armazenamento deste tensor durante seu ciclo de vida. Dois armazenamentos de tensor com ciclos de vida não sobrepostos podem ter o mesmo id.

filename_pattern (`str`, *opcional*) : O padrão para gerar os nomes dos arquivos nos quais o modelo será salvo. O padrão deve ser uma string que pode ser formatada com `filename_pattern.format(suffix=...)` e deve conter a palavra-chave `suffix`

max_shard_size (`int` ou `str`, *opcional*) : O tamanho máximo de cada shard, em bytes. O padrão é 5GB.

**Retorna:** `StateDictSplit`

Um objeto `StateDictSplit` contendo os shards e o índice para recuperá-los.

Divida o dicionário de estado de um modelo em fragmentos para que cada fragmento seja menor que um tamanho dado.

Os shards são determinados iterando pelo `state_dict` na ordem de suas chaves. Não há otimização para tornar cada shard o mais próximo possível do tamanho máximo definido. Por exemplo, se o limite for 10GB e tivermos tensores de tamanhos [6GB, 6GB, 2GB, 6GB, 2GB, 2GB], eles serão divididos em [6GB], [6+2GB], [6+2+2GB] e não em [6+2+2GB], [6+2GB], [6GB].

> [!WARNING]
> Se um dos tensores do modelo for maior que `max_shard_size`, ele ficará em seu próprio shard, que terá um tamanho maior que `max_shard_size`.

## Carregando tensores

Os helpers de carregamento suportam checkpoints em arquivo único e fragmentados, no formato safetensors ou pickle. [load_torch_model()](/docs/huggingface_hub/v2.4.0/pt/package_reference/serialization#huggingface_hub.load_torch_model) recebe um `nn.Module` e um caminho de checkpoint (seja um arquivo único ou um diretório) como entrada e carrega os pesos no modelo.

> [!WARNING]
> Os dois helpers têm como padrão `safe=True`, o que significa que o checkpoint é sempre desserializado com o carregador de safetensors — independentemente do nome do arquivo. Carregar um checkpoint em pickle requer opt-in explícito, pois o unpickling executa código arbitrário no momento do carregamento:
> ```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)
> ```
> O caminho pickle também usa `weights_only=True` por padrão, ou seja, o unpickler restrito do torch. Um checkpoint que contém objetos não tensor (estados do otimizador, um modelo inteiro, ...) precisa de `weights_only=False` em conjunto com `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)
```

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

**Parâmetros:**

model (`torch.nn.Module`) : O modelo no qual carregar o checkpoint.

checkpoint_path (`str` ou `os.PathLike`) : Caminho para o arquivo de checkpoint ou para o diretório que contém os checkpoints.

strict (`bool`, *opcional*, padrão `False`) : Se deve aplicar estritamente que as chaves no state dict do modelo correspondam às chaves no checkpoint. Assim como em `torch.nn.Module.load_state_dict`, a verificação ocorre após o carregamento do checkpoint, portanto o modelo pode ter sido parcialmente atualizado quando o erro é lançado.

safe (`bool`, *opcional*, padrão `True`) : Se `safe` for True, os arquivos safetensors serão carregados. Se `safe` for False, a função primeiro tentará carregar arquivos safetensors, se disponíveis; caso contrário, usará arquivos pickle. Um `filename_pattern` que não descreva arquivos safetensors é rejeitado quando `safe=True`.

weights_only (`bool`, *opcional*, padrão `True`) : Se True, carrega apenas os pesos do modelo, sem os estados do otimizador e outros metadados, usando o unpickler restrito do torch. Defina como False para permitir objetos Python arbitrários em um checkpoint pickle (isso executa código arbitrário no momento da carga). Não tem efeito no PyTorch < 1.13, que não possui um unpickler restrito e sempre faz o unpickle sem restrições.

map_location (`str` ou `torch.device`, *opcional*) : Um objeto `torch.device`, uma string ou um dicionário especificando como remapear os locais de armazenamento. Indica o local onde todos os tensors devem ser carregados.

mmap (`bool`, *opcional*, padrão `False`) : Se deve usar o carregamento de arquivo mapeado em memória. O mapeamento de memória pode melhorar o desempenho de carregamento para modelos grandes no PyTorch >= 2.1.0 com checkpoints baseados em zipfile.

filename_pattern (`str`, *opcional*) : O padrão para localizar o arquivo de índice. O padrão deve ser uma string que pode ser formatada com `filename_pattern.format(suffix=...)` e deve conter a palavra-chave `suffix`. O padrão padrão é `"model{suffix}.safetensors"`.

**Retorna:** `NamedTuple`

Uma tupla nomeada com os campos `missing_keys` e `unexpected_keys`.
- `missing_keys` é uma lista de str contendo as chaves ausentes, ou seja, chaves que estão no modelo mas não no checkpoint.
- `unexpected_keys` é uma lista de str contendo as chaves inesperadas, ou seja, chaves que estão no checkpoint mas não no modelo.

**Exceções:** ``FileNotFoundError`` ou ``ImportError`` ou ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Se o arquivo ou diretório de checkpoint não existir.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Se o safetensors ou o torch não estiverem instalados ao tentar carregar um arquivo .safetensors ou um checkpoint do PyTorch, respectivamente.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Se o formato do checkpoint não puder ser determinado.

Carrega um checkpoint em um modelo, tratando checkpoints fragmentados e não fragmentados.

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

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

**Parâmetros:**

checkpoint_file (`str` ou `os.PathLike`) : Caminho para o arquivo de checkpoint a ser carregado. Pode ser um checkpoint em safetensors ou pickle (`.bin`).

map_location (`str` ou `torch.device`, *opcional*) : Um objeto `torch.device`, uma string ou um dicionário especificando como remapear os locais de armazenamento. Indica o local onde todos os tensors devem ser carregados.

weights_only (`bool`, *opcional*, padrão `True`) : Se True, carrega apenas os pesos do modelo, sem os estados do otimizador e outros metadados, usando o unpickler restrito do torch. Defina como False para permitir objetos Python arbitrários em um checkpoint pickle (isso executa código arbitrário no momento da carga). Não tem efeito ao carregar arquivos safetensors, nem no PyTorch < 1.13, que não possui um unpickler restrito — essas versões sempre fazem unpickle sem restrição e um aviso é registrado.

mmap (`bool`, *opcional*, padrão `False`) : Se deve usar o carregamento de arquivo mapeado em memória. O mapeamento de memória pode melhorar o desempenho de carregamento para modelos grandes no PyTorch >= 2.1.0 com checkpoints baseados em zipfile. Não tem efeito ao carregar arquivos safetensors, pois a biblioteca `safetensors` usa mapeamento de memória por padrão.

safe (`bool`, *opcional*, padrão `True`) : Se True, o checkpoint é sempre carregado como safetensors, independentemente do seu nome. Qualquer outro formato (por exemplo, um arquivo pickle `.bin`) levanta um `ValueError` em vez de ser desserializado: checkpoints pickle podem executar código arbitrário no momento do carregamento. Se False, o arquivo é carregado como safetensors quando seu nome indica isso, e com `torch.load` caso contrário.

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

O checkpoint carregado.
- Para arquivos safetensors: sempre retorna um dicionário que mapeia nomes de parâmetros para tensores.
- Para arquivos pickle: retorna qualquer objeto Python que foi pickled (comumente um state dict, mas pode ser um modelo inteiro, o estado do otimizador ou qualquer outro objeto Python).

**Exceções:** ``FileNotFoundError`` ou ``ImportError`` ou ``OSError`` ou ``ValueError``

- [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) -- Se o arquivo de checkpoint não existir.
- [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) -- Se o safetensors ou o torch não estiverem instalados ao tentar carregar um arquivo .safetensors ou um checkpoint do PyTorch, respectivamente.
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- Se o formato do arquivo de checkpoint for inválido ou se os arquivos git-lfs não forem baixados corretamente.
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- Se o caminho do arquivo de checkpoint estiver vazio ou inválido, ou se ele não puder ser desserializado como safetensors enquanto `safe=True` (passar `safe=False` para permitir checkpoints pickle).

Carrega um arquivo de checkpoint, tratando tanto o formato de checkpoint safetensors quanto o formato pickle.

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

## Helpers de tensores

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

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

Retorna um identificador único para o armazenamento de um tensor.

Vários tensores diferentes podem compartilhar o mesmo armazenamento subjacente. Este identificador é garantido como único e constante para o armazenamento deste tensor durante seu ciclo de vida. Dois armazenamentos de tensores com ciclos de vida não sobrepostos podem ter o mesmo id. No caso de tensores meta, retornamos None, pois não podemos determinar se eles compartilham o mesmo armazenamento.

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

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

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