Integrar la API desde servidor y centralizar la configuración

La aplicación debe controlar credenciales, permisos, política de almacenamiento, errores, límites y selección de modelos. Por eso la integración principal con un proveedor LLM debe vivir en una frontera server-side, no dispersa por componentes de interfaz.

El navegador llama a tu backend. Tu backend decide qué proveedor, modelo, herramientas, instrucciones y política aplicar.

Crea un adaptador de proveedor

Define una interfaz interna orientada a capacidades del producto:

• generateText();
• extractStructured();
• classify();
• runWithTools();
• createEmbedding() si el caso lo necesita.

No necesitas exactamente estos nombres. La idea es que el dominio no dependa de los objetos completos del SDK.

El adaptador traduce:

dominio → petición del proveedor → respuesta del proveedor → resultado normalizado

El resultado normalizado puede incluir:

• estado;
• contenido;
• estructura parseada;
• usage;
• modelo real;
• identificador de la petición;
• tool calls;
• motivo de rechazo o error;
• metadatos mínimos para trazabilidad.

Usa la API actual sin convertirla en dependencia transversal

En OpenAI, la Responses API es actualmente la interfaz recomendada para generación, razonamiento, tool calling y flujos multi-turn. Las definiciones de herramientas y Structured Outputs tienen contratos específicos que pueden evolucionar.

Ese detalle debe quedar dentro del adaptador. Si mañana cambias a otra API o proveedor, el dominio sigue hablando de clasificar_solicitud, no de objetos específicos de Responses.

Centraliza configuración

Mantén en un punto controlado:

• proveedor;
• modelo por tarea;
• timeout;
• límites de entrada y salida;
• herramientas disponibles;
• versión de instrucciones;
• políticas de almacenamiento;
• región cuando exista;
• reintentos;
• feature flags;
• presupuesto;
• streaming;
• modo síncrono o asíncrono.

Evita nombres de modelo repartidos en decenas de archivos. Una política central permite cambiar, comparar y revertir con menos riesgo.

Protege secretos y credenciales

Las API keys deben permanecer en servidor. Utiliza variables de entorno o un gestor de secretos y separa credenciales por entorno.

No:

• las envíes al navegador;
• las incluyas en commits;
• las imprimas en logs;
• las devuelvas en errores;
• las insertes en prompts.

Aplica permisos mínimos y límites de gasto o uso cuando el proveedor los soporte.

Normaliza errores

El proveedor puede devolver autenticación inválida, rate limit, input no aceptado, timeout, fallo interno o rechazo de contenido.

Traduce esos estados a errores de dominio estables, por ejemplo:

PROVIDER_AUTH_ERROR
PROVIDER_RATE_LIMITED
PROVIDER_TIMEOUT
MODEL_OUTPUT_INVALID
MODEL_REFUSAL
TOOL_EXECUTION_DENIED

No expongas al cliente mensajes internos del proveedor sin necesidad. Conserva el request ID de forma segura para soporte y correlación.

Decide política de almacenamiento y estado

Una API puede ofrecer opciones de almacenamiento, estado multi-turn o background execution. No asumas que el comportamiento por defecto coincide con tu política de privacidad.

Define explícitamente:

• qué envías;
• qué se conserva en tu sistema;
• qué estado remoto utilizas;
• cuándo se elimina;
• qué información no debe salir de tu infraestructura.

Las decisiones de retención son parte de la arquitectura, no una propiedad accidental del SDK.

No uses llamadas reales en tests normales

Crea un adaptador falso capaz de reproducir:

• respuesta correcta;
• salida inválida;
• rate limit;
• timeout;
• tool call;
• rechazo;
• respuesta tardía.

Los tests de aplicación deben ser rápidos y reproducibles. Las pruebas live se ejecutan de forma explícita contra un entorno controlado porque consumen cuota, dependen de red y pueden cambiar con el servicio.

Diseña una política de modelos por capacidad

No asumas un único modelo para todo.

Puedes definir tareas:

• extracción;
• clasificación;
• generación;
• razonamiento;
• tool use.

Para cada una registra requisitos y modelo aprobado.

No codifiques «modelo premium» como sinónimo de calidad. Ejecuta evals.

Versiona instrucciones

El prompt de sistema es parte del software.

Conserva:

• ID;
• versión;
• hash;
• fecha;
• cambios.

Una regresión puede venir de instrucciones y no del modelo.

Decide streaming por contrato

Si usas streaming, el adaptador debe normalizar eventos sin filtrar detalles del proveedor.

El cliente puede necesitar:

• started;
• delta;
• tool_pending;
• completed;
• failed.

Así mantienes una API propia.

Maneja compatibilidad

Los proveedores evolucionan. Una opción puede quedar deprecada o cambiar de ubicación.

El adaptador debe:

• validar configuración;
• fallar de forma clara;
• facilitar migración;
• mantener tests live opt-in.

Añade circuit breaker

Si el proveedor falla de forma sostenida, continuar enviando requests puede empeorar el problema.

Un circuit breaker puede:

• abrir tras cierto patrón;
• devolver fallo rápido;
• probar recuperación después.

No siempre es necesario, pero es útil en servicios críticos.

Prepara fallback con cuidado

Cambiar automáticamente de modelo o proveedor puede cambiar:

• calidad;
• formato;
• tools;
• retención;
• coste.

El fallback debe estar evaluado y documentado, no improvisado.

Observa usage

Centralizar el adaptador permite registrar:

• modelo;
• tokens;
• latencia;
• retries;
• coste estimado;
• status.

Sin esta capa, el consumo queda disperso y difícil de controlar.

Ejercicio

Implementa o diseña:

1. interfaz del adaptador;
2. configuración central;
3. carga de secretos;
4. normalización de errores;
5. respuesta normalizada;
6. proveedor falso;
7. cinco tests;
8. un comando live opt-in;
9. política de logs;
10. mecanismo de rollback de modelo.

La integración está bien encapsulada si puedes cambiar el proveedor falso por el real sin tocar la lógica de negocio.

Antes de continuar

Antes de avanzar, comprueba que cuentas con una frontera server-side controlada. La aplicación conoce su propio contrato; el proveedor queda encapsulado detrás de un adaptador que centraliza configuración, errores, secretos y observabilidad.