Demos con Gradio: de una función de Python a una UI compartible

1. Por qué armar una demo

Una demo no es solo para mostrar — es una herramienta de trabajo: le permite a gente no técnica probar tu modelo sin tocar código, a vos encontrar fallos de forma interactiva mucho más rápido que revisando logs, y a cualquiera notar sesgos del modelo con inputs que vos nunca hubieras pensado probar.

Hay una cuarta razón, menos obvia: una demo es el contrato de entrada y salida de tu modelo hecho visible. Declarar "el input es un texto y la salida es una etiqueta con puntaje" te obliga a decidir el formato de salida antes de que alguien lo consuma — y ese formato es lo primero que vas a querer estabilizar cuando el modelo pase a producción.

2. Tu primera demo con Interface

Tres argumentos alcanzan para envolver cualquier función de Python en una UI web:

import gradio as gr

def saludar(nombre):
    return f"Hola {nombre}!"

gr.Interface(fn=saludar, inputs="text", outputs="text").launch()

fn es tu función de predicción; inputs/outputs declaran qué tipo de componente usar — texto, imagen, audio (como un array de NumPy), varios inputs o outputs a la vez. Los strings cortos ("text", "image", "audio") son atajos; la forma larga es instanciar el componente (gr.Textbox(lines=3, label="Prompt")) para controlar etiqueta, tamaño y valor inicial. Lo que fn devuelve tiene que ser del tipo que el componente de salida entiende:

Enchufar un modelo real es la misma idea, con fn llamando a un pipeline() del Capítulo 1 en vez de a un saludo. Fijate que el pipeline se crea una sola vez, fuera de fn: cargar el modelo es lo caro; fn se llama en cada click.

generator = pipeline("text-generation", model="HuggingFaceTB/SmolLM2-360M")   # una vez, al arrancar

def predict(prompt):
    return generator(prompt)[0]["generated_text"]   # en cada llamada: solo inferencia

gr.Interface(fn=predict, inputs="text", outputs="text").launch()

Si fn devuelve varias cosas, outputs es una lista de componentes y la función devuelve una tupla en el mismo orden. Un clasificador que además muestra las probabilidades:

clf = pipeline("sentiment-analysis")

def clasificar(texto):
    r = clf(texto, top_k=None)                      # todas las clases con su score
    return {d["label"]: d["score"] for d in r}  # gr.Label espera un dict etiqueta → prob

gr.Interface(fn=clasificar, inputs=gr.Textbox(lines=3, label="Reseña"), outputs=gr.Label(num_top_classes=2),
             title="Sentimiento", examples=[["Me encantó."], ["Una pérdida de tiempo."]]).launch()

3. Compartir: link temporal o Spaces

Antes de compartir, vale la pena pulir la demo: título, descripción, ejemplos precargados de input — todos argumentos directos de Interface, sin trabajo extra. Y para servir en tu propia red (o dentro de un contenedor) sin pasar por el túnel de Gradio, fijás dónde escucha el servidor:

demo.launch(server_name="0.0.0.0", server_port=7860)   # accesible desde otras máquinas de la red / desde fuera del contenedor

server_name="0.0.0.0" hace que escuche en todas las interfaces (por default solo en 127.0.0.1, es decir, solo tu máquina); server_port fija el puerto en vez de dejar que Gradio busque uno libre a partir del 7860. Es la forma de exponer una demo en un servidor propio — detrás de un proxy inverso o una VPN, no directo a internet.

4. Cargar directo desde el Hub

gr.load("models/usuario/modelo") arma la demo completa a partir de un modelo del Hub sin que escribas la función de predicción vos — Gradio infiere la tarea y el tipo de input/output a partir de la metadata del repo, y las predicciones se hacen contra la API de inferencia de Hugging Face, no en tu máquina. Lo mismo funciona apuntando a un Space existente, que podés cargar y hasta reusar como pieza dentro de una demo más grande:

import gradio as gr

demo = gr.load("models/distilbert/distilbert-base-uncased-finetuned-sst-2-english")   # un modelo del Hub
demo.launch()

demo2 = gr.load("spaces/gradio/hello_world")   # un Space entero, con su UI
demo2.launch()

5. State e interpretación

Por default, cada llamada a fn es independiente — no recuerda nada de la anterior. gr.State le da persistencia entre interacciones dentro de la misma sesión: el ingrediente mínimo para armar un chatbot, que necesita recordar los turnos anteriores de la conversación. La mecánica: el estado entra como un input más y sale como un output más, y Gradio se encarga de guardar el valor devuelto para la próxima llamada de ese usuario (cada pestaña del navegador tiene su propio estado; no se comparte entre usuarios).

def contar(mensaje, historial):
    historial = historial + [mensaje]
    return f"Llevás {len(historial)} mensajes. El último: {mensaje}", historial

gr.Interface(fn=contar,
             inputs=["text", gr.State([])],      # el estado entra como input…
             outputs=["text", gr.State()]).launch()  # …y sale como output, actualizado

Sobre interpretación: el curso original mostraba interpretation="default" (o "shap") como argumento de Interface, que resaltaba qué partes del input pesaron más en la predicción. Esa opción existió en Gradio 3 y fue eliminada en Gradio 4. La idea sigue siendo valiosa — no tratar al modelo como caja negra ni siquiera en la demo — pero hoy la interpretación se calcula aparte, con una librería de atribución como Captum o SHAP, y se muestra con un componente que sepa pintar puntajes por token, como gr.HighlightedText, dentro de un gr.Blocks. En la práctica: tu fn devuelve, además de la predicción, una lista de pares (token, puntaje), y el componente los colorea.

6. Blocks: la API de bajo nivel

Interface alcanza para "una función, unos inputs, unos outputs". Para layouts custom, demos de varios pasos, o actualizar un componente en respuesta a otro, gr.Blocks da control total sobre filas, columnas y qué evento dispara qué función — es, literalmente, la capa sobre la que está construido cualquier componente de más alto nivel de Gradio, incluido el ChatInterface moderno para chatbots.

El ejemplo mínimo que muestra la diferencia de modelo mental — los componentes se declaran dentro de un with, y los eventos se conectan explícitamente:

import gradio as gr

def invertir(texto):
    return texto[::-1]

with gr.Blocks() as demo:
    entrada = gr.Textbox(label="Texto")
    salida  = gr.Textbox(label="Al revés")
    boton   = gr.Button("Invertir")
    boton.click(fn=invertir, inputs=entrada, outputs=salida)   # evento → función → componente

demo.launch()

Tres cosas que Interface hacía por vos y acá decidís vos: qué dispara la función (un botón, entrada.submit al apretar Enter, entrada.change en cada tecla), qué componentes son inputs y cuáles outputs (cualquiera puede ser ambos), y el layout (gr.Row() y gr.Column() como contextos anidados). Un mismo botón puede disparar varias funciones encadenadas con .then(), que es como se arman los flujos de "primero valido, después genero, después muestro".

7. ChatInterface contra un servidor vLLM

El caso de uso más común de Gradio en 2026 es un chat sobre un LLM, y el patrón que recomienda la sección 4 — la UI en un proceso, el modelo en otro — se escribe en veinte líneas. Del lado del modelo, vLLM expone un servidor compatible con la API de OpenAI:

vllm serve google/gemma-4-E2B-it --port 8000   # en otra terminal, o en otro contenedor / máquina

Del lado de la UI, gr.ChatInterface solo necesita una función fn(message, history). Si esa función usa yield en vez de return, Gradio muestra el texto a medida que llega — streaming, sin configurar nada más. El cliente openai con base_url apuntando a vLLM hace el resto:

import gradio as gr
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")   # vLLM no valida la key por default
MODEL = "google/gemma-4-E2B-it"
SYSTEM = "Respondés en español rioplatense, corto y directo."

def responder(message, history):
    # con type="messages", history ya viene como lista de {"role", "content"} (puede traer claves extra: las filtramos)
    messages = [{"role": "system", "content": SYSTEM}]
    messages += [{"role": m["role"], "content": m["content"]} for m in history]
    messages.append({"role": "user", "content": message})

    stream = client.chat.completions.create(model=MODEL, messages=messages, stream=True, temperature=0.7)
    parcial = ""
    for chunk in stream:
        parcial += chunk.choices[0].delta.content or ""
        yield parcial          # cada yield reemplaza el mensaje en pantalla con el texto acumulado

demo = gr.ChatInterface(fn=responder, type="messages", title="Chat sobre vLLM")
demo.launch(server_name="0.0.0.0", server_port=7860)

Tres detalles que hacen que esto funcione y no sean obvios:

• yield parcial, no yield delta: Gradio muestra lo último que yieldeaste, no lo concatena. Si yieldeás solo el fragmento nuevo, ves palabras sueltas parpadeando.
• type="messages": hace que history llegue como lista de diccionarios con role/content, el mismo formato del chat template del Capítulo 11 y de la API de OpenAI. El formato viejo (lista de pares [usuario, bot]) sigue existiendo pero obliga a convertir.
• El chat template lo aplica vLLM, no vos: le mandás mensajes con roles y el servidor los formatea con el template del modelo. Es la razón de fondo para no concatenar strings a mano.

Si el servidor se cae, la demo sigue viva y el próximo mensaje falla con un error de conexión — que es exactamente lo que querés: reiniciás vLLM sin tocar la UI. Y si mañana el modelo es otro, cambiás MODEL y nada más.

8. Errores comunes

Las demos fallan de formas repetitivas. Casi todas se ven en la consola donde corre launch(), no en el navegador.

9. Resumen

1. Interface(fn, inputs, outputs) envuelve cualquier función de Python en una UI web en minutos — y el tipo que fn devuelve tiene que coincidir con lo que el componente de salida espera.
2. Compartir es un link de una semana (share=True, un túnel hacia tu proceso) para algo rápido, o un Space permanente para publicar en serio; server_name/server_port es la forma de servir en tu propia red.
3. gr.load("models/…") o gr.load("spaces/…") arma la demo sola a partir del Hub (la forma Interface.load era de Gradio 3) — hoy, para LLMs, mejor apuntando a un servidor de inferencia separado que cargando el modelo en el proceso de la UI.
4. State es lo mínimo que necesitás para recordar entre llamadas; la interpretación integrada de Gradio 3 ya no existe y se arma aparte con Captum/SHAP más un componente que pinte atribuciones.
5. Blocks es lo que necesitás para cualquier cosa más compleja que una función aislada: componentes declarados, eventos conectados a mano con .click/.submit/.then.
6. ChatInterface + cliente openai con base_url + yield es el patrón completo para un chat con streaming sobre vLLM: la UI en un proceso, el modelo en otro.

10. Ponete a prueba

Respondé antes de abrir cada respuesta. Si fallás una, volvé a la sección indicada.

11. Para practicar

import gradio as gr

POS = {"bueno", "excelente", "genial", "encantó"}
NEG = {"malo", "horrible", "pérdida", "aburrido"}

def clasificar(texto):
    palabras = texto.lower().split()
    p = sum(w.strip(".,!") in POS for w in palabras)
    n = sum(w.strip(".,!") in NEG for w in palabras)
    total = p + n or 1
    return {"positivo": p / total, "negativo": n / total}   # probá cambiar esto por return "positivo"

gr.Interface(fn=clasificar, inputs=gr.Textbox(lines=2), outputs=gr.Label(num_top_classes=2),
             examples=[["Excelente, me encantó."], ["Horrible y aburrido."]]).launch(server_port=7860)

def clasificar2(texto):
    scores = clasificar(texto)
    return scores, {"palabras": len(texto.split()), "scores": scores}

with gr.Blocks() as demo:
    with gr.Row():
        entrada = gr.Textbox(label="Reseña", lines=2)
        with gr.Column():
            etiqueta = gr.Label(num_top_classes=2)
            detalle  = gr.JSON(label="Detalle")
    boton = gr.Button("Clasificar")
    boton.click(clasificar2, inputs=entrada, outputs=[etiqueta, detalle])
    entrada.submit(clasificar2, inputs=entrada, outputs=[etiqueta, detalle])

demo.launch()

import time, gradio as gr

def falso_llm(message, history):
    respuesta = f"Recibí «{message}». Llevamos {len(history)} mensajes previos en esta sesión."
    parcial = ""
    for palabra in respuesta.split():
        parcial += palabra + " "
        time.sleep(0.15)
        yield parcial          # cambiá por `yield palabra` para ver el bug de §8

gr.ChatInterface(fn=falso_llm, type="messages").launch()

12. Fuentes y para seguir

• LLM Course, Chapter 9 — Building and sharing demos — el capítulo original; tené presente que su código es de la era Gradio 3 (Interface.load, interpretation, link de 72 horas).
• Gradio — Documentación — la referencia de cada componente con los tipos exactos que recibe y devuelve; es la tabla de §2 completa.
• Gradio — Creating a chatbot fast — la guía oficial de ChatInterface, incluido streaming con yield y el formato type="messages".
• Gradio — Using Hugging Face integrations — gr.load() con models/ y spaces/, y cómo combinar demos cargadas.
• vLLM — OpenAI-Compatible Server — qué endpoints expone vllm serve y qué parámetros acepta; lo que hay del otro lado del base_url de §7.
• Captum — atribución para modelos PyTorch; el reemplazo actual de la interpretación integrada que tenía Gradio 3.