Redundancia y conmutación por error
La API de Completions puede conmutar por error automáticamente de un modelo a otro cuando falla una llamada al proveedor. Usted define una cadena ordenada (un modelo primario más hasta dos alternativas) y SecureAI prueba cada una de ellas hasta que una tiene éxito. Esto le brinda resiliencia contra interrupciones del proveedor, límites de velocidad y tiempos de espera sin ninguna lógica de reintento en su propio código. La redundancia está disponible tanto en el endpoint clásico/chat/completions como en el endpoint compatible con OpenAI /v1/chat/completions.
Cómo se define una cadena
Hay tres formas de solicitar una cadena, en orden de prioridad:
Una cadena puede contener como máximo 3 modelos distintos. Las entradas duplicadas están colapsadas. Cada entrada de la cadena puede ser una cadena modelo simple o un objeto con tiempos de espera por intento:
models y fallback_models en la misma solicitud.
Opciones para toda la cadena (redundancy)
Los tiempos de espera por intento (establecidos dentro de una entrada
models[]) anulan los valores de toda la cadena para ese intento.
Desencadenantes de conmutación por error
Un intento fallido se clasifica en uno de estos motivos; La conmutación por error ocurre solo si el motivo está en su listaon y queda otro modelo en la cadena:
Las fallas que no se pueden reintentar nunca desencadenan una conmutación por error, por ejemplo, un bloqueo intencional de límite de velocidad de puerta de enlace/presupuesto de token, un disyuntor abierto o un rechazo de política/validación. Una alternativa fallaría de manera idéntica o el bloqueo es deliberado.
Comportamiento de transmisión
Para solicitudes de transmisión, la conmutación por error solo es posible antes de que llegue el primer token de contenido. SecureAI extrae la transmisión ascendente hasta el primer token (delimitado porfirst_token_timeout_ms); si eso falla, pasa al siguiente modelo. Una vez que se ha enviado el primer token a su cliente, el modelo de servicio se bloquea: una interrupción posterior a mitad de camino aparece como un marco error, no como una conmutación por error.
Lo que obtienes a cambio
Cuando se ejecuta una cadena de varios modelos, la respuesta incluye un informe de conmutación por error:- Endpoint clásico:
metadata.failover - Endpoint compatible con OpenAI:
secureai.failover
metadata.served_model / secureai.served_model te dice qué modelo respondió realmente, y requested_model es el primer modelo de la cadena. Una solicitud de modelo único (heredado) no genera ningún informe de conmutación por error.
Cuando falla toda la cadena
Si todos los intentos fallan, la solicitud devuelve un error que enumera todos los intentos:- 429 si cada falla fuera un límite de tasa.
- 502 en caso contrario.
code: "all_models_failed".
Valores predeterminados del administrador (failoverDefaults)
Un administrador puede adjuntar una cadena predeterminada a una clave API para que las personas que llaman obtengan conmutación por error sin enviar una cadena en cada solicitud. Configurada en Admin → Claves API, la carga útil se valida y fija:
models: hasta 3 nombres de modelos distintos.timeout_ms: 1000–300000.first_token_timeout_ms: 500–60000.on: cualquier subconjunto de los cuatro activadores.
model: "a" y a está presente en failoverDefaults.models, la cadena comienza en la posición de a y continúa a través de los valores predeterminados restantes.
Seguridad y facturación por intento
Cada intento es una llamada completa e independiente a través del contenedor SMLTP: aplicación de políticas, gobernanza de salida/residencia y el token de derecho firmado, todo se vuelve a ejecutar por intento, vinculado al modelo de ese intento y a los bytes de solicitud exactos. La facturación refleja el modelo que realmente proporcionó la respuesta. Cada conmutación por error también emite un evento de seguridadapi:model_failover (entregado a cualquier webhooks suscrito) y una entrada del registro de auditoría.
Relacionado
- Finalización del chat
- [Endpoint compatible con OpenAI] (/api/chat/openai-compatible)
- Policy Check: obtenga una vista previa del acceso a toda la cadena sin gastar puntos.
- Webhooks — suscríbete a
api:model_failover.