Hugging Face Spaces: qué es y cómo usarlo ?

#Hugging Face Spaces: ¿qué es exactamente?

Un Space es una pequeña aplicación web alojada por Hugging Face. Técnicamente, es un repositorio git, como los de los modelos y los conjuntos de datos del Hub: contiene el código de la aplicación, un archivo de dependencias y un README cuyo encabezado YAML describe la configuración. Con cada commit que se sube a ese repositorio, Hugging Face reconstruye y reinicia la aplicación. El visitante, en cambio, solo ve una página con campos, botones y un resultado.

Si estás descubriendo Hugging Face, ten clara la diferencia con una página de modelo: la página de modelo contiene archivos (pesos, tokenizador, configuración) que descargas; un Space ejecuta código en un servidor para mostrarte lo que sabe hacer el modelo. La guía «Hugging Face: c'est quoi, et comment s'en servir?» trata el Hub en general; aquí solo hablamos de los Spaces.

La documentación oficial ofrece tres tipos de Spaces, llamados SDK, que se eligen al crearlo:

Gradio

El caso más frecuente. Gradio es una biblioteca de Python que genera una interfaz web a partir de una función: un cuadro de texto como entrada, una imagen como salida, etc. La mayoría de las demos de LLM y de modelos de imagen son Spaces de Gradio.

Docker

El Space se construye a partir de un Dockerfile. Por tanto, puede ejecutar cualquier aplicación web: una interfaz de chat completa, un servidor de API o una herramienta escrita en un lenguaje distinto de Python.

Static HTML

Una simple página HTML, CSS y JavaScript, sin servidor de cómputo. Útil para documentación, una visualización o una demo que se ejecuta íntegramente en el navegador.

Cada Space tiene una dirección en el Hub, con el formato huggingface.co/spaces/propietario/nombre, y una dirección directa de la aplicación, con el formato propietario-nombre.hf.space. Los Spaces pueden ser públicos (código y aplicación visibles para todos), protegidos (código privado, aplicación accesible) o privados (reservados al propietario y a sus colaboradores).

#Paso 1: usar una demo en el navegador

Para probar un Space, en la mayoría de los casos no necesitas cuenta. La página principal de Spaces (huggingface.co/spaces) permite buscar por palabra clave o por tarea, y ordenar por tendencia o por número de «likes». Muchas páginas de modelos también muestran, en la columna derecha, la lista de Spaces que usan ese modelo.

1. 01
   Encontrar el Space adecuado

   Da preferencia a los Spaces publicados por el editor del modelo (la cuenta oficial de la organización) o con muchos seguidores. Un Space reciente de una cuenta desconocida puede funcionar perfectamente, pero no sabes qué hace su código con los datos que envías.
2. 02
   Leer el estado mostrado

   En la parte superior de la página, una insignia indica el estado: en ejecución (Running), en construcción (Building), en reposo (Sleeping), en pausa o con error. Un Space en reposo se reactiva al visitarlo, lo que puede tardar un momento mientras la aplicación se reinicia.
3. 03
   Lanzar una solicitud

   Rellena los campos y confirma. En un Space que comparte una GPU entre todos los visitantes, puede aparecer una cola de espera antes del procesamiento.
4. 04
   Comprobar qué estás probando

   Abre la pestaña Files para leer el archivo principal (a menudo app.py) y el README. Ahí verás qué modelo se carga, con qué precisión (FP16, cuantización de 4 bits…) y con qué parámetros. Una demo no siempre es la versión completa del modelo anunciado.

#Paso 2: llamar a un Space de Gradio por API

Un Space de Gradio no es solo una página web: también expone una API. El enlace «Use via API», en la parte inferior de la aplicación, muestra los endpoints disponibles y ejemplos de código. En Python, la biblioteca oficial gradio_client permite llamar a un Space como si fuera una función, lo que resulta práctico para probar un modelo con una serie de ejemplos sin hacer clic a mano.

pip install gradio_client

from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

Una vez que conoces los parámetros, el método client.predict() envía una solicitud con los argumentos esperados y un api_name indicado por view_api(). Las cuotas y colas del Space se aplican a estas llamadas igual que a las visitas desde el navegador: no es una solución para procesar grandes volúmenes. Para un Space privado o para identificarte (y aprovechar la cuota de ZeroGPU de tu cuenta), pasa un token de acceso de Hugging Face a Client().

#Paso 3: duplicar un Space

Duplicar un Space crea una copia completa en tu cuenta. Es útil para partir de una demo existente y modificarla, o para tener tu propia instancia sin compartir la cola de espera con todos los visitantes. Se hace desde el menú de tres puntos de la parte superior derecha de la página, opción «Duplicate this Space».

1. 01
   Elegir el propietario y el nombre

   La copia puede ir a tu cuenta personal o a una organización en la que tengas permisos de escritura.
2. 02
   Configurar la visibilidad

   La copia es privada por defecto. Déjala privada si piensas procesar en ella tus propios datos.
3. 03
   Elegir el hardware

   Por defecto, la copia se ejecuta en CPU Basic. Puedes elegir una GPU de pago en ese momento o más tarde en la configuración (Settings).
4. 04
   Configurar los secretos

   Las variables públicas del Space original se copian automáticamente. Los secretos (tokens, claves de API) nunca se copian: la interfaz te avisa si tienes que proporcionarlos. Sin ellos, la aplicación puede arrancar y luego fallar en la primera solicitud.

Por encima de CPU Basic, el hardware se factura por hora. Por ejemplo, la documentación indica 0,40 $ por hora para una NVIDIA T4 small, a fecha de 26/10/2026; la tabla completa y actualizada está en la página de precios de Hugging Face. Un Space de pago se puede pausar desde su configuración: el tiempo en pausa no se factura.

#Paso 4: ejecutar un Space de Hugging Face en local

Como el código de un Space público se puede leer y clonar, puedes ejecutarlo en tu propia máquina. Hay dos métodos: descargar la imagen Docker creada por Hugging Face o clonar el repositorio y lanzar la aplicación tú mismo.

#Método A: la imagen Docker del Space

La documentación indica que la mayoría de los Spaces se pueden ejecutar con Docker. El botón «Run with Docker», en el menú de la esquina superior derecha de la página del Space, muestra el comando exacto que debes copiar. Suele tener la siguiente forma, con la imagen alojada en el registro registry.hf.space:

docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

Copia siempre el comando que ofrece el botón en lugar de reconstruirlo: el nombre de la imagen, el comando de inicio y las posibles variables (opción -e, por ejemplo para un token HF_TOKEN) dependen del Space. Algunos Spaces exigen iniciar sesión en el registro con tu nombre de usuario de Hugging Face y un token de acceso como contraseña:

docker login registry.hf.space

Para que un contenedor use una tarjeta NVIDIA, Docker necesita NVIDIA Container Toolkit en la máquina host, y hay que añadir la opción --gpus all al comando docker run. Las imágenes están compiladas para la arquitectura x86_64 (linux/amd64): en un Mac con Apple Silicon, se ejecutan mediante emulación, sin acceso a la GPU del Mac. En ese caso, el método B suele ser más adecuado.

#Método B: clonar el repositorio y ejecutar la aplicación

El menú del Space también ofrece «Clone repository», por HTTPS o por SSH. Para un Space de Gradio, la secuencia clásica consiste en clonar, crear un entorno de Python aislado, instalar las dependencias listadas en requirements.txt y luego ejecutar el archivo principal:

git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

A continuación, Gradio muestra la dirección local de la interfaz, por defecto http://127.0.0.1:7860. Algunos puntos que debes comprobar antes de lanzarla:

Encabezado del README

Las claves sdk_version, app_file y a veces python_version indican la versión de Gradio, el archivo que se ejecuta y la versión de Python que se usan en línea. Instalar la misma versión de Gradio (pip install "gradio==X.Y.Z") evita muchos errores de interfaz.

Archivos voluminosos

Un Space puede contener archivos pesados almacenados mediante el sistema de almacenamiento del Hub. Si después de clonar algunos archivos aparecen como pequeños punteros de texto, instala la extensión de git recomendada por Hugging Face (git-xet o Git LFS) y vuelve a lanzar la descarga.

Decorador @spaces.GPU

Los Spaces ZeroGPU importan el módulo spaces y decoran sus funciones con @spaces.GPU. La documentación precisa que este decorador no tiene ningún efecto fuera de ZeroGPU: basta con instalar el paquete spaces (pip install spaces) para que el código se ejecute en tu propia GPU.

Secrets

Si el código lee variables de entorno (os.getenv), defínelas en tu terminal antes de ejecutar app.py. Un modelo con acceso restringido requiere un token de Hugging Face asociado a una cuenta que haya aceptado la licencia.

En un Space de Docker, el repositorio clonado contiene un Dockerfile: basta con docker build y luego docker run, publicando el puerto declarado en app_port en el README (7860 por defecto).

#Límites de los Hugging Face Spaces: cómputo y privacidad

Un Space es perfecto para una primera impresión. Para un uso habitual, sus limitaciones aparecen pronto. Las siguientes proceden de la documentación oficial consultada el 26/10/2026.

Hardware gratuito modesto

El hardware por defecto, CPU Basic, ofrece 2 vCPU, 16 GB de RAM y 50 GB de disco, sin GPU. Un LLM de varios miles de millones de parámetros funciona lento ahí, cuando cabe en memoria.

Disco no persistente

Los 50 GB de disco se borran al reiniciar. Los archivos subidos o generados no se conservan, salvo que el propietario haya configurado almacenamiento persistente.

Suspensión

En el hardware gratuito, un Space sin uso entra en reposo al cabo de un tiempo y debe reiniciarse en la siguiente visita. El propietario también puede pausarlo o incluso eliminarlo: una demo disponible hoy puede desaparecer mañana.

Cuotas de ZeroGPU

El tiempo de GPU diario está limitado por cuenta (ver más arriba) y, por defecto, cada solicitud está limitada a 60 segundos de GPU, salvo que el autor haya fijado una duración mayor. La cuota se restablece 24 horas después del primer uso.

Red restringida

Un Space solo puede establecer conexiones salientes por los puertos 80, 443 y 8080. Una aplicación que necesite conectarse a un servicio en otro puerto no funcionará tal cual.

En cuanto a la privacidad, la regla es sencilla: todo lo que escribes en un Space se envía a un servidor que ejecuta el código de otra persona. Ese código puede registrar las peticiones, transmitirlas a una API de terceros o conservar los archivos subidos mientras dure la sesión. En un Space público, puedes comprobarlo leyendo app.py; en un Space protegido, el código no es visible. Por tanto, no pegues en una demo documentos de clientes, datos personales, código propietario ni credenciales.

#Cuándo preferir la ejecución local

Lo más sensato es usar los Spaces para decidir y luego pasar a local para trabajar. Algunas situaciones en las que lo local gana claramente:

Datos sensibles

Contratos, historiales médicos, código de empresa: con un modelo local, nada sale de tu equipo.

Uso diario o intensivo

Las cuotas de ZeroGPU y las colas de espera hacen que un Space no sea adecuado para un uso intensivo. En local, el único límite es tu hardware.

Necesidad de estabilidad

Un Space puede cambiar de modelo o de versión, o desaparecer. Un modelo descargado y fijado da resultados reproducibles.

Integración en tus herramientas

Ollama expone una API local en http://localhost:11434, que pueden usar Open WebUI, scripts o automatizaciones, sin depender de un servicio remoto.

Por cierto, en el caso de un LLM, pasar a local no implica necesariamente clonar el Space. Muchas demos cargan el modelo completo en formato safetensors, en FP16: los pesos de un modelo 7B ocupan entonces unos 14 GB, más de lo que admite la mayoría de las tarjetas de consumo. La versión cuantizada del mismo modelo en formato GGUF, en Q4_K_M, requiere unos 5 GB de VRAM y funciona en una RTX 3060 de 12 GB. Lo más sencillo suele ser anotar el nombre del modelo que usa el Space, buscar su versión GGUF en el Hub e importarla en Ollama.

3B en Q4

unos 2 GB de VRAM

7B en Q4

aproximadamente 5 GB

14B en Q4

unos 9 GB (RTX 4070 de 12 GB)

32B en Q4

unos 19 GB (RTX 4090 24 GB o Mac M4 Pro con 24 a 48 GB de memoria unificada)

70B en Q4

aproximadamente 40 GB

#Solución de problemas

«Runtime error» en la página

El Space falló al iniciarse. La pestaña Logs, cuando está accesible, muestra la causa. Si el Space es de otra persona, solo puedes esperar, buscar otro Space o informar del problema en la pestaña Community.

Mensaje de cuota de GPU superada

Has agotado tu cuota diaria de ZeroGPU. Inicia sesión si aún no lo has hecho, espera al restablecimiento o ejecuta el modelo en local.

Error de import après pip install

La versión de Gradio o de alguna dependencia difiere de la del Space. Ajústate a sdk_version y python_version del README, en un entorno virtual nuevo.

CUDA no encontrado en local

El código espera una GPU NVIDIA. Comprueba que PyTorch se haya instalado con compatibilidad con CUDA, o adapta el código para usar la CPU (o mps en Mac), a costa de una ejecución más lenta.

Imagen Docker rechazada o no encontrada

Inicia sesión en el registro con docker login registry.hf.space y luego comprueba que el nombre de la imagen coincide con el que indica el botón «Run with Docker».

#Para ir más allá

Esta guía trata los Spaces. Para entender el Hub en su conjunto, distinguir los formatos de archivo o pasar de una demo a un modelo que se ejecute en tu equipo, estas guías toman el relevo.