Integra tu biblioteca con el Hub

El Hugging Face Hub tiene como objetivo facilitar el intercambio de modelos de aprendizaje automático, puntos de control y artefactos. Este esfuerzo incluye la integración del Hub con muchas de las increíbles bibliotecas de terceros de la comunidad. Algunas de las que ya están integradas incluyen spaCy, Sentence Transformers, OpenCLIP y timm, entre muchas otras. La integración significa que los usuarios pueden descargar y subir archivos al Hub directamente desde su biblioteca. Esperamos que integre su biblioteca y se una a nosotros para democratizar la inteligencia artificial para todos.

Integrar el Hub con tu biblioteca ofrece muchos beneficios, entre ellos:

• Alojamiento gratuito de modelos para ti y tus usuarios.
• Versionado de archivos integrado, incluso para archivos enormes, hecho posible por Git-Xet.
• Funciones de la comunidad (discusiones, solicitudes de extracción, me gusta).
• Métricas de uso de todos los modelos ejecutados con tu biblioteca.

Este tutorial te ayudará a integrar el Hub en tu biblioteca para que tus usuarios se beneficien de todas las funciones que ofrece el Hub.

Antes de comenzar, te recomendamos crear una cuenta de Hugging Face desde la cual puedes gestionar tus repositorios y archivos.

Si necesitas ayuda con la integración, no dudes en abrir un issue y estaremos encantados de ayudarte.

Implementación

Implementar una integración de una biblioteca con el Hub suele implicar proporcionar métodos integrados para cargar modelos desde el Hub y permitir a los usuarios subir nuevos modelos al Hub. Esta sección cubrirá lo básico de cómo hacerlo utilizando la biblioteca huggingface_hub. Para una guía más detallada, consulta esta guía.

Instalación

Para integrar tu biblioteca con el Hub, debes añadir la biblioteca huggingface_hub como dependencia:

pip install huggingface_hub

Para más detalles sobre la instalación de huggingface_hub, consulta esta guía.

En esta guía nos centraremos en las bibliotecas de Python. Si has implementado tu biblioteca en JavaScript, puedes usar @huggingface/hub en su lugar. El resto de la lógica (es decir, alojar archivos, muestras de código, etc.) no depende del lenguaje de programación.

Copiado

npm add @huggingface/hub

Los usuarios deberán autenticarse una vez que hayan instalado correctamente la biblioteca huggingface_hub. La forma más sencilla de autenticarse es guardar el token en la máquina. Los usuarios pueden hacerlo desde la terminal usando el comando login():

hf auth login

El comando les indica si ya están iniciados y les solicita su token. A continuación, el token se valida y se guarda en su directorio HF_HOME (por defecto, ~/.cache/huggingface/token). Cualquier script o biblioteca que interactúe con el Hub utilizará este token al enviar solicitudes.

Alternativamente, los usuarios pueden iniciar sesión de forma programática usando login() en un cuaderno o un script:

from huggingface_hub import login
login()

La autenticación es opcional al descargar archivos de repositorios públicos en el Hub.

Descargar archivos del Hub

Las integraciones permiten a los usuarios descargar un modelo desde el Hub e instanciarlo directamente desde su biblioteca. Esto suele ser posible al proporcionar un método (generalmente llamado from_pretrained o load_from_hf) que debe ser específico de su biblioteca. Para instanciar un modelo desde el Hub, su biblioteca debe:

• descargar archivos del Hub. Esto es lo que discutiremos ahora.
• instanciar el modelo de Python a partir de estos archivos.

Use the hf_hub_download method to download files from a repository on the Hub. Los archivos descargados se almacenan en la caché: ~/.cache/huggingface/hub. Los usuarios no tendrán que volver a descargar el archivo la próxima vez que lo usen, lo que ahorra mucho tiempo en el caso de archivos grandes. Además, si el repositorio se actualiza con una nueva versión del archivo, huggingface_hub descargará automáticamente la versión más reciente y la almacenará en la caché. Los usuarios no tienen que preocuparse por actualizar sus archivos manualmente.

Por ejemplo, descargue el archivo config.json del repositorio lysandre/arxiv-nlp:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

Ahora, config_path contiene la ruta al archivo descargado. Se garantiza que el archivo existe y está actualizado.

Si su biblioteca necesita descargar un repositorio completo, use snapshot_download. Se encargará de descargar todos los archivos en paralelo. El valor de retorno es una ruta al directorio que contiene los archivos descargados.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

Existen muchas opciones para descargar archivos de una revisión específica, para filtrar qué archivos se descargan, para proporcionar un directorio de caché personalizado, para descargar a un directorio local, etc. Consulte la guía de descarga para más detalles.

Subir archivos al Hub

También puede ser útil que proporciones un método para que los usuarios puedan subir sus propios modelos al Hub. Esto permite a la comunidad construir un ecosistema de modelos compatibles con tu biblioteca. La biblioteca huggingface_hub ofrece métodos para crear repositorios y subir archivos:

• create_repo crea un repositorio en el Hub.
• upload_file y upload_folder suben archivos a un repositorio en el Hub.

El método create_repo crea un repositorio en el Hub. Use el parámetro repo_id para proporcionar un nombre a su repositorio:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

Cuando revises tu cuenta de Hugging Face, ahora deberías ver un repositorio test-model bajo tu espacio de nombres.

El método upload_file sube un archivo al Hub. Este método requiere lo siguiente:

• Una ruta al archivo que se va a subir.
• La ruta final en el repositorio.
• El repositorio al que desea enviar los archivos.

Por ejemplo:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Si revisas tu cuenta de Hugging Face, deberías ver el archivo dentro de tu repositorio.

Por lo general, una biblioteca serializa el modelo en un directorio local y luego sube a Hub la carpeta completa de una sola vez. Esto se puede hacer usando upload_folder:

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

Para más detalles sobre cómo subir archivos, consulta la guía de subida.

Tarjetas de modelos

Las tarjetas de modelo son archivos que acompañan a los modelos y proporcionan información útil. En el fondo, las tarjetas de modelo son simples archivos Markdown con metadatos adicionales. Las tarjetas de modelo son esenciales para la descubribilidad, la reproducibilidad y el intercambio. Puedes encontrar una tarjeta de modelo como el archivo README.md en cualquier repositorio de modelos. Consulta la guía de tarjetas de modelo para obtener más detalles sobre cómo crear una buena tarjeta de modelo.

Si su biblioteca permite subir un modelo al Hub, se recomienda generar una tarjeta de modelo mínima con metadatos predefinidos (típicamente library_name, pipeline_tag o tags) e información sobre cómo se ha entrenado el modelo. Esto ayudará a tener una descripción estandarizada para todos los modelos creados con su biblioteca.

Registra tu biblioteca

¡Bien hecho! Ahora deberías tener una biblioteca capaz de cargar un modelo desde el Hub y, eventualmente, subir nuevos modelos. El siguiente paso es asegurarse de que tus modelos en el Hub estén bien documentados e integrados con la plataforma. Para ello, las bibliotecas pueden registrarse en el Hub, lo que conlleva algunos beneficios para los usuarios:

• se puede mostrar una etiqueta legible en la página del modelo (p. ej. KerasNLP en lugar de keras-nlp)
• se añade un enlace a tu repositorio de biblioteca y a su documentación en cada página de modelo
• se puede definir una regla de recuento de descargas personalizada
• Se pueden generar fragmentos de código para mostrar cómo cargar el modelo usando su biblioteca

Para registrar una nueva biblioteca, abra una Pull Request aquí siguiendo las instrucciones a continuación:

• El id de la biblioteca debe estar en minúsculas y separado por guiones (ejemplo: "adapter-transformers"). Asegúrate de mantener el orden alfabético al abrir la PR.
• Establezca repoName y prettyLabel con una capitalización amigable para el usuario (ejemplo: DeepForest).
• Establezca repoUrl con un enlace al código fuente de la biblioteca (normalmente un repositorio de GitHub).
• (opcional) establece docsUrl con un enlace a la documentación de la biblioteca. Si la documentación está en el repositorio de GitHub al que se hace referencia anteriormente, no es necesario establecerla dos veces.
• Establezca filter en false.
• (opcional) definir cómo deben contarse las descargas estableciendo countDownload. Las descargas pueden rastrearse por extensiones de archivo o nombres de archivo. Asegúrese de no duplicar el conteo. Por ejemplo, si cargar un modelo requiere 3 archivos, la regla de conteo de descargas debe contar las descargas solo en 1 de los 3 archivos. De lo contrario, el conteo de descargas se sobreestimará. Nota: si la biblioteca utiliza uno de los archivos de configuración predeterminados (config.json, config.yaml, hyperparams.yaml, params.json y meta.yaml, ver aquí), no es necesario definir manualmente una regla de conteo de descargas.
• (opcional) definir snippets para que el usuario sepa cómo puede instanciar rápidamente un modelo. Más detalles a continuación.

Antes de abrir la PR, asegúrate de que al menos un modelo esté referenciado en https://huggingface.co/models?other=my-library-name. Si no es así, los metadatos de la tarjeta de los modelos correspondientes deben actualizarse con library_name: my-library-name (ver ejemplo). Si no eres el propietario de los modelos en el Hub, abre PRs (ver ejemplo).

Aquí hay un ejemplo mínimo que añade la integración para VFIMamba.

Fragmentos de código

Recomendamos añadir un fragmento de código para explicar cómo usar un modelo en tu biblioteca de nivel inferior.

Para añadir un fragmento de código, debes actualizar el archivo model-libraries-snippets.ts con las instrucciones para tu modelo. Por ejemplo, la integración de Asteroid incluye un breve fragmento de código sobre cómo cargar y usar un modelo de Asteroid:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

Al hacerlo, también se añadirá una etiqueta a tu modelo para que los usuarios puedan identificar rápidamente los modelos de tu biblioteca.

Una vez que tu fragmento se ha añadido a model-libraries-snippets.ts, puedes referenciarlo en model-libraries.ts tal como se describió anteriormente.

Documenta tu biblioteca

Por último, puedes añadir tu biblioteca a la documentación del Hub. Consulta, por ejemplo, el PR de Setfit que añadió SetFit a la documentación.