Skip to content

English · Español

Fase 33 — Servicio de inferencia: de FastAPI al continuous batching

Requiere: 22 — KV cache: de las matemáticas a la memoria · 32 — Agentes: planificación, memoria, sandboxing (tutor de gramática) Enseña: serving · continuous-batching · scheduling · littles-law · load-testing Salta a cualquier capítulo desde el índice de referencia de fases.

Mapa del capítulo

La Fase 32 construyó el agente tutor. La Fase 33 lo pone detrás de un endpoint HTTP que aguante carga concurrente con continuous batching. CPU-only, sin vLLM, sin Ray. La idea es sentir el coste del scheduling antes de delegar.

Anclas: LYNX_CORTEX.md §4 / PHASE 33, PHASE_33_PLAN.md, LYNX_CORTEX_ADDENDUM.md §A13.

Objetivo

Coger el agente tutor de gramática de la Fase 32 y ponerlo detrás de un servicio HTTP con forma de producción. Cubrir el camino desde el servicio síncrono con uvicorn + FastAPI → handlers async → static batching → continuous batching (in-flight batching).

Al final Borja podrá: (a) escribir un servicio FastAPI mínimo que envuelva al agente; (b) explicar por qué el static batching tiene problemas de latencia de cola y qué cambia el continuous batching; © implementar un pequeño scheduler de continuous batching en Python (un solo proceso, sin dependencia de vLLM); (d) medir latencias p50/p95/p99 sobre la carga de corrección de verbos; (e) aplicar la ley de Little para dimensionar la cola.

Lo que vas a construir

Extensiones a src/miniserve/:

src/miniserve/
├── BLUEPRINT.md       # escrito en el pre-flight de la Fase 33, antes de cualquier código
├── app.py             # aplicación FastAPI + handlers de rutas
├── schemas.py         # tipos de request / response Pydantic
├── scheduler.py       # schedulers de static y continuous batching
└── healthz.py         # probes de liveness y readiness

La API HTTP:

POST /correct
{"sentence": "He goed to school"}
↓
{"corrected": "He went to school",
 "explanation": "The past tense of 'go' is the irregular form 'went'."}

Lo que esta fase NO cubre

  • Servicio en GPU / multi-nodo. Fase 35.
  • vLLM, TGI, Ray Serve como dependencias. Se revisan en el lab 04; no se usan.
  • Respuestas en streaming (text/event-stream). Aplazado al pulido de la Fase 39.
  • Autenticación / autorización. Fase 37.
  • PagedAttention. Fase 27 (allí se cubre); aquí solo se referencia.
  • Paneles de coste y capacidad. Fase 34.

Orden de lectura

  1. theory/00-motivation.md — por qué servir por HTTP necesita más que un bucle for.
  2. theory/01-async-and-the-event-loop.md — handlers sync vs async, el GIL.
  3. theory/02-static-vs-continuous-batching.md — el cambio de scheduling.
  4. theory/03-littles-law-and-capacity.md — dimensionar la cola.
  5. lab/00-minimal-fastapi.md — POST /correct, ida y vuelta con curl.
  6. lab/01-sync-vs-async.md — load test, arreglar el handler bloqueante.
  7. lab/02-static-batching.md — recoger-N-luego-ejecutar.
  8. lab/03-continuous-batching.md — scheduler a nivel de iteración.
  9. lab/04-vllm-and-tgi-survey.md — qué añaden los sistemas de producción por encima.

solutions/ se rellena al abrir la fase.

Definition of Done

Ver PHASE_33_PLAN.md §6 (en la raíz del repo). En breve:

  • POST /correct funciona de extremo a extremo sobre los prompts del corpus de verbos.
  • El continuous batching mejora al static batching en p95 en ≥ 30 % en el load test estándar.
  • /healthz y /readyz implementados.
  • CDFs de latencia (sync vs async vs static-batched vs continuous-batched) guardadas.

Piezas que el portal reutilizará (Fase 41)

El Learner Portal de la Fase 41 (docs/phase-41-learner-portal/) es una segunda aplicación FastAPI — multi-estudiante, renderizada en servidor, sin batching — que reutiliza los patrones del framework de la Fase 33. El capítulo de teoría theory/04-portal-building-blocks.md enseña cada patrón por separado; la arquitectura del portal (docs/phase-41-learner-portal/theory/01-architecture.md) los compone. Cuatro puntos concretos de reutilización:

  1. sqlite + vault gestionados por lifespan. El portal abre su motor SQLite y el handle de minivault dentro de un async context manager lifespan de FastAPI, exactamente como el miniserve de la Fase 33 abre el agente. Un único handle por proceso, cerrado en orden inverso al apagar. (§1 de la teoría 04.)
  2. Auth y sesión de DB inyectadas por Depends(). Depends(require_student) y Depends(require_admin) protegen cada ruta protegida; la sesión de DB con ámbito de request viene de Depends(get_db_session). El mismo patrón de inyección de dependencias que la Fase 33 usa para el handle del agente. (§2 de la teoría 04.)
  3. Orden del middleware ASGI con CSRF-después-de-sesión. El portal monta los mismos middlewares de miniserve (rate-limit, body-size, injection-filter) y añade decodificación de sesión + validación CSRF — con CSRF después de decodificar la sesión, nunca antes. (§3 de la teoría 04.)
  4. OpenAPI para endpoints de admin. La Fase 33 establece las convenciones de OpenAPI / /health / log estructurado; las rutas /admin/* del portal las heredan para que un futuro cliente admin externo pueda inspeccionar el schema. (Enlace cruzado entre theory/04-portal-building-blocks.md y el capítulo de arquitectura del portal.)

Siguiente: theory/00-motivation.md

Lecturas recomendadas

Opcional — enriquece pero no es necesario para aprobar la fase.