Qué son los workers en FastAPI y cómo aumentarlos

Tiempo de lectura: 2 minutos

¿Qué es un worker?

Un worker (trabajador) es un proceso del servidor que maneja las peticiones HTTP que llegan a tu aplicación FastAPI.
Piensa en él como una persona en una ventanilla de atención al cliente:
cuantos más workers tengas, más clientes puedes atender al mismo tiempo.

Imagina que tienes una API que procesa peticiones como:

@app.get("/procesar")
def procesar():
    time.sleep(2)
    return {"mensaje": "He terminado"}

Si tienes 1 worker, solo puedes procesar 1 petición cada 2 segundos.
Si tienes 4 workers, puedes procesar 4 peticiones en paralelo, una por proceso.

FastAPI no gestiona directamente los workers, sino el servidor ASGI que ejecuta tu aplicación.
El más usado es Uvicorn, y a veces se combina con Gunicorn en entornos de producción.

Aumentar workers con Uvicorn

Si ejecutas FastAPI con Uvicorn directamente, puedes usar la opción --workers:

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

• Esto lanzará 4 procesos de tu aplicación en paralelo.
• Ideal para aprovechar varios núcleos de CPU.

No uses más workers de los que tu servidor pueda manejar, ya que cada proceso usa memoria adicional.

Aumentar workers en Docker

Si tu aplicación corre dentro de un contenedor Docker, puedes editar el CMD del Dockerfile:

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

O hacerlo automático según los núcleos disponibles:

CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port 8000 --workers $((2 * $(nproc) + 1))"]

• $(nproc) detecta el número de CPUs del contenedor.
• 2 * $(nproc) + 1 es una regla común en servidores web (inspirada en Gunicorn).

Aumentar workers con Gunicorn + Uvicorn

Para entornos de producción (por ejemplo, Ubuntu o AWS), se recomienda usar Gunicorn como gestor principal y Uvicorn como worker:

gunicorn -k uvicorn.workers.UvicornWorker main:app --workers 4 --bind 0.0.0.0:8000

Parámetros importantes:

-k uvicorn.workers.UvicornWorker: indica que Gunicorn debe usar Uvicorn.

--workers: número de procesos (igual que antes).

--bind: dirección y puerto donde escucha.

¿Cuántos workers debería usar?

Una regla general es:

workers = 2 * núcleos_CPU + 1

Si tu servidor tiene 2 núcleos → 2 * 2 + 1 = 5 workers

Pero si tu aplicación usa mucha memoria o hace tareas pesadas, puede convenir usar menos.

Verificación

Puedes verificar cuántos workers se están ejecutando con un comando como:

ps aux | grep uvicorn

Verás varias líneas si hay varios workers activos.

Tabla de comandos:

Entorno	Comando o Configuración
Local (Uvicorn)	uvicorn main:app --workers 4
Dockerfile	CMD ["uvicorn", "main:app", "--workers", "4"]
Gunicorn	gunicorn -k uvicorn.workers.UvicornWorker main:app --workers 4 --bind 0.0.0.0:8000
Regla general	workers = 2 * núcleos_CPU + 1