7 pruebas de migración antes de cambiar una URL base de API de IA

Las pruebas de migración de la URL base de la API de IA deben realizarse antes de que cambien las variables de entorno, no después de que el tráfico de producción comience a fallar. Cambiar un solo baseURL o base_url puede mover la autenticación, la selección de modelos, el streaming, la llamada a herramientas, los registros de uso, el comportamiento de las cuotas y el control de reversión a una nueva ruta al mismo tiempo.

Flatkey está diseñado para equipos que desean una clave, una capa de enrutamiento compatible con OpenAI y una revisión más clara de la facturación y el uso entre proveedores de modelos. La página de inicio pública de Flatkey, consultada el 7 de julio de 2026, mostraba la ruta de ejemplo https://router.flatkey.ai/v1/chat/completions, mientras que las páginas actuales de modelos y precios exponían el contexto del modelo, el punto de conexión, el proveedor y la facturación para su revisión. Trate esas páginas como evidencia del día de la migración y, a continuación, ejecute sus propias pruebas de humo de la cuenta antes de mover el tráfico.

Utilice esta guía como una secuencia práctica de pruebas de migración de la URL base de la API de IA. El objetivo no es probar cada ruta de la aplicación. El objetivo es probar la ruta segura más pequeña a través de la nueva URL base y luego agregar características una capa a la vez.

Las 7 pruebas de migración de la URL base de la API de IA

Ejecute las pruebas en este orden. Cada una debe producir evidencia que pueda adjuntar a un ticket de implementación.

No se salte las primeras pruebas porque un contenedor de framework ya funcionó en el entorno de ensayo. La mayoría de las pruebas de migración de la URL base de la API de IA fallan porque el SDK lee silenciosamente una clave diferente, recibe la raíz de la URL base incorrecta o envía un modelo válido a la familia de puntos de conexión equivocada.

Prueba 1: Autenticación y composición de la URL base

Comience fuera de la aplicación. Necesita demostrar que la clave y la URL base pueden alcanzar la forma más simple del punto de conexión.

El error común con la URL base es pasar el punto de conexión completo al SDK. Para un SDK compatible con OpenAI, la URL base suele ser la raíz de la API, como https://router.flatkey.ai/v1, y el SDK añade /chat/completions, /responses u otro punto de conexión. Pasar https://router.flatkey.ai/v1/chat/completions como URL base puede crear una ruta duplicada.

Utilice primero una comprobación del entorno redactada:

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

Luego, haga una solicitud directa:

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Responde exactamente con: base url ok"}
    ]
  }'

Si esto devuelve 401, corrija la clave y el encabezado de autenticación antes de cambiar los modelos. Si devuelve 404, verifique el host, la raíz /v1 y si la ruta del punto de conexión se duplicó. Si devuelve 403, verifique la cuenta, el proyecto, el modelo, la región o la política de IP. La documentación de códigos de error de OpenAI trata 401 como autenticación, 429 como límite de velocidad o cuota, y 500 o 503 como condiciones del servidor o de sobrecarga; una puerta de enlace puede agregar más detalles, así que guarde el cuerpo de la respuesta.

Prueba 2: Catálogo de modelos y familia de puntos de conexión

Una URL base compatible con OpenAI no hace que todos los nombres de modelo sean portátiles. La API de OpenAI tiene un punto de conexión para listar modelos (List models), y sus puntos de conexión de finalización de chat (Chat Completions) y respuestas (Responses) utilizan formas de solicitud diferentes. Una puerta de enlace o una ruta compatible con el proveedor puede exponer un modelo para una familia de puntos de conexión pero no para otra.

Antes de cambiar la configuración de producción, cree un pequeño mapa de modelos:

La condición de aprobación no es "el nombre del modelo parece correcto". La condición de aprobación es que la consola de Flatkey actual, el directorio de modelos o el catálogo de proveedores muestre el alias exacto para la familia de endpoints exacta que planeas llamar. Vincula este trabajo a tu gobernanza de modelos más amplia con la guía de nombres de modelos compatibles con OpenAI.

Prueba 3: Finalización de chat simple

La tercera prueba de migración de la URL base de la API de IA es la solicitud de generación real más pequeña. Mantenla sin streaming. No incluyas herramientas, esquemas JSON, archivos, imágenes, reintentos ni middleware de la aplicación.

Guarda:

Si la solicitud simple falla, no depures el streaming todavía. Utiliza la guía de solución de problemas de API compatibles con OpenAI para aislar primero los problemas de clave, ruta, familia de endpoints y alias de modelo.

Prueba 4: Paridad de SDK

Después de que curl funcione, demuestra que el SDK construye la misma ruta. Los documentos oficiales actuales de OpenAI dirigen a los desarrolladores a los SDK oficiales para JavaScript y Python. El libro de recetas de OpenAI también muestra el uso de endpoints personalizados donde se crea un cliente con un token y una URL base personalizada. Para la migración, haz esto explícito en el código en lugar de depender de los valores sobrantes de OPENAI_API_KEY o OPENAI_BASE_URL.

Plantilla de Python:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Plantilla de Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

Registra la URL base resuelta al inicio del proceso, pero no registres la clave. Si curl tiene éxito y el SDK falla, inspecciona la precedencia de las variables de entorno, la versión del SDK, la unión de rutas, las cabeceras de organización/proyecto y el comportamiento del proxy antes de cambiar el modelo.

Prueba 5: Streaming o SSE

El streaming es donde muchas migraciones parecen saludables en la capa HTTP pero fallan en la aplicación. La referencia de Chat Completions de OpenAI devuelve un objeto JSON o fragmentos de finalización de chat transmitidos cuando el streaming está habilitado. La API de Respuestas también puede devolver text/event-stream, con nombres de eventos que difieren de los fragmentos de Chat Completions.

Ejecuta esto después de que la solicitud sin streaming funcione:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Condiciones de aprobación:

Para un análisis de flujo más profundo, compara con la prueba de streaming SSE compatible con OpenAI existente.

Prueba 6: Llamada a herramientas o funciones

La llamada a herramientas añade riesgo de esquema y capacidad. La guía de llamada a funciones de OpenAI describe un flujo de varios pasos: enviar herramientas, recibir una llamada a herramienta, ejecutar el código de la aplicación, devolver la salida de la herramienta y luego recibir la respuesta final del modelo. Una migración de URL base puede fallar en cualquiera de esos límites incluso cuando el texto simple funciona.

No comiences con toda tu superficie de herramientas de producción. Usa una función diminuta:

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "Usa la herramienta para el pedido A123."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Devuelve el estado de un pedido de prueba.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Si esto falla mientras el chat simple funciona, ya no estás depurando la URL base. Estás depurando la capacidad del modelo, la familia de puntos de conexión, la rigurosidad del esquema, tool_choice o el soporte de la puerta de enlace para la ruta seleccionada. La guía de compatibilidad de llamadas a herramientas publicada cubre una lista de verificación de proveedores más amplia.

Prueba 7: Uso, cuota y reversión

Las pruebas finales de migración de la URL base de la API de IA son operativas. Una respuesta generada no es suficiente si el departamento de finanzas no puede conciliarla, las cuotas no se comportan como se espera o la reversión requiere un cambio de código de emergencia.

Después de una prueba de humo exitosa, verifica:

Usa un archivo de reversión que sea lo suficientemente simple como para ejecutarlo bajo presión:

# activo
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# reversión
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

No confíes en la memoria para la reversión. Almacena la configuración anterior, el feature flag, el comando de implementación y el comando de verificación en el mismo ticket de implementación que las pruebas de migración de la URL base de la API de IA.

El paquete de evidencia que debes conservar

Para cada entorno, conserva un paquete que responda a estas preguntas:

Esta es la ventaja práctica de ejecutar pruebas de migración de la URL base de la API de IA antes del cambio. El artefacto es útil para la revisión de la implementación, la respuesta a incidentes, la conciliación del uso y la evidencia de adquisiciones.

Dónde encaja Flatkey

Flatkey puede reducir la dispersión de la migración al centralizar el acceso al modelo, el enrutamiento, la facturación, el análisis de uso y la revisión operativa detrás de una sola clave. Eso no elimina la necesidad de realizar pruebas. Le da al equipo un único punto de control donde ingeniería, finanzas y operaciones pueden inspeccionar la misma evidencia de la ruta.

Antes de migrar, revisa las páginas de modelos de Flatkey y precios en vivo, confirma la URL base actual de la consola y comienza con una pequeña prueba de ruta. Si todavía estás planeando el cambio más amplio, combina esta guía con la guía de migración de API compatibles con OpenAI. Cuando estés listo para ejecutar tus propias pruebas, obtén una clave y mantén la primera solicitud lo suficientemente pequeña como para inspeccionarla a mano.

Preguntas frecuentes

¿Qué son las pruebas de migración de la URL base de la API de IA?

Las pruebas de migración de la URL base de la API de IA son verificaciones previas al cambio que demuestran que la nueva raíz de la API funciona para la autenticación, el enrutamiento de modelos, el chat simple, el uso del SDK, el streaming, las herramientas, la lectura de uso, el comportamiento de la cuota y la reversión.

¿Debo probar primero con curl o con el SDK?

Prueba primero con curl. Curl demuestra que la clave, la URL, la ruta del punto de conexión y el alias del modelo funcionan sin el comportamiento del framework. Luego, prueba el SDK con los mismos valores.

¿Debería la URL base incluir /chat/completions?

Normalmente no. Proporciona al SDK la raíz de la API, como /v1, y luego deja que el SDK anexe el punto de conexión. Usa el punto de conexión completo solo para solicitudes directas con curl.

¿Por qué falla el streaming cuando el chat simple funciona?

El streaming puede fallar porque la ruta almacena en búfer las respuestas, el analizador del cliente espera una forma de evento incorrecta, el middleware consume el stream o la familia de puntos de conexión seleccionada no admite la forma de stream que estás utilizando.

¿Qué pasa si todavía no puedo ejecutar solicitudes de Flatkey en vivo?

Conserva los fragmentos de código como plantillas, valida la documentación pública y la configuración de la consola, y no muevas el tráfico de producción hasta que una clave real demuestre que las siete pruebas de migración de la URL base de la API de IA funcionan en tu propio entorno.

En resumen

Cambiar una URL base de API de IA es una migración de producción, no una simple edición de una cadena de texto. Ejecute las pruebas de migración de la URL base de la API de IA en orden: autenticación, catálogo de modelos, chat simple, paridad de SDK, streaming, herramientas y uso más reversión. Cuando las siete pruebas se superan, el cambio de la URL base se convierte en una transición controlada en lugar de una sesión de depuración tardía.