# Mixins y métodos de serialización

## Mixins

La biblioteca `huggingface_hub` ofrece una serie de mixins que pueden usarse como clase padre para tus objetos, a fin de proporcionar funciones simples de carga y descarga. Consulta nuestra [guía de integración](../guides/integrations) para aprender a integrar cualquier framework de ML con el Hub.

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

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

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

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

**Parámetros:**

repo_url (`str`, *opcional*) : URL del repositorio de la biblioteca. Se utiliza para generar la tarjeta del modelo.

paper_url (`str`, *opcional*) : URL del artículo de la biblioteca. Se utiliza para generar la tarjeta del modelo.

docs_url (`str`, *opcional*) : URL de la documentación de la biblioteca. Se utiliza para generar la tarjeta del modelo.

model_card_template (`str`, *opcional*) : Plantilla de la tarjeta del modelo. Se utiliza para generar la tarjeta del modelo. El valor predeterminado es una plantilla genérica.

language (`str` o `list[str]`, *opcional*) : Idioma admitido por la biblioteca. Se utiliza para generar la tarjeta del modelo.

library_name (`str`, *opcional*) : Nombre de la biblioteca que integra ModelHubMixin. Se utiliza para generar la tarjeta del modelo.

license (`str`, *opcional*) : Licencia de la biblioteca que integra ModelHubMixin. Se utiliza para generar la tarjeta del modelo. Ej.: "apache-2.0"

license_name (`str`, *opcional*) : Nombre de la biblioteca que integra ModelHubMixin. Se utiliza para generar la tarjeta del modelo. Solo se usa si `license` está establecido en `other`. Ej.: "coqui-public-model-license".

license_link (`str`, *opcional*) : URL de la licencia de la biblioteca que integra ModelHubMixin. Se utiliza para generar la tarjeta del modelo. Solo se usa si `license` está establecido en `other` y `license_name` está establecido. Ej.: "https://coqui.ai/cpml".

pipeline_tag (`str`, *opcional*) : Etiqueta del pipeline. Se utiliza para generar la tarjeta del modelo. Por ejemplo, "text-classification".

tags (`list[str]`, *opcional*) : Etiquetas que se añadirán a la tarjeta del modelo. Se utilizan para generar la tarjeta del modelo. Por ejemplo, ["computer-vision"]

coders (`dict[Type, tuple[Callable, Callable]]`, *opcional*) : Diccionario de tipos personalizados y sus codificadores/decodificadores. Se utiliza para codificar/decodificar argumentos que no son serializables en JSON de forma predeterminada. Por ejemplo, dataclasses, argparse.Namespace, OmegaConf, etc.

Un mixin genérico para integrar cualquier framework de aprendizaje automático con el Hub.

Para integrar tu framework, tu clase de modelo debe heredar de esta clase. La lógica personalizada para guardar/cargar modelos debe sobrescribirse en `_from_pretrained` y `_save_pretrained`. [PyTorchModelHubMixin](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) es un buen ejemplo de integración de mixin con el Hub. Consulta nuestra [guía de integración](../guides/integrations) para obtener más instrucciones.

Al heredar de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin), puede definir atributos a nivel de clase. Estos atributos no se pasan a `__init__`, sino a la propia definición de la clase. Esto resulta útil para definir metadatos sobre la biblioteca que integra [ModelHubMixin](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin).

Para más detalles sobre cómo integrar el mixin con tu biblioteca, consulta la [guía de integración](../guides/integrations).

Ejemplo:

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

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

**Parámetros:**

save_directory (`str` o `Path`) : Ruta al directorio en el que se guardarán los pesos y la configuración del modelo.

Sobrescribe este método en la subclase para definir cómo guardar tu modelo. Consulta nuestra [guía de integración](../guides/integrations) para obtener instrucciones.

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

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

**Parámetros:**

model_id (`str`) : ID del modelo que se cargará desde Huggingface Hub (p. ej. `bigscience/bloom`).

revision (`str`, *opcional*) : Revisión del modelo en el Hub. Puede ser un nombre de rama, una etiqueta git o cualquier id de commit. Por defecto, es el último commit de la rama `main`.

force_download (`bool`, *opcional*, valor predeterminado `False`) : Si se debe forzar la (re)descarga de los pesos del modelo y los archivos de configuración desde el Hub, invalidando la caché existente.

token (`str` o `bool`, *opcional*) : El token que se usará como autorización HTTP bearer para archivos remotos. De forma predeterminada, se utilizará el token almacenado en caché al ejecutar `hf auth login`.

cache_dir (`str`, `Path`, *opcional*) : Ruta a la carpeta donde se almacenan los archivos en caché.

local_files_only (`bool`, *opcional*, valor predeterminado `False`) : Si es `True`, evita descargar el archivo y devuelve la ruta al archivo en caché local si existe.

model_kwargs : Argumentos de palabra clave adicionales que se pasan al método [_from_pretrained()](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained).

Sobrescribe este método en la subclase para definir cómo cargar tu modelo a partir de uno preentrenado.

Use [hf_hub_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download) o [snapshot_download()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.snapshot_download) para descargar archivos del Hub antes de cargarlos. La mayoría de los argumentos de entrada se pueden pasar directamente a esos 2 métodos. Si es necesario, puede agregar más argumentos a este método usando "model_kwargs". Por ejemplo, `PyTorchModelHubMixin._from_pretrained()` toma como entrada un parámetro `map_location` para establecer en qué dispositivo se debe cargar el modelo.

Consulte nuestra [guía de integración](../guides/integrations) para obtener más instrucciones.

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

[Fuente](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`) : - Either the `model_id` (string) of a model hosted on the Hub, e.g. `bigscience/bloom`. - Or a path to a `directory` containing model weights saved using `save_pretrained`, e.g., `../path/to/my_model_directory/`.

revision (`str`, *opcional*) : Revisión del modelo en el Hub. Puede ser un nombre de rama, una etiqueta git o cualquier id de commit. Por defecto, es el último commit de la rama `main`.

force_download (`bool`, *opcional*, valor predeterminado `False`) : Si se debe forzar la (re)descarga de los pesos del modelo y los archivos de configuración desde el Hub, invalidando la caché existente.

token (`str` o `bool`, *opcional*) : El token que se usará como autorización HTTP bearer para archivos remotos. De forma predeterminada, se utilizará el token almacenado en caché al ejecutar `hf auth login`.

cache_dir (`str`, `Path`, *opcional*) : Ruta a la carpeta donde se almacenan los archivos en caché.

local_files_only (`bool`, *opcional*, valor predeterminado `False`) : Si es `True`, evita descargar el archivo y devuelve la ruta al archivo en caché local si existe.

model_kwargs (`dict`, *opcional*) : Kwargs adicionales para pasar al modelo durante la inicialización.

Descarga un modelo desde el Huggingface Hub y instancialo.

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

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

**Parámetros:**

repo_id (`str`) : ID del repositorio al que se enviarán los cambios (ejemplo: `"username/my-model"`).

config (`dict` o `DataclassInstance`, *opcional*) : Configuración del modelo especificada como un diccionario de clave/valor o una instancia de dataclass.

commit_message (`str`, *opcional*) : Mensaje a confirmar al hacer push.

private (`bool`, *opcional*) : Si el repositorio creado debe ser privado. Si es `None` (predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado.

token (`str`, *opcional*) : El token que se usará como autorización HTTP bearer para archivos remotos. De forma predeterminada, se utilizará el token almacenado en caché al ejecutar `hf auth login`.

branch (`str`, *opcional*) : La rama de git en la que se enviará el modelo. El valor predeterminado es `"main"`.

create_pr (`boolean`, *opcional*) : Si se crea o no una Pull Request desde `branch` con ese commit. El valor predeterminado es `False`.

allow_patterns (`list[str]` o `str`, *opcional*) : Si se proporciona, solo se suben los archivos que coincidan con al menos un patrón.

ignore_patterns (`list[str]` o `str`, *opcional*) : Si se proporciona, los archivos que coincidan con cualquiera de los patrones no se enviarán.

delete_patterns (`list[str]` o `str`, *opcional*) : Si se proporciona, los archivos remotos que coincidan con cualquiera de los patrones se eliminarán del repositorio.

model_card_kwargs (`dict[str, Any]`, *opcional*) : Argumentos adicionales que se pasan a la plantilla de la tarjeta del modelo para personalizarla.

**Devuelve:**

La URL del commit de tu modelo en el repositorio dado.

Subir el punto de control del modelo al Hub.

Use `allow_patterns` y `ignore_patterns` para filtrar con precisión qué archivos deben subirse al hub. Use `delete_patterns` para eliminar archivos remotos existentes en el mismo commit. Consulte la referencia de [upload_folder()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) para más detalles.

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

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

**Parámetros:**

save_directory (`str` o `Path`) : Ruta al directorio en el que se guardarán los pesos y la configuración del modelo.

config (`dict` o `DataclassInstance`, *opcional*) : Configuración del modelo especificada como un diccionario de clave/valor o una instancia de dataclass.

push_to_hub (`bool`, *opcional*, por defecto `False`) : Si se sube o no el modelo al Huggingface Hub después de guardarlo.

repo_id (`str`, *opcional*) : ID de tu repositorio en el Hub. Se usa solo si `push_to_hub=True`. Si no se proporciona, se usará el nombre de la carpeta.

model_card_kwargs (`dict[str, Any]`, *opcional*) : Argumentos adicionales que se pasan a la plantilla de la tarjeta del modelo para personalizarla.

push_to_hub_kwargs : Argumentos de palabra clave adicionales que se pasan al método [push_to_hub()](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin.push_to_hub).

**Devuelve:** `str` o `None`

URL del commit en el Hub si `push_to_hub=True`, `None` en caso contrario.

Guardar los pesos en un directorio local.

### PyTorch[[huggingface_hub.PyTorchModelHubMixin]]

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

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

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

Implementación de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin) para proporcionar capacidades de carga y descarga en el Hub a modelos de PyTorch. El modelo se establece en modo de evaluación de forma predeterminada usando `model.eval()` (los módulos de dropout se desactivan). Para entrenar el modelo, primero debe volver a establecerlo en modo de entrenamiento con `model.train()`.

Consulte [ModelHubMixin](/docs/huggingface_hub/v2.4.0/es/package_reference/mixins#huggingface_hub.ModelHubMixin) para obtener más detalles sobre cómo usar el mixin.

Ejemplo:

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

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

**Parámetros:**

repo_id (`str`) : La ubicación donde se encuentra el fastai.Learner serializado. Puede ser una de las dos opciones siguientes: - Alojado en el Hugging Face Hub. Por ejemplo: 'espejelomar/fatai-pet-breeds-classification' o 'distilgpt2'. Puede añadir una `revision` añadiendo `@` al final de `repo_id`. Por ejemplo: `dbmdz/bert-base-german-cased@main`. La revisión es la versión específica del modelo que se va a utilizar. Dado que utilizamos un sistema basado en git para almacenar modelos y otros artefactos en el Hugging Face Hub, puede ser el nombre de una rama, el nombre de una etiqueta o un identificador de commit. - Alojado localmente. `repo_id` sería un directorio que contiene el archivo pickle y un pyproject.toml que indica las versiones de fastai y fastcore utilizadas para construir el `fastai.Learner`. Por ejemplo: `./my_model_directory/`.

revision (`str`, *opcional*) : Revisión en la que se descargan los archivos del repositorio. Consulte la documentación de `snapshot_download`.

**Devuelve:**

El modelo `fastai.Learner` en el repositorio `repo_id`.

Cargar un modelo fastai preentrenado desde el Hub o desde un directorio 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)
```

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

**Parámetros:**

learner (*Learner*) : El *fastai.Learner' que deseas subir al Hub.

repo_id (*str*) : El identificador del repositorio de tu modelo en Hub, en el formato "namespace/repo_name". El namespace puede ser tu cuenta individual o una organización a la que tengas acceso de escritura (por ejemplo, 'stanfordnlp/stanza-de').

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

private (*bool*, *opcional*) : Indica si el repositorio creado debe ser privado. Si es *None* (valor predeterminado), será público, excepto si el valor predeterminado de la organización es privado.

token (*str*, *opcional*) : El token de la cuenta de Hugging Face que se usará como autorización HTTP bearer para los archivos remotos. Si es `None`, se solicitará el token mediante un prompt.

config (*dict*, *opcional*) : Objeto de configuración que se guardará junto con los pesos del modelo.

branch (*str*, *opcional*) : La rama de git en la que se enviará el modelo. Por defecto, se utiliza la rama predeterminada especificada en su repositorio, que por defecto es *"main"*.

create_pr (*boolean*, *opcional*) : Si se crea o no una Pull Request desde *branch* con ese commit. El valor predeterminado es *False*.

api_endpoint (*str*, *opcional*) : El punto final de la API que se utilizará al enviar el modelo al hub.

allow_patterns (*list[str]* o *str*, *opcional*) : Si se proporciona, solo se suben los archivos que coincidan con al menos un patrón.

ignore_patterns (*list[str]* o *str*, *opcional*) : Si se proporciona, los archivos que coincidan con cualquiera de los patrones no se enviarán.

delete_patterns (*list[str]* o *str*, *opcional*) : Si se proporciona, los archivos remotos que coincidan con cualquiera de los patrones se eliminarán del repositorio.

**Devuelve:**

La URL del commit de tu modelo en el repositorio dado.

Sube los archivos de puntos de control del aprendiz al Hub.

Use *allow_patterns* y *ignore_patterns* para filtrar con precisión qué archivos deben subirse al hub. Use *delete_patterns* para eliminar archivos remotos existentes en el mismo commit. Consulte la referencia de [*upload_folder*] para más detalles.

> [!TIP]
> Lanza el siguiente error:
>
> - [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError) si el usuario no ha iniciado sesión en Hugging Face Hub.