Hugging Face Login CLI: Tu Puerta de Entrada a Modelos de IA
Por Jake Morrison, Entusiasta de la Automatización de IA
El mundo de la IA se mueve rápido y acceder a modelos potentes es clave para mantenerse a la vanguardia. Hugging Face ha surgido como un centro central para el aprendizaje automático, ofreciendo un vasto repositorio de modelos preentrenados, conjuntos de datos y herramientas. Mientras que su interfaz web es excelente, para muchos desarrolladores de IA y entusiastas de la automatización, interactuar con Hugging Face directamente desde la interfaz de línea de comandos (CLI) es esencial. Este artículo te guiará a través de los pasos prácticos para usar el Hugging Face login CLI, haciendo que tus flujos de trabajo de IA sean más fluidos y eficientes.
¿Por Qué Usar el Hugging Face Login CLI?
Para la automatización, scripting y operaciones del lado del servidor, la CLI es el rey. Cuando estás implementando modelos en producción, ejecutando trabajos de entrenamiento en servidores remotos, o integrando modelos de Hugging Face en pipelines complejos, confiar en un navegador web no es práctico. El Hugging Face login CLI proporciona una manera segura y programática de autenticar tus scripts y aplicaciones, otorgándoles acceso a modelos privados, conjuntos de datos y funcionalidades de API.
Pensar en estos escenarios:
* **Implementación Automática de Modelos:** Tu pipeline de CI/CD necesita enviar un modelo afinado a tu repositorio privado de Hugging Face.
* **Inferencia por Lotes:** Estás ejecutando un script que procesa miles de entradas usando un modelo específico de Hugging Face, y ese modelo requiere autenticación.
* **Entrenamiento en Instancias en la Nube:** Tu script de entrenamiento en una instancia de AWS EC2 necesita descargar un conjunto de datos privado de Hugging Face antes de comenzar.
* **Descargas de Modelos por Script:** Quieres escribir un script para descargar automáticamente la versión más reciente de un modelo para el desarrollo local.
En todos estos casos, el Hugging Face login CLI es la herramienta que necesitas.
Requisitos Previos: Lo Que Necesitas Antes de Comenzar
Antes de que empecemos con los comandos, asegúrate de tener lo siguiente configurado:
* **Python Instalado:** Las bibliotecas de Hugging Face están basadas en Python. Necesitarás Python 3.7 o más reciente.
* **Gestor de Paquetes `pip`:** Esto generalmente viene con Python.
* **Cuenta de Hugging Face:** Necesitas una cuenta en huggingface.co. Si no tienes una, regístrate gratuitamente.
* **Conexión a Internet:** Para conectarte a Hugging Face.
Paso 1: Instala la Biblioteca `huggingface_hub` de Hugging Face
El núcleo de la interacción con Hugging Face desde Python y la CLI es la biblioteca `huggingface_hub`. Si no la tienes instalada, abre tu terminal o símbolo del sistema y ejecuta:
“`bash
pip install huggingface_hub
“`
Este comando descarga e instala los componentes necesarios. Es una buena práctica hacer esto dentro de un entorno virtual para mantener tus dependencias de proyecto aisladas.
“`bash
# Ejemplo usando un entorno virtual
python -m venv .venv
source .venv/bin/activate # En Windows: .venv\Scripts\activate
pip install huggingface_hub
“`
Una vez instalada, estás listo para usar el Hugging Face login CLI.
Paso 2: Genera Tu Token de Acceso de Hugging Face
El Hugging Face login CLI no usa tu nombre de usuario y contraseña normal directamente para autenticarse. En cambio, se basa en tokens de API (también llamados tokens de acceso o tokens de autenticación). Estos tokens son seguros, revocables y te permiten otorgar permisos específicos.
1. **Inicia sesión en Hugging Face:** Ve a huggingface.co e inicia sesión con tu cuenta.
2. **Navega a Configuración:** Haz clic en tu foto de perfil en la esquina superior derecha, luego selecciona “Configuración.”
3. **Ve a Tokens de Acceso:** En el menú de la izquierda, haz clic en “Tokens de Acceso.”
4. **Crea un Nuevo Token:** Haz clic en el botón “Nuevo token”.
5. **Configura Tu Token:**
* **Nombre:** Dale a tu token un nombre descriptivo (por ejemplo, “Token de Automatización CLI,” “Token de Mi Servidor”). Esto te ayudará a recordar su propósito.
* **Rol:** Esto es crucial.
* **`read`:** Permite descargar modelos y conjuntos de datos públicos, y leer información. Esto a menudo es suficiente para scripts de inferencia.
* **`write`:** Permite enviar modelos, conjuntos de datos y espacios, además de los permisos de `read`. Elige esto si tus scripts necesitan subir contenido.
* **`admin`:** Control total. Usa con precaución.
* Para la mayoría de las tareas de automatización, `read` o `write` serán suficientes. Comienza con el rol menos permisivo requerido.
6. **Genera y Copia:** Haz clic en “Generar un token.” Hugging Face mostrará tu nuevo token. **Copia este token inmediatamente!** Por razones de seguridad, solo se mostrará una vez. Si lo pierdes, tendrás que generar uno nuevo.
Mantén este token seguro. Trátalo como una contraseña. No lo codifiques directamente en repositorios públicos ni lo compartas innecesariamente.
Paso 3: Usando el Hugging Face Login CLI
Ahora que tienes tu token, puedes usar el Hugging Face login CLI para autenticar tu entorno. Abre tu terminal o símbolo del sistema.
El comando principal para la autenticación es `huggingface-cli login`.
“`bash
huggingface-cli login
“`
Cuando ejecutes este comando, la CLI te pedirá que pegues tu token:
“`
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_|_| _|_| _| _| _| _| _| _| _| _|_| _|
_|_|_|_| _|_|_| _| _| _| _| _| _| _| _| _|_|
_| _| _| _| _| _| _| _| _| _| _|
_| _| _|_| _|_| _|_|_| _|_|_| _|_|_| _| _|
Para más información sobre cómo obtener un token, por favor ve a https://huggingface.co/docs/hub/security-tokens
Token:
“`
Pega tu token de acceso copiado aquí y presiona Enter.
Si es exitoso, verás un mensaje como:
“`
El token ha sido guardado en /home/tuusuario/.cache/huggingface/token
Inicio de sesión exitoso
“`
Este mensaje confirma que tu token ha sido guardado en un archivo de caché local. El Hugging Face login CLI almacena este token de manera segura en el directorio de inicio de tu usuario (por ejemplo, `~/.cache/huggingface/token` en Linux/macOS, o `C:\Users\TuUsuario\.cache\huggingface\token` en Windows). Las operaciones posteriores que utilicen `huggingface_hub` en tu entorno usarán automáticamente este token almacenado para la autenticación.
Verificando Tu Inicio de Sesión
Puedes verificar que estás conectado intentando acceder a un recurso restringido o simplemente ejecutando:
“`bash
huggingface-cli whoami
“`
Este comando mostrará información sobre el usuario asociado con el token actualmente conectado, confirmando tu estado de autenticación.
Métodos de Autenticación Alternativos (Más Allá de `huggingface-cli login`)
Si bien `huggingface-cli login` es la forma más común de autenticar sesiones interactivas y desarrollo, hay otros métodos útiles para escenarios específicos.
1. Usando Variables de Entorno
Para entornos no interactivos como pipelines de CI/CD, contenedores de Docker o funciones en la nube, pasar el token a través de una variable de entorno es a menudo preferido. Esto evita escribir el token en un archivo en el entorno efímero.
Establece la variable de entorno `HF_TOKEN` antes de ejecutar tu script de Python o comando:
“`bash
export HF_TOKEN=”hf_TU_TOKEN_ACTUAL_AQUÍ”
# Ahora ejecuta tu script o cualquier comando huggingface_hub
python my_model_script.py
“`
En Windows:
“`cmd
set HF_TOKEN=”hf_TU_TOKEN_ACTUAL_AQUÍ”
python my_model_script.py
“`
La biblioteca `huggingface_hub` y los comandos del Hugging Face login CLI verifican automáticamente la variable de entorno `HF_TOKEN` si no se encuentra un token en la caché local.
2. Pasando el Token Directamente en Python
Si necesitas un control muy detallado o estás operando en un entorno donde establecer variables de entorno o usar el inicio de sesión de CLI no es viable, puedes pasar el token directamente a las funciones de `huggingface_hub` en tu código Python.
“`python
from huggingface_hub import HfApi
# ADVERTENCIA: Evita codificar tokens directamente en código de producción.
# Usa variables de entorno o un sistema seguro de gestión de configuraciones en su lugar.
token = “hf_TU_TOKEN_ACTUAL_AQUÍ”
api = HfApi(token=token)
# Ejemplo: Lista tus modelos privados
private_models = api.list_models(author=”tu_nombre_de_usuario”, private=True)
for model in private_models:
print(model.modelId)
# Ejemplo: Descarga un modelo privado
from transformers import AutoModelForSequenceClassification, AutoTokenizer
model_name = “tu_nombre_de_usuario/tu_modelo_privado”
tokenizer = AutoTokenizer.from_pretrained(model_name, token=token)
model = AutoModelForSequenceClassification.from_pretrained(model_name, token=token)
“`
Nota el argumento `token=token` en el constructor de `HfApi` y las llamadas a `from_pretrained`. Esto le indica explícitamente a las funciones qué token usar para esa operación específica.
Casos de Uso Comunes Después del Hugging Face Login CLI
Una vez que has autenticado con el Hugging Face login CLI, desbloqueas una gama de capacidades poderosas.
Descargando Modelos y Conjuntos de Datos Privados
Si tienes modelos o conjuntos de datos privados en Hugging Face, o si necesitas acceder a modelos restringidos que requieren aceptar términos, la autenticación es obligatoria.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
# Suponiendo que ya has ejecutado ‘huggingface-cli login’ o configurado HF_TOKEN
model_name = “your_org/your_private_model” # O un modelo restringido como meta-llama/Llama-2-7b-hf
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
print(f”Cargado exitosamente {model_name}”)
“`
La función `from_pretrained` recuperará automáticamente el token guardado por el CLI de inicio de sesión de Hugging Face.
Subiendo Modelos y Conjuntos de Datos
Si tu flujo de trabajo implica ajustar modelos y luego enviarlos de vuelta a Hugging Face, necesitarás un token con permisos de `write`.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import Dataset
# Suponiendo que has ajustado un modelo y tienes un tokenizer
# model = your_fine_tuned_model
# tokenizer = your_tokenizer
# Define el ID de tu repositorio (por ejemplo, “your_username/your_new_model”)
repo_id = “your_username/my-finetuned-model”
# Envía el modelo y el tokenizer
model.push_to_hub(repo_id)
tokenizer.push_to_hub(repo_id)
print(f”Modelo y tokenizer enviados a {repo_id}”)
# Ejemplo para conjuntos de datos
# my_dataset = Dataset.from_dict({“text”: [“hello”, “world”]})
# my_dataset.push_to_hub(“your_username/my-new-dataset”)
“`
Los métodos `push_to_hub` también usarán el token proporcionado por el CLI de inicio de sesión de Hugging Face.
Gestionando Tus Tokens
Periódicamente, podrías necesitar gestionar tus tokens de acceso.
* **Revocando Tokens:** Si un token está comprometido o ya no es necesario, ve a la configuración de “Access Tokens” de Hugging Face y elimínalo. Esto invalida el token de inmediato.
* **Listando Tokens:** Desde el CLI, no puedes listar directamente *todos* tus tokens desde tu cuenta, pero puedes ver qué token está activo actualmente en tu entorno usando `huggingface-cli whoami`.
Resolviendo Problemas Comunes
A veces las cosas no salen como se planean. Aquí hay algunos problemas comunes y sus soluciones al usar el CLI de inicio de sesión de Hugging Face.
* **”Token inválido” o “Error de autenticación”:**
* **Errores tipográficos:** Verifica que hayas copiado y pegado el token correctamente. No debe haber espacios ni caracteres adicionales.
* **Token expirado:** Aunque los tokens de Hugging Face no suelen expirar por defecto, asegúrate de que no haya sido revocado manualmente.
* **Rol incorrecto:** ¿El rol del token (`read`, `write`) es suficiente para la operación que intentas realizar? Por ejemplo, un token `read` no puede enviar modelos.
* **”Comando no encontrado: huggingface-cli”:**
* **Instalación:** Asegúrate de que `huggingface_hub` está instalado (`pip install huggingface_hub`).
* **PATH:** Asegúrate de que el directorio de tus scripts de Python esté en el PATH de tu sistema. Si estás en un entorno virtual, actívalo.
* **”Inicio de sesión exitoso” pero aún así recibes errores:**
* **Entornos diferentes:** ¿Estás ejecutando tu script en el *mismo* entorno donde ejecutaste `huggingface-cli login`? Si cambias de entornos virtuales o sesiones SSH, el token podría no ser recuperado automáticamente.
* **Prioridad de Variable de Entorno:** Si también estás configurando `HF_TOKEN` como una variable de entorno, eso podría tener prioridad sobre el token en caché.
* **Corrupción de Caché:** En casos raros, el archivo de caché del token podría corromperse. Puedes intentar eliminar el archivo (`~/.cache/huggingface/token`) y ejecutar `huggingface-cli login` nuevamente.
* **Problemas con Proxy:** Si estás detrás de un proxy corporativo, es posible que necesites configurar la configuración del proxy para `pip` y potencialmente para `huggingface_hub` si tiene problemas de conexión. Esto generalmente se hace a través de variables de entorno como `HTTP_PROXY` y `HTTPS_PROXY`.
Mejores Prácticas de Seguridad para el CLI de Inicio de Sesión de Hugging Face
* **Mínimos Privilegios:** Siempre crea tokens con los permisos mínimos necesarios (`read` vs. `write`).
* **Nombrado de Tokens:** Da nombres descriptivos a tus tokens para saber para qué se utilizan.
* **Rotar Tokens:** Para aplicaciones críticas, considera rotar tus tokens periódicamente.
* **Variables de Entorno para Producción:** Nunca codifiques tokens en tu código, especialmente en producción. Utiliza variables de entorno (`HF_TOKEN`) o un sistema de gestión de secretos.
* **Almacenamiento Seguro:** El CLI de inicio de sesión de Hugging Face almacena el token en el directorio de caché de tu usuario. Asegúrate de que este directorio esté protegido por permisos estándar del sistema de archivos.
* **Evitar Root:** No ejecutes `huggingface-cli login` como usuario root, a menos que sea absolutamente necesario, y comprende las implicaciones de seguridad.
Conclusión
El CLI de inicio de sesión de Hugging Face es una herramienta fundamental para cualquier persona que busque integrar modelos y conjuntos de datos de Hugging Face en sus flujos de trabajo automatizados. Al comprender cómo generar tokens de API, usar el comando `huggingface-cli login` y métodos de autenticación alternativos como las variables de entorno, puedes simplificar tus procesos de desarrollo y despliegue de IA. Aprovecha el CLI por su eficiencia y poder, y desbloquea todo el potencial de Hugging Face en tus proyectos.
—
FAQ
Q1: ¿Para qué sirve el comando `huggingface-cli login`?
El comando `huggingface-cli login` se utiliza para autenticar tu entorno local con Hugging Face Hub. Te solicita un token de acceso (que generas en el sitio web de Hugging Face) y luego guarda de forma segura este token en un archivo de caché local. Esto permite que tus scripts de Python y otras operaciones de `huggingface_hub` accedan a modelos y conjuntos de datos privados, o realicen acciones como enviar modelos sin necesidad de volver a ingresar tu token cada vez.
Q2: ¿Dónde consigo el token necesario para `huggingface-cli login`?
Generas el token desde la configuración de tu cuenta de Hugging Face. Inicia sesión en huggingface.co, ve a tu “Configuración,” luego navega a “Access Tokens.” Haz clic en “Nuevo token,” asígnale un nombre, selecciona el rol apropiado (por ejemplo, `read` o `write`), y generalo. Recuerda copiar el token inmediatamente ya que solo se muestra una vez.
Q3: ¿Qué pasa si no quiero usar `huggingface-cli login`? ¿Puedo seguir autenticándome?
Sí, tienes un par de alternativas. Para entornos no interactivos como pipelines de CI/CD o contenedores de Docker, puedes establecer la variable de entorno `HF_TOKEN` con tu token de acceso. La biblioteca `huggingface_hub` lo recogerá automáticamente. Alternativamente, puedes pasar el argumento `token` directamente a las funciones de `huggingface_hub` (por ejemplo, `HfApi(token=”your_token”)` o `AutoTokenizer.from_pretrained(…, token=”your_token”)`) en tu código Python, aunque esto generalmente se desaconseja por razones de seguridad en producción.
Q4: Mi `huggingface-cli login` funcionó, pero mi script aún no puede acceder a un modelo privado. ¿Qué está mal?
Hay algunas posibilidades. Primero, asegúrate de que el token que usaste tenga los permisos correctos (por ejemplo, un rol `read` para descargar). Segundo, verifica que tu script se esté ejecutando en el *mismo* entorno (por ejemplo, el mismo entorno virtual o sesión de usuario) en el que ejecutaste `huggingface-cli login`. Si también estás estableciendo la variable de entorno `HF_TOKEN`, eso podría sobrescribir el token en caché, así que revisa su valor. Por último, verifica nuevamente el ID del repositorio del modelo para asegurarte de que sea correcto y que tu cuenta tenga acceso a él.
🕒 Published: