Una misma función requiere llamar a cuatro modelos desde el frontend: GPT-4o como respaldo, DeepSeek para la inferencia principal, Qwen para textos largos en chino y Doubao para los guiones de atención al cliente. Cuatro SDK, cuatro sistemas de autenticación, cuatro documentos. La primera semana tras el lanzamiento, solo alinear estas diferencias consumió dos días-persona.
No es exageración. Lo medimos: tras integrar los cuatro proveedores, la parte del código de negocio relacionada con las llamadas a modelos creció casi tres veces. Cada vez que se cambia un modelo, hay que reescribir la forma de llamada, la lógica de parseo y el manejo de errores. Peor aún, cada vez que un proveedor actualiza su SDK hay que volver a probarlo todo. Este artículo recoge de forma completa los problemas que encontramos y la solución de gateway que finalmente implementamos, con la esperanza de ayudar a equipos que también luchan entre múltiples modelos.
1. Autenticación: cuatro sistemas, cuatro formas de hacerlo
La autenticación es lo primero con lo que uno choca. La familia OpenAI usa Bearer Token; basta con poner Authorization: Bearer sk-xxx en la cabecera. Qwen requiere firma con AccessKey: cada petición debe calcular un HMAC con AK/SK, además de concatenar timestamp y cadena aleatoria. Doubao usa AK/SK más timestamp, pero su algoritmo de firma es distinto al de Qwen. DeepSeek, aunque es compatible con el formato OpenAI, tiene su propio base_url y mapeo de nombres de modelo, y su forma de inicialización no es del todo idéntica a la del SDK oficial.
El resultado es un if-else por todas partes. Una instancia de client por proveedor, una configuración por instancia. La gestión de claves es aún más dolorosa: las claves de los cuatro proveedores están en cuatro sitios distintos, y al rotarlas hay que cambiarlas en cuatro lugares; si se olvida uno, hay un incidente en producción.
Después unificamos en la capa de acceso: hacia fuera se expone una sola API Key y dentro se hace la traducción de protocolo. En concreto, la capa de acceso mantiene una tabla de enrutamiento por proveedor, y cada proveedor tiene su propio adaptador de autenticación. El lado de negocio solo usa una Key; la petición llega a la capa de acceso, que localiza al proveedor correspondiente según el nombre del modelo y usa el adaptador para completar la firma y el reenvío.
Más adelante probamos unificar el base_url en token8341: con una sola Key se pueden llamar GPT-4o, Claude, Gemini, DeepSeek, Qwen, ERNIE y Doubao, es compatible con el SDK de OpenAI y basta cambiar una línea de base_url para alternar. El trabajo sucio de la autenticación queda fuera de la capa de acceso y el código de negocio quedó bastante más limpio. La rotación de claves también pasó a ser una operación en un solo lugar, y el coste operativo bajó un orden de magnitud.
2. Fragmentación de streaming SSE: cuatro formatos, un solo renderizado
La fragmentación del streaming SSE es el segundo problema, y más oculto que la autenticación. En el chunk de GPT-4o, delta.content puede ser null, sobre todo en el primer y el último chunk; si el frontend renderiza sin comprobar nulos, aparece un undefined fugaz. DeepSeek incluye usage en el último chunk, y la estructura de su campo usage no es del todo igual a la de OpenAI. Qwen distingue tipos de evento con más detalle: hay add, finish, error y otros, y la estructura del payload de cada tipo es distinta. La marca de fin de Doubao es otra: usa un campo especial finish_reason para indicar el final del stream.
Con cuatro formatos en el frontend, la lógica de renderizado se rompe directamente. Nuestro primer enfoque fue adaptar en el frontend, escribimos cuatro funciones de parseo, y el resultado fue que cada nuevo modelo obligaba a tocar el frontend. Luego lo cambiamos a normalización en la capa de gateway: unificar a la estructura de chunk de OpenAI, filtrar los delta vacíos y extraer usage por separado para acumularlo. La regla concreta es: todas las respuestas de streaming de todos los proveedores se convierten al formato data: {"choices":[{"delta":{"content":"..."}}]}, el fin se marca de forma unificada con data: [DONE], y usage se devuelve en el último chunk en formato OpenAI.
El frontend solo reconoce un formato y no necesita saber a quién está conectado el backend. Este cambio redujo el código relacionado con modelos en el frontend de más de 400 líneas a unas 80, y al añadir modelos el frontend no requiere ningún cambio.
3. Códigos de error: errores escondidos en HTTP 200
El caos de los códigos de error superó lo esperado. Para el mismo límite de tasa, OpenAI devuelve 429 con rate_limit_exceeded, Qwen devuelve un error de negocio con campo code, y Doubao directamente mete el error en el body de un HTTP 200: el código de estado es 200 pero el body tiene un campo error. DeepSeek coincide con OpenAI la mayoría de las veces, pero ocasionalmente devuelve estructuras de error personalizadas.
Las alertas de monitorización no se pueden unificar en absoluto. No puedes escribir una regla que diga "si 429, alertar", porque algunos proveedores no devuelven 429 al limitar la tasa. Tampoco puedes mirar solo el código de estado HTTP, porque el 200 de Doubao puede ser un error.
En la capa de acceso creamos una tabla de mapeo que reduce los códigos de error de cada proveedor a un sistema interno único: límite de tasa, timeout, fallo de autenticación, moderación de contenido, servicio no disponible. La lógica concreta de mapeo es: primero mirar el código de estado HTTP, luego el error code del body, y decidir combinando ambos. Por ejemplo, si Doubao devuelve 200 pero el body tiene error, se mapea por el error code; si Qwen devuelve 400 con un code de negocio, se mapea por el code. Las reglas de alerta se escriben una sola vez, y al investigar se mira el código de error original.
Mantenemos unas 60 reglas en esta tabla de mapeo, que cubren los escenarios de error habituales de los cuatro proveedores. Tras el lanzamiento, la precisión de las alertas subió de alrededor del 60 % a más del 95 %, y las falsas alarmas prácticamente desaparecieron.
4. Estadísticas de uso: cuatro cifras que no cuadran
Los distintos criterios de las estadísticas de uso son lo más fácil de pasar por alto, pero saldrán a la luz seguro al conciliar con finanzas. El conteo de tokens de GPT-4o incluye el system prompt, DeepSeek factura por separado los tokens con acierto de caché, Qwen calcula entrada y salida por separado, y la unidad de facturación de Doubao es distinta. Al conciliar con finanzas las cuatro cifras no cuadran y es imposible calcular el coste real de cada modelo.
La solución de agregación es registrar en la capa de gateway el model, input_tokens, output_tokens y cache_hit de cada petición, y persistir todo bajo un criterio unificado de facturación por token. En concreto: el gateway registra la hora de inicio y fin al reenviar la petición, extrae el campo usage de cada proveedor de la respuesta y lo convierte a un formato estándar. Para los proveedores con unidades de facturación distintas, se hace una conversión en la capa de gateway y todo se reduce a coste por token.
Así, sea cual sea el proveedor subyacente, el coste se puede nivelar en una misma tabla. Más adelante construimos un panel de costes sobre esa tabla, desglosable por modelo, por línea de negocio y por día. Una vez detectamos que el coste de cierta línea de negocio había subido de repente un 40 %; al investigar, resultó que la estrategia de enrutamiento mandaba una gran cantidad de peticiones a GPT-4o, y tras ajustar el enrutamiento el coste bajó de inmediato. Sin una agregación unificada de uso, este tipo de problema es imposible de detectar.
5. La arquitectura de cuatro capas del gateway de modelos
¿Qué capas debe asumir el gateway de modelos? Mi división es en cuatro.
Primera capa: traducción de protocolo. Unificar los formatos de petición y respuesta de cada proveedor en una interfaz compatible con OpenAI. Esta es la única capa con la que el código de negocio trata directamente; se encarga de traducir la petición en formato OpenAI estándar al formato de cada proveedor y de traducir la respuesta de vuelta.
Segunda capa: enrutamiento. Elegir modelo según el tipo de tarea, por ejemplo texto largo en chino va a Qwen, código va a DeepSeek, respaldo va a GPT-4o. La estrategia de enrutamiento puede ser configurable y admite múltiples dimensiones: por tipo de tarea, por prioridad, por coste. También añadimos lógica de degradación: si el modelo principal da timeout o limita la tasa, se cambia automáticamente al modelo de respaldo.
Tercera capa: agregación de uso. Facturación y cuotas unificadas. El consumo de tokens, los aciertos de caché y el tiempo de respuesta de cada petición se registran en esta capa, que ofrece hacia fuera una interfaz unificada de consulta de uso.
Cuarta capa: observabilidad. Logs, trazabilidad de enlaces y convergencia de códigos de error. Cada petición tiene un trace_id y es rastreable de extremo a extremo desde la entrada hasta la salida. Los códigos de error se mapean de forma unificada en esta capa, y las reglas de alerta también se configuran solo aquí.
El código de negocio solo llama a la interfaz de la primera capa; las tres siguientes le son transparentes. La ventaja es que cambiar de modelo no requiere tocar el código de negocio, añadir un modelo tampoco, y ajustar la estrategia de enrutamiento tampoco. El equipo de negocio solo tiene que preocuparse de "quiero llamar a un modelo"; el resto lo hace el gateway.
6. Advertencias para evitar problemas
No importes directamente los SDK de cada proveedor en el código de negocio. En cuanto el proveedor actualice la interfaz o quieras cambiar de modelo, la superficie de cambio se dispara. Hemos visto equipos que llamaban directamente a los SDK en el código de negocio y, al cambiar de modelo, tuvieron que modificar más de 30 archivos y probar durante una semana antes de desplegar.
Dos días extra en la capa de acceso ahorran dos semanas después. Esta relación coste-beneficio la hemos verificado de forma real: tras el lanzamiento del gateway, añadir un modelo solo requiere agregar un adaptador en la capa de gateway, sin cambios en el código de negocio, y la integración y las pruebas se completan en medio día.
Dos sugerencias más: primero, hacer la agregación de uso cuanto antes, no esperes a la conciliación con finanzas para descubrir que no cuadra; segundo, mantener de forma continua la tabla de mapeo de códigos de error, y lo primero al integrar un nuevo proveedor es completar el mapeo de códigos de error.
Autor: Sun Haoran
Fecha de publicación: 9 de noviembre de 2026