/ C01 · 6
← Clasificación de imágenes C01 · Estación 6 de 12

Código de serving

El modelo ya está compilado y registrado. ¿Qué programa lo pone a responder fotos por la red, sin caerse cuando llega una foto rara, cuando sube el tráfico o cuando el servidor del modelo se traba?

Estás aquí6 · Código de serving

Arranca en 3 pasos

lo vital

Necesitas: Docker Desktop corriendo, con ≈ 700 MB libres para las imágenes de RustFS y MLflow · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 1.2 GB para el entorno virtual (PyTorch solo para crear el mundo) · git (con tu nombre y correo configurados) y curl · Internet la primera vez (los paquetes, las imágenes y Fashion-MNIST) · Los puertos 9700, 9701, 5700, 8700 y 8701 libres en tu Mac

2

Levanta el mundo

Terminalarranque
unzip c01-serving.zip && cd c01-serving
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
docker compose up -d --wait
python mundo/crear.py
git init && git add -A && git commit -m "kit recién descomprimido"
3

Verifica

Terminal
python verificar.py mundo
Listo cuando: verificar.py mundo en verde: los buckets, el examen, classifier v1–v4 con v4 en engine=listo, servir.yaml, fotos-raras/ y git. Ya puedes practicar.
¿Algo falló al levantar?
Ojo: Los puertos de esta estación (9700, 5700, 8700 y 8701) no chocan con los de las anteriores: puedes tener varias estaciones arriba a la vez.

python3 -m venv .venv && source .venv/bin/activate · Tarda unos minutos la primera vez (PyTorch pesa ≈ 1 GB; solo lo usa mundo/crear.py). Desde aquí, cada terminal nueva necesita source .venv/bin/activate.

SalidaSalida real · python3 -m venv .venv && source .venv/bin/activate
Python 3.14.3
1.2G

docker compose up -d --wait · La interfaz de MLflow queda en http://localhost:5700.

SalidaSalida real · docker compose up -d --wait
 Container taller-c01-serving-s3-1 Healthy 
 Container taller-c01-serving-mlflow-1 Healthy
  descargando t10k-images-idx3-ubyte… (Fashion-MNIST, Zalando Research, licencia MIT)
  descargando t10k-labels-idx1-ubyte… (Fashion-MNIST, Zalando Research, licencia MIT)
  golden-v1: 1000 fotos · manifest sha256 0061343ada92…
  entrenando classifier v1 (2026-07) con ds-2026-06-01…
  classifier v1 (2026-07) · val_top1 0.7559 · 21 s
  entrenando classifier v2 (2026-08) con ds-2026-07-01…
  classifier v2 (2026-08) · val_top1 0.8088 · 20 s
  entrenando classifier v3 (2026-09) con ds-2026-08-01…
  classifier v3 (2026-09) · val_top1 0.8395 · 26 s
  entrenando classifier v4 (2026-10) con ds-2026-09-01…
  classifier v4 (2026-10) · val_top1 0.8675 · 31 s
  engine de v3: engine.onnx 76ea30f48b41… · onnxruntime 1.32.0
  engine de v4: engine.onnx 88bdea80ac92… · onnxruntime 1.32.0
  fotos-raras/: 10 fotos de prueba
✓ mundo listo: python verificar.py mundo

git init && git add -A && git commit -m "kit recién descomprimido" · Los ids de commit cambian en cada máquina.

SalidaSalida real · git init && git add -A && git commit -m "kit recién descomprimido"
3963da1 kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo       S3 local (golden-v1, checkpoints) · MLflow: classifier v1–v4, @champion = v3, @challenger = v4 · servir.yaml: v4 (engine listo) · fotos-raras/ · git

1/1 en verde

¿Ya está corriendo? Elige cómo practicar

las cuatro rondas

Cada ronda se trabaja en una sesión de Claude Code abierta en la carpeta del kit. Copia el prompt de la ronda y pégalo; el enlace de cada tarjeta te lleva a su sección en esta página. El CLAUDE.md del kit pone las reglas de fondo.

ConstruirRomper Con ayuda
1 · Construir con ayudaCon el Guiado de abajo: construyen juntos los pasos 1 a 8. Empieza aquí.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 6 de C01, «Código de serving», ronda **Construir con ayuda**.

Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 8 de `GUION.md`, lo que pone a `classifier` v4 a responder fotos: leer qué se sirve y con qué reglas, armar el model repository desde el registro con sus huellas, el `config.pbtxt` de Triton, la revisión de cada foto, el gateway en FastAPI (arranque, salud y classify), el código de cada falla y los topes, los plazos con Triton congelado, y el log, las métricas y las pruebas con un Triton falso.

Entre el paso 0 y el 1, `GUION.md` trae los «Precálculos»: las cuentas de servilleta de la estación. Pídeme que haga cada cuenta yo primero, corrígeme y después corre el comando que la comprueba (o dime en qué paso se va a confirmar).

En cada paso:
1. Dime el objetivo en una línea y explícame los conceptos que usa, rápido, con una analogía y con el término en inglés.
2. Escribe conmigo el archivo del paso, por bloques y con el porqué de cada uno. No me pegues el archivo entero de golpe. El contrato de arriba de cada archivo manda.
3. Dime qué comando correr y espera a que te pegue la salida. Los que cambian algo (`mundo/servicios.py arrancar|parar|reiniciar`, `kill -STOP`/`-CONT`, `git commit`, `git revert`) no los corras tú sin decírmelo antes.
4. Corre `python verificar.py <checks del paso>` y explícame el resultado. Cuando el gateway esté arriba, míralo conmigo con `curl -i`, `tail logs/gateway.log` y `/metrics` (los del gateway y los de Triton).
5. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.

Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
Ir al Guiado ↓
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 6 de C01, «Código de serving», ronda **Romper con ayuda**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`. Ahora:

1. Corre `python romper.py --mostrar` (o `--mostrar --falla <id>` si te digo cuál). El script mete la falla en el mundo, la configuración o la infraestructura, nunca en mi gateway, mi `armar.py` ni mi `config.pbtxt`, y te dice cuál fue. **A mí no me la digas.** Solo cuéntame la «historia»: qué notó alguien en el equipo.
2. Corre `python verificar.py` y pregúntame qué veo.
3. Guíame con preguntas en este orden: síntoma → hipótesis (pídeme al menos dos) → el comando que confirma o descarta cada una (`python mundo/servicios.py estado`, `tail logs/gateway.log`, `tail logs/triton.log`, `curl -i` al gateway y a Triton, `git log -p gateway.yaml`, `python mundo/modelos.py versiones|engine 4|labels 4`, `shasum -a 256 model_repository/classifier/1/model.onnx`, `docker compose ps`, y mi propio `servir/armar.py`) → el arreglo. Si me atoro más de dos veces en el mismo punto, dame una pista concreta y anótala.
4. Cuando lo arregle, corre `python romper.py --verificar`. Ahí sí explícame qué era, el concepto detrás y cómo se vería en C01 de verdad (Triton con TensorRT en una T4, el model repository dentro de la imagen, Kubernetes con sus probes, el ALB, MLflow con Postgres y S3).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.

Repetimos con otra falla hasta que te diga que paremos. Para volver al estado sano entre fallas: `python romper.py --restaurar`.
Ir a Romper ↓
Solo
2 · Construir soloRehaces todo desde el esqueleto, solo con los objetivos de Solo.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 6 de C01, «Código de serving», ronda **Construir solo**.

Lee `CLAUDE.md`. **No leas `GUION.md`**, `mundo/triton_dojo/` ni `mundo/equipo.py`, y no me des código: esta ronda la escribo yo desde el esqueleto, con `OBJETIVOS.md` y los contratos de cada archivo como única guía.

Tu papel:
- Primero corre `python mundo/reiniciar.py --serving`: para Triton y el gateway, respalda mis archivos en `.respaldo/`, pone el esqueleto (`servir/armar.py`, `model_repository/classifier/config.pbtxt`, `gateway/app/main.py`, `gateway/app/revision.py` y `gateway/tests/` con su contrato) y borra el engine del repositorio, `servir/modelo.json` y `logs/` (el registro, el examen y las fotos de prueba se quedan). Confírmame qué se borró y haz conmigo el commit del esqueleto.
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código ni con el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.

Al final, con `python verificar.py` en verde, cierra la ronda en `taller/progreso.json`.
Ir a Solo ↓
4 · Romper soloUna falla escondida; nadie te da pistas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 6 de C01, «Código de serving», ronda **Romper solo**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`.

1. Corre `python romper.py` **sin** `--mostrar`. El script elige una falla al azar y la esconde; tú tampoco sabes cuál es, así que no intentes averiguarla leyendo `romper.py`, `.taller/` ni lo que cambió.
2. Dime solo la «historia» que imprime y la hora de inicio. Desde ahí trabajo yo solo: no me des pistas ni hipótesis. Si te pido correr un comando, córrelo y pégame la salida tal cual, sin interpretarla.
3. Cuando te diga «listo», corre `python romper.py --verificar`. Dime si quedó arreglado, cuál era la falla y cuánto tardé. Si no quedó, dime solo que no y sigo.
4. Si te digo «me rindo», corre `python romper.py --revelar` y explícame la falla completa.
5. Anota en la bitácora la falla, el tiempo, si me rendí y qué haría distinto.
Ir a Romper ↓

Lleva la cuenta en tu tablero: el kit anota tu avance en taller/progreso.json y ahí lo importas.

Guiado

paso a paso

¿Aún no levantas el ambiente? Ve al arranque.

El código que ves es el de la solución de referencia, y cada salida es la que salió al correr el kit en una carpeta limpia.

Precálculos. Antes de escribir el gateway, las cuentas de servilleta: cuánta memoria pide una copia en el peor momento, cuántas requests caben adentro, cuánto plazo le queda a la llamada a Triton, cuántas fotos junta Triton en un lote, cuánto pesa lo que viaja por la red y cuánto log sale al día. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.

1Qué se sirve y con qué reglasSaber, antes de escribir código, qué versión se sirve, qué engine y con qué reglas atiende el gateway.

servir.yaml dice qué se sirve, por número: v4, con el nombre que verá quien llama. El registro dice que v4 pasó el gate y tiene su engine, con su huella y la versión de ONNX Runtime con que se construyó. gateway.yaml trae las reglas del equipo de serving: qué tipos de foto se aceptan, los límites (bytes, píxeles, proporción), los topes (decodes y requests en vuelo) y la cadena de plazos. Tu código las lee; nunca las escribe.

YAMLgateway.yaml
# Las reglas del gateway, del equipo de serving. Tu código las lee al arrancar y nunca las escribe. Cambian solo con
# una revisión (mundo/revisiones.json guarda las huellas aprobadas). En C01: las constantes y variables de entorno
# del Deployment del gateway, revisadas en el repositorio classifier.
contrato:
  ruta: /v1/classify
  tipos: [image/jpeg, image/png, image/webp]
  top_k: {defecto: 5, min: 1, max: 10}   # C01: de 1 a 20, con 500 categorías; aquí hay 10
limites:
  max_bytes: 10485760         # 10 MiB: el body más grande que se lee; se corta al leer, no se confía en Content-Length
  max_pixeles: 40000000       # 40 MP, leídos del encabezado de la imagen, antes de decodificar
  max_proporcion: 8           # el lado largo hasta 8 veces el corto
  decodes: 2                  # decodes a la vez en un proceso (el semáforo)
  espera_cpu_ms: 50           # lo más que una request espera un lugar de decode; después, 503
  en_vuelo: 16                # requests adentro a la vez; la 17 recibe 503 al instante
  memoria_mib: 1024           # la memoria de una copia del gateway (en C01: el límite del pod)
plazos_ms:                    # cada eslabón, menor que el de afuera: el de adentro se rinde primero
  app: 300                    # lo que espera la app antes de mostrar el selector manual de categorías
  gateway: 250                # el plazo total de una request en el gateway
  triton: 150                 # el tope de la llamada a Triton (o lo que le quede a la request, si es menos)
  fila_triton: 100            # lo más que una foto espera en la fila de Triton (default_timeout_microseconds)
triton:
  url: localhost:8700
  modelo: classifier
  conexiones: 64              # el pool de conexiones del cliente de Triton, uno por proceso
  listo_timeout_ms: 500       # lo más que /readyz espera la respuesta de Triton

Del equipo de serving. Sus versiones revisadas están en mundo/revisiones.json.

Terminal
grep -v "^#" servir.yaml
Salida
modelo: classifier
version: 4                       # classifier@challenger al arrancar: el candidato de octubre, con su engine
nombre: miniresnet-2026-10-01    # el model_version que ve quien llama (en C01: resnet50-2026-10-01)
Terminal
python mundo/modelos.py versiones

v3 (@champion) y v4 (@challenger) tienen engine=listo: los dos se pueden servir. Esta noche se arma v4; quién recibe tráfico lo decide el rollout (estación 10).

Salida
v1  —            mes 2026-07 · equipo-2026-07-01 · gate passed · pesos 900f8ba1e607… · engine retirado
v2  —            mes 2026-08 · equipo-2026-08-01 · gate passed · pesos 6509cf6cab5e… · engine retirado
v3  @champion    mes 2026-09 · equipo-2026-09-01 · gate passed · pesos e858003795ba… · engine listo (76ea30f48b41… · fp16 · onnxruntime 1.32.0)
v4  @challenger  mes 2026-10 · cand-2026-10-01   · gate passed · pesos 0e36f3a192b0… · engine listo (88bdea80ac92… · fp16 · onnxruntime 1.32.0)
Terminal
python mundo/modelos.py engine 4
Salida
  batch_max              32
  champion_version       3
  engine                 listo
  engine_sha256          88bdea80ac920c546692c876b1977af2976b132e73b01bc67555307c656fd3c2
  examen                 golden-v1
  gate                   passed
  gate_run_id            wf-2026-10-01-gate
  maquina                Darwin arm64
  onnx_sha256            ba6720d59f21048bcc140a59b1e81c913d1de4dcc1ea5075d62b319e71c5e1d7
  onnxruntime            1.32.0
  opset                  17
  pesos_sha256           0e36f3a192b0c8844d73630c181f16d64c1b80d1e80d406d40a86a6ed1264cb7
  precision              fp16
  engine/engine.json         422 B · sha256 f85886d73b05…
  engine/engine.onnx      181347 B · sha256 88bdea80ac92…
  engine/model.onnx       179906 B · sha256 ba6720d59f21…
Terminal
python verificar.py reglas
Salida
✓ reglas      gateway.yaml = la revisión del PR #51 · plazos 300 > 250 > 150 > 100 ms · peor momento ≈ 920 MiB de 1024 · sin cambios pendientes

1/1 en verde
Listo cuando: Puedes decir en voz alta: sirvo classifier v4 como miniresnet-2026-10-01; acepto JPEG, PNG y WebP de hasta 10 MiB y 40 MP; 2 decodes y 16 requests a la vez; plazos 300 > 250 > 150 > 100 ms.
Ojo: El check reglas hace la cuenta de memoria del peor momento con los números de gateway.yaml: es el precálculo «memoria» hecho código.
Conceptos de este paso
Gateway y servidor de modelosAPI gateway / model serverDos programas con trabajos distintos. El gateway recibe la request, la revisa, prepara la foto en la CPU y contesta. El servidor de modelos solo convierte tensores en tensores en la GPU.Analogía, por qué importa y la trampa

AnalogíaEl mesero y la cocina: el mesero toma el pedido, revisa que se pueda hacer y lo entrega; la cocina solo cocina, y nunca habla con el cliente.

Por qué importaCada uno escala por su lado (gateways baratos en CPU, pocas GPUs caras), y los bytes hostiles de internet nunca llegan al proceso que tiene la GPU.

TrampaMeter el modelo de PyTorch dentro del gateway «porque es más simple»: cada despliegue recarga el modelo y cada foto corre sola en la GPU.

Triton Inference ServerNVIDIA TritonEl servidor de modelos de NVIDIA: carga modelos de una carpeta y los atiende por HTTP o gRPC con el protocolo de inferencia v2 de KServe, juntando peticiones en lotes.Analogía, por qué importa y la trampa

AnalogíaUna cocina industrial con reglas escritas para cada platillo: qué ingredientes recibe, en qué cantidad y cuántos prepara a la vez.

Por qué importaEl gateway le habla con su cliente oficial (tritonclient) y le manda el tensor en binario. En el dojo, un servidor sustituto con el mismo protocolo deja usar ese mismo cliente.

TrampaMandar el tensor como lista de números en JSON: pesa varias veces más y se tarda en convertir.

2Armar el model repositorymodel_repository/classifier/1/model.onnx es la copia exacta del engine aprobado, y servir/modelo.json trae su versión, sus labels y sus huellas.

armar.py no copia «el último engine»: lee la versión de servir.yaml, exige gate=passed y engine=listo, baja el engine y el labels.json de la corrida y solo los usa si su sha256 es el del tag de la versión. Revisa que el engine se haya construido con el runtime del servidor. Lee del engine el nombre y la forma de la entrada y la salida, y deja la ficha para el gateway. El config.pbtxt no lo escribe: es tuyo, y va en git.

Pythonservir/armar.py
"""Paso «repositorio»: arma el model repository de Triton y la ficha del modelo para el gateway, para la versión que
dice servir.yaml, con las huellas del registro.

    python servir/armar.py

Contrato:
- La versión sale de servir.yaml, por número (nunca de un alias leído al correr).
- En el registro, esa versión tiene gate=passed y engine=listo; si no, se detiene.
- Baja engine/engine.onnx de su corrida y solo lo usa si su sha256 es el tag engine_sha256 de la versión.
- Baja modelo/labels.json y solo lo usa si su sha256 es el tag labels_sha256.
- El engine se construyó con el runtime del servidor de modelos: el tag onnxruntime de la versión es la versión de
  onnxruntime instalada (la que corre mundo/triton_dojo/). Si no, se detiene.
- Escribe model_repository/classifier/1/model.onnx (la copia exacta del engine) y servir/modelo.json: modelo, version,
  model_version (el nombre de servir.yaml), engine_sha256, labels, labels_sha256, y el nombre y la forma de la entrada
  y la salida, leídos del engine. El config.pbtxt no lo escribe: es tuyo, y está en git.
- Correrlo dos veces no cambia nada: si el repositorio ya tiene ese engine, lo dice.
"""
from __future__ import annotations

import json
import shutil
import sys
import tempfile
from pathlib import Path

RAIZ = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(RAIZ))
import onnxruntime as ort  # noqa: E402

from mundo.comun import MODELO_JSON, REPO, mlflow_cliente, servir_yaml, sha256  # noqa: E402

# 1 · Qué se sirve: un número, no un alias
cfg = servir_yaml()
modelo, version = cfg["modelo"], str(cfg["version"])
c = mlflow_cliente()
try:
    mv = c.get_model_version(modelo, version)
except Exception as e:  # noqa: BLE001
    sys.exit(f"✗ no pude leer {modelo} v{version} del registro ({type(e).__name__}): ¿está arriba MLflow? docker compose ps")
t = mv.tags
if t.get("gate") != "passed" or t.get("engine") != "listo":
    sys.exit(f"✗ {modelo} v{version} tiene gate={t.get('gate')} y engine={t.get('engine')}: solo se sirve gate=passed y engine=listo")
if t.get("onnxruntime") != ort.__version__:
    sys.exit(f"✗ el engine de v{version} se construyó con onnxruntime {t.get('onnxruntime')} y el servidor corre "
             f"{ort.__version__}: un engine se sirve con el runtime que lo construyó")
print(f"  {modelo} v{version} · gate passed · engine listo ({t['engine_sha256'][:12]}… · onnxruntime {t['onnxruntime']})")

# 2 · Bajar el engine y los labels, y compararlos con las huellas del registro
with tempfile.TemporaryDirectory() as d:
    eng = Path(c.download_artifacts(mv.run_id, "engine/engine.onnx", d))
    lab = Path(c.download_artifacts(mv.run_id, "modelo/labels.json", d))
    if sha256(eng.read_bytes()) != t["engine_sha256"]:
        sys.exit(f"✗ engine/engine.onnx de la corrida tiene huella {sha256(eng.read_bytes())[:12]}… y v{version} dice "
                 f"{t['engine_sha256'][:12]}…: no es el engine que se registró. No lo sirvo")
    if sha256(lab.read_bytes()) != t["labels_sha256"]:
        sys.exit(f"✗ modelo/labels.json de la corrida tiene huella {sha256(lab.read_bytes())[:12]}… y v{version} dice "
                 f"{t['labels_sha256'][:12]}…: las categorías no son las del modelo. No lo sirvo")
    labels = json.loads(lab.read_text())

    # 3 · La entrada y la salida, leídas del engine (lo que el config.pbtxt tiene que declarar)
    s = ort.InferenceSession(str(eng), providers=["CPUExecutionProvider"])
    i, o = s.get_inputs()[0], s.get_outputs()[0]
    entrada = {"nombre": i.name, "forma": [d if isinstance(d, int) else -1 for d in i.shape]}
    salida = {"nombre": o.name, "forma": [d if isinstance(d, int) else -1 for d in o.shape]}
    if salida["forma"][-1] != len(labels):
        sys.exit(f"✗ el engine da {salida['forma'][-1]} logits y labels.json trae {len(labels)} categorías")

    # 4 · El model repository: <modelo>/1/model.onnx, la copia exacta
    destino = REPO / modelo / "1" / "model.onnx"
    if destino.exists() and sha256(destino.read_bytes()) == t["engine_sha256"]:
        print(f"  {destino.relative_to(RAIZ)} ya es el engine de v{version}: no cambio nada")
    else:
        destino.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy(eng, destino)
        print(f"  {destino.relative_to(RAIZ)} · {destino.stat().st_size // 1000} kB · sha256 {t['engine_sha256'][:12]}…")

# 5 · La ficha del modelo para el gateway (en C01: el ConfigMap con labels.json y su huella)
ficha = {"modelo": modelo, "version": int(version), "model_version": cfg["nombre"], "engine_sha256": t["engine_sha256"],
         "labels": labels, "labels_sha256": t["labels_sha256"], "entrada": entrada, "salida": salida}
MODELO_JSON.parent.mkdir(exist_ok=True)
MODELO_JSON.write_text(json.dumps(ficha, ensure_ascii=False, indent=2) + "\n")
print(f"  servir/modelo.json · model_version {cfg['nombre']} · {len(labels)} labels ({t['labels_sha256'][:12]}…) · "
      f"entrada {entrada['nombre']} {entrada['forma']} → salida {salida['nombre']} {salida['forma']}")
print("✓ repositorio listo. Si Triton ya corría: python mundo/servicios.py reiniciar triton (carga solo al arrancar)")

El engine (binario, sale del registro) no va en git: .gitignore ignora model_repository/*/1/. El config.pbtxt sí.

Terminal
python servir/armar.py
Salida
  classifier v4 · gate passed · engine listo (88bdea80ac92… · onnxruntime 1.32.0)
  model_repository/classifier/1/model.onnx · 181 kB · sha256 88bdea80ac92…
  servir/modelo.json · model_version miniresnet-2026-10-01 · 10 labels (97864728052c…) · entrada input [-1, 3, 32, 32] → salida logits [-1, 10]
✓ repositorio listo. Si Triton ya corría: python mundo/servicios.py reiniciar triton (carga solo al arrancar)
Terminal
python servir/armar.py

Otra vez: no cambia nada.

Salida
  classifier v4 · gate passed · engine listo (88bdea80ac92… · onnxruntime 1.32.0)
  model_repository/classifier/1/model.onnx ya es el engine de v4: no cambio nada
  servir/modelo.json · model_version miniresnet-2026-10-01 · 10 labels (97864728052c…) · entrada input [-1, 3, 32, 32] → salida logits [-1, 10]
✓ repositorio listo. Si Triton ya corría: python mundo/servicios.py reiniciar triton (carga solo al arrancar)
Terminal
find model_repository servir -type f | sort
python -m json.tool servir/modelo.json | head -12

El config.pbtxt todavía es el esqueleto: lo escribes en el paso 3.

Salida
model_repository/classifier/1/model.onnx
model_repository/classifier/config.pbtxt
servir/armar.py
servir/modelo.json
{
    "modelo": "classifier",
    "version": 4,
    "model_version": "miniresnet-2026-10-01",
    "engine_sha256": "88bdea80ac920c546692c876b1977af2976b132e73b01bc67555307c656fd3c2",
    "labels": [
        "playeras",
        "pantalones",
        "sueteres",
        "vestidos",
        "abrigos",
        "sandalias",
Terminal
python verificar.py repositorio
Salida
✓ repositorio classifier v4 → model_repository/classifier/1/model.onnx (88bdea80ac92… = su tag) · servir/modelo.json: miniresnet-2026-10-01, 10 labels (97864728052c… = su tag)

1/1 en verde
Listo cuando: model_repository/classifier/1/model.onnx con la huella del tag engine_sha256 de v4, y servir/modelo.json con miniresnet-2026-10-01, los 10 labels en su orden y sus huellas.
Ojo: La carpeta 1/ es la versión dentro de Triton, no la del registro: la de verdad va en la ficha y en cada respuesta (model_version).
Concepto de este paso
Model repositoryTriton model repositoryLa carpeta de donde Triton carga los modelos: una subcarpeta por modelo, con su config.pbtxt y una carpeta numerada por versión con el archivo del modelo.Analogía, por qué importa y la trampa

AnalogíaEl recetario de la cocina: cada platillo con su ficha y la receta de la edición vigente.

Por qué importaCon --model-control-mode=none, Triton carga lo que hay al arrancar y nada más: qué modelo corre lo dice la carpeta (en C01, la imagen). Por eso se arma desde el registro, con huellas, y nunca a mano.

TrampaConfundir la versión de la carpeta (1/) con la del registro (v4): la de verdad va en las huellas y en el model_version de cada respuesta.

3El config.pbtxt y TritonTriton carga classifier con tu config.pbtxt: batching dinámico, fila con plazo, dos copias y warmup, y dice «listo».

El config.pbtxt le dice a Triton cómo atender el modelo. dims va sin el eje del batch (Triton le antepone −1). dynamic_batching espera hasta 2 ms a que lleguen más fotos y rechaza (REJECT) la que lleve 100 ms en la fila: el último eslabón de la cadena de plazos. instance_group carga dos copias y model_warmup las corre con ceros antes de decir «listo». Triton arranca con flags explícitos: carga solo al arrancar, no rellena lo que falta del config, y si un modelo no carga, termina.

model_repository/classifier/config.pbtxt
# La configuración de classifier en el servidor de modelos (Triton). Formato de texto de protobuf.
# En C01: platform "tensorrt_plan", [3, 224, 224] → [500] y KIND_GPU en la T4.
name: "classifier"
platform: "onnxruntime_onnx"
max_batch_size: 32                         # el batch más grande que arma el servidor (el engine acepta hasta 32)
version_policy: { latest { num_versions: 1 } }
input  [ { name: "input"   data_type: TYPE_FP32  dims: [ 3, 32, 32 ] } ]   # sin el eje del batch: Triton le antepone -1
output [ { name: "logits"  data_type: TYPE_FP32  dims: [ 10 ] } ]
dynamic_batching {
  preferred_batch_size: [ 16, 32 ]
  max_queue_delay_microseconds: 2000       # espera hasta 2 ms a que lleguen más fotos para correrlas juntas
  default_queue_policy {
    timeout_action: REJECT
    default_timeout_microseconds: 100000   # 100 ms en la fila sin entrar al modelo: se rechaza (gateway.yaml: fila_triton)
  }
}
instance_group [ { count: 2  kind: KIND_CPU } ]   # dos copias del modelo
model_warmup [ {
  name: "ceros"  batch_size: 32  count: 3
  inputs { key: "input"  value: { data_type: TYPE_FP32  dims: [ 3, 32, 32 ]  zero_data: true } }
} ]

En C01: platform: "tensorrt_plan", [3, 224, 224] → [500] y KIND_GPU.

Terminal
# a propósito: el batch dentro de dims, como [1, 3, 32, 32]
python mundo/servicios.py arrancar triton

Triton revisa la ficha contra el engine y no carga; con --exit-on-error=true, ni arranca. Mejor así que un servidor prendido sin modelo. (Después se regresa el archivo bueno.)

Salida
  $ python mundo/triton_dojo/servidor.py --model-repository=model_repository --http-port=8700 --model-control-mode=none --strict-readiness=true --exit-on-error=true --exit-timeout-secs=30 --disable-auto-complete-config
✗ triton terminó al arrancar (código 1). Lo último de logs/triton.log:
I model repository: ~/c01-serving/model_repository
I loading: classifier
E failed to load 'classifier': input 'input': model expected the shape [3, 32, 32] (sin el eje del batch: Triton le antepone -1) but the config.pbtxt says [1, 3, 32, 32]
+------------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Model      | Version | Status                                                                                                                                                  |
+------------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| classifier | 1       | UNAVAILABLE: input 'input': model expected the shape [3, 32, 32] (sin el eje del batch: Triton le antepone -1) but the config.pbtxt says [1, 3, 32, 32] |
+------------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
E exiting: one or more models failed to load (--exit-on-error=true)
Terminal
python mundo/servicios.py arrancar triton
Salida
  $ python mundo/triton_dojo/servidor.py --model-repository=model_repository --http-port=8700 --model-control-mode=none --strict-readiness=true --exit-on-error=true --exit-timeout-secs=30 --disable-auto-complete-config
✓ triton listo en 0.4 s (PID 5216) · log: logs/triton.log
Terminal
cat logs/triton.log

La huella del engine que cargó queda en el log: es lo que revisa el check triton.

Salida
loading: classifier
warmup de classifier: 6 corridas en 84 ms
successfully loaded 'classifier' version 1 (2 instancia(s) KIND_CPU, model.onnx sha256 88bdea80ac92…)
+------------+---------+--------+
| Model      | Version | Status |
+------------+---------+--------+
| classifier | 1       | READY  |
+------------+---------+--------+
Terminal
curl -s localhost:8700/v2/models/classifier
curl -s -o /dev/null -w "/v2/health/ready → %{http_code}\n" localhost:8700/v2/health/ready
Salida
{"name":"classifier","versions":["1"],"platform":"onnxruntime_onnx","inputs":[{"name":"input","datatype":"FP32","shape":[-1,3,32,32]}],"outputs":[{"name":"logits","datatype":"FP32","shape":[-1,10]}]}
/v2/health/ready → 200
Terminal
python verificar.py config triton
Salida
✓ config      onnxruntime_onnx · batch hasta 32 · input [3, 32, 32] → logits [10] · ventana 2000 µs · fila REJECT a los 100 ms · 2 copias · warmup · en git
✓ triton      PID 5216 · listo · classifier versión 1 con el engine 88bdea80ac92… · su config = la de disco

2/2 en verde
Listo cuando: Triton (el del dojo) en el puerto 8700, listo, con classifier cargado desde el engine aprobado: entrada [-1, 3, 32, 32], salida [-1, 10], y la configuración que sirve es la de tu disco.
Ojo: Triton carga solo al arrancar (--model-control-mode=none): si cambias el config.pbtxt o el engine, python mundo/servicios.py reiniciar triton. El check triton avisa si corre con otra configuración que la de disco.
Conceptos de este paso
config.pbtxtTriton model configurationLa configuración de un modelo en Triton, en el formato de texto de protobuf: el backend, el batch máximo, la entrada y la salida, el batching, las copias y el warmup.Analogía, por qué importa y la trampa

AnalogíaLa ficha técnica de un aparato: el enchufe, el voltaje y cuántos puede atender a la vez.

Por qué importaTriton revisa la ficha contra el modelo y no carga si no cuadran. dims va sin el eje del batch cuando max_batch_size > 0: Triton le antepone −1.

TrampaPoner el batch dentro de dims ([1, 3, 32, 32]): el modelo no carga, y con --exit-on-error Triton ni arranca.

Batching dinámicodynamic batchingTriton espera un poco (aquí 2 ms) desde que llega una foto a que lleguen otras, y las corre juntas en un solo lote.Analogía, por qué importa y la trampa

AnalogíaUn elevador que espera unos segundos con la puerta abierta por si llega alguien más antes de subir.

Por qué importaUn lote de varias fotos cuesta casi lo mismo que una en la GPU: más fotos por segundo con la misma máquina. La espera es corta para que no se note en la latencia.

TrampaUna ventana larga para «llenar» lotes con poco tráfico: cada foto espera y nadie gana.

Política de la filaqueue policyLo que Triton hace con una foto que esperó demasiado en su fila sin entrar al modelo: con REJECT, la saca y contesta error (aquí, a los 100 ms).Analogía, por qué importa y la trampa

AnalogíaUn restaurante que, en vez de dejar crecer la fila de la puerta, le avisa al que lleva mucho esperando que mejor vaya a otro lado.

Por qué importaUna foto que ya esperó 100 ms llegaría tarde de todas formas: correrla gasta GPU en una respuesta que nadie va a ver. Bajo sobrecarga, mejor errores rápidos que una fila que hace lentas a todas.

TrampaUna fila sin tope: bajo carga crece sin límite y todas las respuestas llegan tarde.

Copias del modelo y warmupinstance group / model warmupinstance_group carga varias copias del modelo para atender lotes en paralelo. model_warmup corre el modelo con datos de relleno antes de decir «listo».Analogía, por qué importa y la trampa

AnalogíaDos cocineros en la misma estufa, y prender los quemadores antes de abrir: la primera orden no paga el precalentado.

Por qué importaMientras una copia corre un lote, la otra recibe el siguiente. Y las primeras corridas pagan una preparación que no se repite: mejor antes de atender que en la foto de un cliente.

TrampaDecir «listo» antes del warmup: las primeras requests después de cada despliegue salen lentas.

4Revisar cada foto, de lo barato a lo carorevision.py rechaza cada foto mala con su código antes de gastar en ella, y prepara las buenas con el preprocess compartido.

Siete revisiones, en orden de costo: el tipo (415), el Content-Length (413 sin leer el body), el tamaño real al leer en pedazos (413), el body vacío (400), los píxeles leídos del encabezado (413, sin decodificar), la proporción (400) y al final el decode (400 si está corrupta o cortada). Lo bueno pasa por preprocess.py, el mismo del entrenamiento: endereza por EXIF, convierte a RGB, redimensiona, recorta y normaliza.

Pythongateway/app/revision.py
"""La revisión de cada foto, de lo más barato a lo más caro. Cada rechazo lleva su código HTTP.

Contrato:
- Rechazo(codigo, motivo): la excepción de todo lo que se rechaza; el gateway la convierte en la respuesta.
- revisar_tipo(content_type, tipos): 415 si no es uno de los tipos de gateway.yaml (ignora «; charset=…»).
- revisar_largo(content_length, max_bytes): 413 si el header Content-Length dice más que max_bytes, sin leer el body.
  Si el header no viene, no decide nada.
- leer_body(request, max_bytes): lee el body en pedazos y corta con 413 en cuanto pasa de max_bytes (el header puede
  mentir o no venir). Si quien llama se va a media subida, deja pasar ClientDisconnect (el gateway contesta 499).
- revisar_imagen(data, max_pixeles, max_proporcion): 400 si está vacía; abre SOLO el encabezado (Image.open no
  decodifica los píxeles) y da 400 si Pillow no la reconoce, 413 si ancho × alto pasa de max_pixeles y 400 si el lado
  largo pasa de max_proporcion veces el corto. Devuelve (ancho, alto).
- preparar(data): el decode y el preprocess del paquete compartido (preprocess.py, el mismo del entrenamiento). Si el
  archivo está corrupto o cortado, 400. Devuelve float32 [3, 32, 32].
- Image.MAX_IMAGE_PIXELS se fija en max_pixeles al arrancar: la red propia de Pillow, de respaldo.
"""
from __future__ import annotations

import io

import numpy as np
from PIL import Image, UnidentifiedImageError

from . import preprocess


class Rechazo(Exception):
    def __init__(self, codigo: int, motivo: str, reintentar: bool = False):
        super().__init__(motivo)
        self.codigo, self.motivo, self.reintentar = codigo, motivo, reintentar


def revisar_tipo(content_type: str | None, tipos: list[str]) -> str:
    tipo = (content_type or "").split(";")[0].strip().lower()
    if tipo not in tipos:
        raise Rechazo(415, f"tipo {tipo or '(sin Content-Type)'}: solo {', '.join(tipos)}")
    return tipo


def revisar_largo(content_length: str | None, max_bytes: int) -> None:
    if content_length is None:
        return
    try:
        n = int(content_length)
    except ValueError:
        raise Rechazo(400, f"Content-Length no es un número: {content_length!r}") from None
    if n > max_bytes:
        raise Rechazo(413, f"Content-Length {n} B: el máximo es {max_bytes} B")


async def leer_body(request, max_bytes: int) -> bytes:
    partes, n = [], 0
    async for trozo in request.stream():
        n += len(trozo)
        if n > max_bytes:
            raise Rechazo(413, f"el body pasa de {max_bytes} B (se cortó al leer)")
        partes.append(trozo)
    return b"".join(partes)


def revisar_imagen(data: bytes, max_pixeles: int, max_proporcion: float) -> tuple[int, int]:
    if not data:
        raise Rechazo(400, "body vacío")
    try:
        with Image.open(io.BytesIO(data)) as im:     # solo el encabezado: el ancho y el alto, sin decodificar
            w, h = im.size
    except Image.DecompressionBombError:
        raise Rechazo(413, f"más de {max_pixeles:,} píxeles (Pillow)") from None
    except (UnidentifiedImageError, OSError, ValueError):
        raise Rechazo(400, "no es una imagen que se pueda leer") from None
    if w * h > max_pixeles:
        raise Rechazo(413, f"{w} × {h} = {w * h:,} píxeles: el máximo es {max_pixeles:,}")
    if max(w, h) > max_proporcion * min(w, h):
        raise Rechazo(400, f"{w} × {h}: el lado largo pasa de {max_proporcion:g} veces el corto")
    return w, h


def preparar(data: bytes) -> np.ndarray:
    try:
        return preprocess.preprocess(data)
    except (OSError, ValueError, SyntaxError, Image.DecompressionBombError) as e:
        raise Rechazo(400, f"no se pudo decodificar la imagen ({type(e).__name__})") from None

Image.open lee solo el encabezado: por eso el PNG de 48 MP se rechaza sin gastar los cientos de MB de su decode.

Terminal
python -c "…revisa cada foto de fotos-raras/ con revision.py…"

Sin servidor todavía: solo las funciones. La foto girada da el mismo tensor de [3, 32, 32] porque el preprocess la endereza.

Salida
tenis.jpg           1,278 B · 56 × 56 → tensor [3, 32, 32]
tenis.webp            548 B · 56 × 56 → tensor [3, 32, 32]
tenis-girada.jpg    1,323 B · 56 × 56 → tensor [3, 32, 32]
documento.pdf          77 B → 415 tipo application/pdf: solo image/jpeg, image/png, image/webp
vacia.jpg               0 B → 400 body vacío
gigante.png       139,857 B → 413 8000 × 6000 = 48,000,000 píxeles: el máximo es 40,000,000
tira.png              166 B → 400 1 × 4000: el lado largo pasa de 8 veces el corto
corrupta.jpg        2,020 B → 400 no es una imagen que se pueda leer
cortada.jpg           639 B → 400 no se pudo decodificar la imagen (OSError)
Listo cuando: Las fotos buenas salen como tensor [3, 32, 32]; el PDF da 415, el PNG de 48 MP 413, y la vacía, la tira, la corrupta y la cortada 400.
Ojo: El paso de bytes al leer existe porque el header puede mentir o no venir: lo prueba el check rechazos mandando 11 MiB sin Content-Length.
Concepto de este paso
Revisar de lo barato a lo caroinput validation orderLas revisiones de cada foto van ordenadas por costo: el tipo (comparar un texto), el tamaño anunciado (un header), el tamaño real (leer), los píxeles (el encabezado), la forma y al final el decode.Analogía, por qué importa y la trampa

AnalogíaEn la puerta de un concierto se revisa el boleto antes que la bolsa, y la bolsa antes que el detector de metales.

Por qué importaUna foto que falla lo barato no gasta nada en lo caro, y cada rechazo lleva su código: 415, 413 o 400. La defensa contra una bomba de descompresión (un PNG de 48 MP en negro pesa ≈ 140 KB y decodificado ocupa cientos de MB) es leer el ancho y el alto del encabezado con Image.open, sin decodificar, y rechazar por píxeles; MAX_IMAGE_PIXELS de Pillow queda de respaldo.

TrampaConfiar en Content-Length (puede mentir o no venir: el corte de verdad es al leer, en pedazos), o revisar solo los bytes y creer que con eso basta.

5El gateway: arranque, salud y classifyEl gateway arranca solo si todo cuadra, contesta /healthz y /readyz, y classify responde lo mismo que el engine aprobado.

crear_app() lee las reglas y revisa la cadena de plazos. El lifespan lee la ficha (y la huella de sus labels), crea UN cliente de Triton con su pool de conexiones, le pide la metadata del modelo y revisa que la entrada, la salida y el número de logits sean los de la ficha: si no, no arranca. classify revisa, decodifica en un hilo con el semáforo, llama a Triton con plazo y el tensor en binario, aplica el softmax estable con su guardia y contesta con model_version, las predicciones y X-Request-ID.

Pythongateway/app/main.py
"""El gateway de classifier: recibe la foto, la revisa, la prepara, le pide los logits a Triton con plazo y contesta.

    python mundo/servicios.py arrancar gateway       # uvicorn app.main:app --app-dir gateway --port 8701 --workers 1 …

Contrato:
- crear_app(triton=None, reglas=None, modelo=None) devuelve la app; `app = crear_app()` es la que corre uvicorn.
  Las pruebas le pasan un Triton falso, sus reglas y su ficha del modelo.
- Las reglas salen de gateway.yaml (al crear la app). Si la cadena de plazos no va de mayor a menor
  (app > gateway > triton > fila_triton), no arranca.
- El lifespan, una vez y antes de atender: lee servir/modelo.json y revisa la huella de sus labels; crea UN cliente de
  Triton para todo el proceso (tritonclient.http.aio, con el pool de gateway.yaml); le pide a Triton la metadata del
  modelo y revisa que la entrada y la salida sean las de la ficha y que haya tantos logits como labels. Si algo no
  cuadra, el proceso no arranca. Al apagarse, cierra el cliente.
- GET /healthz: {"status": "ok"} si el proceso responde. No le pregunta a nadie más.
- GET /readyz: 200 si Triton dice que el modelo está listo dentro de listo_timeout_ms; si no, 503.
- GET /metrics: las métricas de Prometheus, con estos nombres (las alertas los buscan así):
  classifier_requests_total{code, source, model_version}, classifier_request_seconds (sin los 4xx),
  classifier_preprocess_seconds, classifier_inference_seconds, classifier_top1_score, classifier_image_bytes y
  classifier_requests_in_flight.
- POST /v1/classify?top_k=N (N de gateway.yaml; fuera de rango, 422 de FastAPI), con los bytes de la foto:
  · request_id del header X-Request-ID o uno nuevo; X-Client-Source (mobile, web, internal u other) solo para métricas;
    X-Caller-Id (en C01 sale del token que verificó el ALB).
  · La 17 en vuelo (en_vuelo de gateway.yaml) recibe 503 + Retry-After: 1 al instante, sin leer el body.
  · La revisión de revision.py, en orden: 415, 413 por header, 413 al leer, 400 vacía, 413 por píxeles, 400 por forma.
  · El decode, en un hilo, con un semáforo de `decodes` lugares; quien espera más de espera_cpu_ms recibe 503 +
    Retry-After: 1. Si el decode falla, 400.
  · Triton con plazo min(triton, lo que le queda a la request de su plazo gateway); si ya no queda, 504 sin llamar.
    Se corta con asyncio.wait_for (el `timeout` de infer() es otra cosa: un tiempo para la fila del servidor).
    Triton no contesta a tiempo: 504. Sin conexión: 503 + Retry-After: 1. Triton contesta con error: 503. Sin reintentos.
  · Logits no finitos: 500, nunca un 200 con basura. Softmax estable (restando el máximo), top_k y labels.
  · 200: {"model_version", "predictions": [{"label", "score" (4 decimales)}], "latency_ms"}.
  · Quien llama se fue a media subida: 499.
- Toda respuesta lleva X-Request-ID (también los errores, el 422 y el 405).
- Una línea de JSON por request en stdout (en un finally), también para el 422, el 499 y el 405: request_id, caller,
  source, model_version, top5 [[índice, score]], ms {pre, triton, post, total}, bytes, sha256 (12 caracteres), status y,
  si falló, error. Nunca la foto.
"""
from __future__ import annotations

import asyncio
import hashlib
import json
import sys
import time
import uuid
import warnings
from contextlib import asynccontextmanager
from pathlib import Path

import aiohttp
import numpy as np
import yaml
from fastapi import FastAPI, Query, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse, Response
from prometheus_client import CONTENT_TYPE_LATEST, CollectorRegistry, Counter, Gauge, Histogram, generate_latest
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.requests import ClientDisconnect
from tritonclient.http.aio import InferenceServerClient, InferInput, InferRequestedOutput
from tritonclient.utils import InferenceServerException

from .revision import Rechazo, leer_body, preparar, revisar_imagen, revisar_largo, revisar_tipo

RAIZ = Path(__file__).resolve().parents[2]
FUENTES = {"mobile", "web", "internal", "other"}


def leer_reglas(p: Path = RAIZ / "gateway.yaml") -> dict:
    r = yaml.safe_load(p.read_text())
    pl = r["plazos_ms"]
    if not pl["app"] > pl["gateway"] > pl["triton"] > pl["fila_triton"] > 0:
        raise RuntimeError(f"gateway.yaml: la cadena de plazos tiene que bajar (app > gateway > triton > fila_triton) "
                           f"y es {pl['app']} > {pl['gateway']} > {pl['triton']} > {pl['fila_triton']}")
    return r


def leer_modelo(p: Path = RAIZ / "servir" / "modelo.json") -> dict:
    if not p.exists():
        raise RuntimeError("falta servir/modelo.json: python servir/armar.py")
    m = json.loads(p.read_text())
    huella = hashlib.sha256((json.dumps(m["labels"], ensure_ascii=False) + "\n").encode()).hexdigest()
    if huella != m["labels_sha256"]:
        raise RuntimeError(f"servir/modelo.json: los labels tienen huella {huella[:12]}… y la ficha dice {m['labels_sha256'][:12]}…")
    return m


def metricas(registro: CollectorRegistry) -> dict:
    ms = (0.005, 0.01, 0.02, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.5, 1.0)
    return {
        "requests": Counter("classifier_requests_total", "Requests por código, fuente y versión del modelo",
                            ["code", "source", "model_version"], registry=registro),
        "latencia": Histogram("classifier_request_seconds", "Latencia total (sin los 4xx)", buckets=ms, registry=registro),
        "pre": Histogram("classifier_preprocess_seconds", "Decode y preprocess", buckets=ms, registry=registro),
        "inferencia": Histogram("classifier_inference_seconds", "La llamada a Triton", buckets=ms, registry=registro),
        "top1": Histogram("classifier_top1_score", "El score de la primera sugerencia",
                          buckets=(0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95, 0.99), registry=registro),
        "bytes": Histogram("classifier_image_bytes", "Tamaño de la foto",
                           buckets=(1e3, 1e4, 1e5, 3e5, 1e6, 3e6, 1e7), registry=registro),
        "en_vuelo": Gauge("classifier_requests_in_flight", "Requests adentro ahora", registry=registro),
    }


def crear_app(triton=None, reglas: dict | None = None, modelo: dict | None = None) -> FastAPI:
    r = reglas or leer_reglas()
    lim, pl, tr, ct = r["limites"], r["plazos_ms"], r["triton"], r["contrato"]
    from PIL import Image

    Image.MAX_IMAGE_PIXELS = lim["max_pixeles"]          # la red de Pillow: avisa arriba de esto, se niega arriba del doble
    warnings.simplefilter("ignore", Image.DecompressionBombWarning)   # el aviso sobra: el paso de píxeles ya dio 413

    @asynccontextmanager
    async def lifespan(app: FastAPI):
        m = modelo or leer_modelo()
        cliente = triton or InferenceServerClient(url=tr["url"], conn_limit=tr["conexiones"])
        try:
            meta = await cliente.get_model_metadata(tr["modelo"])
        except Exception as e:  # noqa: BLE001
            await cliente.close()
            raise RuntimeError(f"no pude leer la metadata de '{tr['modelo']}' en Triton ({tr['url']}): {e}") from None
        ent, sal = meta["inputs"][0], meta["outputs"][0]
        if ent["name"] != m["entrada"]["nombre"] or ent["shape"] != m["entrada"]["forma"] or sal["name"] != m["salida"]["nombre"]:
            await cliente.close()
            raise RuntimeError(f"Triton sirve {ent['name']} {ent['shape']} → {sal['name']} y la ficha dice "
                               f"{m['entrada']['nombre']} {m['entrada']['forma']} → {m['salida']['nombre']}")
        if sal["shape"][-1] != len(m["labels"]):
            await cliente.close()
            raise RuntimeError(f"el modelo da {sal['shape'][-1]} logits y hay {len(m['labels'])} labels")
        app.state.modelo, app.state.triton = m, cliente
        app.state.cpu = asyncio.Semaphore(lim["decodes"])
        app.state.en_vuelo = 0
        print(f"gateway listo · {m['model_version']} · {len(m['labels'])} labels · Triton {tr['url']}", file=sys.stderr, flush=True)
        yield
        await cliente.close()

    app = FastAPI(lifespan=lifespan, title="classifier gateway")
    registro = CollectorRegistry()                       # uno por app: las pruebas crean varias en el mismo proceso
    mt = metricas(registro)

    def anotar(ev: dict, status: int, fuente: str, version: str, t0: float) -> None:
        ev["status"] = status
        ev.setdefault("ms", {})["total"] = round((time.monotonic() - t0) * 1000, 1)
        print(json.dumps(ev, ensure_ascii=False), flush=True)
        mt["requests"].labels(str(status), fuente, version).inc()
        if not 400 <= status < 500:                          # un 415 tarda microsegundos: no baja el p99 de nadie
            mt["latencia"].observe(time.monotonic() - t0)

    def contexto(request: Request) -> tuple[str, dict, str]:
        rid = request.headers.get("x-request-id") or uuid.uuid4().hex
        fuente = request.headers.get("x-client-source", "other")
        fuente = fuente if fuente in FUENTES else "other"
        version = getattr(request.app.state, "modelo", {}).get("model_version", "?")
        ev = {"request_id": rid, "caller": request.headers.get("x-caller-id", "desconocido"), "source": fuente,
              "model_version": version}
        return rid, ev, fuente

    @app.exception_handler(RequestValidationError)
    async def invalida(request: Request, exc: RequestValidationError):        # el 422 pasa antes de classify
        t0 = time.monotonic()
        rid, ev, fuente = contexto(request)
        ev["error"] = "; ".join(f"{'.'.join(map(str, e['loc']))}: {e['msg']}" for e in exc.errors())
        anotar(ev, 422, fuente, ev["model_version"], t0)
        return JSONResponse({"error": ev["error"], "request_id": rid}, 422, headers={"X-Request-ID": rid})

    @app.exception_handler(StarletteHTTPException)
    async def http_error(request: Request, exc: StarletteHTTPException):      # 404, 405
        t0 = time.monotonic()
        rid, ev, fuente = contexto(request)
        ev["error"] = str(exc.detail)
        anotar(ev, exc.status_code, fuente, ev["model_version"], t0)
        return JSONResponse({"error": exc.detail, "request_id": rid}, exc.status_code,
                            headers={"X-Request-ID": rid, **(exc.headers or {})})

    @app.get("/healthz")
    async def healthz():
        return {"status": "ok"}

    @app.get("/readyz")
    async def readyz(request: Request):
        try:
            listo = await asyncio.wait_for(request.app.state.triton.is_model_ready(tr["modelo"]), tr["listo_timeout_ms"] / 1000)
        except Exception:  # noqa: BLE001 — sin respuesta a tiempo o sin conexión: no listo
            listo = False
        return JSONResponse({"status": "ready" if listo else "not ready"}, 200 if listo else 503)

    @app.get("/metrics")
    async def metrics():
        return Response(generate_latest(registro), media_type=CONTENT_TYPE_LATEST)

    @app.post(ct["ruta"])
    async def classify(request: Request,
                       top_k: int = Query(ct["top_k"]["defecto"], ge=ct["top_k"]["min"], le=ct["top_k"]["max"])):
        t0 = time.monotonic()
        st = request.app.state
        rid, ev, fuente = contexto(request)
        version = st.modelo["model_version"]
        hdr = {"X-Request-ID": rid}
        ms = ev["ms"] = {}
        if st.en_vuelo >= lim["en_vuelo"]:                   # load shedding: rechazar cuesta microsegundos
            ev["error"] = f"{lim['en_vuelo']} requests en vuelo"
            anotar(ev, 503, fuente, version, t0)
            return JSONResponse({"error": ev["error"], "request_id": rid}, 503, headers={**hdr, "Retry-After": "1"})
        st.en_vuelo += 1
        mt["en_vuelo"].inc()
        status = 500
        try:
            revisar_tipo(request.headers.get("content-type"), ct["tipos"])
            revisar_largo(request.headers.get("content-length"), lim["max_bytes"])
            data = await leer_body(request, lim["max_bytes"])
            ev["bytes"], ev["sha256"] = len(data), hashlib.sha256(data).hexdigest()[:12]
            mt["bytes"].observe(len(data))
            revisar_imagen(data, lim["max_pixeles"], lim["max_proporcion"])
            try:
                await asyncio.wait_for(st.cpu.acquire(), lim["espera_cpu_ms"] / 1000)
            except TimeoutError:
                raise Rechazo(503, f"sin lugar de decode en {lim['espera_cpu_ms']} ms", reintentar=True) from None
            try:
                t = time.monotonic()
                x = await run_in_threadpool(preparar, data)      # en un hilo: el event loop sigue atendiendo
                ms["pre"] = round((time.monotonic() - t) * 1000, 1)
                mt["pre"].observe(time.monotonic() - t)
            finally:
                st.cpu.release()
            queda = pl["gateway"] / 1000 - (time.monotonic() - t0)
            if queda <= 0:
                raise Rechazo(504, f"se acabó el plazo de {pl['gateway']} ms antes de llamar a Triton")
            plazo = min(pl["triton"] / 1000, queda)
            entrada = InferInput(st.modelo["entrada"]["nombre"], [1, *x.shape], "FP32")
            entrada.set_data_from_numpy(x[None], binary_data=True)
            salida = st.modelo["salida"]["nombre"]
            t = time.monotonic()
            try:
                res = await asyncio.wait_for(
                    st.triton.infer(tr["modelo"], [entrada], outputs=[InferRequestedOutput(salida, binary_data=True)],
                                    request_id=rid), plazo)
            except TimeoutError:
                raise Rechazo(504, f"Triton no contestó en {plazo * 1000:.0f} ms") from None
            except InferenceServerException as e:
                raise Rechazo(503, f"Triton: {e.message()}") from None
            except (aiohttp.ClientError, OSError) as e:
                raise Rechazo(503, f"sin conexión con Triton ({type(e).__name__})", reintentar=True) from None
            finally:
                ms["triton"] = round((time.monotonic() - t) * 1000, 1)
            mt["inferencia"].observe(time.monotonic() - t)
            t = time.monotonic()
            z = res.as_numpy(salida)[0].astype(np.float64)
            if not np.all(np.isfinite(z)):
                raise Rechazo(500, "logits no finitos")
            e = np.exp(z - z.max())                               # softmax estable: restar el máximo no cambia nada
            p = e / e.sum()
            orden = np.argsort(-p, kind="stable")
            labels = st.modelo["labels"]
            ev["top5"] = [[int(i), round(float(p[i]), 4)] for i in orden[:5]]
            mt["top1"].observe(float(p[orden[0]]))
            ms["post"] = round((time.monotonic() - t) * 1000, 1)
            status = 200
            return JSONResponse({"model_version": version,
                                 "predictions": [{"label": labels[i], "score": round(float(p[i]), 4)} for i in orden[:top_k]],
                                 "latency_ms": round((time.monotonic() - t0) * 1000, 1)}, headers=hdr)
        except Rechazo as e:
            status, ev["error"] = e.codigo, e.motivo
            return JSONResponse({"error": e.motivo, "request_id": rid}, e.codigo,
                                headers={**hdr, **({"Retry-After": "1"} if e.reintentar else {})})
        except ClientDisconnect:
            status, ev["error"] = 499, "quien llama cerró la conexión a media subida"
            return Response(status_code=499, headers=hdr)
        except Exception as e:  # noqa: BLE001 — un error del propio código: 500, y que quede en el log
            status, ev["error"] = 500, f"{type(e).__name__}: {str(e)[:200]}"
            return JSONResponse({"error": "error interno", "request_id": rid}, 500, headers=hdr)
        finally:
            st.en_vuelo -= 1
            mt["en_vuelo"].dec()
            anotar(ev, status, fuente, version, t0)

    return app


app = crear_app()

crear_app(triton=…, reglas=…, modelo=…) existe para las pruebas: les deja pasar un Triton falso.

Terminal
python mundo/servicios.py arrancar gateway
Salida
  $ python -m uvicorn app.main:app --app-dir gateway --host 127.0.0.1 --port 8701 --workers 1 --timeout-keep-alive 75 --timeout-graceful-shutdown 20 --no-access-log
✓ gateway listo en 6.2 s (PID 5266) · log: logs/gateway.log
Terminal
python mundo/servicios.py estado
Salida
triton   PID 5216 · ps Ss · /v2/health/live 200 · /v2/health/ready 200
gateway  PID 5266 · ps Ss · /healthz 200 · /readyz 200
Terminal
curl -s -i -X POST "localhost:8701/v1/classify?top_k=3" \
  -H "Content-Type: image/jpeg" -H "X-Request-ID: ana-0001" -H "X-Client-Source: mobile" \
  --data-binary @fotos-raras/tenis.jpg
Salida
HTTP/1.1 200 OK
x-request-id: ana-0001
content-length: 180
content-type: application/json

{"model_version":"miniresnet-2026-10-01","predictions":[{"label":"tenis","score":0.9559},{"label":"sandalias","score":0.0371},{"label":"botines","score":0.0056}],"latency_ms":20.7}
Terminal
curl -s localhost:8701/healthz
curl -s localhost:8701/readyz
Salida
{"status":"ok"}  ← /healthz 200
{"status":"ready"}  ← /readyz 200
Terminal
python verificar.py salud responde

responde manda 200 fotos del examen por HTTP y compara cada top-1 con el engine aprobado corrido aquí mismo.

Salida
✓ salud       /healthz {"status": "ok"} · /readyz 200 · /metrics con sus 6 nombres
✓ responde    200 fotos del examen por HTTP: 200, el mismo top-1 que el engine aprobado (score ± 0.0000) · miniresnet-2026-10-01 · X-Request-ID · top_k 1/3/10 · 972 fotos/s con 8 a la vez

2/2 en verde
Terminal
curl -s localhost:8700/metrics | grep -E "^nv_inference_(count|exec_count)"

Las métricas de Triton: cuántas fotos y en cuántos lotes. Es el precálculo «batch» medido.

Salida
nv_inference_count{model="classifier",version="1"} 204
nv_inference_exec_count{model="classifier",version="1"} 70
204 fotos en 70 batches: 2.91 fotos por batch en promedio
Terminal
ps -o rss= -p $(cat logs/gateway.pid)
Salida
el gateway ocupa 93 MiB (RSS) sin requests
Listo cuando: /healthz y /readyz en 200, las 6 métricas en /metrics, y 200 fotos del examen por HTTP con el mismo top-1 que el engine aprobado (≈ 972 fotos/s con 8 a la vez).
Ojo: La primera foto de cada formato tarda más (Pillow carga su decodificador la primera vez): por eso C01 calienta también el gateway antes de decir «listo».
Conceptos de este paso
uvicorn, ASGI y FastAPIASGI server / frameworkuvicorn es el servidor que abre el puerto y corre el event loop; ASGI es el contrato entre servidor y aplicación; FastAPI es el armazón donde escribes tus rutas.Analogía, por qué importa y la trampa

AnalogíaEl local, el reglamento de la cocina y la carta: cada uno cambia sin tocar a los otros.

Por qué importaCon --workers 1, la concurrencia sale del event loop y del threadpool; la capacidad, de más copias. Cada flag de uvicorn es una decisión (keep-alive, apagado ordenado, sin log de acceso).

TrampaHacer trabajo de CPU (decodificar) directo en la ruta async: congela el event loop y nadie más avanza.

Lifespanlifespan eventsLa función que corre una vez al arrancar, antes de la primera request, y una vez al apagarse.Analogía, por qué importa y la trampa

AnalogíaAbrir el local: revisar que la cocina tenga gas y que el menú corresponda antes de dejar pasar al primer cliente.

Por qué importaAhí se crea UN cliente de Triton para todo el proceso y se revisa lo que no puede fallar: que los labels sean los del modelo y que Triton sirva la forma esperada. Si algo no cuadra, el proceso no arranca.

TrampaCrear un cliente nuevo por request: cada foto abre su conexión y el pool no sirve.

Vivo y listoliveness / readiness/healthz contesta «sigo vivo» sin preguntarle a nadie. /readyz contesta «mándame tráfico» solo si Triton dice que el modelo está listo, con un tope de tiempo.Analogía, por qué importa y la trampa

Analogía«¿Respiras?» contra «¿puedes atender?»: un mesero con la cocina cerrada respira, pero no debe tomar pedidos.

Por qué importaSi /healthz falla, Kubernetes reinicia la copia; si /readyz falla, la saca del reparto sin reiniciarla. Si /healthz preguntara por Triton, una caída de Triton reiniciaría a todos los gateways y no arreglaría nada.

TrampaUn /readyz sin tope: con Triton trabado, la pregunta misma se queda colgada.

Softmax estable y la guardianumerically stable softmaxAntes de sacar la exponencial, a todos los logits se les resta el más grande: el resultado es el mismo y ninguna exponencial se desborda. Y si algún logit no es finito (NaN o infinito), 500.Analogía, por qué importa y la trampa

AnalogíaMedir alturas desde la azotea en lugar de desde el centro de la Tierra: las diferencias son las mismas y los números caben en la regla.

Por qué importaUn engine roto puede dar NaN. Sin la guardia, el error salta al convertir la respuesta en JSON, después de escribir el log: el log diría 200 y la app vería un 500.

TrampaContestar 200 con probabilidades de basura.

Precálculos
4

¿Cuántas fotos junta Triton en cada lote?

n_b = 1 + λ × v: la primera foto abre una ventana de v segundos y entran las que llegan en ella
Ver la cuenta
En C01250/s × 0.002 s en el pico; 500/s con una zona caída1.5 fotos por lote · 2 con una zona caída
En el dojo≈ 800/s × 0.002 s, con 8 clientes a la vez≈ 2.6 fotos por lote

Qué decides con esto. Con el tráfico de C01, los tamaños preferidos (16 y 32) casi nunca se alcanzan, y está bien: la ventana cuesta solo 2 ms. El lote crece solo cuando hay tráfico para llenarlo.

Terminalterminal · compruébalo en el kit
python -c "
for nombre, llegan in [('C01, una T4 en el pico (250/s)', 250), ('C01, una zona caída (500/s)', 500), ('dojo, verificar responde (≈ 800/s)', 800)]:
    print(f'{nombre}: 1 + {llegan} × 0.002 = {1 + llegan * 0.002:.1f} fotos por batch')"
Salida
C01, una T4 en el pico (250/s): 1 + 250 × 0.002 = 1.5 fotos por batch
C01, una zona caída (500/s): 1 + 500 × 0.002 = 2.0 fotos por batch
dojo, verificar responde (≈ 800/s): 1 + 800 × 0.002 = 2.6 fotos por batch

Lo confirmas en el paso 5: las métricas de Triton dicen 2.91 fotos por lote en promedio después de verificar.py responde.

5

¿Cuánto pesa lo que el gateway le manda a Triton?

tensor = canales × alto × ancho × 4 B (FP32), contra los bytes de la foto
Ver la cuenta
En C013 × 224 × 224 × 4 B contra una foto de ≈ 215 KB602 KB: ≈ 2.8 veces la foto
En el dojo3 × 32 × 32 × 4 B contra la foto de tenis de 1,278 B12 KB: ≈ 9.6 veces la foto

Qué decides con esto. Por eso el gateway manda el tensor en binario (la extensión binaria de Triton) y no como una lista de números en JSON, que pesaría varias veces más. Mandar el JPEG y decodificar en Triton ahorraría red, pero pondría trabajo de CPU y bytes hostiles en la máquina cara.

Terminalterminal · compruébalo en el kit
python -c "
for nombre, lado, foto in [('C01', 224, 214_836), ('dojo', 32, 1_278)]:
    t = 3 * lado * lado * 4
    print(f'{nombre}: tensor 3 × {lado} × {lado} × 4 B = {t:,} B · la foto pesa ≈ {foto:,} B · {t / foto:.1f} veces')"
Salida
C01: tensor 3 × 224 × 224 × 4 B = 602,112 B · la foto pesa ≈ 214,836 B · 2.8 veces
dojo: tensor 3 × 32 × 32 × 4 B = 12,288 B · la foto pesa ≈ 1,278 B · 9.6 veces
6El código de cada falla y los topesCada foto mala sale con su código, la 17 en vuelo recibe 503 al instante, y cada falla de Triton tiene su respuesta.

Con el gateway arriba, la tabla de códigos se prueba de verdad: cada foto rara con su código, el 422 de top_k fuera de rango (que FastAPI decide antes de classify, por eso lleva su propio manejador para dejar log), el 405 y el 499 de quien se va a media subida. Los topes y las fallas de Triton (lento, con error, caído, NaN) no se pueden provocar a voluntad con el servidor real: el check topes corre tu gateway dentro de su proceso con un Triton falso.

Terminal
for f in "tenis.png image/png" "documento.pdf application/pdf" …; do
  curl -s -X POST localhost:8701/v1/classify -H "Content-Type: $2" --data-binary @fotos-raras/$1
done
Salida
tenis.png      → {"model_version":"miniresnet-2026-10-01","predictions":[{"label":"tenis","score":0.9559},{"label":"sandalias","score":0.0371},{"label":"botines","score":0.0056},{"label":"bolsas","score":0.0006},{"label":"abrigos","score":0.0004}],"latency_ms":4.8}  [200]
documento.pdf  → {"error":"tipo application/pdf: solo image/jpeg, image/png, image/webp","request_id":"9f30bd3f88004592b0bf6059e1e4953b"}  [415]
vacia.jpg      → {"error":"body vacío","request_id":"905f13b9bcbd4cfbbf7d585973422516"}  [400]
gigante.png    → {"error":"8000 × 6000 = 48,000,000 píxeles: el máximo es 40,000,000","request_id":"a3b2fe4dff824b7c817a988f0127743c"}  [413]
tira.png       → {"error":"1 × 4000: el lado largo pasa de 8 veces el corto","request_id":"7b0b93d575ea4f789027c1ec91211fe6"}  [400]
corrupta.jpg   → {"error":"no es una imagen que se pueda leer","request_id":"f49e30b98281425da02effc8f06b3f3f"}  [400]
cortada.jpg    → {"error":"no se pudo decodificar la imagen (OSError)","request_id":"9c7e029eacf74616b795e5fb4d2e6d58"}  [400]
top_k=50       → {"error":"query.top_k: Input should be less than or equal to 10","request_id":"a44b5b08694749099b58934e36608cda"}  [422]
GET            → {"error":"Method Not Allowed","request_id":"c5691e687bbb458b8d2b43d86ccd776f"}  [405]
Terminal
python verificar.py rechazos topes
Salida
✓ rechazos    200 ×4 (jpeg, png, webp, girada) · 415 pdf · 400 vacía, tira, corrupta, cortada · 413 por píxeles, por header y al leer · 422 · 405 · 499 en el log
✓ topes       la 17 en vuelo → 503 al instante · Triton lento → 504 a los ≈ 150 ms · con error → 503 · caído → 503 + Retry-After · NaN → 500 · /readyz ≤ 0.5 s · /healthz no pregunta

2/2 en verde
Listo cuando: 200 en JPEG, PNG, WebP y la girada; 415, 413 (header, al leer y por píxeles), 400, 422, 405 y 499 en el log; la 17 en vuelo con 503 y Retry-After: 1; Triton lento 504, con error 503, caído 503 con Retry-After, NaN 500.
Ojo: Sin reintentos: con Triton sobrecargado, un segundo intento suma trabajo justo cuando ya sobra. La app tiene su plan B (el selector manual).
Conceptos de este paso
El código de cada fallaHTTP status codesLos 4xx son culpa de quien llama (400, 405, 413, 415, 422) y no cuentan contra la promesa de servicio; los 5xx son del sistema (500, 503, 504). El 499, de nginx, es «quien llama se fue».Analogía, por qué importa y la trampa

AnalogíaEn una paquetería: «tu caja venía rota» no es lo mismo que «se nos descompuso el camión».

Por qué importaLas alertas y el SLO cuentan los 5xx. Un 422 o un 499 mal clasificados como 5xx despiertan a alguien a las 3 de la mañana por un cliente que mandó mal los datos.

TrampaContestar 200 con un error adentro del JSON: nadie lo cuenta.

Semáforo y threadpoolsemaphore / threadpoolEl decode corre en un hilo aparte (run_in_threadpool) para no congelar el event loop, y un semáforo de 2 lugares deja decodificar a solo dos a la vez.Analogía, por qué importa y la trampa

AnalogíaUn probador con dos cabinas: los demás esperan afuera, y si esperan demasiado, se les dice que vuelvan luego.

Por qué importaUn decode de 40 MP ocupa ≈ 320 MB: con los 40 hilos que trae el threadpool por omisión, serían ≈ 13 GB. Quien espera más de 50 ms un lugar recibe 503 con Retry-After.

TrampaUna fila de CPU sin tope: solo produce respuestas que llegan cuando la app ya se rindió.

Tope de requests en vuelomax in-flight requests / load sheddingCuántas requests puede tener adentro una copia a la vez. La que llega con el tope lleno recibe 503 al instante, sin leer su body.Analogía, por qué importa y la trampa

AnalogíaEl cupo de un salón: el que llega con el salón lleno no entra, y se le dice en la puerta, no después de sentarlo.

Por qué importaRechazar cuesta microsegundos y protege la memoria y la latencia de las que ya están adentro. El número sale de la Ley de Little, recortado por la memoria del peor momento.

TrampaSubir el tope porque «la CPU está al 40 %»: el tope cuida la memoria del peor caso, no la CPU de hoy.

Precálculos
1

¿Cuánta memoria pide una copia del gateway en el peor momento?

pico = en vuelo × body máximo + decodes × píxeles máximos × 4 B × 2 copias + lo que ocupa el proceso
Ver la cuenta
En C0116 × 10 MiB + 2 × 40 MP × 4 B × 2 + ≈ 150 MiB≈ 160 + 610 + 150 ≈ 920 MiB: cabe en 1 GiB
En el dojolas mismas reglas; con 64 en vuelo y 8 decodes≈ 920 MiB · con 64 y 8: ≈ 3,200 MiB, más del triple

Qué decides con esto. Los topes salen de la memoria del peor caso, no de la CPU de hoy. Con 16 en vuelo y 2 decodes, una ráfaga de fotos de 40 MP todavía cabe en 1 GiB; con 64 y 8, el proceso muere por memoria (OOM) y se lleva a todas las requests que tenía adentro.

Terminalterminal · compruébalo en el kit
python -c "
MiB = 2**20
for nombre, en_vuelo, decodes in [('C01 y el dojo (gateway.yaml)', 16, 2), ('con 64 en vuelo y 8 decodes', 64, 8)]:
    bodies = en_vuelo * 10 * MiB
    decode = decodes * 40_000_000 * 4 * 2
    print(f'{nombre}: bodies {en_vuelo} × 10 MiB = {bodies / MiB:,.0f} MiB · decodes {decodes} × 40 MP × 4 B × 2 copias = {decode / MiB:,.0f} MiB · total {(bodies + decode) / MiB:,.0f} MiB + el proceso')"
Salida
C01 y el dojo (gateway.yaml): bodies 16 × 10 MiB = 160 MiB · decodes 2 × 40 MP × 4 B × 2 copias = 610 MiB · total 770 MiB + el proceso
con 64 en vuelo y 8 decodes: bodies 64 × 10 MiB = 640 MiB · decodes 8 × 40 MP × 4 B × 2 copias = 2,441 MiB · total 3,081 MiB + el proceso

Lo confirmas en el paso 5: el gateway ocupa 93 MiB sin requests (C01 redondea a ≈ 150 MiB), y el check reglas hace la misma cuenta con gateway.yaml.

2

¿Cuántas requests hay adentro de una copia a la vez?

en vuelo = llegadas por segundo × lo que dura cada una (la Ley de Little)
Ver la cuenta
En C01100/s × 50 ms; si se alargan, 100/s × 200 ms5 normalmente · 20 en el caso lento → tope de 16, recortado por la memoria
En el dojoverificar manda ≈ 972/s con 8 a la vez, de ≈ 10 ms cada una≈ 8 adentro: nunca toca el tope de 16

Qué decides con esto. El tope tiene que dejar pasar el tráfico normal con margen y rechazar al instante lo que de todas formas llegaría tarde. Rechazar la 17 cuesta microsegundos; aceptarla arriesga la memoria y alarga a todas las demás.

Terminalterminal · compruébalo en el kit
python -c "
for nombre, llegan, dura in [('C01, una copia, requests normales', 100, 0.050), ('C01, una copia, requests lentas', 100, 0.200), ('dojo, verificar responde (8 a la vez)', 800, 0.010)]:
    print(f'{nombre}: {llegan}/s × {dura * 1000:.0f} ms = {llegan * dura:.0f} en vuelo')"
Salida
C01, una copia, requests normales: 100/s × 50 ms = 5 en vuelo
C01, una copia, requests lentas: 100/s × 200 ms = 20 en vuelo
dojo, verificar responde (8 a la vez): 800/s × 10 ms = 8 en vuelo

Lo confirmas en el paso 6: el check topes manda 20 a la vez contra un Triton lento y entran 16.

7Los plazos, con Triton congeladoCon Triton congelado de verdad, classify sale con 504 a los ≈ 150 ms, /readyz con 503 y /healthz sigue en 200.

kill -STOP congela el proceso de Triton: acepta conexiones pero no contesta, como una GPU trabada. El gateway corta la llamada con asyncio.wait_for a los 150 ms (o a lo que le quede a la request) y contesta 504; /readyz pregunta con su propio tope y dice 503 (Kubernetes sacaría esta copia del reparto); /healthz no le pregunta a nadie y sigue en 200 (reiniciar el gateway no arreglaría a Triton).

Terminal
kill -STOP $(cat logs/triton.pid)
curl -s -o /dev/null -w "classify → %{http_code} en %{time_total} s\n" -X POST localhost:8701/v1/classify \
  -H "Content-Type: image/jpeg" --data-binary @fotos-raras/tenis.jpg
curl -s localhost:8701/readyz
curl -s localhost:8701/healthz
python mundo/servicios.py estado
kill -CONT $(cat logs/triton.pid)

ps dice T: el proceso está detenido por una señal. kill -CONT lo despierta.

Salida
classify → 504 en 0.152906 s
{"status":"not ready"} ← /readyz 503 en 0.502958 s
{"status":"ok"} ← /healthz 200
triton   PID 5216 · ps Ts (congelado: SIGSTOP) · /v2/health/live sin respuesta en 1 s · /v2/health/ready sin respuesta en 1 s
gateway  PID 5266 · ps Ss · /healthz 200 · /readyz 503
Terminal
grep '"status": 504' logs/gateway.log | tail -1

ms.triton dice dónde se fue el tiempo.

Salida
{"request_id": "27103dce61b540b39dd85dc780770922", "caller": "desconocido", "source": "other", "model_version": "miniresnet-2026-10-01", "ms": {"pre": 0.5, "triton": 150.8, "total": 151.5}, "bytes": 1278, "sha256": "a3620aaeb761", "error": "Triton no contestó en 150 ms", "status": 504}
Terminal
python verificar.py plazos
Salida
✓ plazos      Triton congelado 2 s: classify 504 a los 154 ms · /readyz 503 en 504 ms · /healthz 200 · al despertar, 200

1/1 en verde
Listo cuando: 504 a los ≈ 153 ms, /readyz 503 dentro de su medio segundo, /healthz 200, y al despertar a Triton todo vuelve a 200.
Ojo: El parámetro timeout de infer() no es un plazo del cliente: es un tiempo que se le pide a la fila de Triton. Con una red cortada, solo asyncio.wait_for corta a tiempo.
Concepto de este paso
La cadena de plazosdeadline propagationCada eslabón espera menos que el de afuera: la app 300 ms, el gateway 250, la llamada a Triton 150 (o lo que le quede a la request, si es menos) y la fila de Triton 100.Analogía, por qué importa y la trampa

AnalogíaMuñecas rusas de tiempo: la de adentro siempre cabe en la de afuera, así que se rinde primero y la de afuera todavía alcanza a avisar.

Por qué importaAsí cada falla se contesta a tiempo con su código, en vez de que la app se rinda sin saber qué pasó. El plazo se corta con asyncio.wait_for: el timeout de infer() es otra cosa (un tiempo para la fila del servidor).

TrampaEstirar el plazo de Triton por encima del de la request «porque a veces tarda»: la app se rinde primero y el gateway sigue esperando.

Precálculo
3

¿Cuánto plazo recibe la llamada a Triton?

R = P − g (lo que le queda a la request) · T_e = min(T, R); si R ≤ 0, 504 sin llamar
Ver la cuenta
En C01P = 250, T = 150 · Ana gastó 9 ms · la subida lenta, 206 msAna: 150 ms · la lenta: 44 ms
En el dojolas mismas reglas · una subida de 240 ms4 ms: sale con 504 aunque Triton esté sano

Qué decides con esto. Con un tope fijo de 150 ms, la de la subida lenta esperaría hasta los 356 ms, cuando la app ya mostró su selector manual. Con min(T, R) contesta a los 250 ms, a tiempo.

Terminalterminal · compruébalo en el kit
python -c "
P, T = 250, 150
for nombre, subir, cpu, decode in [('Ana', 3, 0, 6), ('subida lenta', 200, 0, 6), ('subida de 240 ms', 240, 0, 6)]:
    g = subir + cpu + decode
    print(f'{nombre}: gastado {g} ms · queda {P - g} ms · plazo de Triton min({T}, {P - g}) = {min(T, P - g)} ms')"
Salida
Ana: gastado 9 ms · queda 241 ms · plazo de Triton min(150, 241) = 150 ms
subida lenta: gastado 206 ms · queda 44 ms · plazo de Triton min(150, 44) = 44 ms
subida de 240 ms: gastado 246 ms · queda 4 ms · plazo de Triton min(150, 4) = 4 ms

Lo confirmas en el paso 7: con Triton congelado, classify sale con 504 a los 153 ms.

8El log, las métricas y las pruebasUna línea de JSON por request (también el 422 y el 499), las métricas con sus nombres y sin los 4xx en la latencia, y las pruebas en verde sin Triton.

La línea de log se escribe en un finally: sale pase lo que pase, con el mismo request_id de la respuesta. Las métricas viven en un registro por app. Las pruebas usan un Triton falso con los mismos métodos y excepciones que el real, que además revisa el nombre, el tipo y la forma del tensor; cubren cada fila de la tabla de códigos, los topes, el plazo, la salud y el log.

Pythongateway/tests/conftest.py
"""Lo que comparten las pruebas: un Triton falso, las reglas, la ficha del modelo y fotos hechas al vuelo.

Contrato:
- TritonFalso tiene los mismos métodos asíncronos que el cliente real (get_model_metadata, is_model_ready, infer,
  close) y lanza las mismas excepciones, pero contesta lo que la prueba le pida: logits, una demora, un error, «no
  listo». Además revisa el nombre, el tipo y la forma del tensor que le mandan, como lo haría Triton.
- No abre ningún puerto: las pruebas corren sin Triton, sin GPU y sin red, en segundos.
"""
from __future__ import annotations

import asyncio
import io
import json
import struct
import zlib

import numpy as np
import pytest
from PIL import Image
from tritonclient.utils import InferenceServerException

from app.main import leer_reglas

LABELS = ["playeras", "pantalones", "sueteres", "vestidos", "abrigos",
          "sandalias", "camisas", "tenis", "bolsas", "botines"]


class Resultado:
    def __init__(self, y: np.ndarray):
        self.y = y

    def as_numpy(self, nombre: str) -> np.ndarray:
        return self.y


class TritonFalso:
    def __init__(self, logits=None, demora: float = 0.0, error: Exception | None = None, listo: bool = True,
                 demora_listo: float = 0.0, n_logits: int = 10):
        self.logits = np.array(logits if logits is not None else [0.5, 0.1, 0.2, 0.0, 0.3, 1.0, 0.4, 3.0, 0.2, 2.0], np.float32)
        self.demora, self.error, self.listo, self.demora_listo, self.n = demora, error, listo, demora_listo, n_logits
        self.vistos: list[tuple] = []
        self.cerrado = False

    async def get_model_metadata(self, nombre):
        return {"name": nombre, "versions": ["1"], "platform": "onnxruntime_onnx",
                "inputs": [{"name": "input", "datatype": "FP32", "shape": [-1, 3, 32, 32]}],
                "outputs": [{"name": "logits", "datatype": "FP32", "shape": [-1, self.n]}]}

    async def is_model_ready(self, nombre):
        await asyncio.sleep(self.demora_listo)
        return self.listo

    async def infer(self, model_name, inputs, outputs=None, request_id="", **kw):
        e = inputs[0]
        self.vistos.append((e.name(), e.datatype(), list(e.shape()), request_id))
        if e.name() != "input" or e.datatype() != "FP32" or list(e.shape())[1:] != [3, 32, 32]:
            raise InferenceServerException(f"unexpected shape for input '{e.name()}': {e.shape()}", status="400")
        if self.demora:
            await asyncio.sleep(self.demora)
        if self.error:
            raise self.error
        return Resultado(np.tile(self.logits, (list(e.shape())[0], 1)))

    async def close(self):
        self.cerrado = True


@pytest.fixture
def reglas():
    return leer_reglas()


@pytest.fixture
def modelo():
    s = json.dumps(LABELS, ensure_ascii=False) + "\n"
    import hashlib

    return {"modelo": "classifier", "version": 4, "model_version": "miniresnet-2026-10-01", "engine_sha256": "0" * 64,
            "labels": LABELS, "labels_sha256": hashlib.sha256(s.encode()).hexdigest(),
            "entrada": {"nombre": "input", "forma": [-1, 3, 32, 32]}, "salida": {"nombre": "logits", "forma": [-1, 10]}}


def foto(formato: str = "JPEG", lado: tuple[int, int] = (56, 56)) -> bytes:
    b = io.BytesIO()
    Image.new("RGB", lado, (120, 80, 40)).save(b, formato)
    return b.getvalue()


def png_solo_encabezado(ancho: int, alto: int) -> bytes:
    """Un PNG que dice medir ancho × alto y casi no trae píxeles: pesa ≈ 60 B. Image.open lo abre (lee el encabezado)."""
    def trozo(tipo, datos):
        return struct.pack(">I", len(datos)) + tipo + datos + struct.pack(">I", zlib.crc32(tipo + datos))
    return (b"\x89PNG\r\n\x1a\n" + trozo(b"IHDR", struct.pack(">IIBBBBB", ancho, alto, 8, 2, 0, 0, 0))
            + trozo(b"IDAT", zlib.compress(b"\x00" * 16)) + trozo(b"IEND", b""))

El PNG que «mide» 8,000 × 6,000 y pesa ≈ 60 B prueba el 413 por píxeles sin gastar memoria.

Pythongateway/tests/test_gateway.py
"""Las pruebas del gateway: la tabla de códigos, los topes, el plazo, la salud, el log y las métricas.

    python -m pytest -q          # desde la carpeta del kit; ≈ 5 s, sin Triton

Contrato:
- Cada fila de la tabla de códigos tiene al menos una prueba: 200, 400, 405, 413 (header, al leer y por píxeles),
  415, 422, 499, 500, 503 (en vuelo, Triton con error, sin conexión) y 504.
- Revisan lo que le llega a Triton (nombre, tipo y forma del tensor) y lo que sale en el log y en /metrics.
- Ninguna necesita Triton ni red: usan TritonFalso (conftest.py).
"""
from __future__ import annotations

import asyncio
import json
import time

import aiohttp
import httpx
import numpy as np
import pytest
from fastapi.testclient import TestClient
from tritonclient.utils import InferenceServerException

from app.main import crear_app, leer_reglas
from conftest import TritonFalso, foto, png_solo_encabezado

JPEG = {"Content-Type": "image/jpeg"}


def cliente(reglas, modelo, **kw):
    t = TritonFalso(**kw)
    return TestClient(crear_app(triton=t, reglas=reglas, modelo=modelo)), t


def lineas(capsys) -> list[dict]:
    return [json.loads(x) for x in capsys.readouterr().out.splitlines() if x.startswith("{")]


# ---------------------------------------------------------------- 200
def test_200_top5_con_su_contrato(reglas, modelo, capsys):
    c, t = cliente(reglas, modelo)
    with c:
        r = c.post("/v1/classify", content=foto(), headers={**JPEG, "X-Request-ID": "abc123", "X-Client-Source": "mobile"})
    assert r.status_code == 200
    cuerpo = r.json()
    assert cuerpo["model_version"] == "miniresnet-2026-10-01"
    assert [p["label"] for p in cuerpo["predictions"]] == ["tenis", "botines", "sandalias", "playeras", "camisas"]
    assert abs(cuerpo["predictions"][0]["score"] - 0.512) < 1e-4
    assert r.headers["X-Request-ID"] == "abc123"
    assert t.vistos == [("input", "FP32", [1, 3, 32, 32], "abc123")]      # lo que le llega a Triton
    (ln,) = lineas(capsys)
    assert ln["status"] == 200 and ln["source"] == "mobile" and ln["top5"][0] == [7, 0.512]
    assert set(ln["ms"]) == {"pre", "triton", "post", "total"} and len(ln["sha256"]) == 12


@pytest.mark.parametrize("k", [1, 3, 10])
def test_top_k(reglas, modelo, k):
    c, _ = cliente(reglas, modelo)
    with c:
        p = c.post(f"/v1/classify?top_k={k}", content=foto(), headers=JPEG).json()["predictions"]
    assert len(p) == k and [x["score"] for x in p] == sorted((x["score"] for x in p), reverse=True)


@pytest.mark.parametrize("formato,tipo", [("PNG", "image/png"), ("WEBP", "image/webp")])
def test_200_png_y_webp(reglas, modelo, formato, tipo):
    c, _ = cliente(reglas, modelo)
    with c:
        assert c.post("/v1/classify", content=foto(formato), headers={"Content-Type": tipo}).status_code == 200


def test_request_id_nuevo_si_no_viene(reglas, modelo):
    c, _ = cliente(reglas, modelo)
    with c:
        a = c.post("/v1/classify", content=foto(), headers=JPEG).headers["X-Request-ID"]
        b = c.post("/v1/classify", content=foto(), headers=JPEG).headers["X-Request-ID"]
    assert a and b and a != b


def test_softmax_estable_con_logits_enormes(reglas, modelo):
    c, _ = cliente(reglas, modelo, logits=[1000.0 + x for x in [0.5, 0.1, 0.2, 0.0, 0.3, 1.0, 0.4, 3.0, 0.2, 2.0]])
    with c:
        r = c.post("/v1/classify", content=foto(), headers=JPEG)
    assert r.status_code == 200 and abs(r.json()["predictions"][0]["score"] - 0.512) < 1e-4


# ---------------------------------------------------------------- 4xx
@pytest.mark.parametrize("cuerpo,headers,codigo", [
    (b"%PDF-1.4", {"Content-Type": "application/pdf"}, 415),
    (b"x" * (10 * 1024 * 1024 + 1), JPEG, 413),            # el Content-Length lo delata
    (b"", JPEG, 400),
    (png_solo_encabezado(8000, 6000), {"Content-Type": "image/png"}, 413),   # 48 MP en ≈ 60 B
    (png_solo_encabezado(1, 4000), {"Content-Type": "image/png"}, 400),      # más alargada que 1:8
    (foto()[:20] + bytes(2000), JPEG, 400),                 # corrupta
    (foto()[: len(foto()) // 2], JPEG, 400),                # cortada
])
def test_rechazos(reglas, modelo, capsys, cuerpo, headers, codigo):
    c, t = cliente(reglas, modelo)
    with c:
        r = c.post("/v1/classify", content=cuerpo, headers=headers)
    assert r.status_code == codigo and r.headers["X-Request-ID"]
    assert t.vistos == []                                    # nada de eso llega a Triton
    assert lineas(capsys)[-1]["status"] == codigo


def test_413_sin_content_length_se_corta_al_leer(reglas, modelo):
    def trozos():
        for _ in range(11):
            yield b"x" * (1024 * 1024)
    c, _ = cliente(reglas, modelo)
    with c:
        r = c.post("/v1/classify", content=trozos(), headers=JPEG)    # un generador: va sin Content-Length
    assert r.status_code == 413


def test_422_top_k_fuera_de_rango_deja_su_linea(reglas, modelo, capsys):
    c, _ = cliente(reglas, modelo)
    with c:
        r = c.post("/v1/classify?top_k=50", content=foto(), headers=JPEG)
    assert r.status_code == 422 and r.headers["X-Request-ID"]
    assert lineas(capsys)[-1]["status"] == 422


def test_405_get(reglas, modelo, capsys):
    c, _ = cliente(reglas, modelo)
    with c:
        r = c.get("/v1/classify")
    assert r.status_code == 405 and r.headers["X-Request-ID"]
    assert lineas(capsys)[-1]["status"] == 405


def test_499_quien_llama_se_va(reglas, modelo, capsys):
    app = crear_app(triton=TritonFalso(), reglas=reglas, modelo=modelo)
    enviados = []

    async def correr():
        mensajes = iter([{"type": "http.request", "body": b"\xff\xd8" + b"x" * 100, "more_body": True},
                         {"type": "http.disconnect"}])

        async def recibir():
            return next(mensajes)

        async def enviar(m):
            enviados.append(m)

        alcance = {"type": "http", "asgi": {"version": "3.0"}, "http_version": "1.1", "method": "POST", "scheme": "http",
                   "path": "/v1/classify", "raw_path": b"/v1/classify", "query_string": b"", "root_path": "",
                   "headers": [(b"content-type", b"image/jpeg"), (b"content-length", b"5000")],
                   "client": ("127.0.0.1", 1), "server": ("127.0.0.1", 8701)}
        async with app.router.lifespan_context(app):
            await app(alcance, recibir, enviar)

    asyncio.run(correr())
    assert lineas(capsys)[-1]["status"] == 499


# ---------------------------------------------------------------- 5xx
def test_500_logits_no_finitos(reglas, modelo, capsys):
    c, _ = cliente(reglas, modelo, logits=[float("nan")] + [0.0] * 9)
    with c:
        r = c.post("/v1/classify", content=foto(), headers=JPEG)
    assert r.status_code == 500
    assert lineas(capsys)[-1]["status"] == 500                # el log dice lo mismo que la respuesta


def test_503_triton_con_error(reglas, modelo):
    c, _ = cliente(reglas, modelo, error=InferenceServerException("Request timeout expired", status="503"))
    with c:
        assert c.post("/v1/classify", content=foto(), headers=JPEG).status_code == 503


def test_503_sin_conexion_con_retry_after(reglas, modelo):
    c, _ = cliente(reglas, modelo, error=aiohttp.ClientConnectionError("Connection refused"))
    with c:
        r = c.post("/v1/classify", content=foto(), headers=JPEG)
    assert r.status_code == 503 and r.headers["Retry-After"] == "1"


def test_504_triton_lento_se_corta_a_los_150_ms(reglas, modelo):
    c, _ = cliente(reglas, modelo, demora=2.0)
    with c:
        t = time.monotonic()
        r = c.post("/v1/classify", content=foto(), headers=JPEG)
        dt = time.monotonic() - t
    assert r.status_code == 504 and 0.14 < dt < 0.4


def test_503_la_17_en_vuelo(reglas, modelo):
    app = crear_app(triton=TritonFalso(demora=0.1), reglas=reglas, modelo=modelo)

    async def correr():
        async with app.router.lifespan_context(app):
            transporte = httpx.ASGITransport(app=app)
            async with httpx.AsyncClient(transport=transporte, base_url="http://gw") as c:
                rs = await asyncio.gather(*(c.post("/v1/classify", content=foto(), headers=JPEG) for _ in range(20)))
        return [r.status_code for r in rs], [r.headers.get("Retry-After") for r in rs if r.status_code == 503]

    codigos, retry = asyncio.run(correr())
    assert sorted(codigos) == [200] * 16 + [503] * 4 and retry == ["1"] * 4


# ---------------------------------------------------------------- salud, arranque, métricas
def test_healthz_no_pregunta_a_triton_y_readyz_si(reglas, modelo):
    c, _ = cliente(reglas, modelo, listo=False)
    with c:
        assert c.get("/healthz").status_code == 200
        assert c.get("/readyz").status_code == 503


def test_readyz_no_espera_mas_de_medio_segundo(reglas, modelo):
    c, _ = cliente(reglas, modelo, demora_listo=5.0)
    with c:
        t = time.monotonic()
        assert c.get("/readyz").status_code == 503
        assert time.monotonic() - t < 1.0


def test_no_arranca_si_los_labels_no_son_los_del_modelo(reglas, modelo):
    with pytest.raises(RuntimeError, match="logits"):
        with TestClient(crear_app(triton=TritonFalso(n_logits=9), reglas=reglas, modelo=modelo)):
            pass


def test_no_arranca_con_la_cadena_de_plazos_al_reves(tmp_path):
    from pathlib import Path

    import yaml

    r = yaml.safe_load((Path(__file__).resolve().parents[2] / "gateway.yaml").read_text())
    r["plazos_ms"]["triton"] = 400
    p = tmp_path / "gateway.yaml"
    p.write_text(yaml.safe_dump(r))
    with pytest.raises(RuntimeError, match="plazos"):
        leer_reglas(p)


def test_metricas_con_sus_nombres_y_sin_4xx_en_la_latencia(reglas, modelo):
    c, _ = cliente(reglas, modelo)
    with c:
        c.post("/v1/classify", content=foto(), headers=JPEG)
        for _ in range(3):
            c.post("/v1/classify", content=b"%PDF", headers={"Content-Type": "application/pdf"})
        m = c.get("/metrics").text
    for nombre in ("classifier_requests_total", "classifier_request_seconds", "classifier_preprocess_seconds",
                   "classifier_inference_seconds", "classifier_top1_score", "classifier_image_bytes"):
        assert nombre in m
    assert 'classifier_requests_total{code="415",model_version="miniresnet-2026-10-01",source="other"} 3.0' in m
    assert "classifier_request_seconds_count 1.0" in m       # solo el 200


def test_el_log_nunca_lleva_la_foto(reglas, modelo, capsys):
    c, _ = cliente(reglas, modelo)
    with c:
        c.post("/v1/classify", content=foto(), headers=JPEG)
    (ln,) = lineas(capsys)
    assert len(json.dumps(ln)) < 400 and "data" not in ln
    assert np.isclose(sum(s for _, s in ln["top5"]), 0.512 + 0.1883 + 0.0693 + 0.042 + 0.038, atol=1e-3)

La del 499 llama a la aplicación ASGI directamente: el cliente de pruebas siempre entrega el body completo y no sabe cortar una subida.

Terminal
grep '"request_id": "ana-0001"' logs/gateway.log | python -m json.tool
Salida
{
    "request_id": "ana-0001",
    "caller": "desconocido",
    "source": "mobile",
    "model_version": "miniresnet-2026-10-01",
    "ms": {
        "pre": 11.7,
        "triton": 4.7,
        "post": 0.1,
        "total": 20.7
    },
    "bytes": 1278,
    "sha256": "a3620aaeb761",
    "top5": [
        [
            7,
            0.9559
        ],
        [
            5,
            0.0371
        ],
        [
            9,
            0.0056
        ],
        [
            8,
            0.0006
        ],
        [
            4,
            0.0004
        ]
    ],
    "status": 200
}
309 B en una línea
Terminal
curl -s localhost:8701/metrics | grep -E "^classifier_requests_total|^classifier_request_seconds_(count|sum)"

Los 4xx cuentan en classifier_requests_total pero no en la latencia.

Salida
classifier_requests_total{code="200",model_version="miniresnet-2026-10-01",source="mobile"} 1.0
classifier_requests_total{code="200",model_version="miniresnet-2026-10-01",source="other"} 209.0
classifier_requests_total{code="415",model_version="miniresnet-2026-10-01",source="other"} 2.0
classifier_requests_total{code="400",model_version="miniresnet-2026-10-01",source="other"} 8.0
classifier_requests_total{code="413",model_version="miniresnet-2026-10-01",source="other"} 4.0
classifier_requests_total{code="422",model_version="miniresnet-2026-10-01",source="other"} 2.0
classifier_requests_total{code="405",model_version="miniresnet-2026-10-01",source="other"} 2.0
classifier_requests_total{code="499",model_version="miniresnet-2026-10-01",source="other"} 1.0
classifier_requests_total{code="504",model_version="miniresnet-2026-10-01",source="other"} 2.0
classifier_request_seconds_count 212.0
classifier_request_seconds_sum 1.671098622129648
Terminal
python -m pytest -q
Salida
30 passed in 1.13s
real 2.11
Terminal
python verificar.py log pruebas
Salida
✓ log         una línea de JSON por request (también el 422), con request_id, caller, source, model_version, ms y status; sin la foto · la latencia sin los 4xx
✓ pruebas     30 pruebas en 2.1 s, sin Triton

2/2 en verde
Terminal
python verificar.py
Salida
12/12 en verde
Listo cuando: Una línea de 309 B por request, sin la foto; las métricas con sus nombres; 30 pruebas en ≈ 2 s sin Triton; los 12 checks en verde.
Ojo: De esta línea de log sale lo que la estación 1 convierte en etiquetas, y lo que mira el monitoreo (estación 12): el request_id es la llave de unión.
Conceptos de este paso
Una línea de log por requeststructured loggingAl final de cada request, pase lo que pase (un finally), una línea de JSON con campos fijos: request_id, quién llamó, versión del modelo, top-5, milisegundos de cada paso, tamaño, huella y código.Analogía, por qué importa y la trampa

AnalogíaEl ticket de cada venta: siempre con los mismos campos, para poder sumarlos sin leerlos uno por uno.

Por qué importaUna máquina la filtra y la cuenta: de ahí sale el diagnóstico (¿dónde se fue el tiempo?) y, con el request_id, la unión con la publicación que la estación 1 convierte en etiquetas. Junto al log van las métricas de /metrics (requests por código, latencias, score top-1), con nombres fijos: las alertas las buscan por nombre, y los 4xx no entran al histograma de latencia porque un 415 tarda microsegundos.

TrampaMeter la foto o datos de quien vende en el log (pesa terabytes y son datos personales), o renombrar una métrica y apagar una alerta sin que nadie se entere.

Pruebas con un Triton falsotest double / mockUn objeto con los mismos métodos asíncronos que el cliente de Triton y las mismas excepciones, que contesta lo que la prueba le pida: logits, una demora, un error o «no listo».Analogía, por qué importa y la trampa

AnalogíaUn simulador de vuelo: se practica la falla de motor sin estrellar un avión.

Por qué importaLas pruebas corren en segundos en cualquier máquina, sin GPU, y cubren las fallas que en producción no se pueden provocar a voluntad. Además revisan el nombre, el tipo y la forma del tensor que saldría hacia Triton.

TrampaUn falso que acepta cualquier cosa: un cambio que mande los canales al final ([1, 32, 32, 3]) pasaría las pruebas y fallaría en producción.

Precálculo
6

¿Cuánto log sale al día?

bytes al día = requests al día × bytes por línea
Ver la cuenta
En C0110 M requests × ≈ 300 B≈ 3 GB al día
En el dojouna línea real pesa 309 B≈ 0.6 MB por cada 2,000 requests

Qué decides con esto. Una línea por request, sin la foto y sin datos de quien vende, cabe de sobra. Con la foto (≈ 215 KB) serían ≈ 2 TB al día, y datos personales en el log.

Terminalterminal · compruébalo en el kit
python -c "
for nombre, por_dia, bytes_ in [('C01', 10_000_000, 300), ('dojo, un día de verificar', 2_000, 300)]:
    print(f'{nombre}: {por_dia:,} requests × {bytes_} B = {por_dia * bytes_ / 1e9:.3f} GB al día')"
Salida
C01: 10,000,000 requests × 300 B = 3.000 GB al día
dojo, un día de verificar: 2,000 requests × 300 B = 0.001 GB al día

Lo confirmas en el paso 8: la línea de la foto de tenis pesa 309 B.

Solo

12 objetivos

Empieza con python mundo/reiniciar.py --serving y haz commit del esqueleto.

Sin GUION.md: solo estos objetivos y el contrato arriba de cada archivo.

Cada objetivo tiene su check; corre python verificar.py <check> cuando creas que quedó.

Las reglas no se tocan: gateway.yaml, servir.yaml, gateway/app/preprocess.py y mundo/ se quedan como vienen.

01El S3 local y MLflow arriba, el mundo creado y la carpeta en git.python verificar.py mundo
02Trabajas con las reglas revisadas del gateway, en un commit y sin cambios pendientes.python verificar.py reglas
03El model repository tiene la copia exacta del engine aprobado de la versión de servir.yaml, y la ficha del modelo trae su versión, sus labels y sus huellas.python verificar.py repositorioPista: ¿Contra qué compruebas que el archivo que bajaste es el que se aprobó?
04El config.pbtxt cuadra con el engine y trae batching dinámico, una fila que rechaza a tiempo, dos copias y warmup; está en git.python verificar.py configPista: ¿Las dims llevan el eje del batch?
05Triton corre, dice «listo» y cargó el engine aprobado con la configuración de tu disco.python verificar.py triton
06El gateway contesta /healthz sin preguntarle a nadie, /readyz según Triton, y /metrics con sus nombres.python verificar.py salud
07Las fotos del examen por HTTP dan el mismo top-1 que el engine aprobado, con model_version y X-Request-ID.python verificar.py responde
08Cada foto mala sale con su código, incluidos el 413 sin Content-Length, el 422, el 405 y el 499 en el log.python verificar.py rechazosPista: ¿Qué pasa si el header no dice el tamaño, o miente?
09La 17 en vuelo recibe 503 al instante; Triton lento, con error, caído o con NaN tiene su código; /readyz no espera de más.python verificar.py topes
10Con Triton congelado, classify sale con 504 a tiempo y /healthz sigue vivo.python verificar.py plazosPista: ¿Quién corta la llamada: el timeout de infer() o tú?
11Una línea de JSON por request (también el 422) y la latencia sin los 4xx.python verificar.py log
12Al menos 15 pruebas en verde, sin Triton.python verificar.py pruebas

Romper

6 fallas

Con todo en verde, romper.py mete una falla en el mundo, la configuración o la infraestructura (nunca en lo que escribiste) y, si hace falta, deja corriendo lo que «pasó anoche». Tú empiezas por verificar.py.

Terminalromper.py
python romper.py --mostrar   # con ayuda: Claude sabe cuál es
python romper.py             # solo: escondida, ni Claude la sabe
python romper.py --verificar # ¿ya quedó?
python romper.py --revelar   # me rindo
python romper.py --restaurar # deshacer

Repaso

para el celular
Servir un modelo no es llamarlo: es protegerlo.Triton carga el engine aprobado con su config.pbtxt (batching con ventana corta, fila que rechaza, copias y warmup). El gateway revisa de lo barato a lo caro, decodifica en un hilo con semáforo, rechaza la 17 en vuelo al instante, le da a Triton min(150, lo que queda) y contesta siempre con un código que dice qué pasó, con una línea de log y sus métricas. Trampa: Estirar un plazo o subir un tope porque «hoy no alcanza»: los plazos tienen que bajar de afuera hacia adentro y los topes salen de la memoria del peor caso, no de la CPU de hoy. Listo cuando
  • El model repository tiene la copia exacta del engine aprobado, por número y con su huella, y la ficha del gateway trae sus labels con su huella.
  • El config.pbtxt cuadra con el engine, junta lotes con una ventana corta, rechaza lo que esperó demasiado, carga dos copias y se calienta antes de decir «listo».
  • El gateway revisa cada foto de lo barato a lo caro y contesta cada falla con su código, también las que pasan antes o fuera de classify.
  • Los topes salen de la memoria del peor momento, y la cadena de plazos baja de la app a la fila de Triton.
  • Cada request deja una línea de JSON y sus métricas, con nombres fijos y sin los 4xx en la latencia.
  • Las pruebas cubren la tabla de códigos con un Triton falso y corren en segundos sin GPU.

Así te lo pueden preguntar en una entrevista

Diseña el servicio que sirve un clasificador de imágenes con p99 ≤ 200 ms.

Un gateway en FastAPI en CPU, varias copias, delante de Triton en GPU. El gateway revisa la foto de lo barato a lo caro, decodifica en un threadpool con semáforo, tiene un tope de requests en vuelo, y llama a Triton con el tensor en binario y un plazo que es el mínimo entre su tope y lo que le queda a la request. Triton con batching dinámico de pocos ms, fila con timeout, dos instancias por GPU y warmup. /healthz sin dependencias, /readyz que pregunta a Triton, una línea de log por request y métricas con nombres fijos.

¿Por qué separar gateway y servidor de modelos?

Escalan distinto: los gateways son CPU barata y muchas copias; las GPUs son caras y pocas. El decode y la validación de bytes hostiles se quedan fuera del proceso con la GPU. Y Triton hace batching dinámico, que un proceso de FastAPI con el modelo adentro no hace.

¿Qué pasa si Triton se traba?

Cada llamada se corta por el plazo con 504; /readyz pregunta a Triton con su propio tope y dice 503, así Kubernetes saca esa copia del reparto sin reiniciarla; /healthz no pregunta a nadie y sigue en 200, porque reiniciar gateways no arregla a Triton. Sin reintentos, para no sumar carga a un sistema que ya no puede.

¿Cómo eliges el tope de requests en vuelo?

Con la Ley de Little: llegadas por segundo por lo que dura cada una, en el caso normal y en el lento. Y lo recorto por la memoria del peor momento: cada request en vuelo puede traer un body del máximo y cada decode puede ser de una foto enorme. Lo que sobra recibe 503 al instante.

¿Qué es una bomba de descompresión y cómo te defiendes?

Una imagen que pesa poco comprimida y muchísimo decodificada. Leo el ancho y el alto del encabezado sin decodificar (Image.open) y rechazo por píxeles antes del decode, además de la red de Pillow (MAX_IMAGE_PIXELS) y un semáforo que limita cuántos decodes caben a la vez.

¿Cómo pruebas el gateway sin GPU?

Con un Triton falso que tiene los mismos métodos asíncronos y las mismas excepciones que el cliente real, y que revisa el nombre, el tipo y la forma del tensor que le mandan. Así cubro cada fila de la tabla de códigos (incluidos 499, 500 con NaN, 503 y 504) en segundos, en cualquier máquina.

Versión del contenido: 17 de noviembre de 2026.

Contexto opcional

para consultar
Dónde estás en el pipeline

La estación 5 dejó a classifier v4 con su engine y sus huellas en el registro. Falta lo que lo pone a atender: dos programas. El servidor de modelos (Triton) carga el engine desde una carpeta, el model repository, con su config.pbtxt, y solo convierte tensores en tensores, juntando fotos en lotes. Delante va el gateway, un programa en FastAPI que recibe cada foto, la revisa de lo barato a lo caro, la prepara con topes de memoria y de concurrencia, le pide los logits a Triton con un plazo que nunca pasa del que le queda, y contesta siempre con un código que dice qué pasó, dejando una línea de log y sus métricas. Con sus pruebas, que corren sin GPU.

Entra
  • el engine de classifier v4 y su labels.json, por número, con las huellas del registro
  • el preprocess compartido con el entrenamiento (el mismo código, la misma Pillow)
  • las reglas del gateway (gateway.yaml): tipos, tamaños, topes y la cadena de plazos, revisadas en un PR
  • el contrato con quien llama: POST /v1/classify?top_k=5 con los bytes de la foto; la app espera 300 ms
Sale
  • el model repository: classifier/config.pbtxt y classifier/1/model.onnx, la copia exacta del engine aprobado
  • el gateway: /v1/classify, /healthz, /readyz y /metrics, con el código de cada falla
  • una línea de log en JSON por request y las métricas con nombres fijos
  • 30 pruebas con un Triton falso, que corren en segundos sin GPU
El escenario del proyecto
Con kit · 4 rondas

El kit trae el marketplace de C01 el 1 de octubre de 2026, a las 09:00 UTC: el gate aprobó a classifier v4 y la estación 5 le construyó su engine. En MLflow están v1 a v4, y v3 y v4 con engine=listo y sus huellas; servir.yaml dice qué se sirve (v4, por número). El mundo trae además un servidor de modelos con el mismo protocolo que Triton, las reglas del gateway y fotos buenas y malas para probar. Tú escribes lo que pone a v4 a atender.

El mundo vive en dos servicios: el S3 local (el examen y los checkpoints) y MLflow (el registro de modelos). mundo/crear.py los llena igual cada vez: entrena los cuatro modelos del registro y construye los engines de v3 y v4, por eso tarda unos minutos. El servidor de modelos y tu gateway no van en Docker: son procesos de tu Mac que arrancas desde el paso 3.

Glosario: los 18 conceptos

Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.

Gateway y servidor de modelosAPI gateway / model serverDos programas con trabajos distintos. El gateway recibe la request, la revisa, prepara la foto en la CPU y contesta. El servidor de modelos solo convierte tensores en tensores en la GPU.Analogía, por qué importa y la trampa

AnalogíaEl mesero y la cocina: el mesero toma el pedido, revisa que se pueda hacer y lo entrega; la cocina solo cocina, y nunca habla con el cliente.

Por qué importaCada uno escala por su lado (gateways baratos en CPU, pocas GPUs caras), y los bytes hostiles de internet nunca llegan al proceso que tiene la GPU.

TrampaMeter el modelo de PyTorch dentro del gateway «porque es más simple»: cada despliegue recarga el modelo y cada foto corre sola en la GPU.

Triton Inference ServerNVIDIA TritonEl servidor de modelos de NVIDIA: carga modelos de una carpeta y los atiende por HTTP o gRPC con el protocolo de inferencia v2 de KServe, juntando peticiones en lotes.Analogía, por qué importa y la trampa

AnalogíaUna cocina industrial con reglas escritas para cada platillo: qué ingredientes recibe, en qué cantidad y cuántos prepara a la vez.

Por qué importaEl gateway le habla con su cliente oficial (tritonclient) y le manda el tensor en binario. En el dojo, un servidor sustituto con el mismo protocolo deja usar ese mismo cliente.

TrampaMandar el tensor como lista de números en JSON: pesa varias veces más y se tarda en convertir.

Model repositoryTriton model repositoryLa carpeta de donde Triton carga los modelos: una subcarpeta por modelo, con su config.pbtxt y una carpeta numerada por versión con el archivo del modelo.Analogía, por qué importa y la trampa

AnalogíaEl recetario de la cocina: cada platillo con su ficha y la receta de la edición vigente.

Por qué importaCon --model-control-mode=none, Triton carga lo que hay al arrancar y nada más: qué modelo corre lo dice la carpeta (en C01, la imagen). Por eso se arma desde el registro, con huellas, y nunca a mano.

TrampaConfundir la versión de la carpeta (1/) con la del registro (v4): la de verdad va en las huellas y en el model_version de cada respuesta.

config.pbtxtTriton model configurationLa configuración de un modelo en Triton, en el formato de texto de protobuf: el backend, el batch máximo, la entrada y la salida, el batching, las copias y el warmup.Analogía, por qué importa y la trampa

AnalogíaLa ficha técnica de un aparato: el enchufe, el voltaje y cuántos puede atender a la vez.

Por qué importaTriton revisa la ficha contra el modelo y no carga si no cuadran. dims va sin el eje del batch cuando max_batch_size > 0: Triton le antepone −1.

TrampaPoner el batch dentro de dims ([1, 3, 32, 32]): el modelo no carga, y con --exit-on-error Triton ni arranca.

Batching dinámicodynamic batchingTriton espera un poco (aquí 2 ms) desde que llega una foto a que lleguen otras, y las corre juntas en un solo lote.Analogía, por qué importa y la trampa

AnalogíaUn elevador que espera unos segundos con la puerta abierta por si llega alguien más antes de subir.

Por qué importaUn lote de varias fotos cuesta casi lo mismo que una en la GPU: más fotos por segundo con la misma máquina. La espera es corta para que no se note en la latencia.

TrampaUna ventana larga para «llenar» lotes con poco tráfico: cada foto espera y nadie gana.

Política de la filaqueue policyLo que Triton hace con una foto que esperó demasiado en su fila sin entrar al modelo: con REJECT, la saca y contesta error (aquí, a los 100 ms).Analogía, por qué importa y la trampa

AnalogíaUn restaurante que, en vez de dejar crecer la fila de la puerta, le avisa al que lleva mucho esperando que mejor vaya a otro lado.

Por qué importaUna foto que ya esperó 100 ms llegaría tarde de todas formas: correrla gasta GPU en una respuesta que nadie va a ver. Bajo sobrecarga, mejor errores rápidos que una fila que hace lentas a todas.

TrampaUna fila sin tope: bajo carga crece sin límite y todas las respuestas llegan tarde.

Copias del modelo y warmupinstance group / model warmupinstance_group carga varias copias del modelo para atender lotes en paralelo. model_warmup corre el modelo con datos de relleno antes de decir «listo».Analogía, por qué importa y la trampa

AnalogíaDos cocineros en la misma estufa, y prender los quemadores antes de abrir: la primera orden no paga el precalentado.

Por qué importaMientras una copia corre un lote, la otra recibe el siguiente. Y las primeras corridas pagan una preparación que no se repite: mejor antes de atender que en la foto de un cliente.

TrampaDecir «listo» antes del warmup: las primeras requests después de cada despliegue salen lentas.

uvicorn, ASGI y FastAPIASGI server / frameworkuvicorn es el servidor que abre el puerto y corre el event loop; ASGI es el contrato entre servidor y aplicación; FastAPI es el armazón donde escribes tus rutas.Analogía, por qué importa y la trampa

AnalogíaEl local, el reglamento de la cocina y la carta: cada uno cambia sin tocar a los otros.

Por qué importaCon --workers 1, la concurrencia sale del event loop y del threadpool; la capacidad, de más copias. Cada flag de uvicorn es una decisión (keep-alive, apagado ordenado, sin log de acceso).

TrampaHacer trabajo de CPU (decodificar) directo en la ruta async: congela el event loop y nadie más avanza.

Lifespanlifespan eventsLa función que corre una vez al arrancar, antes de la primera request, y una vez al apagarse.Analogía, por qué importa y la trampa

AnalogíaAbrir el local: revisar que la cocina tenga gas y que el menú corresponda antes de dejar pasar al primer cliente.

Por qué importaAhí se crea UN cliente de Triton para todo el proceso y se revisa lo que no puede fallar: que los labels sean los del modelo y que Triton sirva la forma esperada. Si algo no cuadra, el proceso no arranca.

TrampaCrear un cliente nuevo por request: cada foto abre su conexión y el pool no sirve.

Vivo y listoliveness / readiness/healthz contesta «sigo vivo» sin preguntarle a nadie. /readyz contesta «mándame tráfico» solo si Triton dice que el modelo está listo, con un tope de tiempo.Analogía, por qué importa y la trampa

Analogía«¿Respiras?» contra «¿puedes atender?»: un mesero con la cocina cerrada respira, pero no debe tomar pedidos.

Por qué importaSi /healthz falla, Kubernetes reinicia la copia; si /readyz falla, la saca del reparto sin reiniciarla. Si /healthz preguntara por Triton, una caída de Triton reiniciaría a todos los gateways y no arreglaría nada.

TrampaUn /readyz sin tope: con Triton trabado, la pregunta misma se queda colgada.

Revisar de lo barato a lo caroinput validation orderLas revisiones de cada foto van ordenadas por costo: el tipo (comparar un texto), el tamaño anunciado (un header), el tamaño real (leer), los píxeles (el encabezado), la forma y al final el decode.Analogía, por qué importa y la trampa

AnalogíaEn la puerta de un concierto se revisa el boleto antes que la bolsa, y la bolsa antes que el detector de metales.

Por qué importaUna foto que falla lo barato no gasta nada en lo caro, y cada rechazo lleva su código: 415, 413 o 400. La defensa contra una bomba de descompresión (un PNG de 48 MP en negro pesa ≈ 140 KB y decodificado ocupa cientos de MB) es leer el ancho y el alto del encabezado con Image.open, sin decodificar, y rechazar por píxeles; MAX_IMAGE_PIXELS de Pillow queda de respaldo.

TrampaConfiar en Content-Length (puede mentir o no venir: el corte de verdad es al leer, en pedazos), o revisar solo los bytes y creer que con eso basta.

Semáforo y threadpoolsemaphore / threadpoolEl decode corre en un hilo aparte (run_in_threadpool) para no congelar el event loop, y un semáforo de 2 lugares deja decodificar a solo dos a la vez.Analogía, por qué importa y la trampa

AnalogíaUn probador con dos cabinas: los demás esperan afuera, y si esperan demasiado, se les dice que vuelvan luego.

Por qué importaUn decode de 40 MP ocupa ≈ 320 MB: con los 40 hilos que trae el threadpool por omisión, serían ≈ 13 GB. Quien espera más de 50 ms un lugar recibe 503 con Retry-After.

TrampaUna fila de CPU sin tope: solo produce respuestas que llegan cuando la app ya se rindió.

Tope de requests en vuelomax in-flight requests / load sheddingCuántas requests puede tener adentro una copia a la vez. La que llega con el tope lleno recibe 503 al instante, sin leer su body.Analogía, por qué importa y la trampa

AnalogíaEl cupo de un salón: el que llega con el salón lleno no entra, y se le dice en la puerta, no después de sentarlo.

Por qué importaRechazar cuesta microsegundos y protege la memoria y la latencia de las que ya están adentro. El número sale de la Ley de Little, recortado por la memoria del peor momento.

TrampaSubir el tope porque «la CPU está al 40 %»: el tope cuida la memoria del peor caso, no la CPU de hoy.

La cadena de plazosdeadline propagationCada eslabón espera menos que el de afuera: la app 300 ms, el gateway 250, la llamada a Triton 150 (o lo que le quede a la request, si es menos) y la fila de Triton 100.Analogía, por qué importa y la trampa

AnalogíaMuñecas rusas de tiempo: la de adentro siempre cabe en la de afuera, así que se rinde primero y la de afuera todavía alcanza a avisar.

Por qué importaAsí cada falla se contesta a tiempo con su código, en vez de que la app se rinda sin saber qué pasó. El plazo se corta con asyncio.wait_for: el timeout de infer() es otra cosa (un tiempo para la fila del servidor).

TrampaEstirar el plazo de Triton por encima del de la request «porque a veces tarda»: la app se rinde primero y el gateway sigue esperando.

El código de cada fallaHTTP status codesLos 4xx son culpa de quien llama (400, 405, 413, 415, 422) y no cuentan contra la promesa de servicio; los 5xx son del sistema (500, 503, 504). El 499, de nginx, es «quien llama se fue».Analogía, por qué importa y la trampa

AnalogíaEn una paquetería: «tu caja venía rota» no es lo mismo que «se nos descompuso el camión».

Por qué importaLas alertas y el SLO cuentan los 5xx. Un 422 o un 499 mal clasificados como 5xx despiertan a alguien a las 3 de la mañana por un cliente que mandó mal los datos.

TrampaContestar 200 con un error adentro del JSON: nadie lo cuenta.

Softmax estable y la guardianumerically stable softmaxAntes de sacar la exponencial, a todos los logits se les resta el más grande: el resultado es el mismo y ninguna exponencial se desborda. Y si algún logit no es finito (NaN o infinito), 500.Analogía, por qué importa y la trampa

AnalogíaMedir alturas desde la azotea en lugar de desde el centro de la Tierra: las diferencias son las mismas y los números caben en la regla.

Por qué importaUn engine roto puede dar NaN. Sin la guardia, el error salta al convertir la respuesta en JSON, después de escribir el log: el log diría 200 y la app vería un 500.

TrampaContestar 200 con probabilidades de basura.

Una línea de log por requeststructured loggingAl final de cada request, pase lo que pase (un finally), una línea de JSON con campos fijos: request_id, quién llamó, versión del modelo, top-5, milisegundos de cada paso, tamaño, huella y código.Analogía, por qué importa y la trampa

AnalogíaEl ticket de cada venta: siempre con los mismos campos, para poder sumarlos sin leerlos uno por uno.

Por qué importaUna máquina la filtra y la cuenta: de ahí sale el diagnóstico (¿dónde se fue el tiempo?) y, con el request_id, la unión con la publicación que la estación 1 convierte en etiquetas. Junto al log van las métricas de /metrics (requests por código, latencias, score top-1), con nombres fijos: las alertas las buscan por nombre, y los 4xx no entran al histograma de latencia porque un 415 tarda microsegundos.

TrampaMeter la foto o datos de quien vende en el log (pesa terabytes y son datos personales), o renombrar una métrica y apagar una alerta sin que nadie se entere.

Pruebas con un Triton falsotest double / mockUn objeto con los mismos métodos asíncronos que el cliente de Triton y las mismas excepciones, que contesta lo que la prueba le pida: logits, una demora, un error o «no listo».Analogía, por qué importa y la trampa

AnalogíaUn simulador de vuelo: se practica la falla de motor sin estrellar un avión.

Por qué importaLas pruebas corren en segundos en cualquier máquina, sin GPU, y cubren las fallas que en producción no se pueden provocar a voluntad. Además revisan el nombre, el tipo y la forma del tensor que saldría hacia Triton.

TrampaUn falso que acepta cualquier cosa: un cambio que mande los canales al final ([1, 32, 32, 3]) pasaría las pruebas y fallaría en producción.

Nube real vs. local
En C01En el dojo
El servidor de modelosTriton con TensorRT en una T4 por zona; platform: "tensorrt_plan", KIND_GPUel servidor del dojo (mundo/triton_dojo/) con ONNX Runtime en tu CPU; platform: "onnxruntime_onnx", KIND_CPU. Lee el mismo config.pbtxt y habla el mismo protocolo HTTP
El modeloResNet-50: input [3, 224, 224] → logits [500], batch hasta 32MiniResNet: input [3, 32, 32] → logits [10], batch hasta 32 (engine de 181 kB)
El gatewayFastAPI en 3 a 12 copias de 1 vCPU y 1 GiB, detrás del ALBel mismo código, un proceso en tu Mac (mundo/servicios.py) en el puerto 8701
Quién llamala app, con su token verificado por el ALB; ≈ 500 fotos/s en el picocurl y verificar.py (≈ 972 fotos/s con 8 a la vez)
Los límites y plazos10 MiB, 40 MP, 1:8, 2 decodes, 16 en vuelo · 300 > 250 > 150 > 100 mslos mismos, en gateway.yaml
Las pruebas26 pruebas con pytest y un Triton falso, ≈ 2 min en CI30 pruebas, ≈ 2 s
En la nubeEn el dojoQué cambia
Triton con TensorRT en una T4 (<code>tensorrt_plan</code>, <code>KIND_GPU</code>)el servidor del dojo con ONNX Runtime en tu CPU (<code>onnxruntime_onnx</code>, <code>KIND_CPU</code>)Lee el mismo formato de config.pbtxt, se niega a cargar igual que Triton cuando no cuadra, y habla el mismo protocolo HTTP: el gateway usa el cliente oficial tritonclient sin cambiar nada. Solo trae ese backend, solo HTTP y solo los campos que usa la estación.
Pods en Kubernetes: 3 a 12 gateways y un Triton por zonados procesos en tu Mac (<code>mundo/servicios.py</code>)Kubernetes arranca, vigila /healthz y /readyz, y reinicia o saca del reparto. Aquí lo haces tú con servicios.py y lo ves con estado.
El ConfigMap <code>classifier-labels-14</code> con <code>labels.json</code><code>servir/modelo.json</code>, que arma <code>servir/armar.py</code>Los dos traen las categorías de la versión con su huella; el gateway la revisa al arrancar.
El token que verificó el ALB (<code>client_id</code>)el header <code>X-Caller-Id</code>En C01 quien llama no lo puede falsificar; aquí es solo un header, para que el log tenga un caller.
El model repository dentro de la imagen de Tritonla carpeta <code>model_repository/</code> de tu kitEn C01 nadie puede cambiarla con el servidor andando: cambiar de modelo es cambiar de imagen. Aquí es una carpeta, y por eso una de las fallas es justo cambiarla a mano.
El historial de PR del repositorio <code>classifier</code><code>mundo/revisiones.json</code>Las reglas revisadas se comprueban por su huella.
Qué trae el kit y qué escribes tú

Lo que trae no lo escribes

El S3 local y MLflow (compose.yaml). RustFS en el puerto 9700 (el examen y los checkpoints) y MLflow en el 5700, con su interfaz.

mundo/crear.py. Crea todo en ≈ 2 minutos: baja Fashion-MNIST, congela golden-v1, entrena classifier v1 a v4 con la receta de la estación 3, construye los engines de v3 y v4 con la receta de la estación 5, y deja servir.yaml y fotos-raras/.

mundo/triton_dojo/. El servidor de modelos del dojo, el sustituto de Triton: lee tu config.pbtxt (y se niega a cargar si no cuadra con el engine), hace batching dinámico con su fila y su plazo, carga copias con warmup y habla el protocolo HTTP de Triton, con la extensión binaria y sus métricas nv_inference_*.

mundo/servicios.py. Arranca, para, reinicia y revisa los dos procesos (Triton en el 8700 y tu gateway en el 8701), con su log en logs/: lo que en C01 hace Kubernetes.

gateway.yaml y mundo/revisiones.json. Las reglas del gateway (tipos, límites, cadena de plazos, Triton), y el registro de sus versiones revisadas: el sustituto del historial de PR.

gateway/app/preprocess.py. El preprocess compartido con el entrenamiento, tal cual. Tu gateway lo importa: nunca lo reescribe.

mundo/modelos.py. Mirar y reparar el registro: versiones, el engine de cada una, alias y su labels.json.

verificar.py y romper.py. 12 checks con los criterios de «listo» y 6 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.

Lo que escribes lo escribes tú

  1. servir/armar.pyEl model repository y la ficha del modelo (servir/modelo.json) desde el registro: la versión por número, el engine y los labels solo si sus huellas son las del registro.
  2. model_repository/classifier/config.pbtxtCómo carga y atiende Triton el modelo: backend, batch, entrada y salida, batching dinámico, fila con plazo, dos copias y warmup.
  3. gateway/app/revision.pyLa revisión de cada foto, de lo barato a lo caro, con el código de cada rechazo.
  4. gateway/app/main.pyEl gateway: lifespan, salud, métricas y classify con sus topes, su plazo, el código de cada falla y una línea de log por request.
  5. gateway/tests/El Triton falso y las pruebas de la tabla de códigos, los topes, la salud y el log (30 en la solución).
Reglas CLAUDE.md del kit
El CLAUDE.md del kitLas reglas de fondo para Claude Code en la carpeta del kit. Ya viene en el .zip.
Ver el CLAUDE.md
prompt
# Dojo de entrenamiento ML engineer's · C01 · Estación 6: Código de serving

Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Código de serving» del caso C01: el model repository de Triton (con su `config.pbtxt`) y el gateway en FastAPI que recibe cada foto, la revisa, la prepara, le pide los logits a Triton con un plazo y contesta con el código correcto, con su log, sus métricas y sus pruebas. La persona con la que trabajas está aprendiendo; tu trabajo es que **entienda**, no que termine rápido.

## Qué es cada cosa

| Carpeta o archivo | Qué es | ¿Se toca? |
|---|---|---|
| `mundo/` | La empresa ficticia: `crear.py` (el registro v1–v4 con los engines de v3 y v4, el examen, `fotos-raras/` y `servir.yaml`), `triton_dojo/servidor.py` (el servidor de modelos del dojo, el sustituto de Triton), `servicios.py` (arrancar, parar, reiniciar y ver el estado de Triton y del gateway), `modelos.py` (mirar y reparar el registro), `revisiones.json` (las versiones aprobadas de `gateway.yaml`), `equipo.py`, `arquitectura.py`, `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `servicios.py` y `modelos.py` sí se usan. |
| `servir/armar.py` | Lo escribe la persona: arma el model repository y `servir/modelo.json` desde el registro. | **Sí.** |
| `model_repository/classifier/config.pbtxt` | Lo escribe la persona: la configuración del modelo en Triton. | **Sí.** El engine (`1/model.onnx`) lo deja `armar.py`; no se copia a mano. |
| `gateway/app/main.py`, `gateway/app/revision.py` | Lo escribe la persona: el gateway y la revisión de cada foto. Cada archivo trae su contrato arriba. | **Sí.** |
| `gateway/app/preprocess.py` | El preprocess compartido con el entrenamiento. | **No.** Cambiarlo es training-serving skew. |
| `gateway/tests/` | Lo escribe la persona: las pruebas con un Triton falso. | **Sí.** |
| `gateway.yaml` | Las reglas del gateway (contrato, límites, plazos y Triton), del equipo de serving, revisadas en un PR. | Solo con una revisión aprobada. Nunca para que algo pase. |
| `servir.yaml` | Qué versión se sirve, ya resuelta por el orquestador (v4) y su `model_version`. | No a mano. |
| `fotos-raras/`, `logs/`, `data/` | Fotos de prueba, lo que escriben Triton y el gateway (`logs/triton.log`, `logs/gateway.log`) y la caché de Fashion-MNIST. Git las ignora. | No. Los logs se leen mucho. |
| `verificar.py` | Revisa los criterios de «listo», uno por check. | No. |
| `romper.py` | Mete fallas en el mundo, la configuración o la infraestructura. Nunca en lo que escribe la persona. | No. Y no leas su código para adivinar una falla escondida. Tampoco leas `mundo/triton_dojo/` ni `mundo/equipo.py` para resolver un paso. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (Construir con ayuda) y solo los objetivos (Construir solo). | No. |
| `taller/progreso.json`, `BITACORA.md` | El registro de las rondas. | Sí, tú los mantienes (ver abajo). |
| `taller/registro.py` | Lo usan `verificar.py` y `romper.py` para anotar en `progreso.json` sus corridas y las fallas cerradas. | No. |

## Cómo se trabaja

- Responde en español neutro, de tú, directo y sin relleno. Términos técnicos en inglés la primera vez, con su explicación.
- Explica siempre el **por qué**. Cuando algo en el dojo es distinto de C01 real, dilo en una línea: un servidor de modelos del dojo con ONNX Runtime en la CPU en lugar de Triton con TensorRT en una T4 (lee el mismo `config.pbtxt` y habla el mismo protocolo HTTP, así que el gateway usa el cliente oficial `tritonclient`), `platform: "onnxruntime_onnx"` y `KIND_CPU` en lugar de `"tensorrt_plan"` y `KIND_GPU`, procesos en tu Mac (`mundo/servicios.py`) en lugar de pods de Kubernetes, `servir/modelo.json` en lugar del ConfigMap con `labels.json`, el header `X-Caller-Id` en lugar del `client_id` del token que verificó el ALB, 10 categorías y fotos de 32×32 en lugar de 500 y 224×224, `mundo/revisiones.json` en lugar del historial de PR.
- Nunca inventes salidas: si no corriste algo, di que no lo corriste.
- El entorno virtual va activo en cada comando: `source .venv/bin/activate`.
- Antes de correr algo que cambia el mundo o la máquina (`mundo/servicios.py arrancar|parar|reiniciar`, `mundo/modelos.py alias|reparar-labels`, `pip install`, `docker compose …`, `romper.py`, `mundo/*.py`, `git commit`, `git revert`), dilo. Lo que solo lee (`verificar.py`, `python -m pytest`, `servir/armar.py`, `mundo/servicios.py estado`, `mundo/modelos.py versiones|engine|labels`, `curl` al gateway o a Triton, `tail logs/…`, `git status`, `git log`, `git diff`) se puede correr directo.
- Cuando cambies código del gateway, reinícialo (`python mundo/servicios.py reiniciar gateway`); cuando cambie el `config.pbtxt` o el engine, reinicia Triton: carga solo al arrancar (`--model-control-mode=none`).
- `mundo/crear.py` tarda ≈ 2 min; `verificar.py` completo ≈ 10 s; las pruebas, ≈ 2 s.
- Los límites y los plazos de `gateway.yaml` no se mueven para que algo pase. Si la persona propone estirar un plazo o subir los topes, explícale la cadena de plazos y la cuenta de memoria del peor momento.
- Enséñale a mirar: `curl -i` contra el gateway, `tail -f logs/gateway.log`, `curl localhost:8701/metrics`, `curl localhost:8700/metrics` (las métricas de Triton: cuántas fotos y cuántos batches) y la interfaz de MLflow en http://localhost:5700.
- Sigue el prompt de la ronda que te pegaron: en Construir solo y en Romper solo **no das código ni pistas** salvo que la persona se rinda.

## Bitácora

Al terminar cada paso, objetivo o falla, agrega una entrada en los dos archivos:

`BITACORA.md`, legible en el celular:

```markdown
## 2026-11-18 10:42 · Construir con ayuda · paso 5 (classify)
- **Hice:** …
- **Medí:** … (números reales que salieron)
- **Sigue:** …
```

`taller/progreso.json`, el que se importa en «Tu tablero» del Dojo (la página /tablero/ de la app). Agrega a `bitacora` y actualiza `rondas`:

```json
{
  "estacion": "c01-serving",
  "rondas": {
    "guiado":       { "estado": "en_curso", "inicio": "2026-11-18T10:05:12-06:00", "fin": null },
    "solo":         { "estado": "pendiente", "inicio": null, "fin": null, "pistas": 0 },
    "romper_ayuda": { "estado": "pendiente", "fallas": [] },
    "romper_solo":  { "estado": "pendiente", "fallas": [] }
  },
  "bitacora": [
    { "fecha": "2026-11-18T10:42:30-06:00", "ronda": "guiado", "paso": "classify", "hice": "…", "medi": "…", "sigue": "…" }
  ],
  "verificaciones": [
    { "fecha": "2026-11-18T10:41:02-06:00", "pasan": ["mundo", "reglas"], "fallan": [] }
  ]
}
```

- `estado` es `pendiente`, `en_curso` o `hecha`. En el tablero, `guiado` se llama «Construir con ayuda», `solo` «Construir solo», `romper_ayuda` «Romper con ayuda» y `romper_solo` «Romper solo».
- **Fecha y hora en cada avance**, en ISO 8601 con la zona de la Mac: sácala con `date -Iseconds` (da algo como `2026-11-18T10:42:30-06:00`). Nunca solo la fecha.
- `verificaciones` la escribe `verificar.py` solo, en cada corrida. No la edites.
- Cada falla la anota `romper.py` al cerrarla (`--verificar` o `--revelar`): `{ "id", "inicio", "fin", "minutos", "pistas": 0, "rendido", "aprendi": "" }`, con el tiempo real. Tú solo completas `pistas` y `aprendi` en esa misma entrada (la última de su ronda); no agregues otra.
- Mantén el JSON válido: después de editarlo, corre `python -m json.tool taller/progreso.json > /dev/null`.

La estación completa, con su lugar en el mapa: cheat sheet «Del dato a producción».