¿Qué es una API compatible con OpenAI? Cómo cambiar entre proveedores de LLM

Una API compatible con OpenAI sigue el formato de solicitud y respuesta de OpenAI lo suficiente como para que un cliente de OpenAI existente pueda comunicarse con otro proveedor de LLM. En muchas aplicaciones, cambiar de proveedor comienza con tres cambios de configuración: la URL base, la API Key y el ID del modelo.

Estos cambios conectan la aplicación al nuevo servicio. No garantizan que cada endpoint, parámetro o capacidad del modelo se comporte de forma idéntica. Una migración fiable también pone a prueba el streaming, las llamadas a herramientas, la salida estructurada, los límites de token, los errores, la latencia, el coste y la calidad de las tareas.

¿Qué significa una API compatible con OpenAI?

Una API compatible con OpenAI suele aceptar solicitudes con una estructura similar a esta:

{
  "model": "provider/model-name",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector search in two sentences."
    }
  ],
  "stream": false
}

{
  "model": "provider/model-name",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector search in two sentences."
    }
  ],
  "stream": false
}

{
  "model": "provider/model-name",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector search in two sentences."
    }
  ],
  "stream": false
}

La respuesta puede contener campos familiares como id, model, choices, message, finish_reason y usage. Por lo tanto, los desarrolladores pueden seguir utilizando el SDK de Python o JavaScript de OpenAI mientras dirigen las solicitudes a otro host de API.

La compatibilidad con OpenAI es una convención práctica, no una certificación formal. Cada proveedor decide qué endpoints, campos y funciones admite. Evalúe la compatibilidad en cuatro niveles:

Una API puede coincidir con el formato de solicitud esperado y al mismo tiempo producir un comportamiento de modelo diferente.

¿Qué partes de la API de OpenAI suelen ser compatibles?

El endpoint con soporte más generalizado es:

Los elementos habitualmente compatibles incluyen:

• Autenticación mediante Bearer token

• Identificadores de model

• Mensajes de system, user y assistant

• Respuestas sin streaming

• Server-Sent Events para streaming

• Parámetros como temperature, top_p y stop

• Límites de token de Output

• Campos de uso de token

• Definiciones de herramientas

• response_format para Output JSON

Algunos proveedores también implementan GET /v1/models. En SiliconFlow, el endpoint de lista de modelos devuelve los ID de modelo disponibles y permite filtrar por tipo de modelo o tarea.

La compatibilidad con Chat Completions no implica la compatibilidad con todas las demás interfaces de OpenAI. Una aplicación que utilice la API Responses, sesiones en tiempo real, gestión de archivos, procesamiento por lotes, fine-tuning, generación de Image o endpoints de Audio debe verificar cada endpoint requerido por separado.

Cómo funcionan las URL base, las API Keys y los ID de modelo

Estos tres ajustes determinan adónde va la solicitud, cómo se autentica y qué despliegue la procesa.

Para la API internacional de SiliconFlow, la URL base es:

Cada proveedor emite sus propias API Keys. Por lo general, una clave creada para un proveedor no puede autenticar una solicitud directa a otro.

Los ID de modelo también son específicos de cada proveedor. Incluso cuando dos servicios alojan modelos de la misma familia, sus ID, versiones, límites de contexto, parámetros admitidos o configuraciones de despliegue pueden diferir. Un ID de modelo actual de SiliconFlow, por ejemplo, es:

Obtenga el ID del modelo del catálogo actual del proveedor en lugar de crearlo a partir de un nombre visible.

Por qué los desarrolladores utilizan API compatibles con OpenAI

La principal ventaja es la reducción del trabajo de integración. Los equipos pueden mantener los métodos familiares del SDK y las estructuras de la aplicación mientras evalúan diferentes modelos alojados.

Esto puede ayudar a los desarrolladores a:

• Comparar modelos con los mismos prompts y casos de prueba

• Reutilizar interfaces de Chat y herramientas de desarrollo existentes

• Evaluar diferentes perfiles de coste, latencia y calidad

• Acceder a despliegues gestionados de modelos abiertos

• Separar los ajustes de los proveedores de la lógica de la aplicación

• Preparar rutas alternativas para fallos temporales del servicio

En SiliconFlow, una única superficie de API proporciona acceso a múltiples familias de modelos. Los equipos pueden comparar opciones generales de Chat, programación, razonamiento y Multimodal sin tener que crear un nuevo cliente para cada desarrollador de modelos.

La interfaz reduce el trabajo de conexión. La selección del modelo aún requiere pruebas en las tareas reales de la aplicación.

Cómo alternar una aplicación entre proveedores de LLM

Mantenga los valores específicos del proveedor fuera del código de la aplicación:

Tras instalar el SDK de Python de OpenAI actual, configure el cliente a partir de esas variables de entorno:

pip install --upgrade

pip install --upgrade

pip install --upgrade

import os

from openai import APIConnectionError, APIStatusError, OpenAI


base_url = os.getenv("LLM_BASE_URL")
api_key = os.getenv("LLM_API_KEY")
model = os.getenv("LLM_MODEL")

if not all([base_url, api_key, model]):
    raise RuntimeError(
        "LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL must be configured."
    )

client = OpenAI(
    base_url=base_url,
    api_key=api_key,
    timeout=60.0,
    max_retries=2,
)

try:
    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "system",
                "content": "Answer clearly and keep the response under 100 words.",
            },
            {
                "role": "user",
                "content": "What is semantic search?",
            },
        ],
        stream=False,
    )

    print(response.choices[0].message.content or "")

except APIStatusError as exc:
    raise RuntimeError(
        f"Provider returned HTTP {exc.status_code}. "
        f"Request ID: {exc.request_id}"
    ) from exc

except APIConnectionError as exc:
    raise RuntimeError("Could not connect to the LLM provider.") from exc

import os

from openai import APIConnectionError, APIStatusError, OpenAI


base_url = os.getenv("LLM_BASE_URL")
api_key = os.getenv("LLM_API_KEY")
model = os.getenv("LLM_MODEL")

if not all([base_url, api_key, model]):
    raise RuntimeError(
        "LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL must be configured."
    )

client = OpenAI(
    base_url=base_url,
    api_key=api_key,
    timeout=60.0,
    max_retries=2,
)

try:
    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "system",
                "content": "Answer clearly and keep the response under 100 words.",
            },
            {
                "role": "user",
                "content": "What is semantic search?",
            },
        ],
        stream=False,
    )

    print(response.choices[0].message.content or "")

except APIStatusError as exc:
    raise RuntimeError(
        f"Provider returned HTTP {exc.status_code}. "
        f"Request ID: {exc.request_id}"
    ) from exc

except APIConnectionError as exc:
    raise RuntimeError("Could not connect to the LLM provider.") from exc

import os

from openai import APIConnectionError, APIStatusError, OpenAI


base_url = os.getenv("LLM_BASE_URL")
api_key = os.getenv("LLM_API_KEY")
model = os.getenv("LLM_MODEL")

if not all([base_url, api_key, model]):
    raise RuntimeError(
        "LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL must be configured."
    )

client = OpenAI(
    base_url=base_url,
    api_key=api_key,
    timeout=60.0,
    max_retries=2,
)

try:
    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "system",
                "content": "Answer clearly and keep the response under 100 words.",
            },
            {
                "role": "user",
                "content": "What is semantic search?",
            },
        ],
        stream=False,
    )

    print(response.choices[0].message.content or "")

except APIStatusError as exc:
    raise RuntimeError(
        f"Provider returned HTTP {exc.status_code}. "
        f"Request ID: {exc.request_id}"
    ) from exc

except APIConnectionError as exc:
    raise RuntimeError("Could not connect to the LLM provider.") from exc

La configuración compatible con OpenAI de SiliconFlow utiliza el mismo cliente con la URL base de SiliconFlow. El tiempo de espera de 60 segundos de este ejemplo es un punto de partida. Ajústelo en función del modelo seleccionado, la longitud esperada de la salida y el objetivo de latencia.

Cambiar las tres variables de entorno modifica el destino, las credenciales y el modelo. Antes de enviar tráfico de producción, pruebe las siguientes capacidades:

Para una migración a producción, compare ambos proveedores en un conjunto fijo de tareas reales. Defina umbrales de aprobación para la validez del formato, la calidad de la respuesta, el éxito de las herramientas, la latencia y el coste por tarea exitosa. Envíe primero un pequeño porcentaje del tráfico apto al nuevo proveedor, supervise los resultados y mantenga disponible la configuración anterior para poder revertir los cambios.

Lo que no garantiza ser compatible con OpenAI

Los modelos compatibles con OpenAI pueden aceptar la misma estructura de solicitud sin ser operativamente intercambiables. La compatibilidad no garantiza:

• Soporte para cada endpoint de OpenAI

• Límites de contexto y de Output idénticos

• Tokenización o recuento de token idénticos

• Comportamiento equivalente en herramientas, streaming o roles de mensaje

• El mismo comportamiento de seguridad, límites de frecuencia, latencia o precios

• Resultados similares de modelos relacionados o con nombres similares

También pueden aparecer campos de respuesta específicos del proveedor. Por ejemplo, los modelos de razonamiento de SiliconFlow pueden devolver reasoning_content junto con el contenido final. Las aplicaciones deben tolerar los campos desconocidos y gestionar explícitamente cualquier campo adicional que necesiten.

Mantenga los parámetros específicos del proveedor bajo comprobaciones de capacidad. No envíe controles de razonamiento, campos de Multimodal, opciones de Input en caché u otras extensiones a todos los proveedores de forma predeterminada.

Llamadas a herramientas, JSON Mode y compatibilidad de funciones

Las funciones avanzadas deben verificarse para el modelo seleccionado, no solo para el proveedor.

Llamadas a herramientas

Las llamadas a herramientas permiten que un modelo devuelva el nombre de una función y sus argumentos. La aplicación sigue siendo responsable de validar dichos argumentos, ejecutar la función y devolver el resultado.

En SiliconFlow, las solicitudes de herramientas al estilo de OpenAI están disponibles para los despliegues compatibles, pero los requisitos a nivel de modelo pueden variar. Compruebe la compatibilidad actual de llamadas a funciones y ejecute una prueba real de llamadas a herramientas antes del lanzamiento.

Las aplicaciones en producción deben:

• Validar los argumentos contra un esquema

• Rechazar nombres de función desconocidos

• Aplicar permisos fuera del modelo

• Añadir tiempos de espera a las herramientas externas

• Requerir aprobación para acciones sensibles

• Gestionar respuestas que no contengan una llamada a herramienta

No ejecute argumentos generados por el modelo con eval() o mecanismos similares.

JSON Mode

El JSON Mode suele utilizar:

response_format={"type": "json_object"}

response_format={"type": "json_object"}

response_format={"type": "json_object"}

Esto mejora la capacidad de análisis sintáctico, pero no demuestra que la salida coincida con el esquema requerido por la aplicación. Es posible que falten campos, que los valores utilicen un tipo incorrecto y que la salida esté incompleta si la generación alcanza su límite de token.

Las instrucciones de JSON Mode de SiliconFlow detallan la compatibilidad actual y advierten de que las aplicaciones deben gestionar objetos JSON incompletos. Analice la respuesta de forma segura, valídela con un esquema local y defina una ruta de reparación o reintento para los resultados no válidos.

Problemas habituales de migración a comprobar

Utilice el estado HTTP y el mensaje de respuesta para separar los errores de configuración de los fallos temporales del servicio.

La referencia de gestión de errores de SiliconFlow distingue los fallos de parámetros, autenticación, permisos, límites de frecuencia y carga del servidor. Registre el proveedor, el modelo, el estado HTTP y el ID de la solicitud sin guardar API Keys ni entradas confidenciales sin censurar.

Cuándo tiene sentido una API de LLM unificada

Un cliente configurable compatible con OpenAI suele ser suficiente cuando una aplicación utiliza un solo proveedor a la vez. Una pasarela unificada o un adaptador interno resulta útil cuando operan varios proveedores de forma simultánea.

Considere una capa unificada cuando necesite:

• Enrutamiento de modelos basado en tareas

• Conmutación por error automática para fallos reintentables

• Gestión centralizada de credenciales

• Políticas compartidas de tiempos de espera y reintentos

• Informes de costes entre proveedores

• Presupuestos o límites de frecuencia por equipo

• Alias internos estables para los modelos

• Lanzamientos y reversiones controlados de modelos

• Enrutamiento basado en capacidades para herramientas, Vision o JSON

Esta capa también genera trabajo adicional. Debe normalizar los errores y los datos de uso, mantener registros de capacidades y preservar el acceso a funciones útiles específicas de cada proveedor.

Utilice la configuración junto con pruebas de regresión para cambios ocasionales de proveedor. Añada una pasarela cuando el enrutamiento, la gobernanza, la observabilidad o la conmutación por error sean un requisito de producción continuo. Una API compatible con OpenAI facilita la migración, mientras que la portabilidad fiable proviene de comprobaciones de capacidad explícitas y de la evaluación al nivel de cada tarea.

Preguntas frecuentes

¿Está una API compatible con OpenAI afiliada a OpenAI?

No. El término describe un patrón de interfaz y no establece una afiliación comercial o técnica con OpenAI. El proveedor compatible opera su propia infraestructura, catálogo de modelos, cuentas, credenciales, facturación, límites y términos.

¿Es gratis usar una API de LLM compatible con OpenAI?

No necesariamente. La compatibilidad describe el formato de solicitud y respuesta, no los precios. Un proveedor puede ofrecer saldo de prueba, modelos seleccionados sin coste, facturación basada en el uso, suscripciones o contratos empresariales. Compruebe el precio actual del modelo alojado exacto antes de su despliegue.

¿Puede una aplicación continuar la misma conversación después de cambiar de proveedor?

Por lo general, sí, si la aplicación envía el historial de conversación con cada solicitud. Confirme que el nuevo modelo admite los roles de mensaje, los tipos de contenido y el tamaño total de contexto. Es posible que las respuestas sigan variando, ya que diferentes modelos interpretan el mismo historial de forma distinta.

¿Debería producirse una conmutación por error de proveedor tras cada error de API?

No. La conmutación por error es más adecuada para problemas reintentables, como límites de frecuencia, tiempos de espera agotados o sobrecargas temporales del servicio. Los errores de autenticación, permisos, solicitudes no válidas y modelos desconocidos normalmente requieren una corrección de configuración en lugar de una llamada a otro proveedor.