Introducción

El Hugging Face Hub es el lugar de referencia para compartir modelos de aprendizaje automático, demos, conjuntos de datos y métricas. La biblioteca huggingface_hub te permite interactuar con el Hub sin salir de tu entorno de desarrollo. Puedes crear y gestionar repositorios fácilmente, descargar y subir archivos, y obtener metadatos útiles de modelos y conjuntos de datos desde el Hub.

Instalación

Para empezar, instala la biblioteca huggingface_hub:

pip install --upgrade huggingface_hub

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

El huggingface_hub también incluye una CLI hf que te permite interactuar con el Hub directamente desde la terminal. Si estás usando agentes de IA (Claude Code, Codex, Cursor, …), instala la Skill para que tu agente use la CLI:

Copiado

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Consulte la guía Hugging Face CLI for AI Agents para obtener más detalles.

Descargar archivos

Los repositorios en el Hub están controlados por versiones con git, y los usuarios pueden descargar un archivo individual o el repositorio completo. Puedes usar la función hf_hub_download() para descargar archivos. Esta función descarga y almacena en caché un archivo en tu disco local. La próxima vez que necesites ese archivo, se cargará desde tu caché, por lo que no tendrás que volver a descargarlo.

Necesitarás el id del repositorio y el nombre del archivo que deseas descargar. Por ejemplo, para descargar el archivo de configuración del modelo Pegasus:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Para descargar una versión específica del archivo, use el parámetro revision para especificar el nombre de la rama, la etiqueta o el hash de commit. Si elige usar el hash de commit, debe ser el hash de longitud completa en lugar del hash de commit corto de 7 caracteres:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Para más detalles y opciones, consulte la referencia de la API de hf_hub_download().

Autenticación

En muchos casos, debes estar autenticado con una cuenta de Hugging Face para interactuar con el Hub: descargar repositorios privados, subir archivos, crear PR, etc. Crea una cuenta si aún no tienes una.

Comando de inicio de sesión

La forma más sencilla de autenticarse es con el comando login():

hf auth login

Si ya has iniciado sesión, el comando se ejecutará de inmediato. Para forzar un nuevo inicio de sesión, usa hf auth login --force. Si no has iniciado sesión, se te pedirá que lo hagas con tu navegador: abre la URL impresa, introduce el código corto, aprueba la solicitud y se obtendrá un token de acceso que se guardará en tu directorio HF_HOME (por defecto, ~/.cache/huggingface/token). El token caduca después de un tiempo, pero se actualiza automáticamente siempre que sigas usándolo. Cualquier script o biblioteca que interactúe con el Hub utilizará este token al enviar solicitudes. Alternativamente, puedes pegar un User Access Token generado desde tu página de configuración.

Los tokens de acceso de usuario pueden tener permisos de read o write. Asegúrate de tener un token de acceso con write si deseas crear o editar un repositorio. De lo contrario, es mejor generar un token de read para reducir el riesgo en caso de que tu token se filtre accidentalmente.

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

>>> from huggingface_hub import login
>>> login()

Solo puedes iniciar sesión en una cuenta a la vez. Al iniciar sesión en una cuenta nueva, se cerrará automáticamente la sesión de la cuenta anterior. Para determinar tu cuenta activa actual, simplemente ejecuta el comando hf auth whoami.

Una vez que has iniciado sesión, todas las solicitudes al Hub, incluso los métodos que no requieren autenticación, usarán tu token de acceso de forma predeterminada. Si deseas deshabilitar el uso implícito de tu token, debes establecer HF_HUB_DISABLE_IMPLICIT_TOKEN=1 como variable de entorno (consulta la referencia).

Gestionar varios tokens localmente

Puedes guardar varios tokens en tu máquina simplemente iniciando sesión con el comando login() para cada token. Si necesitas cambiar entre estos tokens localmente, puedes usar el comando auth switch:

hf auth switch

Este comando te pedirá que selecciones un token por su nombre a partir de una lista de tokens guardados. Una vez seleccionado, el token elegido se convierte en el token activo y se utilizará para todas las interacciones con el Hub.

Puedes listar todos los tokens de acceso disponibles en tu máquina con hf auth list.

Variable de entorno

La variable de entorno HF_TOKEN también se puede utilizar para autenticarse. Esto resulta especialmente útil en un Space, donde se puede establecer HF_TOKEN como secreto del Space.

NUEVO: Google Colaboratory te permite definir claves privadas para tus cuadernos. Define un secreto HF_TOKEN para autenticarte automáticamente.

La autenticación mediante una variable de entorno o un secreto tiene prioridad sobre el token almacenado en su máquina.

Parámetros del método

Por último, también es posible autenticarse pasando su token a cualquier método que acepte token como parámetro.

from huggingface_hub import whoami

user = whoami(token=...)

Esto suele desaconsejarse, excepto en un entorno donde no se desee almacenar el token de forma permanente o si se necesita manejar varios tokens a la vez.

Tenga cuidado al pasar tokens como parámetro. La mejor práctica es siempre cargar el token desde un almacén seguro en lugar de codificarlo directamente en su base de código o cuaderno. Los tokens codificados directamente representan un riesgo importante de fuga si comparte su código de manera inadvertida.

Crear un repositorio

Una vez que te hayas registrado e iniciado sesión, crea un repositorio con la función create_repo():

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Si quieres que tu repositorio sea privado, entonces:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Los repositorios privados no serán visibles para nadie excepto para ti.

Para crear un repositorio o enviar contenido al Hub, debe proporcionar un User Access Token que tenga el permiso write. Puede elegir el permiso al crear el token en su página de configuración.

Subir archivos

Use la función upload_file() para añadir un archivo a su recién creado repositorio. Debe especificar:

1. La ruta del archivo a subir.
2. La ruta del archivo en el repositorio.
3. El id del repositorio donde deseas agregar el archivo.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Para subir más de un archivo a la vez, consulta la guía de Upload, que te presentará varios métodos para subir archivos (con o sin git).

Próximos pasos

La biblioteca huggingface_hub ofrece una forma sencilla para que los usuarios interactúen con el Hub en Python. Para saber más sobre cómo puedes gestionar tus archivos y repositorios en el Hub, te recomendamos leer nuestras guías de uso para:

• Gestiona tu repositorio.
• Descargar archivos del Hub.
• Sube archivos al Hub.
• Busca en el Hub el modelo o conjunto de datos que desees.
• Ejecutar inferencia en varios servicios para modelos alojados en el Hugging Face Hub.