# Introducción El [Hugging Face Hub](https://huggingface.co/) 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`: ```bash pip install --upgrade huggingface_hub ``` Para más detalles, consulta la guía de [instalación](installation). > [!TIP] > El `huggingface_hub` también incluye una [CLI `hf`](./guides/cli) 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 utilice la CLI: > ```bash > # 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](https://huggingface.co/docs/hub/agents-cli) 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.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 es necesario volver a descargarlo. Necesitarás el identificador del repositorio y el nombre del archivo que deseas descargar. Por ejemplo, para descargar el archivo de configuración del modelo [Pegasus](https://huggingface.co/google/pegasus-xsum): ```py >>> 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 y no el hash de commit corto de 7 caracteres: ```py >>> 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/file_download#huggingface_hub.hf_hub_download). ## Autenticación En muchos casos, es necesario estar autenticado con una cuenta de Hugging Face para interactuar con el Hub: descargar repositorios privados, subir archivos, crear PR, etc. [Crea una cuenta](https://huggingface.co/join) si aún no tienes una. ### Comando de inicio de sesión La forma más sencilla de autenticarse es con el comando [login()](/docs/huggingface_hub/v2.4.0/es/package_reference/authentication#huggingface_hub.login): ```bash 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](https://huggingface.co/docs/hub/security-tokens) generado desde tu [página de configuración](https://huggingface.co/settings/tokens). > [!TIP] > 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/authentication#huggingface_hub.login) en un cuaderno o un script: ```py >>> 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`. > [!WARNING] > 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](../package_reference/environment_variables#hfhubdisableimplicittoken)). ### Gestionar varios tokens localmente Puedes guardar varios tokens en tu máquina simplemente iniciando sesión con el comando [login()](/docs/huggingface_hub/v2.4.0/es/package_reference/authentication#huggingface_hub.login) para cada token. Si necesitas cambiar entre estos tokens localmente, puedes usar el comando `auth switch`: ```bash 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](https://huggingface.co/docs/hub/spaces-overview#managing-secrets). > [!TIP] > **NUEVO:** Google Colaboratory te permite definir [claves privadas](https://twitter.com/GoogleColab/status/1719798406195867814) 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. > [!WARNING] > 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.create_repo): ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` Si quieres que tu repositorio sea privado, entonces: ```py >>> 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. > [!TIP] > 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](https://huggingface.co/settings/tokens). ## Subir archivos Use la función [upload_file()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.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. ```py >>> 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](./guides/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 mediante 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](./guides/overview) para: - [Gestiona tu repositorio](./guides/repository). - [Descargar](./guides/download) archivos del Hub. - [Sube](./guides/upload) archivos al Hub. - [Busca en el Hub](./guides/search) el modelo o conjunto de datos que desees. - [Ejecutar inferencia](./guides/inference) en varios servicios para modelos alojados en el Hugging Face Hub.