Enrutamiento de fallback para API de LLM: un manual de failover para producción

El enrutamiento de fallback para las API de LLM parece simple hasta el primer incidente real: detectar un error, cambiar de modelo y volver a intentarlo. En producción, esa regla puede convertir un problema de un proveedor en llamadas duplicadas a herramientas, JSON roto, salida de streaming mezclada, tráfico de reintentos descontrolado o una respuesta que es técnicamente exitosa pero ya no satisface el contrato del producto.

Un diseño más seguro trata el fallback como una máquina de estados acotada, no como una lista de nombres de modelos de respaldo. Cada solicitud avanza a través de un pequeño conjunto de decisiones:

1. ¿El fallo es reintentable?
2. ¿Es seguro repetir esta solicitud?
3. ¿El siguiente intento debe usar el mismo destino o uno diferente?
4. ¿Puede el fallback preservar el contrato requerido?
5. ¿La solicitud ya ha producido salida o efectos secundarios?
6. ¿Se han agotado la latencia extremo a extremo y el presupuesto de intentos?

Este manual convierte esas preguntas en una matriz de errores, una política de enrutamiento, un controlador en TypeScript, un plan de pruebas y una lista de verificación de despliegue para aplicaciones LLM multi-proveedor.

Las cuatro acciones detrás de un enrutamiento de fallback fiable para API de LLM

No envíes todos los errores al mismo bucle de reintentos. Un enrutador de producción necesita cuatro acciones distintas.

La distinción entre failover y fallback importa. Failover mantiene el contrato lógico del modelo y cambia la infraestructura. Fallback cambia el modelo o el nivel de capacidad. El failover suele ser la opción de menor riesgo.

Si necesitas el diseño más amplio de la ruta de solicitud en torno a alias, puntuación de salud, facturación y observabilidad, empieza con la guía de arquitectura de gateway de API de IA. Este artículo se centra en el controlador que se ejecuta después de que se ha seleccionado un destino.

Construye una matriz de error a acción antes de escribir código de reintentos

Los SDK de los proveedores exponen distintas clases de excepciones y cuerpos de respuesta, pero el enrutador debería normalizarlos en una pequeña taxonomía interna.

La documentación oficial de los proveedores refuerza por qué es necesaria la normalización. Anthropic documenta errores distintos de límite de tasa, API y sobrecarga, y señala que una solicitud en streaming todavía puede fallar después de una respuesta inicial exitosa. OpenAI también separa las solicitudes no válidas, los límites de tasa y los fallos del lado del servidor. Su aplicación debería traducir las señales específicas del proveedor en decisiones internas estables en lugar de incrustar nombres de proveedores en toda la lógica de negocio.

Establezca un único presupuesto de reintentos para toda la solicitud

Los reintentos suelen existir en varios lugares a la vez: el cliente HTTP, el SDK del proveedor, el gateway, el trabajo en segundo plano y el servicio de aplicación. Si cada capa realiza tres intentos, una sola acción del usuario puede multiplicarse en muchas más llamadas aguas arriba de las que el equipo pretendía.

El patrón más seguro es:

• Elegir una capa para encargarse de los reintentos y el fallback de LLM.
• Establecer un único plazo extremo a extremo para la solicitud del usuario o el trabajo.
• Definir un número máximo de intentos aguas arriba.
• Reservar parte del plazo para el destino de fallback.
• Usar backoff exponencial con jitter para fallos transitorios.
• Detenerse cuando el tiempo restante no pueda soportar otro intento significativo.

La guía de AWS sobre timeouts, retries, backoff y jitter describe cómo los reintentos pueden amplificar la sobrecarga y recomienda un comportamiento acotado en lugar de una repetición inmediata constante. El mismo principio se aplica a las API de modelos, donde un proveedor bajo carga es el que menos puede absorber tráfico de reintentos sincronizados.

Un presupuesto interactivo práctico podría expresarse como política en lugar de sleeps codificados de forma rígida:

type RetryBudget = {
  deadlineMs: number;
  maxAttempts: number;
  maxSameTargetAttempts: number;
  reserveForFallbackMs: number;
};

Los valores exactos dependen del producto. Una interfaz de chat, un agente de programación, un evaluador por lotes y un flujo asíncrono de vídeo no deberían compartir el mismo presupuesto.

Use circuit breakers to stop routing into known failures

Un circuit breaker evita que cada nueva solicitud redescubra la misma interrupción.

Los estados estándar son:

• Cerrado: las solicitudes fluyen normalmente mientras el router mide fallos y latencia.
• Abierto: el destino queda temporalmente no elegible porque su comportamiento reciente superó un umbral.
• Semiabierto: un pequeño número de solicitudes de sondeo comprueba si el destino se ha recuperado.

El patrón de circuit breaker de Azure describe este ciclo cerrado/abierto/semiaierto. Para el enrutamiento de LLM, la clave del breaker debe ser lo bastante específica como para aislar la superficie que falla. Entre las dimensiones útiles se incluyen el proveedor, el modelo, la región, el despliegue, la cuenta y la capacidad. Un despliegue de finalización de texto puede estar saludable mientras falla una ruta de llamadas a herramientas o un endpoint regional.

Evite abrir circuitos ante cada error del cliente. La autenticación inválida, las solicitudes mal formadas, el desbordamiento de contexto y el rechazo por políticas suelen decir más sobre la solicitud que sobre la salud del proveedor. Los breakers deberían reaccionar principalmente a señales transitorias de infraestructura como fallos de conexión, timeouts, sobrecarga y errores de servidor.

Conserve un contrato de capacidades entre modelos

Un modelo de fallback no es seguro solo porque acepte una solicitud compatible con OpenAI. Defina el contrato mínimo para cada alias de ruta.

route: support-agent-v3
requires:
  modalities: [text]
  streaming: true
  tools: true
  parallel_tool_calls: false
  structured_output: json_schema
  context_window_min: 64000
  max_output_tokens_min: 4000
quality_gates:
  task_success_rate_min: 0.94
  schema_valid_rate_min: 0.995
policy:
  same_model_failover_first: true
  cross_model_fallback_allowed: true

Antes de añadir un destino al conjunto de fallback, pruebe al menos:

• Parámetros de solicitud compatibles
• Definición de herramientas y comportamiento de llamada a herramientas
• Validez de la salida estructurada
• Forma de los eventos de streaming
• Límites de contexto y salida
• Comportamiento de seguridad adecuado para la aplicación
• Campos de contabilización de tokens utilizados por los controles de costos
• Latencia y calidad en prompts representativos

Este enfoque centrado en el contrato es especialmente importante para flujos de trabajo que cruzan modalidades. La guía de enrutamiento de agentes multimodales cubre comprobaciones adicionales para rutas de texto, imagen, audio y video.

Un controlador de fallback en TypeScript

El siguiente ejemplo es intencionalmente independiente del proveedor. Asume que los adaptadores aguas arriba normalizan los errores y las respuestas antes de que la capa de enrutamiento los vea.

type FailureKind =
  | "connect"
  | "timeout"
  | "rate_limit"
  | "overloaded"
  | "server_error"
  | "invalid_request"
  | "auth"
  | "policy"
  | "context_overflow"
  | "partial_stream"
  | "unknown";

type Target = {
  id: string;
  contractId: string;
  healthy: boolean;
  circuit: "closed" | "open" | "half_open";
};

type RequestState = {
  attempt: number;
  sameTargetAttempts: number;
  deadlineAt: number;
  outputStarted: boolean;
  sideEffectsPossible: boolean;
};

function canReplay(state: RequestState): boolean {
  return !state.outputStarted && !state.sideEffectsPossible;
}

function isTransient(kind: FailureKind): boolean {
  return [
    "connect",
    "timeout",
    "rate_limit",
    "overloaded",
    "server_error",
  ].includes(kind);
}

function chooseNextAction(
  kind: FailureKind,
  state: RequestState,
  current: Target,
  equivalent: Target | undefined,
  fallback: Target | undefined,
) {
  if (!canReplay(state) || kind === "partial_stream") return { type: "stop" };

  if (!isTransient(kind)) return { type: "stop" };

  if (state.attempt >= 3 || Date.now() >= state.deadlineAt) {
    return { type: "stop" };
  }

  if (
    state.sameTargetAttempts < 1 &&
    current.circuit === "closed" &&
    current.healthy
  ) {
    return { type: "retry", target: current };
  }

  if (equivalent?.healthy && equivalent.circuit !== "open") {
    return { type: "failover", target: equivalent };
  }

  if (
    fallback?.healthy &&
    fallback.circuit !== "open" &&
    fallback.contractId === current.contractId
  ) {
    return { type: "fallback", target: fallback };
  }

  return { type: "stop" };
}

El código de producción también necesita retrasos con jitter, propagación de cancelación, IDs de solicitud, actualizaciones del circuit breaker, telemetría y análisis de errores específico del adaptador. La propiedad importante es que la seguridad de reintento y la compatibilidad del contrato se comprueben antes de seleccionar otro destino.

Trata el fallback de streaming como un protocolo separado

El streaming crea un límite duro: una vez que el contenido llega al cliente, la gateway ya no puede fingir que el intento nunca ocurrió.

Si el upstream falla antes de que se reenvíe el primer evento, un reintento o fallback aún puede ser transparente. Después de que se entrega el primer token, delta de herramienta, evento de imagen o fragmento de audio, el cambio automático de modelo corre el riesgo de combinar dos respuestas incompatibles.

Utilice una de estas estrategias explícitas:

1. Fallar el stream claramente. Devuelva un evento de error estable con el ID de la solicitud y deje que el cliente ofrezca reintento.
2. Buffer antes de liberar. Para respuestas estructuradas cortas, valide el resultado completo antes de enviarlo aguas abajo. Esto sacrifica el tiempo hasta el primer token.
3. Implemente reanudación a nivel de aplicación. Inicie un nuevo turno con contexto explícito que indique que la respuesta anterior se interrumpió. Trátelo como una nueva generación del modelo, no como una continuación del mismo flujo de bytes.

No concatene silenciosamente la salida de dos modelos.

Separe la fiabilidad de las llamadas a herramientas de la fiabilidad de las llamadas al modelo

Una solicitud a un LLM puede ser reproducible aunque la herramienta que seleccionó no lo sea. Un pago, correo electrónico, despliegue, escritura en base de datos o creación de ticket puede completarse incluso si la conexión del modelo falla antes de que la aplicación registre el resultado.

Proteja las herramientas de escritura con:

• Una clave de idempotencia derivada de la operación del usuario, no del intento del proveedor
• Un registro duradero de ejecución de la herramienta
• Desduplicación en el límite de la herramienta
• Una distinción clara entre planned, started, succeeded y unknown
• Revisión humana para efectos secundarios inciertos de alto impacto

Si son posibles efectos secundarios y su resultado es desconocido, detenga el fallback automático. Primero reconcílie el estado de la herramienta.

Observe el fallback como un resultado del producto

Una tasa baja de error del proveedor no demuestra que el fallback esté funcionando. Haga seguimiento del resultado completo de la ruta.

Registre un motivo de ruta para cada intento: destino seleccionado, error normalizado, retraso del reintento, estado del circuito, motivo del fallback, tiempo restante de la fecha límite de la solicitud y resultado final. Evite registrar prompts o salidas sensibles, a menos que la política de datos del producto lo permita explícitamente.

Pruebe las rutas de fallo antes de habilitar el fallback automático

Ejecute inyección de fallos en un entorno de staging y luego aplique canary a la política en producción.

Pruebas de transporte y proveedor

• Romper la conexión antes de los encabezados de respuesta.
• Devolver límites de tasa repetidos con y sin guía de reintento.
• Simular sobrecarga y errores del servidor.
• Retrasar el primario hasta que el plazo de la solicitud esté casi agotado.
• Abrir un circuito de destino y verificar que el tráfico se mueve a una ruta elegible.
• Recuperar el destino y verificar que las sondas half-open no restablecen el tráfico completo demasiado pronto.

Pruebas de contrato

• Eliminar una herramienta obligatoria del adaptador de fallback.
• Devolver salida estructurada inválida.
• Cambiar la forma de un evento de streaming.
• Superar los límites de contexto o de salida.
• Comparar la calidad del fallback en un conjunto de evaluación fijo.

Pruebas de seguridad ante reintentos

• Fallar antes y después del primer evento transmitido.
• Fallar después de que comience una herramienta del lado de escritura.
• Repetir la misma clave de idempotencia.
• Cancelar la solicitud del cliente mientras la tentativa de fallback está pendiente.

La prueba solo pasa cuando el enrutador elige la acción esperada y registra el motivo.

Dónde encaja Flatkey

Flatkey proporciona una clave de API y una URL base compatible con OpenAI para los modelos compatibles, con uso y facturación centralizados. Eso crea un límite de integración estable para el acceso y el enrutamiento multmodelo.

Los equipos de aplicación aún deben ser responsables del contrato de ruta descrito en este manual: qué errores pueden reintentarse, qué destinos son equivalentes, si se permite el fallback entre modelos, cómo se deduplican las herramientas y qué umbral de calidad debe cumplir una respuesta recuperada.

Para la ruta de integración más corta, use el Flatkey integration starter. Si está migrando un cliente existente, la lista de verificación de la API gateway compatible con OpenAI cubre la URL base, los parámetros, el streaming y la verificación de la forma de los errores.

Lista de verificación para el despliegue en producción

• Normalice los errores del proveedor en una taxonomía interna estable.
• Defina reintento, failover equivalente, fallback entre modelos y acciones de parada.
• Asigne un componente para encargarse del presupuesto de reintentos.
• Imponga un único plazo de extremo a extremo y un número máximo de intentos.
• Añada backoff exponencial con jitter para fallos transitorios.
• Asigne los circuit breakers por el dominio de fallo más pequeño útil.
• Defina un contrato de capacidades versionado para cada alias de ruta.
• Bloquee el cambio automático después de que comience la salida parcial.
• Añada idempotencia y reconciliación para herramientas del lado de escritura.
• Registre los motivos de ruta y los resultados finales de la tarea.
• Inyecte fallos de transporte, sobrecarga, contrato, streaming y efectos secundarios.
• Haga canary del failover equivalente antes de habilitar el fallback entre modelos.
• Añada interruptores de emergencia para cada destino y política de fallback.

Preguntas frecuentes

¿Qué es el enrutamiento de fallback para APIs de LLM?

El enrutamiento de fallback para APIs de LLM es una política de confiabilidad que selecciona otro modelo o proveedor elegible cuando la ruta preferida no puede completar una solicitud. El fallback seguro comprueba la seguridad ante reintentos, la compatibilidad de capacidades, el estado del circuito, el presupuesto de latencia y el estado de salida antes de cambiar.

¿Cuál es la diferencia entre un reintento de LLM y el fallback?

Un reintento repite la solicitud contra el mismo destino. El failover se traslada a una infraestructura equivalente mientras preserva el contrato lógico del modelo. El fallback entre modelos cambia el modelo y, por tanto, requiere pruebas más rigurosas de compatibilidad y calidad.

¿Debería una API de LLM reintentar cada error 429 o 5xx?

No. Los reintentos deben estar limitados por un plazo end-to-end, un límite de intentos, una política de backoff, el estado del circuito y una verificación de seguridad para reejecución. El failover equivalente puede ser mejor que llamar repetidamente a un destino en mal estado.

¿Puede un router de LLM cambiar de modelo durante un stream?

No de forma transparente después de que la salida haya llegado al cliente. La opción segura por defecto es finalizar el stream de manera clara o iniciar un nuevo turno a nivel de aplicación. Concatenar salidas parciales de distintos modelos puede corromper el contrato de la respuesta.

¿Cuándo debería desactivarse el fallback entre modelos?

Desactívalo cuando el modelo alternativo no pueda preservar las herramientas requeridas, la salida estructurada, los límites de contexto, el comportamiento de seguridad, los umbrales de calidad o las garantías de efectos secundarios. También desactiva la reejecución automática después de una salida parcial o de una ejecución de herramientas incierta.

¿Cuántos intentos de fallback debería hacer una solicitud de LLM?

No existe un número universal. Usa el menor número de intentos acotado que encaje con el presupuesto de latencia del producto y la evidencia de pruebas. El router debe detenerse cuando el plazo restante no pueda sostener otro intento útil.

Un fallback confiable no significa “probarlo todo”. Significa hacer explícita la siguiente acción, compatible, segura para reejecución, observable y fácil de detener.