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

Export, engine y paridad

El gate aprobó un modelo, pero lo que se sirve es otro archivo, con otros números por dentro. ¿Cómo lo fabricas y cómo sabes que responde lo mismo y no es más lento?

Estás aquí5 · Export, engine y paridad

Arranca en 3 pasos

lo vital

Necesitas: Docker Desktop corriendo, con ≈ 700 MB libres para las imágenes de RustFS y MLflow · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 1.2 GB para el entorno virtual (PyTorch y ONNX Runtime) · Una Mac con Apple Silicon (el engine se optimiza para la máquina donde se construye) · git (con tu nombre y correo configurados) · Internet la primera vez (los paquetes, las imágenes y Fashion-MNIST) · Los puertos 9600, 9601 y 5600 libres en tu Mac

2

Levanta el mundo

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

Verifica

Terminal
python verificar.py mundo
Listo cuando: verificar.py mundo en verde: los buckets, el examen, la calibración, classifier v1–v4 con @champion = v3 (con su engine) y @challenger = v4, y git. Ya puedes practicar.
¿Algo falló al levantar?
Ojo: El 5000 lo ocupa AirPlay en macOS: por eso MLflow está en el 5600 (y el S3 en 9600, para no chocar con las estaciones anteriores).

python3 -m venv .venv && source .venv/bin/activate · Tarda unos minutos la primera vez (PyTorch pesa ≈ 1 GB). 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.1G

docker compose up -d --wait · La interfaz de MLflow queda en http://localhost:5600: ahí están las corridas y el modelo classifier.

SalidaSalida real · docker compose up -d --wait
 Container taller-c01-export-s3-1 Healthy 
 Container taller-c01-export-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…
  cal-2026-09: 256 fotos de train de ds-2026-09-01
  entrenando classifier v1 (2026-07) con ds-2026-06-01…
  classifier v1 (2026-07) · val_top1 0.7559 · 23 s
  entrenando classifier v2 (2026-08) con ds-2026-07-01…
  classifier v2 (2026-08) · val_top1 0.8088 · 23 s
  entrenando classifier v3 (2026-09) con ds-2026-08-01…
  classifier v3 (2026-09) · val_top1 0.8395 · 28 s
  entrenando classifier v4 (2026-10) con ds-2026-09-01…
  classifier v4 (2026-10) · val_top1 0.8675 · 34 s
  engine del champion (v3): engine.onnx 76ea30f48b41… · onnxruntime 1.32.0
✓ 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"
6114f2c kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo     S3 local (golden-v1, cal-2026-09, checkpoints) · MLflow: classifier v1–v4, @champion = v3 con su engine, @challenger = v4 · git

1/1 en verde

¿Ya está corriendo? Elige cómo practicar

las cuatro rondas

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

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

Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 6 de `GUION.md`, lo que convierte el modelo que aprobó el gate en lo que se va a servir: leer qué se va a servir y con qué reglas, exportar a ONNX con sus tres chequeos, construir el engine FP16 con su guardia, la paridad contra PyTorch (y un engine int8 que no pasa), el gate de latencia contra el engine del champion y el registro con sus huellas.

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 (`pipeline/registrar.py`, `mundo/modelos.py alias|pesos|reconstruir-engine`, `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 registres, ábrelo conmigo en MLflow (http://localhost:5600): la versión, sus tags y los archivos de `engine/`.
5. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.

Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
Ir al Guiado ↓
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 5 de C01, «Export, engine y paridad», 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, el entorno o la infraestructura, nunca en mi pipeline, 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 (`git log -p engine.yaml`, `git log -p mundo/servidor/`, `git status`, `python mundo/modelos.py versiones`, `python mundo/modelos.py engine 3` o `4`, `python mundo/s3.py …`, `docker compose ps`, y mis propios pasos de `pipeline/`) → 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 (TensorRT en una T4, el config.pbtxt de Triton, la release de NGC, `perf_analyzer`, MLflow con Postgres y S3).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.

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

Lee `CLAUDE.md`. **No leas `GUION.md`** 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 --pipeline`: respalda mis archivos en `.respaldo/`, pone el esqueleto (`pipeline/exportar.py`, `construir.py`, `paridad.py`, `latencia.py` y `registrar.py` con su contrato), borra `artefactos/` y deja a v4 con `engine=pendiente` (el registro, el engine del champion y el examen se quedan). Confírmame qué se borró y haz conmigo el commit del esqueleto.
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código ni con el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.

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

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

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

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

Guiado

paso a paso

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

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

Precálculos. Antes de exportar, las cuentas de servilleta: cuánto pesa el modelo en cada formato, cuánto se mueve un número al pasarlo a FP16, de qué tamaño tiene que ser el examen para separar un engine sano de uno roto, qué tanto de la máquina usa la prueba de latencia y por qué la holgura del dojo es 15 % y no 10 %. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.

1Qué se va a servir y con qué reglasSaber, antes de escribir código, qué versión se exporta, contra qué engine se compara, qué espera el servidor y cuáles son los umbrales.

La estación no decide si el modelo es bueno: eso ya lo decidió el gate. Decide dos cosas: si lo que se va a servir es ese modelo y si cabe en el tiempo. corrida.yaml trae las versiones por número; engine.yaml, la receta y los umbrales, revisados antes; y mundo/servidor/, lo que el servidor espera: el contrato y su versión del runtime. El engine del champion (v3) ya está en MLflow con su huella: es la referencia de la latencia.

YAMLengine.yaml
# engine.yaml · la receta del export y del engine de classifier, y los umbrales de la paridad y la latencia.
# Las escribe el equipo ANTES de la corrida y cambian solo en un PR propio que otra persona revisa (queda anotado en
# mundo/revisiones.json). Tus pasos la leen de aquí: no copies estos números en el código.
export:
  opset: 17                       # la versión de los operadores ONNX; se fija y se LEE del archivo después de exportar
  exportador: clasico             # torch.onnx.export(dynamo=False): traza el modelo una vez (el nuevo es otro PR)
  batch_max: 32                   # el eje 0 es dinámico; se prueba en las dos orillas: batch 1 y batch_max
  fotos_paridad: 512              # paridad del export (FP32 contra FP32), con fotos del golden set
  d_max: 0.001                    # FP32 contra FP32: los logits solo pueden diferir en los últimos decimales
engine:
  precision: fp16                 # pesos en FP16 (en C01, TensorRT con --fp16 en la T4)
  optimizacion: todas             # ORT_ENABLE_ALL: fusiona capas y elige el formato para ESTA máquina
  calibracion: cal-2026-09        # solo para int8: fotos de train, nunca del examen
paridad:
  examen: golden-v1               # las 1,000 fotos del examen congelado del gate
  manifest_sha256: 0061343ada92972b0cd41d17ccb17cdd6751e6a3a3296034ad1bae2879355ae9
  a1_min: 0.995                   # acuerdo top-1 contra PyTorch FP32 (a lo más 5 fotos de 1,000 cambian)
  o5_min: 0.99                    # solapamiento top-5
  d_max: 0.5                      # diferencia máxima de logits (un FP16 sano ≈ 0.01; uno roto, 1 o más)
latencia:
  tasas: [600, 1200]              # peticiones por segundo: el pico de diseño y el doble (una zona caída)
  peticiones: 2000                # por tasa, por ronda
  rondas: 5                       # champion y challenger alternados; se queda la mediana de los 5 p99
  holgura: 0.15                   # p99 del challenger ≤ (1 + holgura) × p99 del champion (en C01, 0.10: ver el precálculo)

Del equipo. Sus versiones revisadas están en mundo/revisiones.json: cada paso comprueba que la de hoy sea una de ellas.

Terminal
grep -v "^#" corrida.yaml
Salida
challenger: 4                   # classifier@challenger al arrancar: el candidato que aprobó el gate
champion: 3                     # classifier@champion: el que sirve hoy (su engine es la referencia de latencia)
examen: golden-v1               # el golden set congelado
Terminal
python mundo/modelos.py versiones

v4 tiene gate=passed pero engine=pendiente: eso es lo que esta estación completa.

Salida
v1  —            mes 2026-07 · equipo-2026-07-01 · gate passed · pesos 900f8ba1e607… · engine retirado
v2  —            mes 2026-08 · equipo-2026-08-01 · gate passed · pesos 6509cf6cab5e… · engine retirado
v3  @champion    mes 2026-09 · equipo-2026-09-01 · gate passed · pesos e858003795ba… · engine listo (76ea30f48b41… · fp16 · onnxruntime 1.32.0)
v4  @challenger  mes 2026-10 · cand-2026-10-01   · gate passed · pesos 0e36f3a192b0… · engine pendiente
Terminal
python mundo/modelos.py engine 3

El engine que hoy sirve producción, con sus huellas. Es lo que vas a fabricar para v4.

Salida
  engine                 listo
  engine_sha256          76ea30f48b41b2bfb5f7e1994a22a7ff651ab65a1d5e8709eb5e087234aca62e
  gate                   passed
  maquina                Darwin arm64
  onnx_sha256            5f9704ae8d2905e4c30c329bb38854302ecfb7939f7dd8442012ddf49a070468
  onnxruntime            1.32.0
  opset                  17
  pesos_sha256           e858003795baa74406aed45d3f9dc0b3d9a048deb2bccf1e145323770de11c07
  precision              fp16
  engine/engine.json         422 B · sha256 4a284937afc5…
  engine/engine.onnx      181347 B · sha256 76ea30f48b41…
  engine/model.onnx       179906 B · sha256 5f9704ae8d29…
Terminal
grep -v "^#" mundo/servidor/classifier.yaml
grep -v "^#" mundo/servidor/requirements.txt
Salida
nombre: classifier
max_batch_size: 32
entrada: {nombre: input, tipo: float32, forma: [3, 32, 32]}     # una foto ya preprocesada por el gateway
salida: {nombre: logits, tipo: float32, forma: [10]}             # un logit por categoría, en el orden de labels.json
onnxruntime==1.32.0
Listo cuando: Puedes decir en voz alta: exporto v4 con opset 17 a un engine FP16, construido con onnxruntime 1.32.0; el servidor espera input [batch, 3, 32, 32] → logits [batch, 10] y lotes de hasta 32; paridad a1 ≥ 99.5 %; latencia ≤ 1.15 × la del engine de v3.
Ojo: «Paridad no es calidad»: una paridad de 100 % dice que el engine se porta como el checkpoint, no que el checkpoint sea bueno. Eso lo dijo el gate.
Conceptos de este paso
Contrato con el servidormodel configuration / signatureCómo espera el servidor al modelo: el nombre, el tipo y la forma de la entrada y de la salida, y el batch más grande que va a juntar.Analogía, por qué importa y la trampa

AnalogíaEl enchufe y el voltaje: un aparato perfecto con otra clavija no se puede conectar.

Por qué importaEn C01 es el config.pbtxt de Triton. Si el engine no lo cumple, el servidor no carga el modelo o rechaza cada petición: se revisa antes de registrar, no en el despliegue.

TrampaCambiar el contrato del lado del servidor sin reconstruir el engine en el mismo cambio.

La guardia del buildbuild guard / pinned runtimeConstruir el engine con exactamente el runtime que lo va a servir, en ese tipo de máquina, y anotar los dos en sus huellas. Si no coinciden, el build se detiene.Analogía, por qué importa y la trampa

AnalogíaUna llave hecha para una cerradura: puede entrar en otra parecida y no girar.

Por qué importaEn C01, el .plan va atado a la compute capability de la T4 y a la release de NGC de Triton. Una actualización del servidor va en el mismo PR que reconstruye y vuelve a medir el engine.

Trampa«Es la misma API»: el engine probablemente carga con otro runtime, y por eso nadie nota que nunca se midió con él.

Precálculo
4

¿Qué tanto de la máquina usa la prueba de latencia?

ρ = λ ÷ X: la tasa de la prueba entre el máximo de fotos por segundo
Ver la cuenta
En C01una T4 da X ≈ 1,200 fotos/s: 250 ÷ 1,200 y 500 ÷ 1,200ρ ≈ 21 % y ≈ 42 %
En el dojoun hilo de tu Mac da X ≈ 2,425 fotos/s: 600 ÷ 2,425 y 1,200 ÷ 2,425ρ ≈ 25% y ≈ 49%

Qué decides con esto. Se mide a dos cargas porque la cola de la latencia crece más rápido que el centro cuando la fila se llena. El dojo elige sus tasas para quedar en el mismo lugar de la curva que C01: un cuarto y la mitad de la máquina.

Terminalterminal · compruébalo en el kit
python -c "
for nombre, X, tasas in [('C01, una T4 con el engine FP16', 1200, (250, 500)), ('dojo, un hilo de tu Mac', 2390, (600, 1200))]:
    print(nombre + ': ' + ' · '.join(f'{t}/s → ρ = {t / X:.0%}' for t in tasas))"
Salida
C01, una T4 con el engine FP16: 250/s → ρ = 21% · 500/s → ρ = 42%
dojo, un hilo de tu Mac: 600/s → ρ = 25% · 1200/s → ρ = 50%

Lo confirmas en el paso 5: latencia.py mide el máximo antes de empezar (2,425 fotos/s el challenger).

2Exportar a ONNX, con tres chequeosEl checkpoint de v4 como model.onnx: opset 17 leído del archivo, batch dinámico y las mismas respuestas que PyTorch en FP32.

Antes de exportar se comprueba que lo que se exporta es lo que aprobó el gate: la versión por número, gate=passed, su labels.json y la huella de sus pesos contra el tag de la versión. El export va en eval(), con los nombres del contrato y el eje 0 dinámico. Después, tres chequeos: onnx.checker con full_check (el grafo está bien formado), el opset escrito en el archivo (no el que pediste) y ONNX Runtime contra PyTorch, FP32 contra FP32, en batch 1 y en batch 32: las dos orillas de la firma. FP32 contra FP32 solo puede diferir en los últimos decimales.

Pythonpipeline/exportar.py
"""Paso «exportar»: el checkpoint que aprobó el gate se vuelve un archivo ONNX, y se revisa ahí mismo con tres chequeos.

    python pipeline/exportar.py                          # el challenger de corrida.yaml
    python pipeline/exportar.py --exportador dynamo      # una prueba con el exportador nuevo (va a artefactos/v4-dynamo/)

Contrato:
- engine.yaml está en un commit y su sha256 es una de las revisiones aprobadas (mundo/revisiones.json). Si no, se detiene.
- La versión es la de corrida.yaml, por número. Tiene que decir gate=passed, su labels.json tiene que ser
  entrada/categorias.json y la huella de sus pesos tiene que ser su tag pesos_sha256. Si algo no cuadra, se detiene.
- El modelo se exporta en eval(), con el opset de engine.yaml, la entrada y la salida con los nombres del contrato del
  servidor (mundo/servidor/classifier.yaml) y el eje 0 (batch) dinámico.
- Tres chequeos, y si uno falla, código 1: (1) onnx.checker con full_check; (2) el opset ESCRITO en el archivo es el
  pedido; (3) ONNX Runtime contra PyTorch, FP32 contra FP32, con las primeras fotos_paridad fotos del golden set
  (manifest con su huella), en batch 1 y en batch_max: mismo top-1 en todas y diferencia máxima ≤ export.d_max.
- Deja artefactos/v<N>/model.onnx y export.json (versión, huellas, opset, exportador y los dos chequeos de paridad).
"""
from __future__ import annotations

import argparse
import io
import json
import logging
import sys
import warnings

import numpy as np
import onnx
import torch
from _comun import (CLASES, MODELO, RAIZ, bajar, carpeta, contrato, corrida, escribir_json, git, huella_pesos, manifest,
                    mlflow_cliente, receta, revisiones, s3, sesion, sha256, sha_archivo, tensores)

from mundo.arquitectura import construir_modelo

ap = argparse.ArgumentParser()
ap.add_argument("--exportador", choices=["clasico", "dynamo"])
a = ap.parse_args()

# 1 · La receta: revisada y en un commit
r, cfg, firma = receta(), corrida(), contrato()
receta_sha = sha256((RAIZ / "engine.yaml").read_bytes())
if git("status", "--porcelain", "--", "engine.yaml"):
    sys.exit("✗ engine.yaml tiene cambios sin commit: la receta de un artefacto que se va a servir tiene que estar en git")
if receta_sha not in {x["engine_yaml_sha256"] for x in revisiones()}:
    sys.exit(f"✗ engine.yaml ({receta_sha[:12]}…) no es ninguna versión revisada (mundo/revisiones.json): git log -p engine.yaml")
exportador = a.exportador or r["export"]["exportador"]
version = cfg["challenger"]

# 2 · La versión aprobada, por número, con sus huellas
c = mlflow_cliente()
mv = c.get_model_version(MODELO, str(version))
if mv.tags.get("gate") != "passed":
    sys.exit(f"✗ {MODELO} v{version} no tiene gate=passed: nadie aprobó ese modelo")
if json.loads(bajar(mv.run_id, "modelo/labels.json")) != CLASES:
    sys.exit(f"✗ el labels.json de v{version} no es entrada/categorias.json: la salida 0 dejaría de ser «{CLASES[0]}»")
pesos = torch.load(io.BytesIO(bajar(mv.run_id, "modelo/pesos.pt")), map_location="cpu", weights_only=True)
huella = huella_pesos(pesos)
if huella != mv.tags.get("pesos_sha256"):
    sys.exit(f"✗ los pesos de v{version} tienen huella {huella[:12]}… y la versión dice {mv.tags.get('pesos_sha256', '?')[:12]}…: "
             "no es el modelo que aprobó el gate")
print(f"  {MODELO} v{version} · gate=passed · pesos {huella[:12]}… = el tag de la versión · labels.json en orden")

# 3 · Exportar, en eval()
modelo = construir_modelo(len(CLASES))
modelo.load_state_dict(pesos)
modelo.eval()
destino = carpeta(version, None if exportador == r["export"]["exportador"] else exportador)
ruta = destino / "model.onnx"
ent, sal = firma["entrada"]["nombre"], firma["salida"]["nombre"]
for nombre in ("onnxscript", "torch.onnx._internal.exporter._registration"):   # ruido del exportador nuevo
    logging.getLogger(nombre).setLevel(logging.CRITICAL)
with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    torch.onnx.export(modelo, (torch.zeros(1, *firma["entrada"]["forma"]),), str(ruta), dynamo=exportador == "dynamo",
                      opset_version=r["export"]["opset"], input_names=[ent], output_names=[sal],
                      dynamic_axes={ent: {0: "batch"}, sal: {0: "batch"}})
m = onnx.load(str(ruta))
forma = lambda v: [d.dim_param or d.dim_value for d in v.type.tensor_type.shape.dim]   # noqa: E731
print(f"[export] opset={next(o.version for o in m.opset_import if o.domain in ('', 'ai.onnx'))} "
      f"input={m.graph.input[0].name}{forma(m.graph.input[0])} output={m.graph.output[0].name}{forma(m.graph.output[0])} · "
      f"{ruta.stat().st_size / 1e3:.0f} kB · exportador {exportador}")

# 4 · Los tres chequeos
onnx.checker.check_model(m, full_check=True)
print("  1 · onnx.checker (full_check): el grafo es válido")
opset = next(o.version for o in m.opset_import if o.domain in ("", "ai.onnx"))
if opset != r["export"]["opset"]:
    sys.exit(f"✗ 2 · se pidió opset {r['export']['opset']} y el archivo dice opset {opset}: el contrato cambió sin que nadie lo pidiera")
print(f"  2 · el archivo dice opset {opset}, el que pide engine.yaml")
s = s3()
b, fotos = manifest(s, f"golden/{r['paridad']['examen']}/manifest.json")
if sha256(b) != r["paridad"]["manifest_sha256"]:
    sys.exit("✗ el manifest del golden set no es el que congeló engine.yaml")
x = tensores(s, fotos[:r["export"]["fotos_paridad"]])
with torch.no_grad():
    ref = modelo(torch.from_numpy(x)).numpy()
ses = sesion(ruta)
chequeos = {}
for lote in (1, r["export"]["batch_max"]):
    out = np.concatenate([ses.run(None, {ent: x[i:i + lote]})[0] for i in range(0, len(x), lote)])
    iguales = int((out.argmax(1) == ref.argmax(1)).sum())
    d = float(np.abs(out - ref).max())
    chequeos[f"batch_{lote}"] = {"fotos": len(x), "top1_iguales": iguales, "d": d}
    print(f"  3 · ONNX Runtime vs PyTorch (FP32), batch {lote:>2}: top-1 igual en {iguales}/{len(x)} · diferencia máxima {d:.2e}")
    if iguales != len(x) or d > r["export"]["d_max"]:
        sys.exit(f"✗ el export no responde como el checkpoint en batch {lote} (FP32 contra FP32 solo puede diferir en los "
                 f"últimos decimales, ≤ {r['export']['d_max']}): revisa eval(), el opset y el exportador")

escribir_json(destino / "export.json", {
    "version": str(version), "pesos_sha256": huella, "onnx_sha256": sha_archivo(ruta), "opset": opset,
    "exportador": exportador, "torch": torch.__version__, "onnx": onnx.__version__, "engine_yaml_sha256": receta_sha,
    "examen": r["paridad"]["examen"], "paridad_fp32": chequeos})
print(f"✓ {destino.name}/model.onnx · sha256 {sha_archivo(ruta)[:12]}… · los tres chequeos en verde")

Cada sys.exit es una razón para no seguir: una receta sin revisar, unos pesos que no son los aprobados, un opset que cambió o un archivo que no responde como el checkpoint.

Terminal
python pipeline/exportar.py
Salida
  classifier v4 · gate=passed · pesos 0e36f3a192b0… = el tag de la versión · labels.json en orden
[export] opset=17 input=input['batch', 3, 32, 32] output=logits['batch', 10] · 180 kB · exportador clasico
  1 · onnx.checker (full_check): el grafo es válido
  2 · el archivo dice opset 17, el que pide engine.yaml
  3 · ONNX Runtime vs PyTorch (FP32), batch  1: top-1 igual en 512/512 · diferencia máxima 1.19e-05
  3 · ONNX Runtime vs PyTorch (FP32), batch 32: top-1 igual en 512/512 · diferencia máxima 1.19e-05
✓ v4/model.onnx · sha256 ba6720d59f21… · los tres chequeos en verde
Terminal
python pipeline/exportar.py --exportador dynamo     # una prueba: va a artefactos/v4-dynamo/

El exportador nuevo, el de omisión desde PyTorch 2.9. Pediste opset 17 y el archivo dice 18: sin el chequeo 2, ese cambio de contrato pasaría con un aviso que nadie lee.

Salida
  classifier v4 · gate=passed · pesos 0e36f3a192b0… = el tag de la versión · labels.json en orden
[aviso de PyTorch] Setting ONNX exporter to use operator set version 18 because the requested opset_version 17 is a lower version than we have implementations for. Automatic version conversion will be performed, which may not be successful at converting to the requested version. If version conversion is unsuccessful, the opset version of the exported model will be kept at 18. Please consider setting opset_version >=18 to leverage latest ONNX features
[export] opset=18 input=input['batch', 3, 32, 32] output=logits['batch', 10] · 48 kB · exportador dynamo
  1 · onnx.checker (full_check): el grafo es válido
✗ 2 · se pidió opset 17 y el archivo dice opset 18: el contrato cambió sin que nadie lo pidiera
[código 1]
Terminal
python verificar.py receta pesos export
Salida
✓ receta    engine.yaml = la revisión del PR #44 (2026-08-20): opset 17, fp16, a1 ≥ 99.5%, holgura 15% · sin cambios pendientes
✓ pesos     v4: gate=passed · pesos 0e36f3a192b0… = su tag = los que exportaste · labels.json en orden
✓ export    model.onnx ba6720d59f21… · opset 17 · input[batch, …] · batch 1, 7 y 32 con el mismo top-1 que PyTorch · diferencia 1.1e-05

3/3 en verde
Listo cuando: artefactos/v4/model.onnx con opset 17, entrada input['batch', 3, 32, 32] y las mismas 512 respuestas que PyTorch en batch 1 y 32 (diferencia máxima 1.19e-05).
Ojo: El exportador nuevo dejó un archivo de 48 kB en lugar de 180: otro grafo. Puede que responda igual, pero cambiar de exportador es un PR aparte con su propia paridad.
Conceptos de este paso
Exportmodel exportConvertir el modelo de PyTorch (código + pesos) en un archivo que solo describe las cuentas: qué operaciones, en qué orden y con qué pesos.Analogía, por qué importa y la trampa

AnalogíaPasar una receta que vive en la cabeza de un chef a una tarjeta escrita: cualquier cocina la puede seguir sin el chef.

Por qué importaEl servidor no necesita Python ni el código de entrenamiento, y no abre un pickle (abrir un pickle puede correr código). Necesita un archivo que diga qué cuentas hacer.

TrampaExportar en modo train: la BatchNorm usa las estadísticas de cada lote y el archivo es otro modelo.

ONNXOpen Neural Network ExchangeUn formato abierto para modelos: un grafo de operadores estándar (Conv, Relu, Gemm…) con sus pesos y una firma: nombres, tipos y formas de la entrada y la salida.Analogía, por qué importa y la trampa

AnalogíaEl PDF de los modelos: lo genera una herramienta y lo leen muchas otras.

Por qué importaEs la entrega entre entrenamiento y serving. De él sale el engine (TensorRT en C01, ONNX Runtime en el dojo), y sirve para comparar en CPU antes de gastar GPU.

TrampaCreer que un ONNX válido es un ONNX correcto: el checker revisa que el grafo esté bien formado, no que responda lo mismo.

Opsetoperator set versionLa versión del conjunto de operadores que usa un archivo ONNX. Cada archivo la declara, y quien lo lee tiene que conocerla.Analogía, por qué importa y la trampa

AnalogíaLa edición de un diccionario: la misma palabra puede cambiar de significado entre ediciones.

Por qué importaEl opset es parte del contrato: si el runtime no lo conoce, no carga; si cambia sin que nadie lo pida, un operador puede significar otra cosa. Se fija en la receta y se lee del archivo después de exportar.

TrampaConfiar en el parámetro que pasaste: el exportador nuevo de PyTorch, al pedirle 17, deja el archivo en 18 con solo un aviso.

Eje de batch dinámicodynamic batch axisDeclarar que la dimensión 0 de la entrada y de la salida tiene un nombre («batch») en vez de un número: el archivo acepta 1 foto o varias juntas.Analogía, por qué importa y la trampa

AnalogíaUna charola con espacios ajustables en vez de una con exactamente 4 huecos.

Por qué importaEl servidor junta peticiones en un lote (batching dinámico). Si el archivo solo acepta batch 1, eso no funciona. Por eso el chequeo prueba las dos orillas: batch 1 y el máximo.

TrampaProbar solo con batch 1: un eje fijo por error pasa esa prueba y truena con el primer lote en producción.

Exportador clásico y exportador nuevoTorchScript-based exporter / dynamo exporterEl clásico (dynamo=False) corre el modelo una vez y graba las operaciones que pasaron (trazar). El nuevo (dynamo=True, el de omisión desde PyTorch 2.9) lo captura con torch.export.Analogía, por qué importa y la trampa

AnalogíaGrabar a alguien cocinando una vez contra copiar su libreta: casi siempre sale la misma receta, pero no siempre escrita igual.

Por qué importaCambiar de exportador cambia el archivo (aquí, de 180 kB a 48 kB y de opset 17 a 18). Es un cambio aparte, con su propia paridad, nunca de pasada.

TrampaActualizar PyTorch y que el exportador por omisión cambie sin que nadie lo note.

3Construir el engineDel model.onnx que pasó sus chequeos a engine.onnx en FP16, construido con el runtime del servidor, para esta máquina, con sus huellas.

Primero la guardia: el onnxruntime con que construyes tiene que ser el del servidor; si no, el build se detiene. Después, los pesos a FP16 dejando la entrada y la salida en FP32 (lo que pide el contrato). Al final, ONNX Runtime optimiza el grafo para esta máquina (fusiona cada Conv con su ReLU, elige el formato de memoria) y guarda el resultado: ese archivo es el engine. ONNX Runtime mismo avisa que el archivo optimizado solo debe usarse en el mismo entorno. Las huellas (pesos, ONNX, engine, receta), el runtime y la CPU quedan en engine.json.

Pythonpipeline/construir.py
"""Paso «construir»: del model.onnx que pasó sus tres chequeos al engine que va a correr el servidor, atado a esta
máquina y a este runtime, con sus huellas.

    python pipeline/construir.py                     # la precisión de engine.yaml (fp16)
    python pipeline/construir.py --precision int8    # una prueba: int8 calibrado (va a artefactos/v4-int8/)

Contrato:
- engine.yaml revisado y en un commit (como en exportar.py).
- Parte de artefactos/v<N>/model.onnx, y solo si su sha256 es el de export.json: el ONNX que pasó los tres chequeos.
- La guardia del build: el onnxruntime con que construyes tiene que ser el que corre el servidor
  (mundo/servidor/requirements.txt). Si no, se detiene: un engine se construye con el runtime que lo va a servir.
- fp16: los pesos a FP16, con la entrada y la salida en FP32 (como pide el contrato del servidor).
  int8: cuantización estática, calibrada con el set de engine.yaml (fotos de train, con su manifest); nunca con el examen.
- Optimiza el grafo con ONNX Runtime (nivel de engine.yaml) y guarda el resultado: ese archivo es el engine.
- Deja engine.onnx y engine.json: versión, huellas (pesos, onnx, engine, receta), precisión, opset, batch_max,
  onnxruntime, máquina y CPU.
"""
from __future__ import annotations

import argparse
import os
import platform
import sys
import tempfile
import time
from collections import Counter
from pathlib import Path

import onnx
import onnxruntime as ort
from _comun import (DATOS, RAIZ, carpeta, corrida, escribir_json, git, leer_json, manifest, receta, revisiones,
                    runtime_servidor, s3, sha256, sha_archivo, tensores)

ap = argparse.ArgumentParser()
ap.add_argument("--precision", choices=["fp16", "int8"])
a = ap.parse_args()

# 1 · La receta y el ONNX que pasó sus chequeos
r, cfg = receta(), corrida()
receta_sha = sha256((RAIZ / "engine.yaml").read_bytes())
if git("status", "--porcelain", "--", "engine.yaml") or receta_sha not in {x["engine_yaml_sha256"] for x in revisiones()}:
    sys.exit("✗ engine.yaml no es una versión revisada y en un commit: git status, git log -p engine.yaml")
version = cfg["challenger"]
precision = a.precision or r["engine"]["precision"]
origen = carpeta(version)
exp = leer_json(origen / "export.json")
if not exp or not (origen / "model.onnx").exists():
    sys.exit(f"✗ falta artefactos/v{version}/model.onnx con su export.json: corre pipeline/exportar.py")
if sha_archivo(origen / "model.onnx") != exp["onnx_sha256"]:
    sys.exit("✗ model.onnx no es el que pasó los tres chequeos (su sha256 no es el de export.json): vuelve a exportar")

# 2 · La guardia del build: el runtime del servidor
if ort.__version__ != runtime_servidor():
    sys.exit(f"✗ construyes con onnxruntime {ort.__version__} y el servidor corre {runtime_servidor()} "
             "(mundo/servidor/requirements.txt): un engine se construye con el runtime que lo va a servir")
destino = carpeta(version, None if precision == r["engine"]["precision"] else precision)
t0 = time.time()

# 3 · Bajar la precisión
with tempfile.TemporaryDirectory() as d:
    intermedio = Path(d) / f"{precision}.onnx"
    if precision == "fp16":
        from onnxruntime.transformers import float16

        onnx.save(float16.convert_float_to_float16(onnx.load(str(origen / "model.onnx")), keep_io_types=True), str(intermedio))
    else:
        from onnxruntime.quantization import CalibrationDataReader, quantize_static

        s = s3()
        _, fotos = manifest(s, f"calibracion/{r['engine']['calibracion']}/manifest.json")
        x = tensores(s, fotos)

        class Lector(CalibrationDataReader):
            def __init__(self):
                self.it = iter([{"input": x[i:i + 1]} for i in range(len(x))])

            def get_next(self):
                return next(self.it, None)

        quantize_static(str(origen / "model.onnx"), str(intermedio), Lector())
        print(f"  int8 calibrado con {len(x)} fotos de {r['engine']['calibracion']} (s3://{DATOS}/calibracion/…)")
    pesos = Counter(onnx.TensorProto.DataType.Name(t.data_type) for t in onnx.load(str(intermedio)).graph.initializer)
    print(f"  {precision}: {intermedio.stat().st_size / 1e3:.0f} kB (el ONNX FP32 pesa {(origen / 'model.onnx').stat().st_size / 1e3:.0f} kB) · "
          f"pesos {dict(pesos)}")

    # 4 · Optimizar para esta máquina y guardar: eso es el engine
    so = ort.SessionOptions()
    so.graph_optimization_level = {"todas": ort.GraphOptimizationLevel.ORT_ENABLE_ALL,
                                   "extendidas": ort.GraphOptimizationLevel.ORT_ENABLE_EXTENDED}[r["engine"]["optimizacion"]]
    so.optimized_model_filepath = str(destino / "engine.onnx")
    ort.InferenceSession(str(intermedio), so, providers=["CPUExecutionProvider"])

g = onnx.load(str(destino / "engine.onnx")).graph
print(f"  engine.onnx: {(destino / 'engine.onnx').stat().st_size / 1e3:.0f} kB · {len(g.node)} nodos "
      f"{dict(Counter(n.op_type for n in g.node).most_common(4))} · {time.time() - t0:.1f} s")
info = {"version": str(version), "precision": precision, "optimizacion": r["engine"]["optimizacion"],
        "pesos_sha256": exp["pesos_sha256"], "onnx_sha256": exp["onnx_sha256"], "engine_sha256": sha_archivo(destino / "engine.onnx"),
        "engine_yaml_sha256": receta_sha, "opset": exp["opset"], "batch_max": r["export"]["batch_max"],
        "onnxruntime": ort.__version__, "maquina": f"{platform.system()} {platform.machine()}",
        "cpu": os.popen("sysctl -n machdep.cpu.brand_string 2>/dev/null").read().strip() or platform.processor()}
escribir_json(destino / "engine.json", info)
print(f"✓ {destino.name}/engine.onnx · sha256 {info['engine_sha256'][:12]}… · onnxruntime {info['onnxruntime']} · {info['cpu']}")

La rama int8 se usa en el paso 4, como prueba.

Terminal
python pipeline/construir.py

El aviso de ONNX Runtime es real y es la idea del paso: un engine es para la máquina y el runtime donde se construyó.

Salida
  fp16: 94 kB (el ONNX FP32 pesa 180 kB) · pesos {'FLOAT16': 20}
[W:onnxruntime:, inference_session.cc:3368 operator()] Serializing optimized model with Graph Optimization level greater than ORT_ENABLE_EXTENDED and the NchwcTransformer enabled. The generated model may contain hardware specific optimizations, and should only be used in the same environment the model was optimized in.
  engine.onnx: 181 kB · 14 nodos {'FusedConv': 7, 'Conv': 2, 'Cast': 2, 'GlobalAveragePool': 1} · 0.0 s
✓ v4/engine.onnx · sha256 88bdea80ac92… · onnxruntime 1.32.0 · Apple M4
Terminal
ls -l artefactos/v4/*.onnx
python -c "…cuenta los operadores de model.onnx y de engine.onnx…"

Las 9 convoluciones y 7 ReLU del ONNX quedaron en 7 FusedConv + 2 Conv. Los 2 Cast pasan la entrada a FP16 y la salida a FP32. En la CPU, los pesos FP16 se volvieron FP32 al optimizar (ya redondeados): por eso engine.onnx pesa casi lo mismo que el ONNX FP32.

Salida
181347 artefactos/v4/engine.onnx
179906 artefactos/v4/model.onnx
artefactos/v4/model.onnx {'Conv': 9, 'Relu': 7, 'Add': 3, 'GlobalAveragePool': 1, 'Flatten': 1, 'Gemm': 1}
artefactos/v4/engine.onnx {'FusedConv': 7, 'Conv': 2, 'GlobalAveragePool': 1, 'Cast': 2, 'Flatten': 1, 'Gemm': 1}
Terminal
python verificar.py engine firma
Salida
✓ engine    engine.onnx 88bdea80ac92… · fp16 · desde model.onnx ba6720d59f21… · onnxruntime 1.32.0 = el del servidor · Darwin arm64 (Apple M4)
✓ firma     input float32 ['batch', 3, 32, 32] → logits float32 ['batch', 10] · 32 fotos juntas = mundo/servidor/classifier.yaml

2/2 en verde
Listo cuando: engine.onnx con su engine.json: sale del model.onnx que pasó los chequeos, FP16, onnxruntime 1.32.0 (el del servidor), Darwin arm64; y su firma cumple mundo/servidor/classifier.yaml con 32 fotos juntas.
Ojo: En C01, el build va en el runner de CI con la misma T4 que producción, nunca al arrancar el servidor: compilar un engine tarda minutos y no se hace con tráfico esperando.
Conceptos de este paso
Engineinference engineEl modelo ya compilado para una máquina y un runtime concretos: capas fusionadas, el formato de memoria que más le conviene a ese chip y, casi siempre, menos bits por número.Analogía, por qué importa y la trampa

AnalogíaUna traducción hecha para un público concreto: dice lo mismo, con las palabras que ese público lee más rápido.

Por qué importaEs lo que de verdad atiende a la gente. En C01, un model.plan de TensorRT en FP16 en la T4; en el dojo, un engine.onnx de ONNX Runtime para la CPU de tu Mac.

TrampaTratarlo como un archivo portátil: un engine de otra GPU o de otra versión del runtime no carga, o carga y da otros números.

FP16half precisionNúmeros de 16 bits: la mitad de memoria que FP32, con 3 a 4 cifras significativas y un máximo de 65,504.Analogía, por qué importa y la trampa

AnalogíaMedir con una regla de milímetros en vez de una de décimas de milímetro: casi siempre basta, y pesa la mitad.

Por qué importaParte el modelo a la mitad y, en una GPU, acelera las cuentas. Mueve los logits ≈ 0.01: casi ninguna respuesta cambia, salvo las casi empatadas.

TrampaUna capa cuyos números pasan de 65,504 se vuelve infinito: ese engine ya no es el modelo, y solo la paridad lo delata.

Huellas del build y build reproduciblebuild provenance / reproducible buildGuardar con la versión el sha256 de cada archivo (pesos, ONNX, engine, receta), con qué runtime y en qué máquina. Con lo mismo, el build da el mismo archivo byte por byte.Analogía, por qué importa y la trampa

AnalogíaEl número de lote de un medicamento: dice de qué ingredientes y de qué línea salió cada caja.

Por qué importaLa guardia de las 3 de la mañana pregunta «¿qué engine sirve y de qué salió?». Y si alguien sobrescribe un archivo, la huella lo delata y el build reproducible permite rehacerlo idéntico.

TrampaRegistrar el engine sin las huellas de su ONNX y de sus pesos: después nadie puede probar de qué checkpoint salió.

Precálculos
1

¿Cuánto pesa el modelo en FP32 y en FP16?

tamaño = parámetros × bytes por número (FP32: 4 B; FP16: 2 B)
Ver la cuenta
En C0124.5 M × 4 B y × 2 B≈ 98 MB en FP32 · ≈ 49 MB en FP16
En el dojo44,230 × 4 B y × 2 B≈ 177 kB en FP32 · ≈ 88 kB en FP16

Qué decides con esto. FP16 parte el archivo a la mitad, y en una GPU también acelera las cuentas. El dojo solo aprovecha lo primero: en la CPU de tu Mac, ONNX Runtime vuelve los pesos a FP32 para hacer las cuentas.

Terminalterminal · compruébalo en el kit
python -c "
from mundo.arquitectura import construir_modelo
n = sum(p.numel() for p in construir_modelo(10).parameters())
for nombre, p in [('C01, ResNet-50', 24_500_000), ('dojo, MiniResNet', n)]:
    print(f'{nombre}: {p:,} parámetros × 4 B = {p * 4 / 1e6:.3f} MB en FP32 · × 2 B = {p * 2 / 1e6:.3f} MB en FP16')"
Salida
C01, ResNet-50: 24,500,000 parámetros × 4 B = 98.000 MB en FP32 · × 2 B = 49.000 MB en FP16
dojo, MiniResNet: 44,230 parámetros × 4 B = 0.177 MB en FP32 · × 2 B = 0.088 MB en FP16

Lo confirmas en el paso 3: el ONNX FP32 pesa 180 kB y el FP16, 94 kB.

2

¿Cuánto se mueve un logit al pasar los pesos a FP16?

FP16 guarda 10 bits de mantisa: entre 2 y 4, los números van de 2⁻⁹ ≈ 0.002 en 0.002; cada peso se mueve a lo más ≈ 0.05 % de su valor
Ver la cuenta
En C01logits de ≈ 10, con 50 capas que suman errores chicosd ≈ 0.01 en un FP16 sano; 1 o más en uno roto
En el dojologits de ≈ 10, 9 convoluciones con pesos redondeadosd del orden de 0.01

Qué decides con esto. El umbral d ≤ 0.5 queda muy arriba de un FP16 sano y muy abajo de uno roto: no da falsas alarmas. Y un empate de 0.001 entre dos categorías puede deshacerse: por eso a1 no se pide del 100 %.

Terminalterminal · compruébalo en el kit
python -c "
import numpy as np
for x in (1.0, 2.3, 10.0):
    print(f'cerca de {x}: el siguiente FP16 está a {float(np.spacing(np.float16(x))):.5f}')
print('2.301 y 2.300 en FP16:', float(np.float16(2.301)), float(np.float16(2.300)), '· el mayor FP16:', float(np.finfo(np.float16).max))"
Salida
cerca de 1.0: el siguiente FP16 está a 0.00098
cerca de 2.3: el siguiente FP16 está a 0.00195
cerca de 10.0: el siguiente FP16 está a 0.00781
2.301 y 2.300 en FP16: 2.30078125 2.30078125 · el mayor FP16: 65504.0

Lo confirmas en el paso 4: el engine FP16 da d = 0.0130 sobre las 1,000 fotos.

4La paridad, y el engine que no pasaEl engine FP16 responde lo mismo que PyTorch FP32 en las 1,000 fotos del examen; uno int8, más chico y más rápido, no.

La referencia es el checkpoint aprobado, en PyTorch FP32 y en eval(). El candidato es el engine, abierto como lo abre el servidor, después de revisar el contrato. Los dos responden las 1,000 fotos de golden-v1 y se calculan tres números: a1 (misma primera categoría), o5 (cuántas de las 5 sugerencias coinciden) y d (la mayor diferencia entre logits). Después, la prueba: un engine int8 calibrado con fotos de train (nunca del examen) es más chico y más rápido, pero ¿es el mismo modelo?

Pythonpipeline/paridad.py
"""Paso «paridad»: ¿el engine que se va a servir responde lo mismo que el checkpoint que aprobó el gate?

    python pipeline/paridad.py                 # el engine de artefactos/v4/
    python pipeline/paridad.py --prueba int8   # el de artefactos/v4-int8/

Contrato:
- engine.yaml revisado y en un commit. El engine.onnx tiene que ser el de su engine.json (misma huella), construido con
  el runtime del servidor.
- El contrato con el servidor (mundo/servidor/classifier.yaml): una entrada con ese nombre, float32, forma
  [batch, 3, 32, 32] con el batch variable; una salida con ese nombre, [batch, 10]; y el engine acepta hasta
  max_batch_size fotos juntas. Si no cuadra, se detiene: el servidor no podría cargarlo.
- La referencia es PyTorch FP32 en eval(), con los pesos de la versión (huella = la de engine.json).
- El examen es el golden set completo de engine.yaml (manifest con su huella). El engine corre en lotes de max_batch_size.
- Tres números contra los umbrales de engine.yaml: a1 (acuerdo top-1), o5 (solapamiento top-5) y d (diferencia
  máxima de logits). Si alguno no pasa, código 1 y el motivo.
- Deja paridad.json: los tres números, los umbrales, pasa, el motivo y las fotos que cambiaron de top-1.
"""
from __future__ import annotations

import argparse
import io
import sys

import numpy as np
import torch
from _comun import (CLASES, MODELO, RAIZ, bajar, carpeta, contrato, corrida, escribir_json, git, huella_pesos, leer_json,
                    manifest, mlflow_cliente, receta, revisiones, runtime_servidor, s3, sesion, sha256, sha_archivo, tensores)

from mundo.arquitectura import construir_modelo

ap = argparse.ArgumentParser()
ap.add_argument("--prueba")
a = ap.parse_args()

# 1 · La receta y el engine, con sus huellas
r, cfg, firma = receta(), corrida(), contrato()
receta_sha = sha256((RAIZ / "engine.yaml").read_bytes())
if git("status", "--porcelain", "--", "engine.yaml") or receta_sha not in {x["engine_yaml_sha256"] for x in revisiones()}:
    sys.exit("✗ engine.yaml no es una versión revisada y en un commit: git status, git log -p engine.yaml")
version = cfg["challenger"]
d_ = carpeta(version, a.prueba)
info = leer_json(d_ / "engine.json")
if not info or not (d_ / "engine.onnx").exists():
    sys.exit(f"✗ falta {d_.name}/engine.onnx con su engine.json: corre pipeline/construir.py")
if sha_archivo(d_ / "engine.onnx") != info["engine_sha256"]:
    sys.exit("✗ engine.onnx no es el de engine.json (otra huella): vuelve a construirlo")
if info["onnxruntime"] != runtime_servidor():
    sys.exit(f"✗ el engine se construyó con onnxruntime {info['onnxruntime']} y el servidor corre {runtime_servidor()}: reconstrúyelo")

# 2 · El contrato con el servidor
ses = sesion(d_ / "engine.onnx")
e, o = ses.get_inputs(), ses.get_outputs()
esperado = f"{firma['entrada']['nombre']} float32 [batch, {', '.join(map(str, firma['entrada']['forma']))}] → " \
           f"{firma['salida']['nombre']} float32 [batch, {', '.join(map(str, firma['salida']['forma']))}]"
tiene = f"{e[0].name} {e[0].type} {e[0].shape} → {o[0].name} {o[0].type} {o[0].shape}"
if (len(e), len(o)) != (1, 1) or e[0].name != firma["entrada"]["nombre"] or o[0].name != firma["salida"]["nombre"] \
        or e[0].type != "tensor(float)" or o[0].type != "tensor(float)" or not isinstance(e[0].shape[0], str) \
        or e[0].shape[1:] != firma["entrada"]["forma"] or o[0].shape[1:] != firma["salida"]["forma"] \
        or info["batch_max"] < firma["max_batch_size"]:
    sys.exit(f"✗ el engine no cumple el contrato del servidor (mundo/servidor/classifier.yaml)\n  espera: {esperado} · "
             f"hasta {firma['max_batch_size']} fotos\n  tiene:  {tiene} · batch_max {info['batch_max']}")
print(f"  contrato: {tiene} · batch hasta {firma['max_batch_size']} = mundo/servidor/classifier.yaml")

# 3 · La referencia: PyTorch FP32 con los pesos de la versión
c = mlflow_cliente()
mv = c.get_model_version(MODELO, str(version))
pesos = torch.load(io.BytesIO(bajar(mv.run_id, "modelo/pesos.pt")), map_location="cpu", weights_only=True)
if huella_pesos(pesos) != info["pesos_sha256"] or info["pesos_sha256"] != mv.tags.get("pesos_sha256"):
    sys.exit(f"✗ los pesos de v{version} no son los que se exportaron (otra huella)")
modelo = construir_modelo(len(CLASES))
modelo.load_state_dict(pesos)
modelo.eval()

# 4 · El examen completo, en los dos
s = s3()
b, fotos = manifest(s, f"golden/{r['paridad']['examen']}/manifest.json")
if sha256(b) != r["paridad"]["manifest_sha256"]:
    sys.exit("✗ el manifest del golden set no es el que congeló engine.yaml")
x = tensores(s, fotos)
with torch.no_grad():
    ref = modelo(torch.from_numpy(x)).numpy()
lote = firma["max_batch_size"]
eng = np.concatenate([ses.run(None, {e[0].name: x[i:i + lote]})[0] for i in range(0, len(x), lote)])

# 5 · Los tres números
N = len(x)
igual = ref.argmax(1) == eng.argmax(1)
a1 = float(igual.mean())
t5r, t5e = np.argsort(-ref, 1)[:, :5], np.argsort(-eng, 1)[:, :5]
o5 = float(np.mean([len(set(p) & set(q)) / 5 for p, q in zip(t5r, t5e)]))
d = float(np.abs(ref - eng).max())
p = r["paridad"]
motivos = [m for m, mal in ((f"acuerdo top-1 {a1:.1%} < {p['a1_min']:.1%}", a1 < p["a1_min"]),
                            (f"solapamiento top-5 {o5:.2%} < {p['o5_min']:.0%}", o5 < p["o5_min"]),
                            (f"diferencia máxima de logits {d:.3f} > {p['d_max']}", d > p["d_max"])) if mal]
ordenados = np.sort(ref, 1)
cambios = [{"id": fotos[i]["id"], "ref": CLASES[int(ref[i].argmax())], "engine": CLASES[int(eng[i].argmax())],
            "margen_ref": round(float(ordenados[i, -1] - ordenados[i, -2]), 4)} for i in np.flatnonzero(~igual)]
print(f"  examen {r['paridad']['examen']}: {N} fotos · engine {info['precision']} vs PyTorch FP32")
print(f"  a1 = {a1:.1%} ({int(igual.sum())}/{N}, cambian {N - int(igual.sum())}; el límite deja {int(round((1 - p['a1_min']) * N))}) · "
      f"o5 = {o5:.2%} · d = {d:.4f}")
for x_ in cambios[:5]:
    print(f"    {x_['id']}: {x_['ref']} → {x_['engine']} (margen en FP32 entre los dos primeros logits: {x_['margen_ref']})")
escribir_json(d_ / "paridad.json", {
    "version": str(version), "engine_sha256": info["engine_sha256"], "precision": info["precision"],
    "examen": r["paridad"]["examen"], "manifest_sha256": r["paridad"]["manifest_sha256"], "engine_yaml_sha256": receta_sha,
    "n": N, "a1": a1, "o5": o5, "d": d, "umbrales": p, "pasa": not motivos, "motivo": "; ".join(motivos), "cambios": cambios})
if motivos:
    sys.exit(f"✗ paridad: NO pasa · {'; '.join(motivos)}. El engine no es el modelo que aprobó el gate: no se registra")
print(f"✓ paridad: pasa · a1 {a1:.1%} ≥ {p['a1_min']:.1%} · o5 {o5:.2%} ≥ {p['o5_min']:.0%} · d {d:.4f} ≤ {p['d_max']}")

Las fotos que cambian se guardan con el margen que tenían en FP32: un engine sano solo cambia las casi empatadas.

Terminal
python pipeline/paridad.py
Salida
  contrato: input tensor(float) ['batch', 3, 32, 32] → logits tensor(float) ['batch', 10] · batch hasta 32 = mundo/servidor/classifier.yaml
  examen golden-v1: 1000 fotos · engine fp16 vs PyTorch FP32
  a1 = 100.0% (1000/1000, cambian 0; el límite deja 5) · o5 = 99.98% · d = 0.0130
✓ paridad: pasa · a1 100.0% ≥ 99.5% · o5 99.98% ≥ 99% · d 0.0130 ≤ 0.5
Terminal
python pipeline/construir.py --precision int8
Salida
WARNING:root:Please consider to run pre-processing before quantization. Refer to example: https://github.com/microsoft/onnxruntime-inference-examples/blob/main/quantization/image_classification/cpu/ReadMe.md 
WARNING:root:Please consider pre-processing before quantization. See https://github.com/microsoft/onnxruntime-inference-examples/blob/main/quantization/image_classification/cpu/ReadMe.md 
  int8 calibrado con 256 fotos de cal-2026-09 (s3://ml-datos/calibracion/…)
  int8: 64 kB (el ONNX FP32 pesa 180 kB) · pesos {'INT8': 35, 'FLOAT': 35, 'INT32': 20}
  engine.onnx: 56 kB · 19 nodos {'QLinearConv': 9, 'QLinearAdd': 3, 'Transpose': 2, 'QuantizeLinear': 1} · 0.6 s
✓ v4-int8/engine.onnx · sha256 71931ab8a75e… · onnxruntime 1.32.0 · Apple M4
Terminal
python pipeline/paridad.py --prueba int8

Termina con código 1: en el pipeline, el paso se pone en rojo y no sigue.

Salida
  contrato: input tensor(float) ['batch', 3, 32, 32] → logits tensor(float) ['batch', 10] · batch hasta 32 = mundo/servidor/classifier.yaml
  examen golden-v1: 1000 fotos · engine int8 vs PyTorch FP32
  a1 = 98.9% (989/1000, cambian 11; el límite deja 5) · o5 = 99.24% · d = 0.8802
    g-0130: abrigos → vestidos (margen en FP32 entre los dos primeros logits: 0.0108)
    g-0143: abrigos → sueteres (margen en FP32 entre los dos primeros logits: 0.0057)
    g-0245: tenis → botines (margen en FP32 entre los dos primeros logits: 0.0169)
    g-0314: bolsas → sandalias (margen en FP32 entre los dos primeros logits: 0.148)
    g-0375: tenis → sandalias (margen en FP32 entre los dos primeros logits: 0.1093)
✗ paridad: NO pasa · acuerdo top-1 98.9% < 99.5%; diferencia máxima de logits 0.880 > 0.5. El engine no es el modelo que aprobó el gate: no se registra
[código 1]
Terminal
python verificar.py paridad frena
Salida
✓ paridad   golden-v1 completo: a1 100.0% · o5 99.98% · d 0.0130 (recalculados) · umbrales 99.5% / 99% / 0.5
✓ frena     int8: a1 98.9% · o5 99.24% · d 0.880 → NO pasa (acuerdo top-1 98.9% < 99.5%; diferencia máxima de logits 0.880 > 0.5) · no se registró

2/2 en verde
Listo cuando: FP16: a1 = 100.0 %, o5 = 99.98 %, d = 0.0130: pasa. Int8: a1 = 98.9 % (11 de 1,000 cambian, el límite deja 5) y d = 0.8802: no pasa, y no se registra.
Ojo: Varias fotos que el int8 cambió tenían un margen de 0.01 o menos en FP32: eran casi empates. Pero también cambió fotos con margen de 0.1, y d pasó de 0.5. No es redondeo: es otro modelo. Si de verdad conviene int8, va en su propio PR, quizás con un modelo entrenado para int8.
Conceptos de este paso
Paridad del engineengine parityComparar, foto por foto, lo que responde el engine con lo que responde el checkpoint aprobado en PyTorch FP32. No mide si el modelo es bueno: mide si es el mismo.Analogía, por qué importa y la trampa

AnalogíaLa prueba de imprenta: antes de imprimir 10,000 libros se revisa que el impreso diga lo que dice el original.

Por qué importaSin ella, lo que midió el gate (por categoría y por pedazo) no vale para lo que se sirve. Con ella, el gate aprobó el modelo y la paridad dice que lo servido es ese modelo.

TrampaConfundirla con la prueba de paridad del preprocesamiento (misma foto, mismos números en entrenamiento y serving): son dos exámenes distintos con el mismo apellido.

Acuerdo top-1, solapamiento top-5 y diferencia máximatop-1 agreement / top-5 overlap / max logit diffa1: fracción de fotos con la misma primera categoría. o5: fracción promedio de las 5 sugerencias que coinciden. d: la mayor diferencia entre un logit de la referencia y el del engine.Analogía, por qué importa y la trampa

AnalogíaDos traducciones: ¿dicen lo mismo en el título (a1), en el resumen (o5), y cuál es la palabra que más se aleja (d)?

Por qué importaa1 es lo que ve quien vende; o5, las sugerencias de abajo; d delata un bug antes de que cambie una respuesta. Umbrales: a1 ≥ 99.5 %, o5 ≥ 99 %, d ≤ 0.5.

TrampaMirar solo a1: un engine con una capa desbordada puede acertar casi todo el top-1 con logits deformes, y d lo atrapa.

El ruido del examentest-set size and noiseCuántas respuestas cambia un engine sano es un volado repetido N veces: alrededor de N × f, a veces más, a veces menos. El examen necesita lugar para eso sin confundirlo con un bug.Analogía, por qué importa y la trampa

AnalogíaUna báscula que oscila ± 50 g no sirve para decidir si un paquete pesa 1,010 o 1,000 g.

Por qué importaCon pocas fotos, el examen reprueba engines sanos por mala suerte y deja pasar rotos por buena. Con miles, los separa con varias desviaciones de margen.

TrampaBajar el examen a unas cuantas fotos «para que corra más rápido».

INT8 y calibraciónINT8 quantization / calibrationGuardar y calcular con enteros de 8 bits. Cada capa necesita una escala, que se elige viendo cómo se mueven sus números con fotos de ejemplo: la calibración.Analogía, por qué importa y la trampa

AnalogíaDescribir colores con solo 256 tonos: hay que elegir bien qué rango cubren, mirando fotos de verdad.

Por qué importaEs más chico y más rápido (aquí, 64 kB y casi el doble de fotos por segundo), pero mueve mucho más los números. Con una red que no se entrenó pensando en int8, la paridad puede no pasar.

TrampaCalibrar con el golden set: es otra forma de verle las respuestas al examen.

Precálculo
3

¿Con cuántas fotos el examen separa un engine sano de uno roto?

L = (1 − a_min) × N cambios permitidos; un engine que cambia una fracción f espera N × f, con σ = √(N × f × (1 − f)); margen D = (L − N × f) ÷ σ
Ver la cuenta
En C01N = 10,000, L = 50: sano (f = 0.2 %) espera 20, σ ≈ 4.5; roto (f = 1 %) espera 100, σ ≈ 9.9D ≈ +6.7 el sano · ≈ −5.0 el roto
En el dojoN = 1,000, L = 5: sano espera 2, σ ≈ 1.4; roto espera 10, σ ≈ 3.1D ≈ +2.1 el sano · ≈ −1.6 el roto

Qué decides con esto. Con 1,000 fotos el examen todavía separa, pero con poco margen: un engine con un bug chico podría pasar por suerte. Por eso C01 usa 10,000. Con las 512 del chequeo del export no alcanzaría para FP16, y no hace falta: FP32 contra FP32 no cambia ninguna respuesta.

Terminalterminal · compruébalo en el kit
python -c "
import math
for nombre, N in [('C01, 10,000 fotos', 10000), ('dojo, golden-v1', 1000), ('chequeo del export', 512)]:
    L = (1 - 0.995) * N
    for f in (0.002, 0.01):
        s = math.sqrt(N * f * (1 - f))
        print(f'{nombre}: L = {L:.1f} · f = {f:.1%}: espera {N * f:.1f} cambios, σ = {s:.2f}, D = {(L - N * f) / s:+.1f}')"
Salida
C01, 10,000 fotos: L = 50.0 · f = 0.2%: espera 20.0 cambios, σ = 4.47, D = +6.7
C01, 10,000 fotos: L = 50.0 · f = 1.0%: espera 100.0 cambios, σ = 9.95, D = -5.0
dojo, golden-v1: L = 5.0 · f = 0.2%: espera 2.0 cambios, σ = 1.41, D = +2.1
dojo, golden-v1: L = 5.0 · f = 1.0%: espera 10.0 cambios, σ = 3.15, D = -1.6
chequeo del export: L = 2.6 · f = 0.2%: espera 1.0 cambios, σ = 1.01, D = +1.5
chequeo del export: L = 2.6 · f = 1.0%: espera 5.1 cambios, σ = 2.25, D = -1.1
5El gate de latenciaEl p99 del engine nuevo no pasa de 1.15 × el del engine del champion, a 600 y a 1,200 peticiones por segundo.

Primero, la referencia: el engine de v3 desde MLflow, con su huella contra el tag de la versión. Sin él no hay gate. Después, la carga abierta: las peticiones llegan a su hora (Poisson, con la misma semilla para los dos) aunque la anterior no haya terminado, y cada latencia cuenta desde que llegó, con la fila. A cada tasa, cinco rondas alternadas (champion, challenger, champion…): se queda la mediana de los cinco p99 de cada uno, para que una ronda con ruido no decida.

Pythonpipeline/latencia.py
"""Paso «latencia»: ¿el engine nuevo no se volvió más lento que el que hoy sirve producción?

    python pipeline/latencia.py

Contrato:
- engine.yaml revisado y en un commit. El engine del challenger es el de artefactos/v<N>/ (huella = engine.json) y ya
  pasó la paridad (paridad.json con pasa y la misma huella). Si no, se detiene: medir un engine que no es el modelo no
  sirve de nada.
- La referencia es el engine del champion, el de corrida.yaml, por número: el que guarda su versión en MLflow
  (engine/engine.onnx), con la huella de su tag engine_sha256. Si no está o no cuadra, se detiene: sin referencia no
  hay gate (nunca «pasa» por default).
- Los dos se abren igual (como el servidor) y se miden en la misma máquina, a cada tasa de engine.yaml, con carga
  abierta: las peticiones llegan a su hora (Poisson con semilla fija, la misma para los dos) aunque la anterior no haya
  terminado. La latencia de cada una es desde que llegó hasta que tuvo respuesta (incluye la espera en la fila).
- Por tasa: rondas alternadas (champion, challenger, champion…); el p99 de cada ronda y la mediana de las rondas.
- La regla, a cada tasa: p99 del challenger ≤ (1 + holgura) × p99 del champion. Si no, código 1 y el motivo.
- Deja latencia.json: por tasa, los p99 de cada ronda, las medianas, el límite y pasa; y el máximo de fotos por
  segundo de cada engine.
"""
from __future__ import annotations

import math
import statistics
import sys
import tempfile
import time
from pathlib import Path

import numpy as np
from _comun import (MODELO, RAIZ, bajar, carpeta, corrida, escribir_json, git, leer_json, mlflow_cliente, receta,
                    revisiones, sesion, sha256, sha_archivo)

# 1 · La receta, el challenger (con su paridad) y el champion (por número, con su huella)
r, cfg = receta(), corrida()
receta_sha = sha256((RAIZ / "engine.yaml").read_bytes())
if git("status", "--porcelain", "--", "engine.yaml") or receta_sha not in {x["engine_yaml_sha256"] for x in revisiones()}:
    sys.exit("✗ engine.yaml no es una versión revisada y en un commit: git status, git log -p engine.yaml")
d_ = carpeta(cfg["challenger"])
info, par = leer_json(d_ / "engine.json"), leer_json(d_ / "paridad.json")
if not info or sha_archivo(d_ / "engine.onnx") != info["engine_sha256"]:
    sys.exit("✗ falta el engine del challenger con su engine.json: corre pipeline/construir.py")
if not par or not par["pasa"] or par["engine_sha256"] != info["engine_sha256"]:
    sys.exit("✗ ese engine no tiene una paridad que pasó: corre pipeline/paridad.py (y si no pasa, no se mide)")
c = mlflow_cliente()
v_ch = c.get_model_version(MODELO, str(cfg["champion"]))
esperada = v_ch.tags.get("engine_sha256")
try:
    champ = bajar(v_ch.run_id, "engine/engine.onnx")
except Exception:  # noqa: BLE001
    champ = b""
if not esperada or sha256(champ) != esperada:
    sys.exit(f"✗ el engine del champion (v{cfg['champion']}) no está en MLflow o no es el de su tag engine_sha256 "
             f"({sha256(champ)[:12] if champ else 'no hay archivo'}… vs {(esperada or '?')[:12]}…): sin la referencia de "
             "producción no hay gate de latencia")
tmp = Path(tempfile.mkdtemp()) / "champion.onnx"
tmp.write_bytes(champ)
engines = {"champion": sesion(tmp), "challenger": sesion(d_ / "engine.onnx")}

# 2 · Cómo se mide: carga abierta a una tasa fija, una petición = una foto
x = np.random.default_rng(0).standard_normal((256, 3, 32, 32)).astype(np.float32)   # la latencia no depende de la foto
for s in engines.values():   # calentar: las primeras corridas pagan cargas y cachés
    for i in range(300):
        s.run(None, {"input": x[i % 256:i % 256 + 1]})


def p99(s, tasa: float, n: int, semilla: int) -> float:
    llegadas = np.cumsum(np.random.default_rng(semilla).exponential(1 / tasa, n))   # Poisson: a veces llegan juntas
    t0, lat = time.perf_counter() + 0.005, []
    for i in range(n):
        llega = t0 + llegadas[i]
        while time.perf_counter() < llega:          # espera activa: la petición llega a su hora, no antes
            pass
        s.run(None, {"input": x[i % 256:i % 256 + 1]})
        lat.append((time.perf_counter() - llega) * 1000)   # desde que llegó: incluye la fila
    lat.sort()
    return lat[math.ceil(0.99 * n) - 1]                  # rango más cercano: la latencia número ⌈0.99·n⌉


def maximo(s, n: int = 3000) -> float:
    t = time.perf_counter()
    for i in range(n):
        s.run(None, {"input": x[i % 256:i % 256 + 1]})
    return n / (time.perf_counter() - t)


L = r["latencia"]
X = {k: maximo(s) for k, s in engines.items()}
print(f"  máximo, una foto a la vez: champion {X['champion']:,.0f} fotos/s · challenger {X['challenger']:,.0f} fotos/s")
tasas, motivos = {}, []
for tasa in L["tasas"]:
    rondas = {"champion": [], "challenger": []}
    for k in range(L["rondas"]):
        for quien in ("champion", "challenger"):
            rondas[quien].append(p99(engines[quien], tasa, L["peticiones"], semilla=1000 * tasa + k))
    t_c, t_n = statistics.median(rondas["champion"]), statistics.median(rondas["challenger"])
    limite = (1 + L["holgura"]) * t_c
    pasa = bool(t_n <= limite)
    tasas[str(tasa)] = {"rondas_champion": rondas["champion"], "rondas_challenger": rondas["challenger"], "p99_champion": t_c,
                        "p99_challenger": t_n, "limite": limite, "uso": tasa / X["challenger"], "pasa": pasa}
    print(f"  {tasa:>5} peticiones/s (uso ≈ {tasa / X['challenger']:.0%}) · p99 champion {t_c:.3f} ms · challenger {t_n:.3f} ms · "
          f"límite {limite:.3f} ms · {'pasa' if pasa else 'NO pasa'}")
    if not pasa:
        motivos.append(f"a {tasa}/s el p99 del challenger ({t_n:.3f} ms) pasa del límite ({limite:.3f} ms)")

escribir_json(d_ / "latencia.json", {
    "version": str(cfg["challenger"]), "engine_sha256": info["engine_sha256"], "champion_version": str(cfg["champion"]),
    "champion_engine_sha256": esperada, "engine_yaml_sha256": receta_sha, "holgura": L["holgura"], "peticiones": L["peticiones"],
    "rondas": L["rondas"], "maximo_fotos_s": X, "tasas": tasas, "pasa": not motivos, "motivo": "; ".join(motivos)})
if motivos:
    sys.exit(f"✗ latencia: NO pasa · {'; '.join(motivos)}")
print(f"✓ latencia: pasa a las {len(L['tasas'])} tasas (holgura {L['holgura']:.0%} sobre el champion v{cfg['champion']})")

La espera activa (while … pass) hace que cada petición llegue a su hora con precisión de microsegundos; un sleep se despierta tarde.

Terminal
python pipeline/latencia.py

No corras nada pesado mientras mide: tu Mac es el runner.

Salida
  máximo, una foto a la vez: champion 2,428 fotos/s · challenger 2,425 fotos/s
    600 peticiones/s (uso ≈ 25%) · p99 champion 1.092 ms · challenger 1.116 ms · límite 1.256 ms · pasa
   1200 peticiones/s (uso ≈ 49%) · p99 champion 1.937 ms · challenger 1.963 ms · límite 2.228 ms · pasa
✓ latencia: pasa a las 2 tasas (holgura 15% sobre el champion v3)
real 53.80
Terminal
python -c "…los p99 de cada ronda…"

Entre rondas del mismo engine, el p99 se mueve varios %: por eso la mediana, y por eso la holgura de 15 %.

Salida
600 /s · champion [1.086, 1.092, 1.059, 1.097, 1.121] · challenger [1.15, 1.098, 1.052, 1.127, 1.116]
1200 /s · champion [1.827, 1.937, 1.591, 2.111, 1.994] · challenger [1.751, 1.963, 1.602, 3.295, 1.988]
Terminal
python verificar.py latencia
Salida
✓ latencia  600/s: 1.12 ms vs 1.09 ms (límite 1.26) · 1200/s: 1.96 ms vs 1.94 ms (límite 2.23) · contra el engine del champion 76ea30f48b41…

1/1 en verde
Listo cuando: A 600/s: 1.116 ms contra 1.092 (límite 1.256). A 1,200/s: 1.963 ms contra 1.937 (límite 2.228). Pasa a las dos, contra el engine del champion con su huella.
Ojo: A 1,200/s el p99 casi se duplica aunque cada foto tarda lo mismo: la mitad de la máquina ocupada ya forma fila. Por eso se mide a dos cargas: un engine puede empatar a media carga y quedarse atrás con la carga doble.
Conceptos de este paso
Gate de latencialatency regression gateEl p99 del engine nuevo, medido como lo vería un cliente, no puede pasar de (1 + holgura) × el p99 del champion medido igual, a cada tasa de la prueba.Analogía, por qué importa y la trampa

AnalogíaUn corredor nuevo para el relevo: no tiene que ganar, pero no puede ser mucho más lento que el que ya corre, en la misma pista y el mismo día.

Por qué importaCada mes el engine se construye de nuevo: el build pudo elegir otras tácticas o cambiar la release. Comparar contra el champion, y no contra un número fijo, cancela todo lo que no es el modelo.

TrampaPasar por default cuando no hay referencia: sin el engine del champion no hay gate, y el paso tiene que fallar.

Carga abiertaopen-loop loadLas peticiones llegan a su hora, aunque la anterior no haya terminado; la latencia de cada una cuenta desde que llegó, con la espera en la fila incluida.Analogía, por qué importa y la trampa

AnalogíaLos clientes de un banco llegan cuando llegan, no cuando el cajero se desocupa.

Por qué importaAsí llega el tráfico real. Una carga cerrada (mandar la siguiente cuando vuelve la anterior) nunca forma fila y esconde la cola de la latencia.

TrampaMedir latencia mandando una petición tras otra y llamar a eso «el p99 del servidor».

Precálculo
5

¿Por qué la holgura del dojo es 15 % y no 10 %?

la holgura tiene que quedar arriba del ruido de medir dos veces lo mismo: dos engines de la misma red, medidos igual
Ver la cuenta
En C01runner dedicado con su T4 y perf_analyzer con miles de peticiones: el ruido entre corridas es de pocos %holgura 10 %
En el dojotu Mac, con otras cosas abiertas: dos engines de la misma red, medidos igual, se separaron hasta ≈ 8 % al probar el kitholgura 15 %, con la mediana de 5 rondas alternadas

Qué decides con esto. Una holgura más chica que el ruido frenaría engines sanos por suerte; una mucho más grande dejaría pasar engines lentos. Por eso el gate compara contra el champion medido igual, en la misma máquina y en rondas alternadas: lo que no es el modelo se cancela.

Lo confirmas en el paso 5: con la misma red, el challenger queda a +2.2% del champion a 600/s y a +1.3% a 1,200/s.

6Huellas y registrov4 con engine=listo, sus archivos en MLflow y las huellas de todo lo que se usó; ningún alias se mueve.

Registrar no es «subir el engine»: es dejar escrito qué es y por qué se puede servir. registrar.py exige que los cuatro reportes sean del mismo engine (la huella del archivo) y de la misma receta, que la paridad y la latencia hayan pasado, que el runtime sea el del servidor y que los alias sigan donde los dejó el orquestador. Sube model.onnx, engine.onnx y los reportes a la corrida de v4 y pone los tags. engine=listo va al final: si algo falla a la mitad, la versión sigue «pendiente».

Pythonpipeline/registrar.py
"""Paso «registrar»: el engine que pasó la paridad y la latencia queda en la versión del registro, con sus huellas.

    python pipeline/registrar.py

Contrato:
- engine.yaml revisado y en un commit. Los cuatro reportes de artefactos/v<N>/ (export, engine, paridad y latencia)
  son del MISMO engine (la misma huella, que es la del archivo) y de la misma receta; la paridad y la latencia pasaron;
  el engine se construyó con el runtime del servidor. Si algo no cuadra, se detiene y no registra nada.
- La versión es la de corrida.yaml, y los alias siguen donde los dejó el orquestador: challenger = esa versión y
  champion = el de corrida.yaml. Si alguien los movió, se detiene.
- Sube model.onnx, engine.onnx y los cuatro reportes a la corrida de la versión (artefactos engine/) y le pone sus
  tags: engine=listo, las huellas (onnx, engine, receta), onnxruntime, máquina, precisión, opset, los tres números de
  la paridad y el p99 de cada tasa.
- No mueve ningún alias: el despliegue (estaciones 8 a 10) toma el challenger desde aquí.
- Correrlo dos veces no cambia nada. Si la versión ya tiene OTRO engine, se detiene: el engine de una versión no cambia.
"""
from __future__ import annotations

import sys

from _comun import (MODELO, RAIZ, carpeta, corrida, git, leer_json, mlflow_cliente, receta, revisiones, runtime_servidor,
                    sha256, sha_archivo)

r, cfg = receta(), corrida()
receta_sha = sha256((RAIZ / "engine.yaml").read_bytes())
if git("status", "--porcelain", "--", "engine.yaml") or receta_sha not in {x["engine_yaml_sha256"] for x in revisiones()}:
    sys.exit("✗ engine.yaml no es una versión revisada y en un commit: git status, git log -p engine.yaml")
version = str(cfg["challenger"])
d_ = carpeta(version)
rep = {k: leer_json(d_ / f"{k}.json") for k in ("export", "engine", "paridad", "latencia")}
faltan = [k for k, v in rep.items() if not v]
if faltan or not (d_ / "engine.onnx").exists():
    sys.exit(f"✗ faltan reportes en artefactos/v{version}/: {faltan or ['engine.onnx']}. Corre los pasos anteriores")
e = rep["engine"]
if sha_archivo(d_ / "engine.onnx") != e["engine_sha256"] or sha_archivo(d_ / "model.onnx") != rep["export"]["onnx_sha256"]:
    sys.exit("✗ engine.onnx o model.onnx no son los de sus reportes (otra huella): vuelve a construir y a medir")
if {rep["paridad"]["engine_sha256"], rep["latencia"]["engine_sha256"]} != {e["engine_sha256"]} or e["onnx_sha256"] != rep["export"]["onnx_sha256"]:
    sys.exit("✗ la paridad o la latencia son de otro engine: vuelve a medir el de hoy")
if {x["engine_yaml_sha256"] for x in rep.values()} != {receta_sha}:
    sys.exit("✗ algún reporte se hizo con otra versión de engine.yaml")
if not rep["paridad"]["pasa"] or not rep["latencia"]["pasa"]:
    sys.exit(f"✗ no pasó: paridad {rep['paridad']['motivo'] or 'pasa'} · latencia {rep['latencia']['motivo'] or 'pasa'}")
if e["onnxruntime"] != runtime_servidor():
    sys.exit(f"✗ el engine es de onnxruntime {e['onnxruntime']} y el servidor corre {runtime_servidor()}: reconstrúyelo")

c = mlflow_cliente()
aliases = c.get_registered_model(MODELO).aliases
if str(aliases.get("challenger")) != version or str(aliases.get("champion")) != str(cfg["champion"]):
    sys.exit(f"✗ los alias se movieron: @challenger = v{aliases.get('challenger')} y @champion = v{aliases.get('champion')}; "
             f"la corrida es de v{version} contra v{cfg['champion']}. python mundo/modelos.py versiones")
mv = c.get_model_version(MODELO, version)
ya = mv.tags.get("engine_sha256")
if ya == e["engine_sha256"]:
    print(f"  v{version} ya tiene este engine ({ya[:12]}…): nada que hacer")
elif ya:
    sys.exit(f"✗ v{version} ya tiene otro engine ({ya[:12]}…): el engine de una versión no cambia")
else:
    for f in ("model.onnx", "engine.onnx", "export.json", "engine.json", "paridad.json", "latencia.json"):
        c.log_artifact(mv.run_id, str(d_ / f), "engine")
    tags = {"engine_sha256": e["engine_sha256"], "onnx_sha256": e["onnx_sha256"], "engine_yaml_sha256": receta_sha,
            "onnxruntime": e["onnxruntime"], "maquina": e["maquina"], "precision": e["precision"], "opset": str(e["opset"]),
            "paridad_a1": f"{rep['paridad']['a1']:.4f}", "paridad_o5": f"{rep['paridad']['o5']:.4f}",
            "paridad_d": f"{rep['paridad']['d']:.4f}",
            **{f"latencia_p99_{t}": f"{x['p99_challenger']:.3f}" for t, x in rep["latencia"]["tasas"].items()},
            "engine": "listo"}                      # al final: si algo de arriba falla, la versión sigue «pendiente»
    for k, v in tags.items():
        c.set_model_version_tag(MODELO, version, k, v)
    print(f"  v{version}: 6 archivos en engine/ y {len(tags)} tags")
print(f"✓ {MODELO} v{version} @challenger · engine {e['engine_sha256'][:12]}… · paridad a1 {rep['paridad']['a1']:.1%} · "
      f"latencia " + ", ".join(f"{t}/s {x['p99_challenger']:.2f} ms" for t, x in rep["latencia"]["tasas"].items()) +
      f" · champion sigue en v{cfg['champion']}")
Terminal
python pipeline/registrar.py
Salida
  v4: 6 archivos en engine/ y 13 tags
✓ classifier v4 @challenger · engine 88bdea80ac92… · paridad a1 100.0% · latencia 600/s 1.12 ms, 1200/s 1.96 ms · champion sigue en v3
Terminal
python pipeline/registrar.py

Otra vez: no cambia nada.

Salida
  v4 ya tiene este engine (88bdea80ac92…): nada que hacer
✓ classifier v4 @challenger · engine 88bdea80ac92… · paridad a1 100.0% · latencia 600/s 1.12 ms, 1200/s 1.96 ms · champion sigue en v3
Terminal
python mundo/modelos.py versiones
Salida
v1  —            mes 2026-07 · equipo-2026-07-01 · gate passed · pesos 900f8ba1e607… · engine retirado
v2  —            mes 2026-08 · equipo-2026-08-01 · gate passed · pesos 6509cf6cab5e… · engine retirado
v3  @champion    mes 2026-09 · equipo-2026-09-01 · gate passed · pesos e858003795ba… · engine listo (76ea30f48b41… · fp16 · onnxruntime 1.32.0)
v4  @challenger  mes 2026-10 · cand-2026-10-01   · gate passed · pesos 0e36f3a192b0… · engine listo (88bdea80ac92… · fp16 · onnxruntime 1.32.0)
Terminal
python mundo/modelos.py engine 4

Ábrelo también en MLflow: la versión 4 de classifier, sus tags y la carpeta engine/ de su corrida.

Salida
  champion_version       3
  engine                 listo
  engine_sha256          88bdea80ac920c546692c876b1977af2976b132e73b01bc67555307c656fd3c2
  engine_yaml_sha256     a5555c7b955c0739adc7af843a156b73ef767f1b6d5a0613eb6ecd246465c8a2
  examen                 golden-v1
  gate                   passed
  gate_run_id            wf-2026-10-01-gate
  latencia_p99_1200      1.963
  latencia_p99_600       1.116
  maquina                Darwin arm64
  onnx_sha256            ba6720d59f21048bcc140a59b1e81c913d1de4dcc1ea5075d62b319e71c5e1d7
  onnxruntime            1.32.0
  opset                  17
  paridad_a1             1.0000
  paridad_d              0.0130
  paridad_o5             0.9998
  pesos_sha256           0e36f3a192b0c8844d73630c181f16d64c1b80d1e80d406d40a86a6ed1264cb7
  precision              fp16
  engine/engine.json         532 B · sha256 a7a3a1f0abd8…
  engine/engine.onnx      181347 B · sha256 88bdea80ac92…
  engine/export.json         627 B · sha256 a65b16c351ad…
  engine/latencia.json      1603 B · sha256 121f2cf52a48…
  engine/model.onnx       179906 B · sha256 ba6720d59f21…
  engine/paridad.json        666 B · sha256 01f6c1d97226…
Terminal
python verificar.py registro
Salida
✓ registro  v4 @challenger · engine=listo · engine 88bdea80ac92… (el archivo en MLflow = el tag) · fp16 · onnxruntime 1.32.0 · paridad a1 100.0% · @champion sigue en v3

1/1 en verde
Terminal
python verificar.py
Salida
10/10 en verde
Listo cuando: classifier v4 @challenger con engine=listo, la huella de su engine (el archivo en MLflow = el tag), FP16, onnxruntime 1.32.0 y los números de paridad y latencia; @champion sigue en v3; los 10 checks en verde.
Ojo: Desde aquí, el despliegue (estaciones 8 a 10) toma el engine de la versión, no de tu carpeta: si alguien reemplaza el archivo, la huella lo delata.

Solo

10 objetivos

Empieza con python mundo/reiniciar.py --pipeline 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: engine.yaml, corrida.yaml y mundo/servidor/ se quedan como vienen.

01El S3 local y MLflow arriba, el mundo creado y la carpeta en git.python verificar.py mundo
02Trabajas con la receta revisada, en un commit y sin cambios pendientes.python verificar.py recetaPista: ¿Dónde dice cuáles versiones de engine.yaml están aprobadas?
03Exportas los pesos que aprobó el gate: los de v4, con su huella.python verificar.py pesos
04model.onnx con el opset de la receta (leído del archivo), batch dinámico y las mismas respuestas que PyTorch en FP32 en batch 1 y 32.python verificar.py exportPista: ¿Qué dos tamaños de lote son las orillas de lo que promete la firma?
05engine.onnx en FP16, desde ese model.onnx, construido con el runtime del servidor en esta máquina, con sus huellas.python verificar.py engine
06El engine cumple el contrato del servidor: nombres, tipos, formas y el batch más grande.python verificar.py firma
07La paridad del engine FP16 sobre las 1,000 fotos: a1, o5 y d correctos, y pasa.python verificar.py paridad
08Un engine int8 calibrado con fotos de train queda como NO pasa en su paridad, y no se registra.python verificar.py frenaPista: ¿Con qué fotos se calibra, y con cuáles nunca?
09El gate de latencia contra el engine del champion (con su huella), a las dos tasas, con rondas alternadas.python verificar.py latenciaPista: ¿Desde qué momento cuenta la latencia de una petición que llegó mientras otra se atendía?
10v4 con engine=listo, sus archivos y sus huellas en MLflow; ningún alias se movió.python verificar.py registro

Romper

6 fallas

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

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

Repaso

para el celular
El gate aprueba un modelo; esta estación prueba que lo que se sirve es ese modelo.Export a ONNX con opset fijo y batch dinámico, y tres chequeos (checker, opset leído del archivo, FP32 contra FP32 en batch 1 y el máximo). Engine con el runtime del servidor, para su máquina. Paridad con tres números sobre miles de fotos, latencia contra el champion medido igual, y las huellas de todo en el registro. Trampa: Aflojar los umbrales de paridad porque el engine nuevo es más rápido. Más rápido y distinto no es una mejora: es otro modelo que nadie aprobó. Listo cuando
  • model.onnx sale de los pesos que aprobó el gate (con su huella), con el opset de la receta leído del archivo, batch dinámico y las mismas respuestas que PyTorch en FP32.
  • engine.onnx se construyó con el runtime del servidor, en esta máquina, desde ese model.onnx, y cumple el contrato del servidor.
  • La paridad del engine sobre el examen congelado pasa los tres umbrales; un engine que no los pasa deja el paso en rojo y no se registra.
  • El p99 del engine nuevo cabe en la holgura contra el engine del champion, a las dos tasas, medido igual.
  • La versión tiene engine=listo, sus archivos y las huellas de todo; ningún alias se movió.
  • Sabes de qué pesos, con qué receta, con qué runtime y en qué máquina salió el engine que se va a servir.

Así te lo pueden preguntar en una entrevista

¿Cómo pasas un modelo de PyTorch a producción en GPU?

Lo exporto a ONNX en eval(), con opset fijo y el eje de batch dinámico, y lo reviso: onnx.checker, el opset leído del archivo y ONNX Runtime contra PyTorch FP32 en batch 1 y el máximo. Después construyo el engine de TensorRT en FP16 en la misma GPU y la misma release de Triton que producción, en CI. Paridad del engine en Triton contra PyTorch FP32 con miles de fotos, gate de latencia con perf_analyzer contra el champion, y registro con las huellas.

¿Cómo sabes que el engine FP16 es el mismo modelo?

Paridad foto por foto contra el checkpoint en FP32 sobre el golden set: acuerdo top-1 (≥ 99.5 %), solapamiento top-5 (≥ 99 %) y diferencia máxima de logits (≤ 0.5; un FP16 sano da ≈ 0.01). Con un examen grande, para que los pocos cambios de fotos casi empatadas no se confundan con un bug.

Tu engine FP16 da 97 % de acuerdo top-1. ¿Qué haces?

No es redondeo, es un bug. Parto el camino: corro el mismo examen con el ONNX en ONNX Runtime en FP32. Si ahí ya da 97 %, el problema es el export (eval(), opset, exportador). Si el ONNX da ≈ 100 %, es el build: busco la capa que se desborda en FP16 comparando salidas intermedias y la dejo en FP32. Mientras, nada se registra.

¿Por qué el engine se construye en CI y no al arrancar el servidor?

Porque va atado a la GPU (compute capability) y a la versión de TensorRT, tarda minutos y tiene que pasar paridad y latencia antes de servir. Se construye una vez en un runner con la misma GPU y la misma release, se le sacan huellas y se mete en la imagen. El servidor solo lo carga.

¿Cómo haces un gate de latencia que no dé falsas alarmas?

Comparo contra el champion medido igual, en la misma máquina y con la misma herramienta, en vez de contra un número fijo; con carga abierta a tasas fijas (el pico y el doble), mirando el p99, y con varias rondas alternadas. La holgura queda arriba del ruido de medir dos veces lo mismo.

¿Por qué no servir directamente el checkpoint de PyTorch?

Porque el servidor no necesita Python ni el código de entrenamiento, un pickle puede correr código al abrirse, y un engine compilado en FP16 es varias veces más rápido en la misma GPU. El costo es que el engine es otro archivo con otros números: por eso la paridad.

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

Contexto opcional

para consultar
Dónde estás en el pipeline

La estación 4 dejó a classifier v4 aprobado y con el alias challenger. Pero el servidor no corre ese checkpoint de PyTorch: corre un engine, el mismo modelo compilado para la máquina y el runtime que lo van a servir, con los pesos en menos bits. Esta estación lo fabrica en dos pasos (primero un ONNX, el modelo como archivo neutral, y después el engine) y lo examina dos veces: que responda lo mismo que el checkpoint que aprobó el gate (paridad) y que no sea más lento que el engine que hoy sirve producción (gate de latencia). Solo con las dos en verde queda en el registro, con las huellas de todo lo que se usó para fabricarlo. Si cualquiera falla, no se registra nada y el champion sigue atendiendo.

Entra
  • el checkpoint aprobado: classifier v4, por número, con la huella de sus pesos
  • la receta y los umbrales (engine.yaml), revisados en un PR antes de la corrida
  • el contrato del servidor (nombres, tipos y formas, el batch más grande) y la versión de su runtime
  • el golden set congelado, y el engine del champion como referencia de latencia
Sale
  • model.onnx: la entrega neutral, revisada con tres chequeos
  • engine.onnx: lo que de verdad corre el servidor, atado a esta máquina y a este runtime
  • los reportes de paridad y de latencia, y las huellas del build
  • la versión v4 con engine=listo, sus archivos y sus tags; ningún alias se mueve
El escenario del proyecto
Con kit · 4 rondas

El kit trae el marketplace de C01 el 1 de octubre de 2026, a las 07:00 UTC: el gate de la estación 4 aprobó al candidato de octubre y lo dejó como classifier v4 con el alias challenger y engine=pendiente. En el S3 local están el examen congelado golden-v1, el set de calibración y los checkpoints; en MLflow, el registro de v1 a v4, y v3 (@champion) con el engine que hoy sirve producción. Tú fabricas el engine de v4, lo examinas y lo registras.

El mundo vive en dos servicios: el S3 local (el examen, la calibración y los checkpoints) y MLflow (el registro de modelos). mundo/crear.py los llena igual cada vez: entrena los cuatro modelos del registro con la receta de la estación 3 y construye el engine del champion, por eso tarda unos minutos.

Glosario: los 16 conceptos

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

Exportmodel exportConvertir el modelo de PyTorch (código + pesos) en un archivo que solo describe las cuentas: qué operaciones, en qué orden y con qué pesos.Analogía, por qué importa y la trampa

AnalogíaPasar una receta que vive en la cabeza de un chef a una tarjeta escrita: cualquier cocina la puede seguir sin el chef.

Por qué importaEl servidor no necesita Python ni el código de entrenamiento, y no abre un pickle (abrir un pickle puede correr código). Necesita un archivo que diga qué cuentas hacer.

TrampaExportar en modo train: la BatchNorm usa las estadísticas de cada lote y el archivo es otro modelo.

ONNXOpen Neural Network ExchangeUn formato abierto para modelos: un grafo de operadores estándar (Conv, Relu, Gemm…) con sus pesos y una firma: nombres, tipos y formas de la entrada y la salida.Analogía, por qué importa y la trampa

AnalogíaEl PDF de los modelos: lo genera una herramienta y lo leen muchas otras.

Por qué importaEs la entrega entre entrenamiento y serving. De él sale el engine (TensorRT en C01, ONNX Runtime en el dojo), y sirve para comparar en CPU antes de gastar GPU.

TrampaCreer que un ONNX válido es un ONNX correcto: el checker revisa que el grafo esté bien formado, no que responda lo mismo.

Opsetoperator set versionLa versión del conjunto de operadores que usa un archivo ONNX. Cada archivo la declara, y quien lo lee tiene que conocerla.Analogía, por qué importa y la trampa

AnalogíaLa edición de un diccionario: la misma palabra puede cambiar de significado entre ediciones.

Por qué importaEl opset es parte del contrato: si el runtime no lo conoce, no carga; si cambia sin que nadie lo pida, un operador puede significar otra cosa. Se fija en la receta y se lee del archivo después de exportar.

TrampaConfiar en el parámetro que pasaste: el exportador nuevo de PyTorch, al pedirle 17, deja el archivo en 18 con solo un aviso.

Eje de batch dinámicodynamic batch axisDeclarar que la dimensión 0 de la entrada y de la salida tiene un nombre («batch») en vez de un número: el archivo acepta 1 foto o varias juntas.Analogía, por qué importa y la trampa

AnalogíaUna charola con espacios ajustables en vez de una con exactamente 4 huecos.

Por qué importaEl servidor junta peticiones en un lote (batching dinámico). Si el archivo solo acepta batch 1, eso no funciona. Por eso el chequeo prueba las dos orillas: batch 1 y el máximo.

TrampaProbar solo con batch 1: un eje fijo por error pasa esa prueba y truena con el primer lote en producción.

Exportador clásico y exportador nuevoTorchScript-based exporter / dynamo exporterEl clásico (dynamo=False) corre el modelo una vez y graba las operaciones que pasaron (trazar). El nuevo (dynamo=True, el de omisión desde PyTorch 2.9) lo captura con torch.export.Analogía, por qué importa y la trampa

AnalogíaGrabar a alguien cocinando una vez contra copiar su libreta: casi siempre sale la misma receta, pero no siempre escrita igual.

Por qué importaCambiar de exportador cambia el archivo (aquí, de 180 kB a 48 kB y de opset 17 a 18). Es un cambio aparte, con su propia paridad, nunca de pasada.

TrampaActualizar PyTorch y que el exportador por omisión cambie sin que nadie lo note.

Engineinference engineEl modelo ya compilado para una máquina y un runtime concretos: capas fusionadas, el formato de memoria que más le conviene a ese chip y, casi siempre, menos bits por número.Analogía, por qué importa y la trampa

AnalogíaUna traducción hecha para un público concreto: dice lo mismo, con las palabras que ese público lee más rápido.

Por qué importaEs lo que de verdad atiende a la gente. En C01, un model.plan de TensorRT en FP16 en la T4; en el dojo, un engine.onnx de ONNX Runtime para la CPU de tu Mac.

TrampaTratarlo como un archivo portátil: un engine de otra GPU o de otra versión del runtime no carga, o carga y da otros números.

FP16half precisionNúmeros de 16 bits: la mitad de memoria que FP32, con 3 a 4 cifras significativas y un máximo de 65,504.Analogía, por qué importa y la trampa

AnalogíaMedir con una regla de milímetros en vez de una de décimas de milímetro: casi siempre basta, y pesa la mitad.

Por qué importaParte el modelo a la mitad y, en una GPU, acelera las cuentas. Mueve los logits ≈ 0.01: casi ninguna respuesta cambia, salvo las casi empatadas.

TrampaUna capa cuyos números pasan de 65,504 se vuelve infinito: ese engine ya no es el modelo, y solo la paridad lo delata.

INT8 y calibraciónINT8 quantization / calibrationGuardar y calcular con enteros de 8 bits. Cada capa necesita una escala, que se elige viendo cómo se mueven sus números con fotos de ejemplo: la calibración.Analogía, por qué importa y la trampa

AnalogíaDescribir colores con solo 256 tonos: hay que elegir bien qué rango cubren, mirando fotos de verdad.

Por qué importaEs más chico y más rápido (aquí, 64 kB y casi el doble de fotos por segundo), pero mueve mucho más los números. Con una red que no se entrenó pensando en int8, la paridad puede no pasar.

TrampaCalibrar con el golden set: es otra forma de verle las respuestas al examen.

La guardia del buildbuild guard / pinned runtimeConstruir el engine con exactamente el runtime que lo va a servir, en ese tipo de máquina, y anotar los dos en sus huellas. Si no coinciden, el build se detiene.Analogía, por qué importa y la trampa

AnalogíaUna llave hecha para una cerradura: puede entrar en otra parecida y no girar.

Por qué importaEn C01, el .plan va atado a la compute capability de la T4 y a la release de NGC de Triton. Una actualización del servidor va en el mismo PR que reconstruye y vuelve a medir el engine.

Trampa«Es la misma API»: el engine probablemente carga con otro runtime, y por eso nadie nota que nunca se midió con él.

Contrato con el servidormodel configuration / signatureCómo espera el servidor al modelo: el nombre, el tipo y la forma de la entrada y de la salida, y el batch más grande que va a juntar.Analogía, por qué importa y la trampa

AnalogíaEl enchufe y el voltaje: un aparato perfecto con otra clavija no se puede conectar.

Por qué importaEn C01 es el config.pbtxt de Triton. Si el engine no lo cumple, el servidor no carga el modelo o rechaza cada petición: se revisa antes de registrar, no en el despliegue.

TrampaCambiar el contrato del lado del servidor sin reconstruir el engine en el mismo cambio.

Paridad del engineengine parityComparar, foto por foto, lo que responde el engine con lo que responde el checkpoint aprobado en PyTorch FP32. No mide si el modelo es bueno: mide si es el mismo.Analogía, por qué importa y la trampa

AnalogíaLa prueba de imprenta: antes de imprimir 10,000 libros se revisa que el impreso diga lo que dice el original.

Por qué importaSin ella, lo que midió el gate (por categoría y por pedazo) no vale para lo que se sirve. Con ella, el gate aprobó el modelo y la paridad dice que lo servido es ese modelo.

TrampaConfundirla con la prueba de paridad del preprocesamiento (misma foto, mismos números en entrenamiento y serving): son dos exámenes distintos con el mismo apellido.

Acuerdo top-1, solapamiento top-5 y diferencia máximatop-1 agreement / top-5 overlap / max logit diffa1: fracción de fotos con la misma primera categoría. o5: fracción promedio de las 5 sugerencias que coinciden. d: la mayor diferencia entre un logit de la referencia y el del engine.Analogía, por qué importa y la trampa

AnalogíaDos traducciones: ¿dicen lo mismo en el título (a1), en el resumen (o5), y cuál es la palabra que más se aleja (d)?

Por qué importaa1 es lo que ve quien vende; o5, las sugerencias de abajo; d delata un bug antes de que cambie una respuesta. Umbrales: a1 ≥ 99.5 %, o5 ≥ 99 %, d ≤ 0.5.

TrampaMirar solo a1: un engine con una capa desbordada puede acertar casi todo el top-1 con logits deformes, y d lo atrapa.

El ruido del examentest-set size and noiseCuántas respuestas cambia un engine sano es un volado repetido N veces: alrededor de N × f, a veces más, a veces menos. El examen necesita lugar para eso sin confundirlo con un bug.Analogía, por qué importa y la trampa

AnalogíaUna báscula que oscila ± 50 g no sirve para decidir si un paquete pesa 1,010 o 1,000 g.

Por qué importaCon pocas fotos, el examen reprueba engines sanos por mala suerte y deja pasar rotos por buena. Con miles, los separa con varias desviaciones de margen.

TrampaBajar el examen a unas cuantas fotos «para que corra más rápido».

Gate de latencialatency regression gateEl p99 del engine nuevo, medido como lo vería un cliente, no puede pasar de (1 + holgura) × el p99 del champion medido igual, a cada tasa de la prueba.Analogía, por qué importa y la trampa

AnalogíaUn corredor nuevo para el relevo: no tiene que ganar, pero no puede ser mucho más lento que el que ya corre, en la misma pista y el mismo día.

Por qué importaCada mes el engine se construye de nuevo: el build pudo elegir otras tácticas o cambiar la release. Comparar contra el champion, y no contra un número fijo, cancela todo lo que no es el modelo.

TrampaPasar por default cuando no hay referencia: sin el engine del champion no hay gate, y el paso tiene que fallar.

Carga abiertaopen-loop loadLas peticiones llegan a su hora, aunque la anterior no haya terminado; la latencia de cada una cuenta desde que llegó, con la espera en la fila incluida.Analogía, por qué importa y la trampa

AnalogíaLos clientes de un banco llegan cuando llegan, no cuando el cajero se desocupa.

Por qué importaAsí llega el tráfico real. Una carga cerrada (mandar la siguiente cuando vuelve la anterior) nunca forma fila y esconde la cola de la latencia.

TrampaMedir latencia mandando una petición tras otra y llamar a eso «el p99 del servidor».

Huellas del build y build reproduciblebuild provenance / reproducible buildGuardar con la versión el sha256 de cada archivo (pesos, ONNX, engine, receta), con qué runtime y en qué máquina. Con lo mismo, el build da el mismo archivo byte por byte.Analogía, por qué importa y la trampa

AnalogíaEl número de lote de un medicamento: dice de qué ingredientes y de qué línea salió cada caja.

Por qué importaLa guardia de las 3 de la mañana pregunta «¿qué engine sirve y de qué salió?». Y si alguien sobrescribe un archivo, la huella lo delata y el build reproducible permite rehacerlo idéntico.

TrampaRegistrar el engine sin las huellas de su ONNX y de sus pesos: después nadie puede probar de qué checkpoint salió.

Nube real vs. local
En C01En el dojo
El modeloResNet-50, ≈ 24.5 M de parámetros (≈ 98 MB en FP32)MiniResNet, 44,230 parámetros (≈ 180 kB en ONNX FP32)
El enginemodel.plan de TensorRT, FP16, compilado en una T4engine.onnx de ONNX Runtime: pesos en FP16 y el grafo optimizado para la CPU de tu Mac
El contrato con el servidorconfig.pbtxt de Triton: input [3, 224, 224] → logits [500], batch hasta 16mundo/servidor/classifier.yaml: input [3, 32, 32] → logits [10], batch hasta 32
El examen de paridad≈ 10,000 fotos del golden set, contra Triton en la T4las 1,000 de golden-v1, contra el engine abierto como lo abre el servidor
La latenciaperf_analyzer contra Triton a 250 y 500 peticiones/s; holgura 10 %carga abierta dentro del proceso a 600 y 1,200 peticiones/s; holgura 15 %
Dónde correun runner de CI con una T4 (g4dn.xlarge), ≈ 20–30 minla CPU de tu Mac: ≈ 15 s todo menos la latencia (≈ 53 s)
En la nubeEn el dojoQué cambia
TensorRT en una T4: <code>model.plan</code> en FP16ONNX Runtime en la CPU de tu Mac: <code>engine.onnx</code> con pesos FP16Los dos fusionan capas, eligen el formato para su chip y quedan atados a él y a su versión. TensorRT hace las cuentas en FP16 en la GPU; ONNX Runtime en la CPU guarda los pesos en FP16 y los vuelve a FP32 para calcular. El redondeo de los pesos mueve los logits del mismo orden (≈ 0.01).
El config.pbtxt de Triton en el model repository<code>mundo/servidor/classifier.yaml</code>Los dos dicen nombres, tipos, formas y el batch más grande. Triton se niega a cargar un modelo que no cumple; aquí lo revisan paridad.py y verificar.py.
La release de NGC de Triton (fija la versión de TensorRT)<code>mundo/servidor/requirements.txt</code> (fija onnxruntime)Con TensorRT, un engine de otra versión no carga; con ONNX Runtime, probablemente sí, y por eso la guardia del build tiene que revisarlo a propósito.
<code>perf_analyzer</code> contra Triton en la T4, 250 y 500 peticiones/s, holgura 10 %<code>latencia.py</code>: carga abierta dentro del proceso, 600 y 1,200 peticiones/s, holgura 15 %La misma regla contra el champion, sin red ni servidor de por medio. Las tasas quedan en el mismo uso de la máquina (≈ 25 y 50 %); la holgura es más grande porque tu Mac mide con más ruido que un runner dedicado.
≈ 10,000 fotos del golden set para la paridadlas 1,000 de <code>golden-v1</code>El mismo umbral (99.5 %) deja 5 cambios en lugar de 50: el examen separa con menos margen (lo calcula el precálculo «examen»).
El historial de PR de <code>ml-catalogo</code>; los parámetros de Argo<code>mundo/revisiones.json</code>; <code>corrida.yaml</code>La receta revisada se comprueba por su huella; las versiones llegan ya resueltas a números.
MLflow con Postgres y S3; Amazon S3MLflow con SQLite; RustFS en localhost:9600La misma API y la misma interfaz.
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 9600 (buckets ml-datos y ml-ckpt, los dos con versionado) y MLflow en el 5600, con su interfaz.

mundo/crear.py. Crea todo en ≈ 2 minutos: baja Fashion-MNIST, congela golden-v1 (el mismo examen de la estación 4), publica el set de calibración cal-2026-09, entrena classifier v1 a v4 con la receta de la estación 3, guarda sus checkpoints y construye el engine del champion.

engine.yaml y mundo/revisiones.json. La receta (opset, exportador, precisión, optimización, calibración) y los umbrales de paridad y latencia, y el registro de sus versiones revisadas: el sustituto del historial de PR.

mundo/servidor/. Lo que el servidor de modelos espera: classifier.yaml (el contrato, como el config.pbtxt de Triton) y requirements.txt (su versión de onnxruntime, como la release de Triton).

corrida.yaml. Los parámetros de esta noche, ya resueltos: challenger = 4 y champion = 3.

mundo/modelos.py y mundo/s3.py. Mirar y reparar el registro (versiones, el engine de cada una, alias, pesos desde su checkpoint, reconstruir un engine) y el S3 (el examen, la calibración, versiones).

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

Lo que escribes lo escribes tú

  1. pipeline/exportar.pyEl checkpoint de v4, por número y con su huella, a ONNX con opset fijo y batch dinámico, y los tres chequeos: checker, opset leído del archivo y FP32 contra FP32 en batch 1 y 32.
  2. pipeline/construir.pyLa guardia del build (el runtime del servidor), los pesos a FP16 (o int8 calibrado) y el grafo optimizado para esta máquina: engine.onnx con sus huellas.
  3. pipeline/paridad.pyEl contrato con el servidor y los tres números contra PyTorch FP32 sobre las 1,000 fotos del examen. Si no pasa, en rojo.
  4. pipeline/latencia.pyCarga abierta a dos tasas, champion y challenger alternados, la mediana de los p99 y la regla de la holgura. Sin el engine del champion, en rojo.
  5. pipeline/registrar.pySolo con todo en verde y del mismo engine: los archivos y las huellas en la versión v4, engine=listo. Ningún alias se mueve.
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 5: Export, engine y paridad

Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Export, engine y paridad» del caso C01: convertir el modelo que aprobó el gate en el archivo que se va a servir, demostrar que responde lo mismo (paridad) y que no es más lento que el de producción (latencia), y dejarlo en el registro con sus huellas. 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 examen congelado, el set de calibración, el registro v1–v4, los checkpoints y el engine del champion), `arquitectura.py` (la red), `gateway/` (el preprocess), `servidor/` (el contrato `classifier.yaml` y el runtime `requirements.txt` del servidor), `modelos.py` (mirar y reparar el registro), `s3.py` (mirar el S3), `revisiones.json` (las versiones aprobadas de `engine.yaml`), `equipo.py`, `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `modelos.py` y `s3.py` sí se usan. |
| `pipeline/exportar.py`, `construir.py`, `paridad.py`, `latencia.py`, `registrar.py` | Lo que escribe la persona. Cada archivo trae su contrato arriba. | **Sí.** |
| `pipeline/_comun.py` | Lo que comparten los pasos: `corrida()`, `receta()`, `revisiones()`, `contrato()`, `runtime_servidor()`, `carpeta()`, `s3()`, `mlflow_cliente()`, `bajar()`, `manifest()`, `tensores()`, `sesion()`, `git()`, `sha256()`, `huella_pesos()` y las constantes. | No. |
| `engine.yaml` | La receta del export y del engine y los umbrales de paridad y latencia (del equipo, revisados en un PR). | Solo con una revisión aprobada. Nunca para que un engine pase. |
| `corrida.yaml` | Los parámetros de esta noche, ya resueltos por el orquestador: challenger y champion, por número. | No a mano. |
| `entrada/categorias.json` | Las 10 categorías; su orden es el `label_id`. | No. |
| `artefactos/` | Lo que fabrican y miden los pasos: `v4/` (model.onnx, engine.onnx, export, engine, paridad y latencia) y `v4-int8/` (la prueba int8). Git la ignora. | No a mano. |
| `data/` | Caché local: Fashion-MNIST. Git la ignora. | No. |
| `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/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: ONNX Runtime en la CPU de la Mac en lugar de TensorRT en una T4 (aquí el engine guarda los pesos en FP16 pero hace las cuentas en FP32), `engine.onnx` en lugar de `model.plan`, el contrato `mundo/servidor/classifier.yaml` en lugar del `config.pbtxt` de Triton, la latencia medida dentro del proceso en lugar de `perf_analyzer` contra Triton, una holgura de 15 % en lugar de 10 %, 1,000 fotos de examen en lugar de ≈ 10,000, `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 (`pipeline/registrar.py`, `mundo/modelos.py alias|pesos|reconstruir-engine`, `pip install`, `docker compose …`, `romper.py`, `mundo/*.py`, `git commit`, `git revert`), dilo. Lo que solo lee o escribe en `artefactos/` (`verificar.py`, `pipeline/exportar.py`, `construir.py`, `paridad.py`, `latencia.py`, `mundo/modelos.py versiones|engine`, `mundo/s3.py`, `git status`, `git log`, `git diff`) se puede correr directo.
- `exportar.py` tarda ≈ 5 s, `construir.py` ≈ 2 s, `paridad.py` ≈ 5 s y `latencia.py` ≈ 1 min (no corras nada pesado mientras mide). `mundo/crear.py`, ≈ 3 min.
- Los umbrales no se mueven para que un engine pase. Si la persona propone aflojar la paridad porque int8 es más rápido, explícale por qué no, y cómo se haría bien (un PR propio, con su calibración y su paridad).
- La interfaz de MLflow está en http://localhost:5600. Úsala para enseñar: las versiones, sus alias, sus tags y los archivos de `engine/`.
- 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 4 (paridad)
- **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-export",
  "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": "paridad", "hice": "…", "medi": "…", "sigue": "…" }
  ],
  "verificaciones": [
    { "fecha": "2026-11-18T10:41:02-06:00", "pasan": ["mundo", "receta"], "fallan": [] }
  ]
}
```

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

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

La teoría, en Sensei

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.

Lección de la estación 5Export, engine y paridadLeer en Sensei ↗ Si te falta base, lee antes