# Mixins & métodos de serialização

## Mixins

A biblioteca `huggingface_hub` oferece uma variedade de mixins que podem ser usados como classe pai para seus objetos, a fim de fornecer funções simples de upload e download. Consulte nosso [guia de integração](../guides/integrations) para aprender a integrar qualquer framework de ML com o Hub.

### Genérico[[huggingface_hub.ModelHubMixin]]

#### huggingface_hub.ModelHubMixin[[huggingface_hub.ModelHubMixin]]

```python
huggingface_hub.ModelHubMixin(*args, **kwargs)
```

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

**Parâmetros:**

repo_url (`str`, *opcional*) : URL do repositório da biblioteca. Usado para gerar o cartão do modelo.

paper_url (`str`, *opcional*) : URL do paper da biblioteca. Usado para gerar o model card.

docs_url (`str`, *opcional*) : URL da documentação da biblioteca. Usado para gerar o cartão do modelo.

model_card_template (`str`, *opcional*) : Modelo do cartão do modelo. Usado para gerar o cartão do modelo. O padrão é um modelo genérico.

language (`str` ou `list[str]`, *opcional*) : Idioma suportado pela biblioteca. Usado para gerar o cartão do modelo.

library_name (`str`, *opcional*) : Nome da biblioteca que integra o ModelHubMixin. Usado para gerar o cartão do modelo.

license (`str`, *opcional*) : Licença da biblioteca que integra o ModelHubMixin. Usada para gerar o cartão do modelo. Ex.: "apache-2.0"

license_name (`str`, *opcional*) : Nome da biblioteca que integra o ModelHubMixin. Usado para gerar o cartão do modelo. Utilizado apenas se `license` estiver definido como `other`. Ex.: "coqui-public-model-license".

license_link (`str`, *opcional*) : URL para a licença da biblioteca que integra o ModelHubMixin. Usado para gerar o cartão do modelo. Usado apenas se `license` estiver definido como `other` e `license_name` estiver definido. Ex.: "https://coqui.ai/cpml".

pipeline_tag (`str`, *opcional*) : Tag do pipeline. Usado para gerar o cartão do modelo. Ex.: "text-classification".

tags (`list[str]`, *opcional*) : Tags a serem adicionadas ao model card. Usado para gerar o model card. Ex.: ["computer-vision"]

coders (`dict[Type, tuple[Callable, Callable]]`, *opcional*) : Dicionário de tipos personalizados e seus codificadores/decodificadores. Usado para codificar/decodificar argumentos que não são jsonáveis por padrão. Ex.: dataclasses, argparse.Namespace, OmegaConf, etc.

Um mixin genérico para integrar QUALQUER framework de aprendizado de máquina com o Hub.

Para integrar seu framework, sua classe de modelo deve herdar desta classe. A lógica personalizada para salvar/carregar modelos deve ser sobrescrita em `_from_pretrained` e `_save_pretrained`. [PyTorchModelHubMixin](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) é um bom exemplo de integração de mixin com o Hub. Consulte nosso [guia de integração](../guides/integrations) para mais instruções.

Ao herdar de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin), você pode definir atributos de nível de classe. Esses atributos não são passados para `__init__`, mas para a própria definição da classe. Isso é útil para definir metadados sobre a biblioteca que integra [ModelHubMixin](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin).

Para mais detalhes sobre como integrar o mixin com sua biblioteca, consulte o [guia de integração](../guides/integrations).

Exemplo:

```python
>>> from huggingface_hub import ModelHubMixin

# Inherit from ModelHubMixin
>>> class MyCustomModel(
...         ModelHubMixin,
...         library_name="my-library",
...         tags=["computer-vision"],
...         repo_url="https://github.com/huggingface/my-cool-library",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://huggingface.co/docs/my-cool-library",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, size: int = 512, device: str = "cpu"):
...         # define how to initialize your model
...         super().__init__()
...         ...
...
...     def _save_pretrained(self, save_directory: Path) -> None:
...         # define how to serialize your model
...         ...
...
...     @classmethod
...     def from_pretrained(
...         cls: type[T],
...         pretrained_model_name_or_path: Union[str, Path],
...         *,
...         force_download: bool = False,
...         token: Optional[Union[str, bool]] = None,
...         cache_dir: Optional[Union[str, Path]] = None,
...         local_files_only: bool = False,
...         revision: Optional[str] = None,
...         **model_kwargs,
...     ) -> T:
...         # define how to deserialize your model
...         ...

>>> model = MyCustomModel(size=256, device="gpu")

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> reloaded_model = MyCustomModel.from_pretrained("username/my-awesome-model")
>>> reloaded_model.size
256

# Model card has been correctly populated
>>> from huggingface_hub import ModelCard
>>> card = ModelCard.load("username/my-awesome-model")
>>> card.data.tags
["x-custom-tag", "pytorch_model_hub_mixin", "model_hub_mixin"]
>>> card.data.library_name
"my-library"
```

#### _save_pretrained[[huggingface_hub.ModelHubMixin._save_pretrained]]

```python
_save_pretrained(save_directory: Path)
```

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

**Parâmetros:**

save_directory (`str` ou `Path`) : Caminho para o diretório em que os pesos e a configuração do modelo serão salvos.

Sobrescreva este método na subclasse para definir como salvar seu modelo. Consulte nosso [guia de integração](../guides/integrations) para obter instruções.

#### _from_pretrained[[huggingface_hub.ModelHubMixin._from_pretrained]]

```python
_from_pretrained(model_id: str, revision: str | None, cache_dir: str | pathlib.Path | None, force_download: bool, local_files_only: bool, token: str | bool | None, **model_kwargs)
```

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

**Parâmetros:**

model_id (`str`) : ID do modelo a ser carregado do Huggingface Hub (ex.: `bigscience/bloom`).

revision (`str`, *opcional*) : Revisão do modelo no Hub. Pode ser um nome de branch, uma tag git ou qualquer id de commit. O padrão é o commit mais recente na branch `main`.

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração do Hub, sobrescrevendo o cache existente.

token (`str` ou `bool`, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Por padrão, será utilizado o token em cache obtido ao executar `hf auth login`.

cache_dir (`str`, `Path`, *opcional*) : Caminho para a pasta onde os arquivos em cache são armazenados.

local_files_only (`bool`, *opcional*, padrão `False`) : Se `True`, evita o download do arquivo e retorna o caminho para o arquivo em cache local, se ele existir.

model_kwargs : Argumentos de palavra-chave adicionais passados para o método [_from_pretrained()](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained).

Sobrescreva este método em uma subclasse para definir como carregar seu modelo a partir de um pré-treinado.

Use [hf_hub_download()](/docs/huggingface_hub/v2.4.0/pt/package_reference/file_download#huggingface_hub.hf_hub_download) ou [snapshot_download()](/docs/huggingface_hub/v2.4.0/pt/package_reference/file_download#huggingface_hub.snapshot_download) para baixar arquivos do Hub antes de carregá-los. A maioria dos argumentos de entrada pode ser passada diretamente para esses 2 métodos. Se necessário, você pode adicionar mais argumentos a este método usando "model_kwargs". Por exemplo, `PyTorchModelHubMixin._from_pretrained()` recebe como entrada um parâmetro `map_location` para definir em qual dispositivo o modelo deve ser carregado.

Confira nosso [guia de integração](../guides/integrations) para mais instruções.

#### from_pretrained[[huggingface_hub.ModelHubMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | pathlib.Path, force_download: bool = False, token: str | bool | None = None, cache_dir: str | pathlib.Path | None = None, local_files_only: bool = False, revision: str | None = None, **model_kwargs)
```

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

**Parâmetros:**

pretrained_model_name_or_path (`str`, `Path`) : - O `model_id` (string) de um modelo hospedado no Hub, por exemplo, `bigscience/bloom`. - Ou um caminho para um `directory` contendo pesos de modelo salvos usando `save_pretrained`, por exemplo, `../path/to/my_model_directory/`.

revision (`str`, *opcional*) : Revisão do modelo no Hub. Pode ser um nome de branch, uma tag git ou qualquer id de commit. O padrão é o commit mais recente na branch `main`.

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração do Hub, sobrescrevendo o cache existente.

token (`str` ou `bool`, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Por padrão, será utilizado o token em cache obtido ao executar `hf auth login`.

cache_dir (`str`, `Path`, *opcional*) : Caminho para a pasta onde os arquivos em cache são armazenados.

local_files_only (`bool`, *opcional*, padrão `False`) : Se `True`, evita o download do arquivo e retorna o caminho para o arquivo em cache local, se ele existir.

model_kwargs (`dict`, *opcional*) : Kwargs adicionais para passar ao modelo durante a inicialização.

Baixe um modelo do Huggingface Hub e instancie-o.

#### push_to_hub[[huggingface_hub.ModelHubMixin.push_to_hub]]

```python
push_to_hub(repo_id: str, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, commit_message: str = 'Push model using huggingface_hub.', private: bool | None = None, token: str | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, model_card_kwargs: dict[str, typing.Any] | None = None)
```

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

**Parâmetros:**

repo_id (`str`) : ID do repositório para o qual será feito o push (exemplo: `"username/my-model"`).

config (`dict` ou `DataclassInstance`, *opcional*) : Configuração do modelo especificada como um dicionário de chave/valor ou uma instância de dataclass.

commit_message (`str`, *opcional*) : Mensagem a ser commitada durante o push.

private (`bool`, *opcional*) : Se o repositório criado deve ser privado. Se `None` (padrão), o repositório será público, a menos que o padrão da organização seja privado.

token (`str`, *opcional*) : O token a ser usado como autorização bearer HTTP para arquivos remotos. Por padrão, será usado o token em cache obtido ao executar `hf auth login`.

branch (`str`, *opcional*) : O branch do git no qual o modelo será enviado. O padrão é `"main"`.

create_pr (`boolean`, *opcional*) : Se deve ou não criar um Pull Request a partir de `branch` com esse commit. O padrão é `False`.

allow_patterns (`list[str]` ou `str`, *opcional*) : Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.

ignore_patterns (`list[str]` ou `str`, *opcional*) : Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.

delete_patterns (`list[str]` ou `str`, *opcional*) : Se fornecido, os arquivos remotos que corresponderem a qualquer um dos padrões serão excluídos do repositório.

model_card_kwargs (`dict[str, Any]`, *opcional*) : Argumentos adicionais passados para o modelo de cartão do modelo para personalizar o cartão do modelo.

**Retorna:**

A URL do commit do seu modelo no repositório fornecido.

Envie o checkpoint do modelo para o Hub.

Use `allow_patterns` e `ignore_patterns` para filtrar com precisão quais arquivos devem ser enviados ao hub. Use `delete_patterns` para excluir arquivos remotos existentes no mesmo commit. Consulte a referência de [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) para mais detalhes.

#### save_pretrained[[huggingface_hub.ModelHubMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | pathlib.Path, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, repo_id: str | None = None, push_to_hub: bool = False, model_card_kwargs: dict[str, typing.Any] | None = None, **push_to_hub_kwargs)
```

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

**Parâmetros:**

save_directory (`str` ou `Path`) : Caminho para o diretório em que os pesos e a configuração do modelo serão salvos.

config (`dict` ou `DataclassInstance`, *opcional*) : Configuração do modelo especificada como um dicionário de chave/valor ou uma instância de dataclass.

push_to_hub (`bool`, *opcional*, padrão `False`) : Se deve ou não enviar seu modelo para o Huggingface Hub após salvá-lo.

repo_id (`str`, *opcional*) : ID do seu repositório no Hub. Usado apenas se `push_to_hub=True`. Se não for fornecido, o padrão será o nome da pasta.

model_card_kwargs (`dict[str, Any]`, *opcional*) : Argumentos adicionais passados para o modelo de cartão do modelo para personalizar o cartão do modelo.

push_to_hub_kwargs : Argumentos de palavra-chave adicionais passados ao método [push_to_hub()](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin.push_to_hub).

**Retorna:** `str` ou `None`

URL do commit no Hub se `push_to_hub=True`, `None` caso contrário.

Salve os pesos em um diretório local.

### PyTorch[[huggingface_hub.PyTorchModelHubMixin]]

#### huggingface_hub.PyTorchModelHubMixin[[huggingface_hub.PyTorchModelHubMixin]]

```python
huggingface_hub.PyTorchModelHubMixin(*args, **kwargs)
```

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

Implementação de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin) para fornecer capacidades de upload/download no Hub para modelos PyTorch. O modelo é definido no modo de avaliação por padrão usando `model.eval()` (módulos de dropout são desativados). Para treinar o modelo, você deve primeiro redefinir o modo de treinamento com `model.train()`.

Veja [ModelHubMixin](/docs/huggingface_hub/v2.4.0/pt/package_reference/mixins#huggingface_hub.ModelHubMixin) para mais detalhes sobre como usar o mixin.

Exemplo:

```python
>>> import torch
>>> import torch.nn as nn
>>> from huggingface_hub import PyTorchModelHubMixin

>>> class MyModel(
...         nn.Module,
...         PyTorchModelHubMixin,
...         library_name="keras-nlp",
...         repo_url="https://github.com/keras-team/keras-nlp",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://keras.io/keras_nlp/",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4):
...         super().__init__()
...         self.param = nn.Parameter(torch.rand(hidden_size, vocab_size))
...         self.linear = nn.Linear(output_size, vocab_size)

...     def forward(self, x):
...         return self.linear(x + self.param)
>>> model = MyModel(hidden_size=256)

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> model = MyModel.from_pretrained("username/my-awesome-model")
>>> model.hidden_size
256
```

### Fastai[[huggingface_hub.from_pretrained_fastai]]

#### huggingface_hub.from_pretrained_fastai[[huggingface_hub.from_pretrained_fastai]]

```python
huggingface_hub.from_pretrained_fastai(repo_id: str, revision: str | None = None)
```

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

**Parâmetros:**

repo_id (`str`) : A localização onde o fastai.Learner em formato pickle está. Pode ser uma das duas opções: - Hospedado no Hugging Face Hub. Ex.: 'espejelomar/fatai-pet-breeds-classification' ou 'distilgpt2'. Você pode adicionar uma `revision` acrescentando `@` no final de `repo_id`. Ex.: `dbmdz/bert-base-german-cased@main`. A `revision` é a versão específica do modelo a ser usada. Como usamos um sistema baseado em git para armazenar modelos e outros artefatos no Hugging Face Hub, ela pode ser um nome de branch, um nome de tag ou um id de commit. - Hospedado localmente. `repo_id` seria um diretório contendo o pickle e um pyproject.toml indicando as versões do fastai e do fastcore usadas para construir o `fastai.Learner`. Ex.: `./my_model_directory/`.

revision (`str`, *opcional*) : Revisão na qual os arquivos do repositório são baixados. Consulte a documentação de `snapshot_download`.

**Retorna:**

O modelo `fastai.Learner` no repositório `repo_id`.

Carregue um modelo fastai pré-treinado do Hub ou de um diretório local.

#### huggingface_hub.push_to_hub_fastai[[huggingface_hub.push_to_hub_fastai]]

```python
huggingface_hub.push_to_hub_fastai(learner, repo_id: str, commit_message: str = 'Push FastAI model using huggingface_hub.', private: bool | None = None, token: str | None = None, config: dict | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, api_endpoint: str | None = None)
```

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

**Parâmetros:**

learner (*Learner*) : O *fastai.Learner' que você deseja enviar para o Hub.

repo_id (*str*) : O id do repositório do seu modelo no Hub, no formato "namespace/repo_name". O namespace pode ser sua conta individual ou uma organização à qual você tem acesso de escrita (por exemplo, 'stanfordnlp/stanza-de').

commit_message (*str`, *optional*) : Message to commit while pushing. Will default to `"add model"`.

private (*bool*, *opcional*) : Indica se o repositório criado deve ser privado. Se *None* (padrão), o repositório será público, exceto se o padrão da organização for privado.

token (*str*, *opcional*) : O token da conta do Hugging Face a ser usado como autorização bearer HTTP para arquivos remotos. Se `None`, o token será solicitado por meio de um prompt.

config (*dict*, *opcional*) : Objeto de configuração a ser salvo junto com os pesos do modelo.

branch (*str*, *opcional*) : O branch do git no qual o modelo será enviado. O padrão é o branch padrão especificado no seu repositório, que por padrão é *"main"*.

create_pr (*boolean*, *opcional*) : Se deve ou não criar um Pull Request a partir de *branch* com esse commit. O padrão é *False*.

api_endpoint (*str*, *opcional*) : O endpoint da API a ser usado ao enviar o modelo para o hub.

allow_patterns (*list[str]* ou *str*, *opcional*) : Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.

ignore_patterns (*list[str]* ou *str*, *opcional*) : Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.

delete_patterns (*list[str]* ou *str*, *opcional*) : Se fornecido, os arquivos remotos que corresponderem a qualquer um dos padrões serão excluídos do repositório.

**Retorna:**

A URL do commit do seu modelo no repositório fornecido.

Envie os arquivos de checkpoint do aprendiz para o Hub.

Use *allow_patterns* e *ignore_patterns* para filtrar com precisão quais arquivos devem ser enviados ao hub. Use *delete_patterns* para excluir arquivos remotos existentes no mesmo commit. Consulte a referência de [*upload_folder*] para mais detalhes.

> [!TIP]
> Gera o seguinte erro:
>
> - [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError) se o usuário não estiver conectado ao Hugging Face Hub.