← Atlas

Lección 7 — Recuperación, reintentos, bucles y observabilidad

Descargar MP3 · Transcripción

# Lección 7 — Recuperación, reintentos, bucles y observabilidad

## Objetivo

Diseñar la capa de recuperación de un agente sin atribuirle al modelo garantías que pertenecen al orquestador. Al terminar, podrás decidir qué fallos son reintentables, fijar presupuestos y *timeouts*, evitar efectos duplicados mediante idempotencia, cortar bucles y exigir trazas suficientes para reconstruir cada intento.

## Prerrequisitos

- Distinguir inferencia, llamada de herramienta y ejecución de una acción.
- Conocer `tool_call`, `call_id`, códigos HTTP y estados terminales.
- Entender que contexto máximo, tokens de salida y tiempo de pared son recursos diferentes.

## Estado de evidencia en r3.2

- **Demostrado:** Ornith propone llamadas, pero la aplicación llamadora define herramientas, aporta contexto y ejecuta o maneja las llamadas. La card no especifica política de reintentos, *backoff*, idempotencia, reparación de JSON ni recuperación multivuelta.
- **Demostrado:** vLLM permite cancelar una Response. Cancelar no significa reanudarla ni garantiza que una herramienta externa no haya actuado.
- **Demostrado:** `llama-server` ofrece `/health`, *prompt cache*, guardado de slots y checkpoints de contexto. Son mecanismos de estado u observabilidad, no una promesa de *retry* o *failover* automático.
- **Demostrado, con alcance estrecho:** vLLM documenta una recuperación de bloques KV externos inválidos. No generaliza a OOM, caída de proceso, error de herramienta o conversación dañada.
- **No demostrado:** que Ornith-1.5-9B se recupere solo de JSON inválido, 429, 5xx, *timeout*, herramientas fallidas, procesos caídos o bucles.

## 1. Dos sistemas, dos responsabilidades

Un modelo produce una propuesta probabilística: texto, argumentos o una decisión de usar herramienta. Puede reconocer un error devuelto y proponer otra acción, pero eso es **conducta del modelo**, no control operativo. El **orquestador** posee el reloj, los contadores, el estado durable, las credenciales, la política de reintento y la autoridad para ejecutar.

Esta frontera evita una confusión peligrosa. Instruir «si falla, vuelve a intentar» no crea un límite. Si el mismo error vuelve a entrar al contexto, el modelo puede repetir la llamada hasta agotar tokens, cuota o dinero. El límite efectivo debe vivir fuera del prompt:

| Responsabilidad | Modelo | Orquestador |
|---|---:|---:|
| Proponer herramienta y argumentos | Sí | Valida |
| Clasificar error por política estable | Puede sugerir | Sí, decide |
| Contar intentos y consumo | No confiable | Sí |
| Aplicar *timeout*, cancelación y *backoff* | No | Sí |
| Generar y conservar clave idempotente | No | Sí |
| Ejecutar efectos externos | Nunca directamente | Sí, tras autorización |
| Registrar traza y estado final | No | Sí |

El modelo puede ayudar a reparar un argumento semántico, por ejemplo pedir el identificador que falta. No debe decidir cuántas veces cobrar, cuánto esperar ni cuándo ignorar un error de autorización.

## 2. Recuperar no es repetir

Primero se clasifica el fallo. Un `400` por schema inválido requiere corregir datos, no repetir bytes idénticos. Un `401` o `403` exige detenerse y reparar autenticación o permisos. Un `404` normalmente requiere revisar el identificador. Un `409` puede ser conflicto de estado y necesita lectura antes de decidir. Un `429` puede admitir espera respetando `Retry-After`. Un `500`, `502`, `503`, desconexión o *timeout* puede ser transitorio, pero sólo se reintenta si la operación es segura y queda presupuesto.

El *timeout* es ambiguo: el cliente dejó de esperar, pero el servidor quizá terminó la acción. Por eso nunca debe traducirse automáticamente a «no ocurrió». En una lectura, repetir suele ser seguro. En una escritura, primero consulta por clave idempotente o estado de negocio. Si no existe forma de conocer el resultado, escala a `resultado_desconocido`; no inventes éxito ni dispares otra escritura a ciegas.

Una política mínima tiene estados explícitos:

`pendiente → en_ejecución → éxito | fallo_permanente | agotado | resultado_desconocido | cancelado`.

Cada transición conserva causa y evidencia. «Recuperado» significa que se alcanzó un estado verificable; no que el modelo produjo una respuesta tranquilizadora.

## 3. Presupuestos que cierran el sistema

Todo episodio necesita un presupuesto compuesto, no sólo `max_tokens`:

- **Intentos:** máximo total y máximo por herramienta.
- **Tiempo:** *deadline* global y *timeout* por inferencia, cola y herramienta.
- **Tokens:** entrada, razonamiento cuando aplique y salida visible.
- **Herramientas:** número de llamadas, tamaño de resultados y paralelismo.
- **Costo/cuota:** gasto, RPM/TPM o unidades internas.
- **Estado:** tamaño máximo de historial y número de reparaciones.

Los límites deben compartir una sola fecha límite. Si quedan ocho segundos, no se inicia una herramienta cuyo *timeout* normal es treinta. Tampoco se reinicia el reloj después de cada retry. Una configuración didáctica, no un valor universal, podría ser: 90 segundos totales, 3 inferencias, 5 llamadas de herramienta, 2 intentos por operación, 8.000 tokens de salida acumulados y resultados de herramienta de hasta 64 KiB. Lo obligatorio es declararlos, medirlos y finalizar al agotarlos.

El *backoff* exponencial con *jitter* reduce ráfagas sincronizadas: espera creciente y un componente aleatorio antes del siguiente intento. Debe respetar `Retry-After` y el *deadline*. No convierte un fallo permanente en transitorio ni justifica exceder el presupuesto.

## 4. Idempotencia antes del retry

Una operación idempotente produce el mismo estado observable aunque la solicitud equivalente llegue varias veces. `GET` suele ser repetible; «crear pedido», «enviar mensaje» o «cobrar» no lo es por naturaleza. Para estas escrituras, el orquestador crea una clave estable por intención lógica, por ejemplo `sesión + paso + operación`, y la reutiliza en todos los intentos. Nunca genera una clave nueva al reintentar, porque eso convierte el retry en otra operación.

El receptor debe almacenar de forma atómica la clave, el hash de la petición, el estado y la respuesta. Misma clave con mismo hash devuelve el resultado previo; misma clave con cuerpo distinto se rechaza como conflicto. La deduplicación necesita una ventana de retención mayor que la vida máxima del episodio. Para sistemas sin soporte idempotente, usa un identificador natural consultable, una bandeja transaccional o verificación posterior. Si nada de eso existe, la política correcta puede ser no reintentar escrituras ambiguas.

Idempotencia no sustituye autorización. Cada intento conserva tenant, actor, alcance y aprobación original; un replay no debe ampliar permisos ni reutilizar una aprobación vencida.

## 5. Detectar y cortar bucles

Un bucle no siempre repite texto idéntico. Puede alternar `buscar → fallar → reformular → buscar`, variar espacios en JSON o saltar entre dos herramientas. El orquestador calcula una firma normalizada con nombre de herramienta, argumentos canónicos, clase de error y estado relevante. Mantiene además un resumen de progreso: hechos nuevos, campos resueltos, estado cambiado y checker mejorado.

Se corta cuando ocurre cualquiera de estas condiciones:

1. se repite la misma firma sin progreso;
2. se supera el máximo por operación o episodio;
3. el mismo error permanente reaparece;
4. el checker no mejora tras reparaciones permitidas;
5. se agota tiempo, tokens, cuota o llamadas;
6. el modelo solicita una acción ya confirmada.

La salida terminal debe decir qué se intentó, qué quedó incierto y qué dato o intervención permitiría continuar. Cambiar de modelo puede ser un fallback, pero consume el mismo presupuesto global y no borra los intentos anteriores.

## 6. Observabilidad para explicar, no para acumular

Cada episodio recibe `trace_id`; cada inferencia, herramienta y retry, un `span_id`; cada intención con efectos, una `idempotency_key`. Los eventos estructurados registran, como mínimo:

- versión y hash de modelo, runtime, template, parser y política;
- protocolo, `call_id`, herramienta y hash de argumentos redactados;
- intento actual, máximo, *deadline* restante y razón del retry;
- tiempos de cola, inferencia y herramienta; TTFT y duración total;
- tokens de entrada/salida, bytes de resultados y consumo acumulado;
- código HTTP o clase de error, `finish_reason` y transición de estado;
- resultado del checker, deduplicación, cancelación y causa terminal.

No se guardan secretos, PII, argumentos sensibles ni razonamiento privado. Se registran hashes, tamaños, categorías y campos permitidos. Logs explican eventos; métricas muestran tasas y percentiles; trazas conectan causalidad. Un panel útil separa éxito al primer intento, éxito recuperado, fallo permanente, presupuesto agotado, resultado desconocido y bucle cortado. Mezclarlos en «éxito final» oculta fragilidad y costo.

Las alertas deben detectar tasa de retry, secuencias sin progreso, 429 sostenidos, 5xx, *timeouts*, duplicados evitados y crecimiento de p95/p99. Un caso fallido permanece en el denominador aunque luego una respuesta manual lo maquille.

## Guion de audio — 90 segundos

Imagina que Ornith propone enviar una factura. El modelo escribe el nombre de la herramienta y sus argumentos; no posee el botón real. El orquestador valida, autoriza y ejecuta. Si a los diez segundos hay *timeout*, no sabemos todavía si la factura salió. Repetir a ciegas podría enviarla dos veces.

La recuperación fiable usa tres cinturones. Primero, presupuesto: fecha límite global, máximo de intentos, llamadas, tokens y costo. Segundo, idempotencia: la misma intención conserva la misma clave, de modo que un retry no crea otra factura. Tercero, observabilidad: una traza conecta propuesta, validación, intento, error, consulta posterior y estado final.

Los errores tampoco se tratan igual. Un 403 se detiene; un schema inválido se corrige; un 429 espera según `Retry-After`; un 503 puede reintentarse con *backoff* y *jitter*, si quedan tiempo e intentos. Si la misma llamada vuelve con el mismo error y no hay progreso, el orquestador corta el bucle.

La idea clave es ésta: el modelo puede sugerir cómo continuar; el orquestador decide si puede, cuántas veces y con qué evidencia. Recuperar no es insistir. Es llegar a un estado verificable sin duplicar efectos ni esconder el costo.

## Práctica segura

Construye un simulador en memoria, sin red ni credenciales, con cuatro herramientas ficticias: `leer_estado`, `crear_evento`, `siempre_503` y `respuesta_lenta`. Define seis escenarios: lectura con 503 transitorio; escritura exitosa cuya respuesta se pierde; 403; JSON inválido reparable; 429 con `Retry-After`; y alternancia sin progreso entre dos llamadas.

Para cada escenario, completa una tabla con: clase de error, ¿retry sí/no?, clave idempotente, máximo de intentos, *timeout*, *deadline*, transición final y campos de traza. Ejecuta al menos dos veces la escritura ambigua y verifica que exista un solo evento lógico.

## Criterio de éxito

La práctica aprueba si: ningún 401/403 se reintenta; los retries conservan clave; el reloj global nunca se reinicia; el bucle termina dentro del presupuesto; una cancelación no se declara rollback; la escritura ambigua se consulta antes de repetirse; y la traza permite reconstruir todos los intentos sin exponer datos sensibles. Los fallos y agotamientos permanecen en las métricas.

## Fuentes

1. [Ornith-1.5-9B model card](https://huggingface.co/ornith-ai/Ornith-1.5-9B) — interfaz y alcance declarado del modelo.
2. [vLLM: Tool Calling](https://docs.vllm.ai/en/latest/features/tool_calling/) — responsabilidades del llamador y modos de selección.
3. [vLLM: OpenAI-Compatible Server](https://docs.vllm.ai/en/latest/serving/openai_compatible_server/) — Responses, consulta y cancelación.
4. [vLLM: KV load failure recovery example](https://github.com/vllm-project/vllm/tree/main/examples/disaggregated/kv_load_failure_recovery_offline) — recuperación acotada de KV externo.
5. [llama.cpp server README](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md) — `/health`, slots, caché y opciones del servidor.
6. [AWS Builders’ Library: Timeouts, retries and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) — límites, amplificación de retries y *jitter*.
7. [Stripe: Idempotent requests](https://docs.stripe.com/api/idempotent_requests) — patrón práctico de claves y replay seguro.
8. [OpenTelemetry: Traces](https://opentelemetry.io/docs/concepts/signals/traces/) — trazas, spans y contexto causal.
9. [RFC 9110, HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — semántica de métodos, códigos y solicitudes idempotentes.