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 para aprender a integrar cualquier framework de ML con el Hub.

Genérico

clase huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

Parámetros

repo_url (str, opcional) — URL del repositorio de la biblioteca. Se usa 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. Por ejemplo: “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. Por ejemplo: “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. Por ejemplo: ”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 jsonables 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 es un buen ejemplo de integración de mixin con el Hub. Consulta nuestra guía de integración para obtener más instrucciones.

Al heredar de 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.

Para más detalles sobre cómo integrar el mixin con tu biblioteca, consulta la guía de integración.

Ejemplo:

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

< source >

( save_directory: Path )

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 para obtener instrucciones.

_from_pretrained

< source >

Parámetros

model_id (str) — ID del modelo que se cargará desde el Huggingface Hub (p. ej. bigscience/bloom).
revision (str, opcional) — Revisión del modelo en el Hub. Puede ser el nombre de una rama, una etiqueta de 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 los archivos remotos. De forma predeterminada, se utilizará el token en caché al ejecutar hf auth login.
cache_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los archivos en caché.
local_files_only (bool, opcional, valor predeterminado False) — Si 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().

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

Use hf_hub_download() o 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 para obtener más instrucciones.

from_pretrained

< source >

Parámetros

pretrained_model_name_or_path (str, Path) —
- El model_id (cadena) de un modelo alojado en el Hub, por ejemplo, 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 el nombre de una rama, una etiqueta de 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 los archivos remotos. De forma predeterminada, se utilizará el token en caché al ejecutar hf auth login.
cache_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los archivos en caché.
local_files_only (bool, opcional, valor predeterminado False) — Si 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

< source >

Parámetros

repo_id (str) — ID del repositorio al que se enviarán los datos (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 para el commit al hacer push.
private (bool, opcional) — Si el repositorio creado debe ser privado. Si es None (valor 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 en caché al ejecutar hf auth login.
branch (str, opcional) — La rama de git en la que se publicará el modelo. El valor predeterminado es "main".
create_pr (boolean, opcional) — Indica si se debe crear un 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.

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() para más detalles.

save_pretrained

< source >

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, valor predeterminado False) — Indica si se debe subir 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 por defecto.
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().

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

clase huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

Implementación de 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 para obtener más detalles sobre cómo usar el mixin.

Ejemplo:

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

< source >

( repo_id: strrevision: str | None = None )

Parámetros

repo_id (str) — La ubicación donde se encuentra el fastai.Learner serializado. Puede ser una de las siguientes:
- Alojado en el Hugging Face Hub. Por ejemplo: ‘espejelomar/fatai-pet-breeds-classification’ o ‘distilgpt2’. Puedes 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 usar. 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 id 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.

Cargar un modelo fastai preentrenado desde el Hub o desde un directorio local.

huggingface_hub.push_to_hub_fastai

< source >

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`, opcional*) — Mensaje para el commit al hacer push. El valor predeterminado es "add model".
private (bool, opcional) — Indica si el repositorio creado debe ser privado. Si es None (valor predeterminado), será público por defecto, a menos que el valor predeterminado de la organización sea 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, optional) — Configuration object to be saved alongside the model weights.
branch (str, opcional) — La rama de git en la que se enviará el modelo. Por defecto, se utiliza la rama predeterminada especificada en tu repositorio, que por defecto es “main”.
create_pr (boolean, opcional) — Indica si se debe o no crear una Pull Request desde branch con ese commit. El valor predeterminado es False.
api_endpoint (str, opcional) — El punto de acceso de la API que se utilizará al subir 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.

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.

Lanza el siguiente error:

ValueError si el usuario no ha iniciado sesión en Hugging Face Hub.

Update on GitHub

Hub Python Library

Mixins y métodos de serialización

Mixins

Genérico

clase huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

clase huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai