Migración de SDK multimodelo: Conserva los clientes de OpenAI para Claude, Gemini y DeepSeek

La migración de SDK multimodelo no debería comenzar reemplazando cada biblioteca de cliente en tu aplicación. Si tu código de producción ya utiliza el SDK de Python o Node de OpenAI para las finalizaciones de chat, el primer paso más seguro es mantener estable esa superficie de cliente, mover la elección del proveedor a la configuración y probar el comportamiento de Claude, Gemini y DeepSeek detrás de una ruta compatible antes de ampliar el tráfico.

Flatkey está diseñado para equipos que desean una sola clave, una capa de enrutamiento compatible con OpenAI, acceso a modelos de diferentes proveedores y revisión de uso y facturación en un solo lugar. Eso lo hace útil para una migración de SDK multimodelo, pero no elimina la necesidad de probar familias de puntos de conexión, alias de modelos, streaming, llamadas a herramientas y registros de uso. Trata cada muestra de código aquí como una plantilla hasta que la valides con tu propia clave de Flatkey y tu catálogo de modelos actual.

El objetivo práctico es simple: mantener el objeto de solicitud que tu aplicación ya conoce, aislar los pocos valores que deben cambiar y construir un paquete de prueba antes del cambio.

Matriz de decisión para la migración de SDK multimodelo

Usa esta matriz antes de cambiar el código. Separa lo que puede permanecer estable de lo que debe volverse configurable.

Esta es la disciplina central de la migración de SDK multimodelo: no mezcles el reemplazo de bibliotecas, la migración de prompts, la evaluación de proveedores, la validación de la facturación y el despliegue en producción en una sola implementación.

Lo que dicen los documentos oficiales sobre la compatibilidad

Los SDK de OpenAI ya admiten el patrón que necesitas. El README actual de OpenAI para Python documenta el cliente OpenAI y una opción base_url, y el README de Node documenta el cliente OpenAI estándar y las finalizaciones de chat. La referencia de la API de OpenAI dice que las finalizaciones de chat crean una respuesta de modelo para una conversación, admiten streaming y devuelven un objeto de finalización de chat o fragmentos de stream.

Si estás dividiendo el despliegue por entorno de ejecución, combina esta lista de verificación con la guía de URL base personalizada del SDK de Python de OpenAI y la guía de URL base del SDK de Node de OpenAI. Si la primera decisión es el enrutamiento de proveedores en lugar de la configuración del cliente, utiliza la guía de enrutamiento de API de Claude vs. GPT antes de elegir la carga de trabajo de prueba.

La compatibilidad de los proveedores difiere:

La lección importante es que "compatible con OpenAI" generalmente significa que el cliente puede enviar una solicitud con el formato de OpenAI. No significa que cada parámetro, esquema de herramienta, control de razonamiento, entrada de medios o campo de uso se comporte de manera idéntica entre los proveedores.

Paso 1: Congelar el límite del cliente

Comienza la migración del SDK multimodelo colocando el cliente de OpenAI detrás de una fábrica local. La fábrica debe ser el único lugar que conozca la clave, la URL base, el tiempo de espera y el alias del modelo.

import os
from openai import OpenAI


def make_llm_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
        timeout=float(os.getenv("LLM_TIMEOUT_SECONDS", "60")),
        max_retries=int(os.getenv("LLM_MAX_RETRIES", "2")),
    )


client = make_llm_client()

completion = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[
        {"role": "system", "content": "You answer with short implementation notes."},
        {"role": "user", "content": "Reply with exactly: migration probe ok"},
    ],
)

print(completion.choices[0].message.content)

Para Node:

import OpenAI from "openai";

export function makeLlmClient() {
  return new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
    timeout: Number(process.env.LLM_TIMEOUT_MS ?? 60000),
    maxRetries: Number(process.env.LLM_MAX_RETRIES ?? 2),
  });
}

const client = makeLlmClient();

const completion = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL,
  messages: [
    { role: "system", content: "You answer with short implementation notes." },
    { role: "user", content: "Reply with exactly: migration probe ok" },
  ],
});

console.log(completion.choices[0].message.content);

La aplicación debe llamar a make_llm_client() o makeLlmClient(), no construir clientes en diferentes controladores, trabajadores y scripts. Ese único límite es lo que permite que una migración de SDK multimodelo siga siendo reversible.

Paso 2: Construir un mapa de modelos y endpoints

No apuntes cada carga de trabajo a un solo nombre de modelo nuevo. Comienza con un mapa que nombre la carga de trabajo, la familia de endpoints, el proveedor actual, el proveedor objetivo y el valor de reversión.

La página de modelos de Flatkey es útil aquí porque expone los tipos de endpoints. Si un modelo aparece bajo una familia de endpoints nativa, no asumas que está disponible a través de la ruta de chat de OpenAI hasta que el catálogo de tu cuenta y las pruebas de humo lo demuestren.

Paso 3: Ejecutar la prueba de humo de cuatro proveedores

La prueba de humo mínima útil para la migración de un SDK multimodelo tiene cuatro filas de proveedores y el mismo prompt. Mantén el prompt simple para que el estilo de la respuesta no oculte fallos de transporte.

Guarda el cuerpo de la solicitud sin procesar, las cabeceras redactadas, el cuerpo de la respuesta, el estado HTTP, el alias del modelo, el ID de la solicitud si se devuelve y la entrada de uso del panel de control. Si algún proveedor necesita un parámetro diferente, mueve ese parámetro a un perfil de proveedor en lugar de esparcir ramas if provider == por toda tu aplicación.

Paso 4: Probar el streaming y las llamadas a herramientas por separado

Un completado simple solo prueba la ruta de menor riesgo. El streaming y las llamadas a herramientas son contratos separados.

Para el streaming, guarda:

Para las herramientas, prueba primero un esquema pequeño:

{
  "type": "function",
  "function": {
    "name": "lookup_order_status",
    "description": "Return a test order status.",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" }
      },
      "required": ["order_id"]
    }
  }
}

No utilices tu esquema de herramientas de producción más grande como primera prueba. La documentación de compatibilidad de Anthropic, por ejemplo, señala las limitaciones en torno a la compatibilidad con OpenAI y recomienda la API nativa de Claude para obtener el conjunto completo de características de Claude. Ese es exactamente el tipo de detalle que una lista de verificación para la migración de un SDK multimodelo debería detectar antes del despliegue.

Paso 5: Mantén perfiles de proveedor pequeños

Los perfiles de proveedor deben describir las diferencias, no contener la lógica de negocio.

{
  "support_chat": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_SUPPORT_CHAT_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": true,
    "tools": "basic",
    "fallback_alias": "support_chat_previous"
  },
  "analysis_fast": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_ANALYSIS_FAST_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": false,
    "tools": "none",
    "fallback_alias": "analysis_fast_previous"
  }
}

Mantén las características nativas del proveedor fuera de la ruta del cliente compartido de OpenAI a menos que tengas pruebas para cada proveedor de destino. Si se requieren citas de Claude, comportamiento de medios específico de Gemini, controles de pensamiento de DeepSeek o un punto de conexión por lotes nativo del proveedor, crea un adaptador nativo con nombre y conserva la ruta compatible con OpenAI para las cargas de trabajo que realmente se ajusten a ella.

Paso 6: Comprueba la facturación y la reversión

Una migración que devuelve texto pero pierde la evidencia de facturación no está completa. Antes de aumentar el tráfico, guarda:

Aquí es donde importa la revisión unificada de facturación y uso de Flatkey. El objetivo no es solo tener acceso a más modelos. El objetivo de una migración de SDK multimodelo es un acceso que los equipos de producto, operaciones y finanzas puedan inspeccionar después de que se mueva el tráfico.

Un flujo de trabajo de transición para la migración de SDK multimodelo

Utiliza este orden para la primera porción de producción:

1. Elige una carga de trabajo de bajo riesgo con un cliente de SDK de OpenAI existente.
2. Añade la fábrica de clientes y las variables de entorno sin cambiar el proveedor actual.
3. Prueba el modelo actual a través de la nueva fábrica.
4. Prueba un destino de Claude, Gemini o DeepSeek con una finalización simple.
5. Prueba el streaming y las herramientas solo si esa carga de trabajo los utiliza.
6. Verifica el uso, la facturación, el manejo de errores y la reversión.
7. Dirige un pequeño porcentaje del tráfico al nuevo alias del modelo.
8. Revisa los fallos por proveedor y familia de puntos de conexión antes de añadir la siguiente carga de trabajo.

Si la primera carga de trabajo necesita características nativas del proveedor, elige una carga de trabajo diferente para la primera migración de SDK multimodelo. La primera porción debe probar el patrón de migración, no todas las capacidades del modelo.

Preguntas frecuentes

¿Puedo usar un cliente de SDK de OpenAI para Claude, Gemini y DeepSeek?

A menudo puedes mantener un cliente de SDK de OpenAI para rutas compatibles con OpenAI, pero aún necesitas pruebas específicas del proveedor. Google y DeepSeek documentan el acceso compatible con OpenAI. Anthropic documenta una capa de compatibilidad con el SDK de OpenAI, pero dice que es principalmente para pruebas y comparación en lugar de ser la opción de producción a largo plazo para la mayoría de los casos de uso.

¿Debo migrar el tráfico de la API de respuestas de la misma manera?

Solo si la puerta de enlace de destino y el modelo de destino admiten explícitamente la familia de puntos de conexión que estás utilizando. Las finalizaciones de chat y las respuestas no son el mismo contrato. Comienza con la familia de puntos de conexión que tu aplicación ya utiliza y luego crea un plan de pruebas separado para las respuestas.

¿Cuál es el error más común en una migración de SDK multimodelo?

El error más común es tratar el cambio de la URL base como si fuera toda la migración. Una verdadera migración de SDK multimodelo también verifica los nombres de los modelos, las familias de puntos de conexión, el streaming, las herramientas, el uso, la cuota, el manejo de errores y la reversión.

¿Cuándo debo mantener un SDK de proveedor nativo?

Conserva un SDK de proveedor nativo cuando tu carga de trabajo dependa de características específicas del proveedor que la capa de compatibilidad no cubra. Las características nativas de Claude, las rutas de medios específicas de Gemini o los controles de razonamiento específicos de DeepSeek pueden justificar un adaptador separado.

Lista de verificación final

Antes de dar por completada la migración, confirma que tienes:

La migración de SDK multimodelo funciona mejor cuando es aburrida: una pequeña carga de trabajo, un límite de cliente, un mapa de modelos y evidencia para cada proveedor que agregues. Cuando estés listo para ejecutar esas pruebas a través de una ruta unificada, obtén una clave de Flatkey y comienza con una ruta de chat compatible con OpenAI de bajo riesgo.