# Lección 02 — Serving, runtimes y protocolos: del mensaje al token **Curso:** Atlas Ornith v4.4 **Duración objetivo:** 12 minutos **Nivel:** intermedio **Estado:** guion previo a locución; no publicar ## Propósito de la lección Al terminar podrás explicar por qué “el modelo funciona” y “el sistema funciona” no son la misma afirmación. Vas a seguir una solicitud desde el cliente hasta el runtime, distinguir protocolo, plantilla y parser, entender para qué sirve la caché KV y diseñar una prueba mínima de serving sin confundir compatibilidad declarada con validación de extremo a extremo. ## Apertura Imagina que conectas una aplicación a un modelo local. La petición llega, el servidor devuelve texto y parece que todo está resuelto. Después activas herramientas: el modelo imprime etiquetas extrañas, el cliente no reconoce la llamada o la conversación se rompe en el segundo turno. El problema quizá no está en los pesos. Puede estar en cualquiera de las capas que hay alrededor. Hoy construiremos un mapa sencillo: `cliente → protocolo HTTP → servidor → chat template → tokenizer/modelo → parser → respuesta` Ese mapa evita una frase peligrosa: “es OpenAI-compatible, por tanto todo es compatible”. No. La compatibilidad es un contrato concreto, no una marca. ## 1. Runtime y serving no son sinónimos Un **runtime de inferencia** es el software que carga los pesos, reserva memoria, ejecuta kernels y produce tokens. `llama.cpp`, vLLM y SGLang son ejemplos de runtimes con decisiones distintas sobre formatos, hardware, paralelismo y planificación. El **serving** añade la operación alrededor de esa inferencia: escucha peticiones, valida JSON, organiza colas, agrupa solicitudes, transmite eventos, expone métricas y devuelve errores. Un runtime puede servir bien una generación aislada y fallar como servicio concurrente. También puede cargar una arquitectura y, aun así, no ofrecer el protocolo exacto que espera un cliente. vLLM se presenta en su repositorio como motor de inferencia y serving, e incluye batching continuo, gestión eficiente de memoria de atención, streaming, parsers de tools y un servidor OpenAI-compatible.[3] `llama-server`, por otra parte, documenta rutas compatibles para chat, responses y embeddings, además de batching continuo y function calling.[6] Estas superficies se solapan, pero no son intercambiables en cada detalle. La unidad de compatibilidad útil no es “runtime X”. Es la tupla completa: `modelo + revisión + cuantización + tokenizer + template + runtime/build + flags + parser + endpoint + cliente + streaming` Cambiar un elemento crea una celda nueva que debe probarse. ## 2. Qué significa OpenAI-compatible En Chat Completions, un cliente suele enviar `POST /v1/chat/completions` con un identificador de modelo, una lista de mensajes y parámetros de generación. La respuesta incluye `choices`, un `message` y un `finish_reason`; cuando hay herramientas, ese motivo puede ser `tool_calls`.[1] Responses usa otro contrato: trabaja con ítems y eventos, y una llamada de función lleva campos como `name`, `arguments` y un `call_id` estable que debe enlazarse con su resultado.[2] Que un servidor implemente Chat Completions no demuestra que implemente Responses. Que acepte una petición de texto tampoco demuestra tools, multimodalidad, logprobs o streaming. Por eso conviene hacer cuatro preguntas: 1. ¿Qué ruta consume realmente el cliente? 2. ¿Qué campos envía, incluidos los opcionales? 3. ¿Qué forma de respuesta y qué evento terminal espera? 4. ¿Qué conserva entre la llamada de tool y el siguiente turno? “Compatible” puede signific sólo que existe una ruta parecida. La compatibilidad operativa exige probar el subconjunto exacto que se utilizará. ## 3. La chat template: el protocolo interno del modelo La API recibe mensajes estructurados: `system`, `user`, `assistant` y, quizá, `tool`. El modelo no ve esos objetos JSON directamente. La **chat template** los transforma en una secuencia de texto y tokens especiales que el checkpoint aprendió a interpretar. La plantilla decide dónde empieza cada rol, cómo se cierran los turnos, cómo se describen las herramientas y cómo se representa su resultado. En la plantilla publicada para Ornith-1.5-9B, las tools se serializan dentro de un bloque, las llamadas usan etiquetas estructuradas y las respuestas de herramienta se reinyectan con su propio envoltorio.[5] Esto muestra por qué no debemos inventar una plantilla “aproximada”. Una sintaxis distinta puede degradar la selección de tools aunque el modelo siga generando español o código razonable. Piensa en la template como el adaptador de entrada. Si falta, está desactualizada o no coincide con el parser, los pesos reciben otro dialecto. El fallo puede parecer inteligencia deficiente cuando en realidad es traducción defectuosa. ## 4. El parser: de tokens a estructura El modelo genera tokens. Un cliente de herramientas necesita objetos: nombre de función, argumentos JSON e identificador. El **parser** reconoce la sintaxis emitida por el modelo y la convierte en `tool_calls` o en ítems equivalentes. Template y parser forman una pareja. La template enseña al modelo el formato esperado; el parser intenta recuperar ese formato de la salida. Activar un parser por nombre no garantiza éxito. Hay que comprobar, como mínimo: - nombre exacto de la función; - argumentos válidos según el schema; - identificador estable; - una sola ejecución de la herramienta; - reinyección correcta del resultado; - respuesta final después de la herramienta; - segundo turno sin perder el historial. Con streaming, la dificultad aumenta: el nombre y los argumentos pueden llegar fragmentados en múltiples eventos. El cliente debe reconstruirlos antes de ejecutar nada. Nunca se debe ejecutar una llamada parcial ni una tool fuera de una lista permitida. ## 5. Caché KV: memoria de la conversación activa Durante la atención, cada token produce representaciones **key** y **value**. Guardarlas evita recalcular todo el prefijo cada vez que se genera el token siguiente. Esa memoria temporal es la **caché KV**. Crece con la longitud de las secuencias y con el número de solicitudes activas; por eso puede limitar concurrencia y contexto incluso cuando los pesos ya caben en VRAM. El trabajo de PagedAttention parte precisamente de ese problema: la KV cambia de tamaño y una asignación ineficiente desperdicia memoria por fragmentación y duplicación. El paper propone organizarla con una idea inspirada en memoria virtual y paginación, y reporta mejoras de throughput de dos a cuatro veces frente a los sistemas comparados en sus experimentos de 2023.[4] Dos límites son importantes. Primero, esas cifras pertenecen a aquel diseño, hardware, modelos y comparación; no son una promesa universal para nuestro despliegue. Segundo, KV cache no es lo mismo que pesos ni que contexto máximo declarado. Un modelo puede cargar y después quedarse sin memoria al aumentar contexto o concurrencia. El serving intenta equilibrar tres objetivos que compiten: - **latencia al primer token**, importante para interacción; - **throughput**, tokens o solicitudes atendidas por unidad de tiempo; - **capacidad**, cuántas secuencias y cuánto contexto caben simultáneamente. Más batching puede mejorar throughput y empeorar la espera de una petición individual. La configuración correcta depende de la carga, no de un número mágico. ## 6. Práctica guiada — diseña el contrato antes de lanzar el servidor No vamos a publicar ni desplegar nada. La práctica consiste en escribir una ficha de validación para un canario local. ### Paso 1: congela la celda Anota checkpoint y revisión, cuantización, tokenizer, hash de template, runtime y build, parser, flags, endpoint, cliente y versión. Define `streaming: no` y concurrencia uno para la primera prueba. ### Paso 2: declara el contrato Elige Chat Completions **o** Responses; no mezcles ambos. Para Chat, especifica `POST /v1/chat/completions`, roles aceptados, forma de `tools`, `tool_choice`, `finish_reason` y estructura de `tool_calls`. Para Responses, especifica los tipos de ítem, `call_id` y evento terminal. ### Paso 3: usa una herramienta inocua Define `eco_json`, que recibe un texto y devuelve exactamente ese texto. Prueba un argumento con comillas escapadas. El servidor debe producir una llamada estructurada; el harness valida el JSON, ejecuta sólo `eco_json`, devuelve el resultado con el mismo ID y exige una respuesta final. ### Paso 4: prueba fallos Envía una tool inexistente, omite un argumento requerido, limita mucho la salida y provoca un error controlado de la herramienta. El sistema debe fallar de forma visible: nada de reintentos infinitos, XML suelto o ejecución duplicada. ### Paso 5: añade complejidad de una en una Sólo después prueba streaming, segundo turno, varias tools, thinking, más contexto y concurrencia. Registra latencia, tokens, razón de terminación, validez de argumentos y errores. Si cambias template o parser, repite la celda completa. **Criterio de éxito de la práctica:** puedes señalar en qué capa ocurrió cada fallo y demostrar el round trip completo, no sólo una respuesta textual. ## Límites y trazabilidad de esta lección - **[BASE r3.2]** L2 estaba definida como “serving, runtime y protocolos”, con una práctica centrada en endpoint, template, parser, streaming y fallos; presupuesto de 12 minutos. - **[ACCESO LIMITADO]** Durante la auditoría r3.2, `docs.vllm.ai` devolvió HTTP 429. La URL se conserva como registro, pero esta lección **no afirma acceso comprobado ni usa su contenido como evidencia nueva**.[7] - **[FUENTE PRIMARIA ALTERNATIVA]** Las afirmaciones generales sobre funciones de vLLM se apoyan en su repositorio público y las de PagedAttention en el paper, no en los dos vídeos suplementarios.[3][4] - **[VÍDEOS CON RESERVA]** Los vídeos seleccionados para L2 tienen ASR detectada pero descarga 429; sirven como apoyo pedagógico previsto, no como prueba de cifras o compatibilidad. - **[NO DEMOSTRADO]** Aquí no se ejecutó Ornith, vLLM, llama.cpp, un cliente, una tool ni una prueba de carga. Los ejemplos describen un protocolo de validación, no resultados. - **[ALCANCE]** “OpenAI-compatible” no implica conformidad total ni equivalencia entre Chat Completions y Responses. ## Glosario **Runtime:** motor que carga el modelo y ejecuta la inferencia. **Serving:** capa que convierte inferencia en un servicio operable para uno o más clientes. **Endpoint:** ruta HTTP que recibe una operación concreta. **Chat template:** transformación de mensajes estructurados al formato de tokens esperado por el modelo. **Parser:** componente que transforma la salida textual o tokenizada en campos estructurados. **KV cache:** memoria temporal de keys y values de atención reutilizada durante la generación. **Batching continuo:** planificación que incorpora y retira solicitudes mientras otras siguen generando. **Streaming:** entrega incremental de la respuesta mediante eventos o fragmentos. **E2E:** validación de extremo a extremo, desde el cliente hasta la respuesta final y el siguiente turno. **Canario:** prueba limitada y reversible antes de ampliar tráfico o capacidades. ## Recapitulación Un modelo no llega solo a una aplicación. Entre ambos hay un runtime, un servidor, un protocolo, una chat template y, para herramientas, un parser. La caché KV permite reutilizar el trabajo de atención, pero consume memoria y condiciona contexto, concurrencia y rendimiento. OpenAI-compatible es un punto de partida: cada endpoint y cada función deben verificarse. La regla final es sencilla: congela la celda, prueba el contrato mínimo, añade complejidad de una en una y llama “compatible” únicamente a lo que hayas observado de extremo a extremo. ## Sources [1] https://developers.openai.com/api/reference/resources/chat [2] https://platform.openai.com/docs/api-reference/responses [3] https://github.com/vllm-project/vllm [4] https://arxiv.org/abs/2309.06180 [5] https://huggingface.co/ornith-ai/Ornith-1.5-9B/raw/main/chat_template.jinja [6] https://github.com/ggml-org/llama.cpp/blob/60081bb2b5b3294165a4d67c5cbeebe74c868014/tools/server/README.md [7] https://docs.vllm.ai