APIs: REST, JSON, gRPC y streaming

El backend del marketplace, el programa que atiende la app de Ana, lo escribió un equipo. El gateway de C01, el programa que recibe la foto y se la pasa al modelo, lo escribió otro. Quizás en lenguajes distintos, en meses distintos. Para que el primero le pida algo al segundo, los dos tienen que estar de acuerdo en cinco cosas:

1. 1

   Dónde

   A qué máquina y a qué dirección se manda la request.

2. 2

   Qué se puede pedir

   Las operaciones que existen: clasificar una foto, consultar un trabajo, borrar un archivo.

3. 3

   Cómo se escribe

   El formato de los datos que van: una foto en bytes, un texto, un número.

4. 4

   Qué regresa

   La forma exacta de la respuesta: qué campos trae y de qué tipo es cada uno.

5. 5

   Qué pasa si sale mal

   Qué error regresa si la foto no sirve, si el servidor está saturado o si se acabó el tiempo.

Ese acuerdo escrito es el contrato de la API. La api es la ventanilla; el contrato es el reglamento pegado en el vidrio. La Ronda lo subraya en M02: el contrato no es solo la entrada y la salida, también dice qué pasa cuando no llegas a tiempo.

El endpoint: una puerta de la API

Cada operación de una API tiene su puerta, el endpoint: un método HTTP más una ruta. El de C01 es POST /v1/classify. La misma ruta con otro método es otro endpoint, con otro contrato: GET /v1/jobs/8f3a consulta un trabajo y DELETE /v1/jobs/8f3a lo cancela.

Detrás del signo ? van los parámetros de la consulta (query parameters), que afinan la petición sin cambiar de puerta: en POST /v1/classify?top_k=5, el top_k=5 pide las cinco categorías más probables.

Fíjate en un detalle de la figura: la request de C01 no lleva JSON. El cuerpo son los bytes del JPEG, tal cual, y el encabezado Content-Type: image/jpeg dice qué son. El JSON aparece solo en la respuesta. En la sección 3 verás por qué.

REST: cosas con nombre y verbos

Hay muchas maneras de organizar los endpoints. La más común en la web se llama REST (Representational State Transfer), y la describió Roy Fielding en su tesis doctoral del año 2000. Sus ideas, en palabras simples:

• Las cosas tienen nombre. Cada cosa que la API maneja (un trabajo, un modelo, un usuario) es un recurso con su propia URL: /v1/jobs/8f3a es el trabajo 8f3a.
• Los métodos son los verbos. GET lee, POST crea o manda algo para procesar, PUT reemplaza, DELETE borra. No se inventan rutas como /v1/borrarTrabajo.
• Sin estado (stateless). Cada request trae todo lo que el servidor necesita para responderla. El servidor no recuerda la request anterior de ese cliente.
• Los códigos de estado dicen lo que dicen: 200 salió bien, 404 no existe, 503 estoy saturado.

¿Por qué importa «sin estado»? Porque si ninguna copia del servidor recuerda nada, cualquier copia puede contestar cualquier request. C01 corre varias copias del gateway detrás de un balanceador de carga (el programa que reparte las requests entre las copias; lo verás en «Balanceadores, proxies y gateways»), y puede agregar o quitar copias sin que ningún cliente lo note.

Dentro de un programa de Python, un diccionario vive en la memoria en una forma que solo ese programa entiende. Para mandarlo por la red hay que convertirlo en una fila de bytes, y el otro lado tiene que reconstruirlo. Convertir datos en bytes para guardarlos o mandarlos se llama serializar (serialize); reconstruirlos del otro lado, deserializar.

JSON: seis tipos y nada más

El formato más usado para serializar en las APIs es JSON (JavaScript Object Notation). Lo popularizó Douglas Crockford a principios de los 2000, hoy lo define un estándar del IETF, el grupo que escribe las reglas técnicas de internet (el RFC 8259, de 2017) y lo leen todos los lenguajes. Es texto: lo puedes abrir y leer. Solo tiene seis tipos de valor:

Igual de importante es lo que no tiene:

• Bytes. No hay manera de meter un JPEG tal cual. Hay que convertirlo en texto (sección 3).
• Fechas. Se escriben como texto, por convención en el formato ISO 8601: "2026-11-05T14:03:00Z". Cada lado tiene que saber que ese texto es una fecha.
• NaN e infinito. El estándar no los permite. Un modelo que devuelve un NaN (lo viste en «Cómo guarda números una computadora») no se puede escribir en JSON válido.
• Enteros grandes, en la práctica. El estándar no pone límite a los números, pero casi todos los lectores de JSON, empezando por el de JavaScript, guardan cada número como FP64, con 53 bits de dígitos: arriba de 2⁵³ = 9,007,199,254,740,992, los enteros ya no son exactos. El propio RFC avisa que solo los enteros por debajo de 2⁵³ viajan seguros entre lenguajes.

import json, datetime

pedido = {"top_k": 5, "fuente": "app", "fotos": ["tenis.jpg"], "urgente": False, "nota": None}
texto = json.dumps(pedido)                     # serializar: del objeto de Python al texto
print(texto, "·", len(texto), "bytes")
print("¿vuelve igual?", json.loads(texto) == pedido)   # deserializar: del texto al objeto

print(json.dumps({"shape": (3, 224, 224)}))    # la tupla regresa como lista
for raro in (b"\xff\xd8\xff", datetime.date(2026, 11, 5)):
    try:
        json.dumps(raro)
    except TypeError as error:
        print("no se puede:", error)

print(json.dumps([0.83, float("nan")]))        # Python lo escribe, pero eso ya no es JSON
try:
    json.dumps(float("nan"), allow_nan=False)
except ValueError as error:
    print("con allow_nan=False:", error)
print(9007199254740993, "como float de 64 bits:", float(9007199254740993))

{"top_k": 5, "fuente": "app", "fotos": ["tenis.jpg"], "urgente": false, "nota": null} · 85 bytes
¿vuelve igual? True
{"shape": [3, 224, 224]}
no se puede: Object of type bytes is not JSON serializable
no se puede: Object of type date is not JSON serializable
[0.83, NaN]
con allow_nan=False: Out of range float values are not JSON compliant: nan
9007199254740993 como float de 64 bits: 9007199254740992.0

La trampa está en la sexta línea de la salida: Python escribe NaN sin quejarse, y el cliente de otro lenguaje truena al leerlo. Con allow_nan=False, el error sale de tu lado, donde lo puedes atender.

Cuánto pesa un número escrito con letras

En binario, un float32 ocupa 4 bytes, siempre. En JSON se escribe con sus cifras: -1.7754088640213013 son 19 letras, más la coma y el espacio. El programa de abajo arma el tensor de la foto de Ana con píxeles al azar, normalizados como en C01, y lo mide de las dos maneras:

import json, random, struct, time

random.seed(0)
n = 3 * 224 * 224                                  # el tensor de la foto de Ana
medias, desv = (0.485, 0.456, 0.406), (0.229, 0.224, 0.225)
valores = []
for c in range(3):                                 # píxeles al azar, normalizados como en C01
    for _ in range(224 * 224):
        v = (random.randint(0, 255) / 255 - medias[c]) / desv[c]
        valores.append(struct.unpack("<f", struct.pack("<f", v))[0])   # redondeado a float32

binario = struct.pack(f"<{n}f", *valores)          # 4 bytes por número, tal cual
texto = json.dumps(valores)                        # cada número escrito con sus cifras
corto = json.dumps([round(v, 4) for v in valores])
print(f"binario:              {len(binario):>9,} B")
print(f"JSON:                 {len(texto):>9,} B · {len(texto) / n:.1f} B por número · {len(texto) / len(binario):.1f} veces")
print(f"JSON con 4 decimales: {len(corto):>9,} B")
print("así empieza el JSON:", texto[:58])

t0 = time.perf_counter(); json.dumps(valores); t_json = time.perf_counter() - t0
t0 = time.perf_counter(); struct.pack(f"<{n}f", *valores); t_bin = time.perf_counter() - t0
print("¿json.dumps tardó más de 10 veces lo que struct.pack?", t_json > 10 * t_bin)

binario:                602,112 B
JSON:                 3,069,263 B · 20.4 B por número · 5.1 veces
JSON con 4 decimales: 1,256,173 B
así empieza el JSON: [1.255672574043274, 1.563918113708496, -1.7754088640213013
¿json.dumps tardó más de 10 veces lo que struct.pack? True

En la lección de unidades viste que cada una de las dos máquinas del gateway de C01 sostiene ≈ 1.56 Gb/s de red: los ≈ 2.4 Gb/s del binario ya ocupan buena parte de las dos, y los ≈ 12.3 del JSON no caben ni de lejos.

El peso no es lo único. Escribir y leer el texto cuesta CPU. La Ronda (M07) midió en una laptop (una Apple M4) ≈ 50 ms para serializar ese tensor con json.dumps y ≈ 23 ms más para leerlo de vuelta. A 500 requests por segundo, son 500 × 0.05 s = 25 segundos de CPU por cada segundo: solo serializar ocuparía ≈ 25 núcleos todo el tiempo. Los tiempos cambian según la máquina; la proporción contra el binario, de decenas de veces, se mantiene.

En la lección de HTTP viste las tres formas de mandar la foto en el body y que base64 la hace crecer un tercio. Aquí ves de dónde sale ese tercio y cuándo conviene cada forma.

Un JPEG son bytes, y muchos no son letras. Todo JPEG empieza con los bytes FF D8 FF (escritos en hexadecimal, con 0–9 y A–F, como en «Cómo guarda números una computadora»: FF es 255 y D8 es 216), que no corresponden a ningún carácter que se pueda escribir entre comillas. ¿Cómo se mete una foto en un JSON?

base64: tres bytes en cuatro letras

base64 escribe cualquier serie de bytes con solo 64 letras seguras: de la A a la Z, de la a a la z, del 0 al 9, + y /. Con 64 letras, cada una lleva 6 bits (2⁶ = 64). El truco es agrupar:

1. 1

   Toma 3 bytes

   Son 3 × 8 = 24 bits.

2. 2

   Córtalos en 4 pedazos de 6 bits

   Cada pedazo es un número del 0 al 63.

3. 3

   Cambia cada número por su letra

   0 es A, 25 es Z, 26 es a, 51 es z, 52 es 0, 61 es 9, 62 es + y 63 es /.

Si los bytes no son múltiplo de 3, el final se rellena con =. Siempre salen 4 letras por cada 3 bytes, o sea, 33 % más:

import base64

inicio_jpeg = b"\xff\xd8\xff"                      # así empieza todo archivo JPEG
letras = base64.b64encode(inicio_jpeg)
print(inicio_jpeg.hex(" "), "→", letras.decode())  # 3 bytes → 4 letras
print("¿regresa igual?", base64.b64decode(letras) == inicio_jpeg)

for k in (1, 2, 3, 4, 300, 200_000, 602_112):
    n = len(base64.b64encode(bytes(k)))
    print(f"{k:>7,} bytes → {n:>7,} letras · {n / k - 1:+.0%}")
print(base64.b64encode(b"T"), base64.b64encode(b"Te"), base64.b64encode(b"Ten"))

ff d8 ff → /9j/
¿regresa igual? True
      1 bytes →       4 letras · +300%
      2 bytes →       4 letras · +100%
      3 bytes →       4 letras · +33%
      4 bytes →       8 letras · +100%
    300 bytes →     400 letras · +33%
200,000 bytes → 266,668 letras · +33%
602,112 bytes → 802,816 letras · +33%
b'VA==' b'VGU=' b'VGVu'

Las otras dos salidas

Para bytes grandes o frecuentes, hay dos caminos mejores que base64:

• Mandar los bytes crudos en el cuerpo. Si la request solo lleva una foto, no hace falta JSON: el body son los bytes y el header Content-Type: image/jpeg dice qué son. Es lo que hace C01. Los parámetros chicos, como top_k, van en la URL.
• Mandar una referencia. Se sube el archivo antes a un almacén de archivos en la nube (object storage, como S3 de AWS, la nube de Amazon) y la request lleva solo su dirección: una URL o una key, como uploads/8f3a.pdf. Para subirlo sin darle al cliente las llaves del almacén, se usa una URL prefirmada (presigned URL): una dirección que permite subir un solo archivo, a una key fija, durante un rato corto que elige el servidor (por ejemplo, 15 minutos). Es el patrón de M02 para los trabajos largos de la sección 8.

La referencia cuesta un viaje más (el servidor tiene que ir por el archivo), así que conviene cuando ese viaje extra cabe en el tiempo que tienes para responder, contando la cola lenta (el p99). La regla práctica: base64 para lo chico y ocasional (un ícono, una firma de 2 KB); bytes crudos o una URL para lo grande.

Un contrato que solo vive en la cabeza de alguien se rompe. Por eso se escribe: el esquema (schema) de la API dice qué campos lleva cada request y cada respuesta, de qué tipo es cada uno, cuáles son obligatorios y qué valores se permiten. El de C01, en palabras:

• Entrada: el cuerpo es un JPEG, PNG o WebP de hasta 10 MB. top_k es un entero entre 1 y 20; si no viene, vale 5.
• Salida: model_version es texto; predictions es una lista de objetos, cada uno con label (texto) y score (un número entre 0 y 1); latency_ms es un número.

Validar en la puerta

Con el esquema escrito, el servidor revisa cada request antes de gastar CPU o GPU en ella. Si top_k vale 0, la rechaza al instante con un error 422 (Unprocessable Content): «entendí lo que mandaste, pero no cumple el contrato». Es distinto de un 400, que en C01 significa «la imagen ni siquiera se puede leer», de un 413 («es demasiado grande») y de un 415 («ese tipo de archivo no lo acepto»).

En Python, el esquema se escribe casi siempre con Pydantic, una librería en la que describes cada mensaje como una clase de Python (una plantilla con el nombre y el tipo de cada campo, como label: str, «label es texto») y que revisa que los datos la cumplan. Lo usa FastAPI, el framework (la librería que arma el servidor web) del gateway de C01. Es una ilustración, sin salida, porque necesita las dos librerías:

from fastapi import FastAPI, Query, Request
from pydantic import BaseModel, Field

class Prediccion(BaseModel):
    label: str                               # el nombre de la categoría, nunca su posición
    score: float = Field(ge=0, le=1)

class Respuesta(BaseModel):
    model_version: str
    predictions: list[Prediccion]
    latency_ms: float

app = FastAPI()

@app.post("/v1/classify", response_model=Respuesta)
async def classify(request: Request, top_k: int = Query(5, ge=1, le=20)):
    ...                                      # top_k=0 ni siquiera llega aquí: FastAPI responde 422

ge y le quieren decir «mayor o igual» y «menor o igual» (greater/less than or equal): score va de 0 a 1 y top_k, de 1 a 20, con 5 si no viene. FastAPI lee esos tipos y hace tres cosas solo: valida cada request (422 con el detalle de qué campo falló), revisa que tu respuesta cumpla Respuesta y publica el esquema completo en el formato OpenAPI, un estándar para describir APIs HTTP, en /openapi.json, con una página para probarla en /docs. Con ese archivo, otros equipos pueden generar el código de su cliente sin leer el tuyo.

Por dentro, OpenAPI describe los datos con JSON Schema, un lenguaje estándar para escribir esquemas en JSON. Lo vas a volver a ver en M14: un LLM puede recibir un JSON Schema para que su salida salga con esa forma. La Ronda avisa que eso garantiza la forma, no el contenido: una marca inventada es JSON perfecto.

{"detail": [{"type": "greater_than_equal",
             "loc": ["query", "top_k"],
             "msg": "Input should be greater than or equal to 1",
             "input": "0",
             "ctx": {"ge": 1}}]}

Versionar sin romper a nadie

En cuanto otro equipo usa tu API, el contrato es una promesa. Cambiarlo sin avisar rompe programas que no son tuyos. El versionado separa los cambios en dos clases (M11):

El /v1/ de la ruta es para eso. Un cambio que rompe se publica como /v2/classify, que convive con /v1 mientras los clientes se cambian; al final se apaga el viejo. La Ronda llama a la receta expand and contract: primero todos aprenden a aceptar lo nuevo, después se empieza a producir lo nuevo y al final se deja de soportar lo viejo.

C01 tiene una regla que conviene memorizar: se versiona el contrato, no el modelo. El modelo cambia cada mes y no estrena /v2 por eso. A cambio, cada respuesta lleva su model_version. Sin ella, dice la Ronda, no puedes depurar ni unir la predicción con sus etiquetas.

Del gateway hacia Triton, el servidor del modelo, cambia todo. Ahí no hay personas leyendo ni otros equipos integrándose: hay un solo cliente, el gateway, que manda el tensor de 602 KB hasta 500 veces por segundo. Lo que importa es que pese poco, que se lea rápido y que nadie se equivoque de tipos.

gRPC y protobuf: el contrato compilado

gRPC es una forma de llamar funciones de otro programa por la red como si estuvieran en el tuyo (remote procedure call, RPC). Google lo publicó como código abierto en 2015. Su contrato se escribe en un archivo .proto, con el lenguaje de protobuf (Protocol Buffers):

syntax = "proto3";

message ClassifyRequest {
  bytes image = 1;              // los bytes del JPEG, sin base64
  int32 top_k = 2;
}
message Prediccion {
  string label = 1;
  float score = 2;
}
message ClassifyResponse {
  string model_version = 1;
  repeated Prediccion predictions = 2;   // repeated: una lista
  float latency_ms = 3;
}
service Clasificador {
  rpc Classify (ClassifyRequest) returns (ClassifyResponse);
}

Un compilador, protoc, lee ese archivo y genera el código del cliente y del servidor en Python, Go, Java o el lenguaje que quieras. El cliente llama stub.Classify(request) como una función cualquiera (el stub es el objeto que generó protoc y que hace la llamada por la red); nunca escribe ni lee JSON. Si mandas un texto donde va un número, el código generado se queja antes de mandar nada.

Lo que viaja es binario: cada float ocupa sus 4 bytes, y en vez del nombre de cada campo va su número. Una predicción con "Tenis" y 0.83 ocupa 12 bytes en protobuf y 33 en JSON; el tensor de C01, 602,116 bytes contra ≈ 3.07 MB. Los detalles están en la sección extra «Protobuf por dentro».

gRPC viaja sobre HTTP/2: abre una sola conexión larga y la usa para muchas llamadas a la vez (hasta el tope que ponga el servidor; las que pasan de ahí esperan su turno), y permite streams en los dos sentidos (mandar la respuesta, o la petición, por pedazos: lo verás en la sección 7). Lo que cuesta:

• No se lee a simple vista. curl no sirve; se usa grpcurl o un cliente generado.
• Los navegadores no lo hablan directo. Hace falta gRPC-Web o un proxy.
• El balanceo. Como todo viaja por una sola conexión larga, un balanceador que reparte conexiones (y no requests) deja a cada gateway pegado a un solo Triton. Lo verás en la lección de balanceadores.

Un contrato común para servidores de modelos

Cada servidor de modelos podría inventar su propia API. Para no atarte a uno, existe un protocolo estándar de inferencia: el KServe v2 (KServe es un proyecto para servir modelos en Kubernetes), también llamado Open Inference Protocol. Define los mismos endpoints para Triton, los servidores de KServe, MLServer de Seldon y OpenVINO Model Server, entre otros. Si tu gateway habla v2, cambiar de servidor no cambia el cliente.

El cuerpo de infer, en su forma JSON, describe cada tensor con nombre, shape, dtype y datos: {"inputs": [{"name": "input", "shape": [1, 3, 224, 224], "datatype": "FP32", "data": [1.2557, …]}]}. Los mismos endpoints existen por HTTP y por gRPC: Triton, por omisión, escucha HTTP en el puerto 8000 y gRPC en el 8001.

¿Y los 150,528 números como texto? Triton agrega una extensión binaria que no es parte del protocolo base: un JSON corto con el nombre, el shape y el tipo, y detrás los 602,112 bytes crudos. Un header, Inference-Header-Content-Length, dice dónde termina el JSON y empiezan los bytes.

{"name": "classifier", "versions": ["1"], "platform": "tensorrt_plan",
 "inputs":  [{"name": "input",  "datatype": "FP32", "shape": [-1, 3, 224, 224]}],
 "outputs": [{"name": "logits", "datatype": "FP32", "shape": [-1, 500]}]}

Lo que eligió C01

C01 manda el tensor a Triton por HTTP, con la extensión binaria, usando el cliente asíncrono de Triton (tritonclient.http.aio). El tensor viaja en bruto, igual de chico que con gRPC; la parte JSON se puede revisar con curl, y el balanceo es más sencillo. gRPC queda como alternativa si una medición muestra que su menor costo por request importa. La Ronda marca como respuesta débil «gRPC siempre es más rápido que REST»: con la extensión binaria, la diferencia suele ser chica frente a los 150 ms que el gateway le da a Triton.

Ya tienes la respuesta a la pregunta de la lección. Hacia afuera, JSON: muchos clientes distintos, de otros equipos, que necesitan leer y depurar, y una respuesta de unos cientos de bytes. Hacia adentro, binario: un solo cliente, un tensor de 602 KB, 500 veces por segundo.

Hasta aquí, cada request esperaba una respuesta completa. Para C01 está bien: en ≈ 50 ms llegan las cinco categorías. Para un LLM no. En la lección de LLMs viste la request típica de C10: tarda 0.6 s en dar el primer token (TTFT) y después 40 ms por token (TPOT).

Mandar la respuesta en pedazos, conforme se produce, se llama streaming.

SSE: una respuesta que no se acaba

La forma más común de mandar tokens es SSE (Server-Sent Events, eventos que manda el servidor). Es HTTP normal: el cliente hace una request y el servidor contesta con Content-Type: text/event-stream, pero en vez de mandar todo y cerrar, va escribiendo eventos conforme los tiene. Cada evento lleva una o más líneas que empiezan con data: (puede llevar otras, como id:), y una línea en blanco lo cierra.

La API de OpenAI usa SSE en su endpoint de chat (Chat Completions), y casi todos los servidores de LLMs (los motores que corren el modelo) la copian: vLLM (el que usa C10), SGLang, TensorRT-LLM y el frontend de OpenAI de Triton exponen una API compatible con OpenAI. Es el otro protocolo estándar de inferencia de esta lección. Con "stream": true en el JSON de la request a POST /v1/chat/completions, la respuesta se ve así:

Content-Type: text/event-stream

data: {"choices": [{"delta": {"content": "Te"}}], ...}

data: {"choices": [{"delta": {"content": "nis"}}], ...}

data: [DONE]

Cada delta trae el pedazo nuevo, y [DONE] cierra el stream. Como el contrato es el mismo, puedes cambiar de motor sin tocar a los clientes, y las librerías oficiales de OpenAI funcionan apuntándolas a tu URL. La Ronda pone una advertencia: compatible no es idéntico, porque cada motor acepta o ignora parámetros distintos. Prueba tu cliente contra el motor que vas a usar.

Leer SSE tiene una trampa. La red entrega los bytes en pedazos que no respetan los eventos: un pedazo puede traer evento y medio. El cliente junta lo que llega y solo procesa cuando ve la línea en blanco:

import json

def eventos_sse(pedazos):
    """Junta lo que llega de la red y entrega cada evento completo."""
    pendiente = ""
    for pedazo in pedazos:
        pendiente += pedazo
        while "\n\n" in pendiente:                 # una línea en blanco cierra el evento
            evento, pendiente = pendiente.split("\n\n", 1)
            datos = [l.removeprefix("data:").removeprefix(" ")
                     for l in evento.split("\n") if l.startswith("data:")]
            yield "\n".join(datos)

# Los cortes caen donde le toca a la red, no donde termina un evento
llegada = ['data: {"choices": [{"delta": {"content": "Te"}}]}\n\nda',
           'ta: {"choices": [{"delta": {"content": "nis"}}]}\n',
           '\ndata: {"choices": [{"delta": {"content": " rojos"}}]}\n\ndata: [DONE]\n\n']
pantalla = ""
for datos in eventos_sse(llegada):
    if datos == "[DONE]":
        print("[DONE]: se acabó el stream")
        break
    nuevo = json.loads(datos)["choices"][0]["delta"]["content"]
    pantalla += nuevo
    print(f"llegó {nuevo!r:<9} → la pantalla dice {pantalla!r}")

llegó 'Te'      → la pantalla dice 'Te'
llegó 'nis'     → la pantalla dice 'Tenis'
llegó ' rojos'  → la pantalla dice 'Tenis rojos'
[DONE]: se acabó el stream

yield entrega un evento a quien recorre la función con el for y, cuando le piden el siguiente, la función sigue justo donde se quedó. El primer pedazo trae un evento completo y el principio de otro, da. El lector guarda ese principio y lo completa con el siguiente pedazo. Si procesara cada pedazo por separado, intentaría leer da como JSON y tronaría.

WebSocket: hablar en los dos sentidos

SSE va en un solo sentido: del servidor al cliente. En una transcripción de voz en vivo, el cliente también manda datos sin parar: fragmentos de audio mientras la persona habla, y el servidor regresa texto parcial mientras escucha. Para eso está WebSocket. Empieza como una request HTTP que pide cambiar de protocolo (el header Upgrade: websocket); el servidor acepta con el código 101 (Switching Protocols, «cambio de protocolo») y, desde ahí, la conexión es un canal de mensajes en los dos sentidos, abierto todo el tiempo que haga falta.

Leer un PDF de 200 páginas con OCR tarda minutos. Ninguna request espera tanto: quien llama, los proxies y los balanceadores tienen timeouts (tiempos máximos de espera) de segundos. La salida es separar aceptar el trabajo de hacerlo (M02):

1. 1

   Aceptar, en milisegundos

   El cliente sube el PDF al almacén con una URL prefirmada y hace POST /v1/jobs con la referencia. La API valida, anota el trabajo como queued («en fila»), lo mete en una cola (una fila de mensajes donde los trabajos esperan su turno; la verás en la lección de colas) y responde 202 Accepted («lo recibí, todavía no está») con un job_id y la dirección donde consultar su estado.

2. 2

   Hacer, en segundo plano

   Un worker (trabajador) toma el trabajo de la cola, corre el modelo y guarda el resultado en el almacén.

3. 3

   Avisar

   El cliente se entera de que terminó, de una de dos maneras.

Polling: preguntar cada tanto

Con polling, el cliente pregunta: GET /v1/jobs/8f3a cada cierto tiempo, hasta que el estado diga succeeded o failed. Es simple y sirve para cualquier cliente, incluso un script en una laptop sin dirección pública (una laptop en casa tiene una IP privada: nadie de afuera le puede escribir). El servidor puede sugerir cada cuánto preguntar con el header Retry-After.

El cliente se entera tarde: el trabajo termina en algún momento entre dos preguntas, en promedio a la mitad, así que preguntando cada 2 s se entera ≈ 1 s después.

Y el problema mayor es la cuenta. Con la ley de Little de la lección de async (cuántos hay a la vez = cuántos llegan por segundo × cuánto dura cada uno) sale cuántos trabajos están vivos, y cada uno pregunta:

Webhook: que te avisen

Con un webhook, el cliente registra una URL suya y tu servicio le hace un POST cuando el trabajo termina: 50 avisos por segundo, uno por trabajo. Es lo justo, pero trae sus cuidados:

• El cliente necesita una dirección pública que tu servicio pueda alcanzar.
• Su endpoint puede estar caído. Hay que reintentar, esperando cada vez más: el backoff de la lección de fallas de red.
• Puede llegar dos veces. Si el aviso llegó pero la confirmación se perdió, se vuelve a mandar: la entrega es «al menos una vez» (at least once). El receptor descarta los repetidos por job_id.
• Hay que firmarlo. Cualquiera podría mandarle un POST falso al cliente. Se firma con HMAC: una huella del mensaje calculada con un secreto que solo comparten las dos partes. El receptor recalcula la huella; si no coincide, lo tira.

Lo común es combinar: webhook para quien lo puede recibir y polling como respaldo, con un intervalo sugerido. Si una persona espera en la app, el aviso puede llegar por SSE, WebSocket o una notificación al celular.

1. Mandar tensores en JSON

Funciona en la laptop y revienta en producción: el tensor de C01 pesa 5 veces más y serializarlo quema decenas de núcleos.

Cómo evitarlo: JSON para lo que leen las personas y para depurar; binario (la extensión binaria de Triton o gRPC) para tensores. Y si puedes, mándalos en uint8: cuatro veces menos que en float32.

2. Dejar que se cuele un NaN

El modelo devuelve un NaN, Python lo escribe como NaN y el cliente, en otro lenguaje, no puede leer la respuesta. El error aparece lejos de donde nació.

Cómo evitarlo: allow_nan=False al serializar, un esquema de respuesta que valide los números y una regla explícita: si sale NaN, el gateway responde un error (C01 responde 500), no un JSON roto.

3. Meter fotos grandes en base64

Cada foto cuesta un tercio más de bytes, más el tiempo de convertir de ida y de vuelta, y el lector de JSON tiene que recorrer un texto de megabytes.

Cómo evitarlo: bytes crudos en el cuerpo si la request es solo la foto; una URL o una key de object storage si es grande o va a una cola.

4. Cambiar el contrato sin cambiar la versión

Renombrar score a confidence, cambiar el valor por omisión de top_k o calibrar el score sin avisar. Tu prueba pasa; el programa de otro equipo deja de funcionar.

Cómo evitarlo: revisar cada cambio contra la tabla de lo que rompe; si rompe, /v2 conviviendo con /v1. Y devolver nombres de categoría, nunca su posición en el vector.

5. Creer que gRPC siempre es más rápido

Cambiar a gRPC «por velocidad» sin medir, y descubrir que el Triton nuevo no recibe tráfico porque el balanceo reparte conexiones, no requests.

Cómo evitarlo: medir con tu tensor y tu tráfico; si ya mandas binario por HTTP, la diferencia suele ser chica. Si eliges gRPC, resuelve el balanceo por request.

6. Un proxy que guarda el stream, o un polling sin freno

El stream de tokens llega todo junto al final porque un proxy lo juntó. O mil clientes preguntan cada segundo por trabajos que tardan minutos.

Cómo evitarlo: probar el streaming de punta a punta, midiendo el TTFT del lado del cliente. Para el polling, Retry-After, un intervalo que crece y webhook para quien pueda recibirlo.

Resuélvelos con lápiz antes de abrir la solución. Los de tamaños y de polling se comprueban con las calculadoras.

1. 1Fácil

   Diseña los endpoints REST de una API de trabajos de OCR para estas tres acciones: crear un trabajo, consultar cómo va el trabajo 51c2 y cancelarlo. ¿Qué código de estado responde cada una si sale bien?

   Ver la solución paso a paso

   • Crear: POST /v1/jobs, con la referencia del documento en el cuerpo. Responde 202 Accepted con el job_id, porque el trabajo todavía no está hecho.
   • Consultar: GET /v1/jobs/51c2. Responde 200 con el estado (queued, running, succeeded o failed).
   • Cancelar: DELETE /v1/jobs/51c2. Responde 200 o 204 (sin cuerpo).
   • La ruta es la misma en las dos últimas; el método decide qué endpoint es.
2. 2Fácil

   Este texto pretende ser JSON: {'label': 'Tenis', "score": NaN, "creado": 2026-11-05}. Encuentra los tres errores y corrígelos.

   Ver la solución paso a paso

   • Las comillas simples: JSON solo acepta comillas dobles. "label": "Tenis".
   • NaN no existe en JSON. Si el score no se pudo calcular, null, o mejor, responder un error.
   • La fecha no es un tipo de JSON: va como texto, "2026-11-05".
3. 3Fácil

   Una app manda 3 fotos de 200 KB cada una, en base64, dentro de un JSON. ¿Cuánto pesa la request, sin contar el resto del JSON? ¿Cuánto pesaría con los bytes crudos?

   Ver la solución paso a paso

   • Cada foto: 4 × ⌈200,000 ÷ 3⌉ = 4 × 66,667 = 266,668 B.
   • Las tres: 3 × 266,668 = 800,004 B ≈ 800 KB.
   • Crudas: 3 × 200,000 = 600 KB. base64 agrega ≈ 200 KB, el 33 %.
4. 4Fácil

   ¿Cuáles de estos cambios a la respuesta de /v1/classify rompen a un cliente? (a) Agregar un campo request_id. (b) Renombrar score a confidence. (c) Cambiar el valor por omisión de top_k de 5 a 3. (d) Calibrar los scores sin avisar.

   Ver la solución paso a paso

   • (a) No rompe: un campo opcional nuevo; quien no lo conoce, lo ignora.
   • (b) Rompe: el cliente busca score y no lo encuentra.
   • (c) Rompe: quien no mandaba top_k y mostraba 5 sugerencias ahora recibe 3.
   • (d) Rompe, aunque el JSON se vea igual: cambió lo que significa el número, y cualquier umbral del cliente (como «muéstralo si pasa de 0.3») cambia de efecto.
5. 5Medio

   Un servicio de búsqueda manda embeddings de 768 floats, 1,000 veces por segundo. ¿Cuánto pesa cada uno en binario y en JSON (≈ 20.4 B por número)? ¿Cuánta red ocupa cada forma?

   Ver la solución paso a paso

   • Binario: 768 × 4 = 3,072 B.
   • JSON: 768 × 20.4 ≈ 15.7 KB, unas 5 veces más.
   • Red, binario: 3,072 × 1,000 × 8 ≈ 24.6 Mb/s.
   • Red, JSON: 15,667 × 1,000 × 8 ≈ 125 Mb/s. No es grave para una red de 10 Gb/s, pero el costo de CPU de serializar se repite en cada request.
6. 6Medio

   Del extra «Protobuf por dentro»: escribe 150 y 1,000 como varint.

   Ver la solución paso a paso

   • 150 = 128 + 16 + 4 + 2. Los 7 bits de abajo: 150 − 128 = 22 = 0x16; con el bit de «sigue» prendido, 22 + 128 = 150 = 0x96. Lo que sobra: 150 ÷ 128 = 1 → 0x01. Resultado: 96 01.
   • 1,000: 1,000 ÷ 128 = 7, y sobran 1,000 − 7 × 128 = 104 = 0x68. Primer byte: 104 + 128 = 232 = 0xE8. Segundo: 0x07. Resultado: E8 07.
   • Los dos ocupan 2 bytes; un int32 fijo ocuparía 4.
7. 7Medio

   Llegan 1,200 trabajos por minuto, cada uno dura en promedio 90 s y los clientes preguntan cada 3 s. ¿Cuántas consultas por segundo recibe la API de estado? ¿Y si el servidor responde Retry-After: 15?

   Ver la solución paso a paso

   • Llegan 1,200 ÷ 60 = 20 por segundo.
   • Vivos a la vez, por Little: 20 × 90 = 1,800.
   • Cada 3 s: 1,800 ÷ 3 = 600 GET/s, 30 veces la tasa de creación.
   • Cada 15 s: 1,800 ÷ 15 = 120 GET/s. A cambio, el cliente se entera en promedio 7.5 s después de que terminó, en vez de 1.5 s.
8. 8Medio

   Un LLM tiene un TTFT de 0.8 s y un TPOT de 50 ms. La respuesta tiene 400 tokens. ¿Cuánto tarda completa? ¿Cuándo ve la persona la primera palabra con streaming, y cuándo si un proxy junta la respuesta?

   Ver la solución paso a paso

   • Completa: 0.8 + 399 × 0.05 = 0.8 + 19.95 = 20.75 s.
   • Con streaming: el primer token a los 0.8 s, y después 1 ÷ 0.05 = 20 tokens por segundo.
   • Con un proxy que junta todo: la primera palabra llega a los 20.75 s. El servidor cumple su TTFT y la persona espera 26 veces más.
9. 9Reto

   Alguien propone que el gateway de C01 mande el tensor a Triton en base64 dentro del JSON de KServe v2, «para no depender de la extensión binaria». ¿Cuánta red cuesta a 500 requests por segundo, comparado con la extensión binaria, con los floats como texto y con uint8? ¿Qué le respondes?

   Ver la solución paso a paso

   • Extensión binaria: 602,112 × 500 × 8 ≈ 2.4 Gb/s.
   • base64: 802,816 × 500 × 8 ≈ 3.2 Gb/s: 33 % más, y además convertir 803 KB de ida y de vuelta en cada request.
   • Floats como texto: ≈ 3.07 MB × 500 × 8 ≈ 12.3 Gb/s, cinco veces más, y decenas de núcleos solo para serializar.
   • uint8 en binario: 150,528 × 500 × 8 ≈ 0.6 Gb/s.
   • Respuesta: si el miedo es depender de una extensión de Triton, la salida estándar es gRPC, que lleva bytes crudos dentro del protocolo base, no base64. Y la mejora grande no es el protocolo sino el dtype: uint8 baja la red 4 veces.
10. 10Reto

    Diseña el contrato de una API de OCR que recibe documentos de 1 a 200 páginas. Una página tarda ≈ 2 s y quien llama espera, como mucho, 10 s. ¿Qué documentos se responden en la misma request y cuáles con 202? ¿Cómo viaja el PDF? ¿Cómo se entera el cliente?

    Ver la solución paso a paso

    • Con 10 s de espera y ≈ 2 s por página, caben unas 5 páginas, sin margen. Con margen para la cola y el p99, se responden en la request los de 1 o 2 páginas (≈ 4 s), con 200 y el resultado.
    • El resto recibe 202 con job_id. La regla se decide antes de procesar, por número de páginas, nunca después de que venció el tiempo.
    • El PDF no viaja en base64: el cliente lo sube con una URL prefirmada y manda la key.
    • Aviso: webhook firmado con HMAC, con reintentos y descarte de repetidos por job_id, y polling con Retry-After como respaldo. El resultado queda en results/{job_id}.json.
    • El contrato lleva /v1/ y escribe los dos casos: 200 con el resultado, o 202 con la dirección del estado.

En la Ronda:

• M02 · Patrones de inferencia separa lo síncrono (200 con la respuesta) de lo asíncrono (202 con un job_id), hace la cuenta del polling contra el webhook y explica la firma HMAC y la URL prefirmada.
• M07 · Servidores de modelos compara JSON, la extensión binaria y gRPC con el tensor de C01, presenta KServe v2 y la API compatible con OpenAI, y pone en una tabla SSE, WebSocket y los streams de gRPC.
• M14 · Sistemas con LLMs sigue un token desde vLLM hasta la app por SSE, explica el buffering, la cancelación y las salidas con JSON Schema.
• M11 cuenta los tres contratos de un modelo y qué cambios los rompen. C01 decide HTTP o gRPC hacia Triton; C10 pone una API compatible con OpenAI delante de su LLM.

En el Dojo: la estación 6, «Código de serving», escribe el gateway de C01: el endpoint /v1/classify, su esquema, el 422 y la llamada a Triton con la extensión binaria. Cuando abra, ahí la vas a practicar.

En Sensei: «Balanceadores, proxies y gateways» explica por qué gRPC se pega a un solo servidor y qué proxy guarda un stream. «Timeouts, reintentos e idempotencia» retoma el webhook que llega dos veces y el Retry-After, y «Qué tan rápido y cuánto» mide lo que cuesta cada request.

Estos son los conceptos que presentó esta lección. Cada uno tiene su tarjeta con la definición completa.

Intenta responder en tu cabeza antes de abrir cada respuesta.

1. 1¿Qué es un endpoint? Da el de C01.Ver respuesta

   Una puerta concreta de una API: un método HTTP más una ruta, con su propio contrato. El de C01 es POST /v1/classify, con top_k en la URL.

2. 2¿Qué le falta a JSON que un modelo suele necesitar?Ver respuesta

   Bytes (hay que usar base64 o mandarlos aparte), fechas (van como texto), NaN e infinito (no existen en el estándar) y enteros exactos arriba de 2⁵³ si el cliente los lee como FP64, como JavaScript.

3. 3¿Cuánto crece algo al pasarlo a base64, y por qué?Ver respuesta

   Un 33 %: cada 3 bytes (24 bits) se escriben como 4 letras de 6 bits.

4. 4¿Por qué C01 contesta en JSON pero le manda el tensor a Triton en binario?Ver respuesta

   Hacia afuera hay muchos clientes de otros equipos y una respuesta chica: conviene que sea legible. Hacia adentro hay un solo cliente y un tensor de 602 KB, 500 veces por segundo: en JSON pesaría 5 veces más y serializarlo quemaría decenas de núcleos.

5. 5¿Qué quiere decir «se versiona el contrato, no el modelo»?Ver respuesta

   El modelo cambia seguido sin cambiar la API; cada respuesta dice qué model_version contestó. Solo un cambio que rompe el contrato estrena /v2.

6. 6¿Para qué sirve SSE y qué arruina su efecto?Ver respuesta

   Para mandar la respuesta en pedazos, como los tokens de un LLM, y que la persona empiece a leer con el primero. Lo arruina un proxy que junta la respuesta antes de pasarla (buffering).

7. 7¿Polling o webhook para 10,000 trabajos vivos?Ver respuesta

   El polling cada 2 s serían 5,000 consultas por segundo, casi todas inútiles. El webhook manda un aviso por trabajo, pero el cliente necesita una dirección pública, firmas y descartar repetidos. Lo común: webhook, con polling como respaldo.