Esta guía se basa en la CLI de Hugging Face desde la versión 0.34.4. En esta versión la sintaxis antigua huggingface-cli se sustituye por el nuevo comando hf. He creado este recordatorio para tener una referencia breve y clara de la CLI de Hugging Face. En lugar de buscar en la documentación oficial, aquí encuentro los comandos, descripciones y ejemplos más importantes de un vistazo.
¿Qué es Hugging Face?
Hugging Face es una plataforma de aprendizaje automático. En el centro está el Hugging Face Hub, un repositorio público y privado para modelos de IA, conjuntos de datos y aplicaciones (Spaces). Desarrolladoras y desarrolladores pueden compartir, descargar y reutilizar modelos allí. Además del Hub, Hugging Face ofrece bibliotecas como transformers, datasets y diffusers, que facilitan el uso práctico de modelos de IA. El Hub funciona tanto como mercado como infraestructura para el desarrollo colaborativo.
¿Qué es la CLI de Hugging Face?
La CLI de Hugging Face es una herramienta de línea de comandos que te permite acceder directamente al Hub de Hugging Face. Con ella gestionas la autenticación, descarga, subida y administración de repositorios de modelos, conjuntos de datos y Spaces. La CLI utiliza internamente la biblioteca de Python huggingface_hub. Todo lo que puedes hacer con esta biblioteca a menudo también puede hacerse con la CLI de forma scriptable.
| Comando hf | Descripción | Ejemplo de uso |
|---|---|---|
| hf auth login | Autenticación en Hugging Face con un token de acceso personal. El comando guarda el token localmente en la caché y (opcionalmente) en el administrador de credenciales de Git. | - |
| hf auth whoami | Muestra la cuenta actualmente autenticada. | - |
| hf auth logout | Desautenticación. Elimina el token del almacenamiento local. | - |
| hf cache scan | Muestra los modelos, conjuntos de datos, etc., que están almacenados en caché localmente, junto con sus tamaños, número de archivos y rutas. | - |
| hf cache delete | Ofrece la opción de eliminar versiones en caché de forma interactiva (TUI) o mediante selección de archivos. | - |
| hf download | Descarga archivos o repositorios del Hub y los guarda en la caché local. | hf download meta-llama/Llama-3.1-8B-Instruct –local-dir ./llama3-8b |
| hf upload | hf upload sube un único archivo a un repositorio en el Hugging Face Hub que hayas creado. Este repositorio pertenece ya sea a tu cuenta de usuario o a una organización de la que eres miembro. Tú decides si es público o privado. Si la subida se interrumpe, debes volver a subir el archivo. hf upload está pensado para archivos pequeños o para unos pocos archivos. | Repositorio de ejemplo: https://huggingface.co/ |
| hf upload-large-folder | Sube carpetas completas; admite reanudar la transferencia en caso de interrupción. | hf upload-large-folder –repo-id [dein-username]/[mein-repository-name] [folder_path] p. ej. hf upload-large-folder –repo-id aaron/my-model ./training_output |
| hf lfs-multipart-upload | Con este comando se pueden subir archivos muy grandes de manera fiable, por ejemplo pesos de modelos o puntos de control de entrenamiento en el rango de decenas de gigabytes. El archivo se divide localmente en bloques de datos más pequeños. Cada bloque se transfiere de forma individual al repositorio de Hugging Face en el Hub y allí se recompone automáticamente en un archivo completo. La ventaja de esta técnica es que una subida interrumpida no tiene que comenzar desde cero. Los bloques ya subidos permanecen en el repositorio. Al reiniciar, la herramienta comprueba qué bloques faltan y sólo transfiere esos. De este modo, también es posible cargar archivos muy grandes de forma estable y sin repeticiones innecesarias en un repositorio. | hf lfs-multipart-upload –repo-id [dein-username]/[mein-repository-name] [file_path] p. ej. hf lfs-multipart-upload –repo-id aaron/my-model ./model.safetensors |
| hf lfs-enable-largefiles | Si trabajas con un repositorio en Hugging Face Hub usando Git y Git LFS, en tu carpeta local están todos los archivos, incluidos los grandes pesos del modelo. Al hacer push, Git distingue: archivos pequeños como una config.json se almacenan directamente en el historial de Git, mientras que archivos grandes como model.safetensors se sustituyen mediante Git LFS. En el historial queda sólo un puntero pequeño; los datos reales se guardan por separado en el almacenamiento LFS de Hugging Face. Al clonar o con hf download, el cliente primero descarga los punteros y luego los archivos completos desde ese almacenamiento LFS. GitHub funciona con el mismo principio. Allí también se externalizan los archivos grandes con Git LFS. Por defecto, el límite es de 100 MB por archivo. Todo lo que exceda no se puede hacer push directamente, por lo que Git LFS es necesario. Hugging Face está construido de forma similar, pero optimizado para modelos grandes. Archivos de varios gigabytes son comunes allí y Git LFS es la solución prevista. El comando hf lfs-enable-largefiles configura un repositorio clonado de Hugging Face para que los archivos grandes se gestionen automáticamente con Git LFS. Git LFS evita que los archivos grandes inflen el historial de Git y previene pushs fallidos. Sólo necesitas este comando si realmente trabajas con Git en el repositorio, es decir, clonas, haces commits y pushes. Si subes archivos únicamente con hf upload o hf upload-large-folder, no es necesario. | En el repositorio clonado: hf lfs-enable-largefiles |
| hf repo create | Crea un nuevo repositorio para modelo, conjunto de datos, Space, etc | hf repo create [dein-username]/[mein-repository-name] –type model p. ej. hf repo create aaron/my-model –type model |
| hf repo-files | Muestra la estructura (archivos) de un repositorio | hf repo-files [dein-username]/[mein-repository-name] p. ej. hf repo-files aaron/my-model |
| hf env | hf env ofrece una visión detallada de tu entorno de trabajo local. Incluye la versión instalada de huggingface_hub, el sistema operativo, la versión de Python, bibliotecas utilizadas como PyTorch o TensorFlow, así como las ubicaciones de la caché y de los tokens. La salida está pensada principalmente para fines de diagnóstico, por ejemplo, cuando informes de un problema en el repositorio de GitHub de Hugging Face o quieras revisar tu propia configuración | - |
| hf version | Muestra la versión instalada de hf (es decir, de huggingface_hub) | - |
| hf jobs | Gestión de jobs en el Hub: ejecutar scripts o contenedores Docker en Hugging Face (además de la CLI) | hf jobs run –flavor t4-small ubuntu nvidia-smi |