Módulo 6: Modal — Deployment serverless de LLMs

Setup de cuenta y CLI

Siguiente →

Antes de poder deployar un LLM a Modal, necesitas tres cosas funcionando: una cuenta, la CLI instalada en tu máquina, y un token que las conecte. En esta cápsula vas a tener las tres listas y vas a verificarlas corriendo una función remota trivial.

Al terminar vas a poder:

  • Crear tu cuenta de Modal y entender qué te dan los créditos iniciales
  • Instalar y autenticar la CLI desde tu terminal
  • Ejecutar una función Python en la nube de Modal con un solo comando
  • Diagnosticar los errores más comunes de setup (token, versión, autenticación)

¿Por qué importa esta cápsula?

Es la única cápsula del módulo que no es estrictamente "AI". Setup parece aburrido, pero el 90% de los problemas que verás en las cápsulas siguientes vienen de un setup mal hecho: un token expirado, una versión vieja de la CLI, una variable de entorno olvidada.

Hacerlo bien acá te ahorra horas de debugging más adelante.

Paso 1 — Crear la cuenta

Modal usa autenticación con GitHub o Google. No hay flujo de email/password tradicional.

  1. Abre modal.com/signup
  2. Elige "Sign up with GitHub" (recomendado si planeas usar Modal en proyectos open-source) o "Sign up with Google"
  3. Autoriza el acceso (lectura de tu email; no pide repos privados)
  4. Verifica el email si te lo pide

Al crear la cuenta recibes créditos gratuitos (a inicios de 2026 son $30/mes recurrentes en el free tier, suficientes para todo este módulo y experimentos personales). Los créditos se renuevan cada mes calendario. Si los agotas, tu cuenta no se bloquea — simplemente no puedes ejecutar más hasta el próximo ciclo o hasta que agregues método de pago.

Verificación visual: después de signup, deberías ver el dashboard en https://modal.com/apps (vacío, todavía no hay apps).

Paso 2 — Instalar la CLI

Modal se administra desde Python. La CLI viene como parte del paquete modal en PyPI.

Requisitos:

  • Python 3.10 o superior
  • pip o uv instalado

Verificar Python:

python --version
# Debes ver Python 3.10.x o superior

Si tienes Python 3.9 o menor, actualiza antes de continuar. Modal no soporta versiones más viejas.

Recomendado: usar un entorno virtual. Mezclar el modal global con otros proyectos termina mal. Crea un venv específico para este módulo:

mkdir modal-tutorial
cd modal-tutorial
python -m venv .venv
source .venv/bin/activate    # macOS/Linux
# .venv\Scripts\activate     # Windows PowerShell

Instalar:

pip install modal

Esto baja el paquete modal (y dependencias como grpclib, synchronicity, typer). Toma unos 20-30 segundos.

Verificar instalación:

modal --version
# modal client version: 0.64.x (o similar)

Si el comando modal no se reconoce, tu venv no está activado o la instalación falló. Veremos troubleshooting al final.

Paso 3 — Autenticar la CLI con un token

La CLI necesita un token que demuestre que eres tú. Modal lo genera abriendo el navegador y pidiéndote confirmación.

modal token new

Esto abre una pestaña en tu navegador con una URL del tipo https://modal.com/token-flow/.... Confirma "Authorize CLI" y vuelves al terminal.

Output esperado:

Web authentication finished successfully!
Token written to ~/.modal.toml in profile 'default'.

El archivo ~/.modal.toml queda con algo así:

[default]
token_id = "ak-XXXXXXXXXXXXXXXXXXXXXX"
token_secret = "as-XXXXXXXXXXXXXXXXXXXXXX"
active = true

Importante: este archivo es un secreto. No lo commitees a git. No lo pegues en Slack ni en issues públicos. Si lo expones por accidente, ejecuta modal token rotate para invalidarlo y generar uno nuevo.

Paso 4 — Tu primera función remota

Vamos a probar que todo funciona con un "hello world" mínimo. No usa GPU ni LLM — eso viene en cápsulas siguientes. El objetivo de esta cápsula es solamente verificar el setup.

Crea hello.py:

# hello.py
import modal

app = modal.App("hello-modal")

@app.function()
def saludar(nombre: str) -> str:
    import platform
    return f"Hola {nombre}, te saludo desde {platform.node()}"


@app.local_entrypoint()
def main():
    resultado_local = saludar.local("Mike")
    resultado_remoto = saludar.remote("Mike")
    print("Local:", resultado_local)
    print("Remoto:", resultado_remoto)

Qué hace cada línea:

  • modal.App("hello-modal") — define el "namespace" de tu aplicación en Modal. El nombre aparecerá en tu dashboard.
  • @app.function() — decorador que marca saludar como ejecutable en la nube de Modal.
  • saludar.local(...) — corre la función en tu máquina, como cualquier función Python.
  • saludar.remote(...) — empaqueta el código, lo manda a Modal, ejecuta allá, te devuelve el resultado.
  • @app.local_entrypoint() — marca main como el punto de entrada cuando ejecutas modal run hello.py.

Ejecutar:

modal run hello.py

Output esperado (la primera vez):

✓ Initialized. View run at https://modal.com/apps/.../hello-modal
✓ Created objects.
├── 🔨 Created mount /Users/.../hello.py
└── 🔨 Created function saludar.
✓ App finished.

Local: Hola Mike, te saludo desde tu-laptop.local
Remoto: Hola Mike, te saludo desde modal-container-xxxxxx

Fíjate en dos detalles:

  1. El hostname cambia entre local y remoto — eso confirma que la versión remota realmente corrió en un container de Modal, no en tu máquina.
  2. La primera ejecución tardó algunos segundos (10-15s típicamente). Eso es el cold start: Modal levantó un container desde cero. Si corres modal run hello.py otra vez en los siguientes minutos, va a ser instantáneo porque el container queda "caliente" un rato.

Trampas comunes en el setup

Trampa 1 — command not found: modal

Tu venv no está activado o el pip install modal corrió en otro Python. Soluciones:

# Confirma qué Python está activo
which python
# Reactiva el venv si hace falta
source .venv/bin/activate
# Reinstala
pip install --force-reinstall modal

Trampa 2 — Token has expired o unauthenticated

Tu token caducó o ~/.modal.toml está mal. Soluciones:

modal token new            # Genera token nuevo (sobreescribe el viejo)
# O si necesitas borrar y arrancar limpio:
rm ~/.modal.toml
modal token new

Trampa 3 — Pegas el token en una variable de entorno y no funciona

Modal prioriza las variables MODAL_TOKEN_ID y MODAL_TOKEN_SECRET sobre ~/.modal.toml. Si pusiste valores viejos en tu .bashrc / .zshrc, la CLI los usa aunque hayas regenerado el token. Soluciones:

# Verifica si están seteadas
echo $MODAL_TOKEN_ID
echo $MODAL_TOKEN_SECRET
# Si tienen valor viejo, des-séteadas
unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET
# Y quítalas de tu shell rc para siempre

Trampa 4 — "Function is taking forever the first time"

No es un error: es el cold start construyendo la imagen. La primera vez Modal tiene que descargar la imagen base de Linux + dependencias, lo cual puede tomar 30-60s. Las siguientes corridas reusan la imagen y son rápidas. Cubrimos cómo minimizar esto en la cápsula 06-autoscaling.md.

Trampa 5 — Quiero usar Modal sin instalar Python localmente

No se puede. Modal requiere Python local porque tu código fuente vive ahí; lo que se "sube" a Modal es el código que tu Python serializa. No hay un cliente web puro.

Ejercicio de verificación

Antes de pasar a la cápsula 03, demuéstrate a ti mismo que tienes el setup completo. Modifica hello.py para:

  1. Agregar un segundo parámetro repetir: int = 1 a saludar
  2. Que devuelva el saludo concatenado repetir veces
  3. Llamar saludar.remote("tu-nombre", repetir=3) desde main

Espera ver tu saludo tres veces seguidas.

Ver solución 
# hello.py
import modal

app = modal.App("hello-modal")

@app.function()
def saludar(nombre: str, repetir: int = 1) -> str:
    return " ".join([f"Hola {nombre}!" for _ in range(repetir)])


@app.local_entrypoint()
def main():
    print(saludar.remote("Ana", repetir=3))
    # Output: Hola Ana! Hola Ana! Hola Ana!

Si esto funciona, tu setup está completo.

Resumen

Ahora tienes:

  • ✅ Cuenta de Modal con créditos gratuitos disponibles
  • ✅ CLI modal instalada en tu venv
  • ✅ Token de autenticación en ~/.modal.toml
  • ✅ Función Python ejecutándose remotamente

Checkpoint antes de avanzar: si modal run hello.py devuelve un saludo y ~/.modal.toml existe con tu token, estás listo.

Siguiente cápsula

En 03 — Primera función serverless vamos a profundizar en lo que pasó "detrás" cuando corriste saludar.remote: cómo Modal construyó la imagen, qué es el cold start, y cómo agregar dependencias Python a una función remota. Es la base que necesitas antes de meter modelos LLM en el siguiente paso.

Recursos

  1. Modal — Getting Started — guía oficial paso a paso.
  2. Modal — CLI Reference — todos los comandos disponibles.
  3. Modal — Free tier details — créditos mensuales y límites del free tier.
  4. Python venv documentation — entornos virtuales si nunca los usaste.
← AnteriorMódulo 6: Modal — Deployment serverless de LLMsSiguiente →Primera función serverless con dependencias