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?
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
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.
ConstruirRomperCon 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`.
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`.
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`.
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.
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 10limites:
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).
✓ 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: E402from 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 registrowith 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))
ifsha256(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")
ifsha256(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 ifisinstance(d, int) else -1for d in i.shape]}
salida = {"nombre": o.name, "forma": [d ifisinstance(d, int) else -1for 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() andsha256(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í.
✓ 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)
✓ 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
classRechazo(Exception):
def__init__(self, codigo: int, motivo: str, reintentar: bool = False):
super().__init__(motivo)
self.codigo, self.motivo, self.reintentar = codigo, motivo, reintentar
defrevisar_tipo(content_type: str | None, tipos: list[str]) -> str:
tipo = (content_type or"").split(";")[0].strip().lower()
if tipo notin tipos:
raiseRechazo(415, f"tipo {tipo or '(sin Content-Type)'}: solo {', '.join(tipos)}")
return tipo
defrevisar_largo(content_length: str | None, max_bytes: int) -> None:
if content_length isNone:
returntry:
n = int(content_length)
except ValueError:
raiseRechazo(400, f"Content-Length no es un número: {content_length!r}") fromNoneif n > max_bytes:
raiseRechazo(413, f"Content-Length {n} B: el máximo es {max_bytes} B")
asyncdefleer_body(request, max_bytes: int) -> bytes:
partes, n = [], 0asyncfor trozo in request.stream():
n += len(trozo)
if n > max_bytes:
raiseRechazo(413, f"el body pasa de {max_bytes} B (se cortó al leer)")
partes.append(trozo)
returnb"".join(partes)
defrevisar_imagen(data: bytes, max_pixeles: int, max_proporcion: float) -> tuple[int, int]:
ifnot data:
raiseRechazo(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:
raiseRechazo(413, f"más de {max_pixeles:,} píxeles (Pillow)") fromNoneexcept (UnidentifiedImageError, OSError, ValueError):
raiseRechazo(400, "no es una imagen que se pueda leer") fromNoneif w * h > max_pixeles:
raiseRechazo(413, f"{w} × {h} = {w * h:,} píxeles: el máximo es {max_pixeles:,}")
ifmax(w, h) > max_proporcion * min(w, h):
raiseRechazo(400, f"{w} × {h}: el lado largo pasa de {max_proporcion:g} veces el corto")
return w, h
defpreparar(data: bytes) -> np.ndarray:
try:
return preprocess.preprocess(data)
except (OSError, ValueError, SyntaxError, Image.DecompressionBombError) as e:
raiseRechazo(400, f"no se pudo decodificar la imagen ({type(e).__name__})") fromNone
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"}
defleer_reglas(p: Path = RAIZ / "gateway.yaml") -> dict:
r = yaml.safe_load(p.read_text())
pl = r["plazos_ms"]
ifnot pl["app"] > pl["gateway"] > pl["triton"] > pl["fila_triton"] > 0:
raiseRuntimeError(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
defleer_modelo(p: Path = RAIZ / "servir" / "modelo.json") -> dict:
ifnot p.exists():
raiseRuntimeError("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"]:
raiseRuntimeError(f"servir/modelo.json: los labels tienen huella {huella[:12]}… y la ficha dice {m['labels_sha256'][:12]}…")
return m
defmetricas(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),
}
defcrear_app(triton=None, reglas: dict | None = None, modelo: dict | None = None) -> FastAPI:
r = reglas orleer_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@asynccontextmanagerasyncdeflifespan(app: FastAPI):
m = modelo orleer_modelo()
cliente = triton orInferenceServerClient(url=tr["url"], conn_limit=tr["conexiones"])
try:
meta = await cliente.get_model_metadata(tr["modelo"])
except Exception as e: # noqa: BLE001await cliente.close()
raiseRuntimeError(f"no pude leer la metadata de '{tr['modelo']}' en Triton ({tr['url']}): {e}") fromNone
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()
raiseRuntimeError(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()
raiseRuntimeError(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 = 0print(f"gateway listo · {m['model_version']} · {len(m['labels'])} labels · Triton {tr['url']}", file=sys.stderr, flush=True)
yieldawait 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)
defanotar(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()
ifnot400 <= status < 500: # un 415 tarda microsegundos: no baja el p99 de nadie
mt["latencia"].observe(time.monotonic() - t0)
defcontexto(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)
asyncdefinvalida(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)
returnJSONResponse({"error": ev["error"], "request_id": rid}, 422, headers={"X-Request-ID": rid})
@app.exception_handler(StarletteHTTPException)
asyncdefhttp_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)
returnJSONResponse({"error": exc.detail, "request_id": rid}, exc.status_code,
headers={"X-Request-ID": rid, **(exc.headers or {})})
@app.get("/healthz")
asyncdefhealthz():
return {"status": "ok"}
@app.get("/readyz")
asyncdefreadyz(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 = FalsereturnJSONResponse({"status": "ready"if listo else"not ready"}, 200if listo else503)
@app.get("/metrics")
asyncdefmetrics():
returnResponse(generate_latest(registro), media_type=CONTENT_TYPE_LATEST)
@app.post(ct["ruta"])
asyncdefclassify(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)
returnJSONResponse({"error": ev["error"], "request_id": rid}, 503, headers={**hdr, "Retry-After": "1"})
st.en_vuelo += 1
mt["en_vuelo"].inc()
status = 500try:
revisar_tipo(request.headers.get("content-type"), ct["tipos"])
revisar_largo(request.headers.get("content-length"), lim["max_bytes"])
data = awaitleer_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:
raiseRechazo(503, f"sin lugar de decode en {lim['espera_cpu_ms']} ms", reintentar=True) fromNonetry:
t = time.monotonic()
x = awaitrun_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:
raiseRechazo(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:
raiseRechazo(504, f"Triton no contestó en {plazo * 1000:.0f} ms") fromNoneexcept InferenceServerException as e:
raiseRechazo(503, f"Triton: {e.message()}") fromNoneexcept (aiohttp.ClientError, OSError) as e:
raiseRechazo(503, f"sin conexión con Triton ({type(e).__name__})", reintentar=True) fromNonefinally:
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)
ifnot np.all(np.isfinite(z)):
raiseRechazo(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 = 200returnJSONResponse({"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
returnJSONResponse({"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"returnResponse(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]}"returnJSONResponse({"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.
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
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
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
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" …;docurl-s-X POST localhost:8701/v1/classify -H"Content-Type: $2"--data-binary @fotos-raras/$1done
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
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)
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
✓ 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
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"]
classResultado:
def__init__(self, y: np.ndarray):
self.y = y
defas_numpy(self, nombre: str) -> np.ndarray:
return self.y
classTritonFalso:
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 isnotNoneelse [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 = Falseasyncdefget_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]}]}
asyncdefis_model_ready(self, nombre):
await asyncio.sleep(self.demora_listo)
return self.listo
asyncdefinfer(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"orlist(e.shape())[1:] != [3, 32, 32]:
raiseInferenceServerException(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
returnResultado(np.tile(self.logits, (list(e.shape())[0], 1)))
asyncdefclose(self):
self.cerrado = True@pytest.fixturedefreglas():
returnleer_reglas()
@pytest.fixturedefmodelo():
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]}}
deffoto(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()
defpng_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)."""deftrozo(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"}
defcliente(reglas, modelo, **kw):
t = TritonFalso(**kw)
returnTestClient(crear_app(triton=t, reglas=reglas, modelo=modelo)), t
deflineas(capsys) -> list[dict]:
return [json.loads(x) for x in capsys.readouterr().out.splitlines() if x.startswith("{")]
# ---------------------------------------------------------------- 200deftest_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"]
assertabs(cuerpo["predictions"][0]["score"] - 0.512) < 1e-4assert 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"] == 200and ln["source"] == "mobile"and ln["top5"][0] == [7, 0.512]
assertset(ln["ms"]) == {"pre", "triton", "post", "total"} andlen(ln["sha256"]) == 12@pytest.mark.parametrize("k", [1, 3, 10])
deftest_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"]
assertlen(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")])
deftest_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 == 200deftest_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
deftest_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 == 200andabs(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
])
deftest_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 Tritonassertlineas(capsys)[-1]["status"] == codigo
deftest_413_sin_content_length_se_corta_al_leer(reglas, modelo):
deftrozos():
for _ inrange(11):
yieldb"x" * (1024 * 1024)
c, _ = cliente(reglas, modelo)
with c:
r = c.post("/v1/classify", content=trozos(), headers=JPEG) # un generador: va sin Content-Lengthassert r.status_code == 413deftest_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 == 422and r.headers["X-Request-ID"]
assertlineas(capsys)[-1]["status"] == 422deftest_405_get(reglas, modelo, capsys):
c, _ = cliente(reglas, modelo)
with c:
r = c.get("/v1/classify")
assert r.status_code == 405and r.headers["X-Request-ID"]
assertlineas(capsys)[-1]["status"] == 405deftest_499_quien_llama_se_va(reglas, modelo, capsys):
app = crear_app(triton=TritonFalso(), reglas=reglas, modelo=modelo)
enviados = []
asyncdefcorrer():
mensajes = iter([{"type": "http.request", "body": b"\xff\xd8" + b"x" * 100, "more_body": True},
{"type": "http.disconnect"}])
asyncdefrecibir():
returnnext(mensajes)
asyncdefenviar(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)}
asyncwith app.router.lifespan_context(app):
awaitapp(alcance, recibir, enviar)
asyncio.run(correr())
assertlineas(capsys)[-1]["status"] == 499# ---------------------------------------------------------------- 5xxdeftest_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 == 500assertlineas(capsys)[-1]["status"] == 500# el log dice lo mismo que la respuestadeftest_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 == 503deftest_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 == 503and r.headers["Retry-After"] == "1"deftest_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 == 504and0.14 < dt < 0.4deftest_503_la_17_en_vuelo(reglas, modelo):
app = crear_app(triton=TritonFalso(demora=0.1), reglas=reglas, modelo=modelo)
asyncdefcorrer():
asyncwith app.router.lifespan_context(app):
transporte = httpx.ASGITransport(app=app)
asyncwith httpx.AsyncClient(transport=transporte, base_url="http://gw") as c:
rs = await asyncio.gather(*(c.post("/v1/classify", content=foto(), headers=JPEG) for _ inrange(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())
assertsorted(codigos) == [200] * 16 + [503] * 4and retry == ["1"] * 4# ---------------------------------------------------------------- salud, arranque, métricasdeftest_healthz_no_pregunta_a_triton_y_readyz_si(reglas, modelo):
c, _ = cliente(reglas, modelo, listo=False)
with c:
assert c.get("/healthz").status_code == 200assert c.get("/readyz").status_code == 503deftest_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 == 503assert time.monotonic() - t < 1.0deftest_no_arranca_si_los_labels_no_son_los_del_modelo(reglas, modelo):
with pytest.raises(RuntimeError, match="logits"):
withTestClient(crear_app(triton=TritonFalso(n_logits=9), reglas=reglas, modelo=modelo)):
passdeftest_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)
deftest_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 _ inrange(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 200deftest_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)
assertlen(json.dumps(ln)) < 400and"data"notin 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.
✓ 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.
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 espython romper.py # solo: escondida, ni Claude la sabepython romper.py --verificar# ¿ya quedó?python romper.py --revelar# me rindopython romper.py --restaurar# deshacer
Catálogo de fallas (spoilers)El catálogo de abajo trae las respuestas. Ábrelo después de romper, para repasar.Abrir el catálogo
config
Más plazo para Triton
En la hora pico hubo una ráfaga de 504. El equipo de plataforma subió un commit a gateway.yaml directo a main y redesplegó el gateway: «le dimos más plazo a Triton, ya no debería cortar».
Síntoma. verificar.py: ✗ reglas gateway.yaml (7c6ed8d6ca07…) no es ninguna versión revisada (mundo/revisiones.json): git log -p gateway.yaml · la cadena de plazos no baja: 300 > 250 > 400 > 100
✗ salud tu gateway no responde en localhost:8701: python mundo/servicios.py estado (y logs/gateway.log)
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Alguien cambió las reglas del gateway.
Se cayó Triton.
Se cayó el gateway por otra cosa.
Terminalcómo confirmar
git log -1 --format="%h %an · %s" -- gateway.yaml
git show HEAD -- gateway.yaml | grep "^[-+] "
python mundo/servicios.py estado
tail -3 logs/gateway.log
Salida
1bec28f Equipo de plataforma · gateway: más plazo para Triton (400 ms): en la hora pico vimos 504 de más
- triton: 150 # el tope de la llamada a Triton (o lo que le quede a la request, si es menos)
+ triton: 400 # el tope de la llamada a Triton (o lo que le quede a la request, si es menos)
triton PID 5216 · ps Ss · /v2/health/live 200 · /v2/health/ready 200
gateway no corre
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']}")
RuntimeError: gateway.yaml: la cadena de plazos tiene que bajar (app > gateway > triton > fila_triton) y es 300 > 250 > 400 > 100
El arreglo. Un commit sin revisión dejó plazos_ms.triton: 400: la llamada a Triton podría esperar más que la request entera y que la app. La app se rendiría primero mientras el gateway sigue esperando: más 504, no menos. Tu gateway se niega a arrancar con la cadena al revés, y está bien. Arreglo: git revert --no-edit HEAD y python mundo/servicios.py arrancar gateway. Los 504 de la hora pico se investigan con ms.triton del log y las métricas de Triton, no estirando el plazo.
El equipo de plataforma vio la CPU del gateway al 40 % y subió un commit: «64 en vuelo y 8 decodes a la vez; así aprovechamos la máquina». Redesplegaron el gateway y todo responde.
Síntoma. verificar.py: ✗ reglas gateway.yaml (969fc1a5ffc9…) no es ninguna versión revisada (mundo/revisiones.json): git log -p gateway.yaml · en el peor momento una copia ocuparía ≈ 3,231 MiB y tiene 1024
✗ pruebas pytest no pasa: 1 failed, 29 passed in 1.14s
1cc9e26 Equipo de plataforma · gateway: más throughput (64 en vuelo y 8 decodes a la vez); la CPU estaba al 40 %
- decodes: 2 # decodes a la vez en un proceso (el semáforo)
+ decodes: 8 # decodes a la vez en un proceso (el semáforo)
- en_vuelo: 16 # requests adentro a la vez; la 17 recibe 503 al instante
+ en_vuelo: 64 # requests adentro a la vez; la 17 recibe 503 al instante
✗ reglas gateway.yaml (969fc1a5ffc9…) no es ninguna versión revisada (mundo/revisiones.json): git log -p gateway.yaml · en el peor momento una copia ocuparía ≈ 3,231 MiB y tiene 1024
Traceback (most recent call last):
File "~/c01-serving/verificar.py", line 616, in <module>
print(f"\n{len(r) - len(malos)}/{len(r)} en verde" + (f" · falta: {', '.join(malos)}" if malos else ""))
~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
BrokenPipeError: [Errno 32] Broken pipe
El arreglo. en_vuelo: 64 y decodes: 8, sin revisión. Hoy todo responde porque llegan fotos normales; el problema es el peor momento: 64 bodies de 10 MiB y 8 decodes de 40 MP son ≈ 3 GiB en una copia de 1 GiB. La primera ráfaga de fotos grandes mata al proceso por memoria y con él a las 63 requests que tenía adentro. Arreglo: git revert --no-edit HEAD y python mundo/servicios.py reiniciar gateway. Si falta throughput, se agregan copias (estación 9), no lugares en una.
Alguien de plataforma escribió en el canal: «el modelo de octubre daba resultados raros en mi prueba, puse el de septiembre en el repositorio mientras y reinicié Triton». Todo responde 200.
Síntoma. verificar.py: ✗ repositorio model_repository/classifier/1/model.onnx tiene huella 76ea30f48b41… y v4 dice 88bdea80ac92…: no es el engine aprobado
✗ triton Triton cargó el engine 76ea30f48b41… y el aprobado es 88bdea80ac92…: python servir/armar.py y python mundo/servicios.py reiniciar triton
✗ responde 13 de 200 fotos tienen otro top-1 que el engine aprobado (la primera: g-0023): lo que sirves no es el modelo aprobado o no lo preparas igual
El arreglo. El model.onnx del repositorio es el engine de v3, copiado a mano, y Triton lo cargó al reiniciar. El gateway sigue diciendo miniresnet-2026-10-01: cada respuesta afirma ser un modelo que no es, con código 200. Lo delatan las huellas: la del archivo, la que Triton anota en su log y el tag de v4. Arreglo: python servir/armar.py (vuelve a bajar el engine aprobado y compara su huella) y python mundo/servicios.py reiniciar triton. En C01 el model repository va dentro de la imagen de Triton: nadie lo cambia «mientras».
Un script de limpieza de plataforma «normalizó» los artefactos del registro: «dejamos los labels.json en orden alfabético, como en los demás modelos». El gateway sigue respondiendo bien.
Síntoma. verificar.py: ✗ repositorio el labels.json de v4 en el registro no tiene la huella de su tag labels_sha256: python mundo/modelos.py labels 4
classifier v4 · gate passed · engine listo (88bdea80ac92… · onnxruntime 1.32.0)
✗ modelo/labels.json de la corrida tiene huella d4c157898500… y v4 dice 97864728052c…: las categorías no son las del modelo. No lo sirvo
modelo/labels.json ["abrigos", "bolsas", "botines", "camisas", "pantalones", "playeras", "sandalias", "sueteres", "tenis", "vestidos"]
sha256 d4c157898500… · tag labels_sha256 97864728052c… · NO COINCIDEN
El arreglo. El labels.json de la corrida de v4 quedó en orden alfabético: los artefactos de una corrida se pueden reemplazar. El gateway responde bien porque su ficha se armó antes; el daño llegaría con el próximo armado: abrigos sería la posición 0 y cada respuesta diría otra categoría con buena confianza y código 200. Tu armar.py compara la huella con el tag labels_sha256 y se niega. Arreglo: python mundo/modelos.py reparar-labels 4 y python servir/armar.py.
Desde hace unos minutos, todas las fotos salen con 504. El gateway está vivo: su /healthz contesta 200.
Síntoma. verificar.py: ✗ triton Triton no dice «listo» (/v2/health/ready → sin respuesta en 1 s): python mundo/servicios.py estado
✗ salud /readyz → 503: Triton no está listo o tu gateway no lo sabe preguntar (python mundo/servicios.py estado)
✗ responde 200 de 200 fotos del examen no dieron 200 (la primera: g-0001 → 504)
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Triton está trabado.
El gateway está trabado.
La red está lenta.
Terminalcómo confirmar
python mundo/servicios.py estado
grep'"status": 504' logs/gateway.log |tail -1
Salida
triton PID 5923 · ps Ts (congelado: SIGSTOP) · /v2/health/live sin respuesta en 1 s · /v2/health/ready sin respuesta en 1 s
gateway PID 5740 · ps Ss · /healthz 200 · /readyz 503
{"request_id": "verificar-log-200-362318", "caller": "verificar", "source": "other", "model_version": "miniresnet-2026-10-01", "ms": {"pre": 0.8, "triton": 151.6, "total": 152.9}, "bytes": 1278, "sha256": "a3620aaeb761",
El arreglo. El proceso de Triton está congelado (SIGSTOP; en C01 sería una GPU o un driver colgados): acepta conexiones pero no contesta. Tu gateway hace lo correcto: corta cada llamada a los 150 ms con 504, /readyz dice 503 (Kubernetes sacaría la copia del reparto) y /healthz sigue en 200 (reiniciar el gateway no arreglaría nada). Arreglo: python mundo/servicios.py reiniciar triton. En C01, el liveness probe de Triton lo reinicia solo.
El canal de plataforma avisa que MLflow está en mantenimiento. Alguien pregunta: «¿se cayó también el clasificador?».
Síntoma. verificar.py: ✗ mundo MLflow no responde en localhost:5700: docker compose ps (¿está arriba el servicio mlflow?)
✗ repositorio MLflow no responde en localhost:5700: docker compose ps (¿está arriba el servicio mlflow?)
10/12 en verde · falta: mundo, repositorio
mlflow: exited · Exited (137) 7 seconds ago
s3: running · Up 6 minutes (healthy)
classify → 200
✗ no pude leer classifier v4 del registro (MlflowException): ¿está arriba MLflow? docker compose ps
[código 1]
El arreglo. MLflow está detenido, y el clasificador NO se cayó: Triton y el gateway ya tienen todo lo que necesitan (el engine en el repositorio y la ficha con sus labels), y siguen respondiendo 200. Lo que no se puede es armar un repositorio nuevo: armar.py falla en segundos, y está bien que falle. Servir no depende del registro en cada request; desplegar, sí. Arreglo: docker compose up -d --wait mlflow.
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
→6→
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 C01
En el dojo
El servidor de modelos
Triton con TensorRT en una T4 por zona; platform: "tensorrt_plan", KIND_GPU
el 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
MiniResNet: input [3, 32, 32] → logits [10], batch hasta 32 (engine de 181 kB)
El gateway
FastAPI en 3 a 12 copias de 1 vCPU y 1 GiB, detrás del ALB
el mismo código, un proceso en tu Mac (mundo/servicios.py) en el puerto 8701
Quién llama
la app, con su token verificado por el ALB; ≈ 500 fotos/s en el pico
curl y verificar.py (≈ 972 fotos/s con 8 a la vez)
Los límites y plazos
10 MiB, 40 MP, 1:8, 2 decodes, 16 en vuelo · 300 > 250 > 150 > 100 ms
los mismos, en gateway.yaml
Las pruebas
26 pruebas con pytest y un Triton falso, ≈ 2 min en CI
30 pruebas, ≈ 2 s
En la nube
En el dojo
Qué 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 zona
dos 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 Triton
la carpeta <code>model_repository/</code> de tu kit
En 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ú
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.
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.
gateway/app/revision.pyLa revisión de cada foto, de lo barato a lo caro, con el código de cada rechazo.
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.
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`.
Sensei es el curso de teoría desde cero de TrueML. Su lección de esta estación explica el porqué de lo que aquí construyes; léela antes o vuelve a ella cuando algo no cierre.