Guía de migración de API: Cambio seguro de proveedores de LLM
Esta guía de migración de API explica cómo mover una aplicación que ya se comunica con un endpoint de chat estilo OpenAI a un proveedor diferente. La mayor parte del trabajo no son las dos líneas que cambias, sino encontrar qué dependía del proveedor antiguo por accidente.
Última actualización

Resumen
- Para un destino compatible con OpenAI, cambia la URL base, la clave y el ID del modelo, luego verifica el comportamiento.
- Haz un inventario de las funciones primero: los embeddings, imágenes y ajustes finos no se moverán a una API solo de texto.
- Lanza por porcentaje con una bandera para que la reversión tome un solo cambio de configuración.
- Estima la nueva factura a partir de tus propios conteos de tokens antes del cambio.
El plan en seis pasos
- Inventario de todas las características de API que tu aplicación llama.
- Mueve los ajustes del proveedor a la configuración.
- Mapea parámetros y nombres de modelos.
- Añade manejo de errores y límites de peticiones que coincida con los nuevos límites.
- Enruta una pequeña parte del tráfico al nuevo proveedor y compara.
- Revisa el costo, haz el cambio y mantén la ruta antigua por un tiempo.
El objetivo en los ejemplos es https://api.apimigration.com/v1 con ID de modelo uncensored. Los mismos pasos aplican a cualquier proveedor compatible con OpenAI, así que léelos como una lista de verificación en lugar de una receta de proveedor. Si algo falla en el camino, el artículo de solución de problemas sobre errores comunes de integración LLM cubre las causas habituales.
Paso 1: Inventario de lo que usa tu aplicación
Busca en tu código cada llamada al proveedor antiguo y enumera las características así como los endpoints. Una sola llamada de chat a menudo oculta varias dependencias: un prompt de sistema que depende de un estilo particular, un esquema de herramienta, un formato de respuesta JSON, un contexto grande.
| Característica en tu aplicación | En esta API |
|---|---|
Completaciones de chat, /v1/responses | Compatible |
| Streaming sobre SSE | Compatible, el uso se envía al final |
| Llamadas a funciones | Compatible, incluyendo streaming de tool_calls |
| Modo JSON | Compatible vía response_format |
| Contexto | 100.000 tokens, prompt más completado |
| Embeddings, imágenes, audio, ajuste fino | No disponible, mantén esto en otro proveedor |
Si el proveedor antiguo también manejaba embeddings o generación de imágenes, divide la migración: mueve solo las llamadas de texto y deja el resto donde están.
Paso 2: Colocar la configuración del proveedor en la configuración
Las URL codificadas en duro son lo que convierte una migración en un cambio de código. Lee la URL base, la clave y el modelo del entorno para que puedas cambiar sin un despliegue.
export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["LLM_BASE_URL"],
api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")
La autenticación es el encabezado estándar Authorization: Bearer, que el SDK configura por ti. Para confirmar la clave y ver qué ofrece el servidor, llama a GET /v1/models.
curl https://api.apimigration.com/v1/models \
-H "Authorization: Bearer $LLM_API_KEY"Paso 3: Mapea parámetros y prompts
Parámetros que pasan a través de esta API: temperature, top_p, stop, seed y las penalizaciones de frecuencia y presencia. max_tokens es opcional. Si tu código antiguo lo establece para proteger contra costos descontrolados, manténlo.
Tres cosas merecen una verificación deliberada.
- Campos específicos del proveedor. Cualquier cosa fuera del formato de solicitud de OpenAI puede ignorarse o rechazarse. Envía una solicitud con tu carga útil de producción exacta y lee la respuesta.
- Comportamiento del modelo. Un modelo diferente interpreta el mismo prompt de manera distinta. Los system prompts ajustados para el modelo antiguo a menudo requieren pequeñas ediciones. Pruébalos, no asumas.
- Rechazos. Si tus prompts antiguos incluían soluciones alternativas para evitar rechazos, generalmente puedes eliminarlos aquí, lo que acorta el prompt.
El modelo también difiere en lo que responderá. Este está ajustado para uso adulto legal sin rechazos de contenido, y el contenido sexual que involucra a menores está bloqueado.
Paso 4: Adapta el manejo de errores a los nuevos límites
Una clave completa permite 8 peticiones simultáneas y 300 por minuto. Una clave de prueba permite 2 y 60. Al superar el límite obtienes HTTP 429 con código de error rate_limited o concurrency. En sobrecarga temporal también obtienes un 429, con Retry-After: 5.
import time
from openai import RateLimitError
def chat(messages, retries=4):
for attempt in range(retries):
try:
return client.chat.completions.create(model=MODEL, messages=messages)
except RateLimitError:
time.sleep(5 * (attempt + 1))
raise RuntimeError("still rate limited after retries")
Las solicitudes en streaming mantienen su espacio de concurrencia hasta que termina el stream, por lo que un cliente atascado puede privar al resto. Cierra streams en un bloque finally. Si tu proveedor antiguo permitía más llamadas paralelas, añade un semáforo dimensionado al nuevo límite. Las solicitudes fallidas no se cobran, lo que hace que los reintentos sean seguros para tu presupuesto.
Paso 5: Lanzamiento por porcentaje
No cambies todo a la vez. Envía una pequeña parte estable de usuarios al nuevo proveedor y mantén el antiguo como respaldo. El hash del ID de usuario mantiene a cada usuario en un lado, para que las conversaciones no cambien de voz a mitad de camino.
import hashlib
def use_new(user_id: str, percent: int) -> bool:
bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
return bucket < percent
# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])
def pick(user_id):
return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client
Aumenta el porcentaje solo después de que la etapa anterior haya funcionado correctamente durante un día o así. La reversión es entonces una variable de entorno establecida de nuevo a 0.
Lo que suele sorprender a los equipos después del cambio
El cambio de la URL base funciona a la primera. Las sorpresas llegan después.
- Derivación de tono y formato. El mismo prompt produce una respuesta con palabras diferentes. Las funciones que analizan texto libre, como una expresión regular en los prefijos "Respuesta:", son las primeras en fallar. Prefiere el modo JSON o las llamadas a funciones para cualquier cosa que un programa deba leer.
- Diferencias en el conteo de tokens. Cada modelo tokeniza el texto de su propia manera. Tu estimación de costos basada en los conteos de tokens del proveedor antiguo será imprecisa, así que vuelve a medir usando el campo
usage. - Longitud de la salida. Sin
max_tokens, el completado puede usar el resto de la ventana de 100,000 tokens. Si tu configuración anterior tenía un límite predeterminado, establécelo a propósito. - Cambios en los tiempos de espera. Tu tiempo de espera del cliente estaba ajustado para el proveedor anterior. Las respuestas largas en uno nuevo pueden superarlo. Usa streaming donde puedas y aumenta el tiempo de espera para las llamadas sin streaming.
- Cambios en los rechazos silenciosos. Si tu producto solía capturar mensajes de rechazo y mostrar una alternativa, ese código puede dejar de ejecutarse. Decide si aún lo deseas.
Una lista de verificación breve antes del cambio
- Cada función de tu inventario tiene un equivalente probado o una brecha documentada.
- La URL base, la clave y el modelo provienen de la configuración en cada servicio que llama a la API.
- Los límites de tasa y los límites de concurrencia en tu código coinciden con los nuevos límites.
- Los streams se cierran al desconectar el cliente.
- Los registros incluyen el encabezado
X-Request-Id, para que puedas citar una petición al solicitar ayuda. - El saldo se monitorea a través de
X-Balance-USDoGET /v1/balance, con una alerta antes de que se agote. - El proveedor anterior sigue financiado y configurado para la reversión.
- Una persona designada es dueña de la decisión de revertir.
Ese último punto parece tonto hasta que ocurre un incidente a las 2 a. m. Alguien debe tener permiso para cambiar la bandera.
Paso 6: Comprueba el coste y luego haz el cambio
Calcula la nueva factura con tu propio tráfico. Los precios son $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida.
Ejemplo: 10.000 peticiones al día, cada una con 1.500 tokens de entrada y 400 tokens de salida.
- Entrada: 15.000.000 tokens x $0,15 / 1.000.000 = $2,25.
- Salida: 4.000.000 tokens x $0,50 / 1.000.000 = $2,00.
- Total: $4,25 por día.
Compara eso con la factura antigua, usando la página de precios actual del proveedor antiguo. La facturación aquí es crédito prepago sin suscripción, y el crédito no caduca. Las recargas van de $20 a $500 en cantidades enteras, con un bono del 5% desde $50, 10% desde $100 y 15% desde $200, pagados en cripto (USDT en TRC20 o USDC en Base). El saldo se muestra en el encabezado de respuesta X-Balance-USD, así que puedes configurar una alerta para él.
Las nuevas cuentas pueden reclamar $0,50 de crédito de prueba para las primeras pruebas. Consulta precios, luego obtén una clave de API y mantén la documentación abierta mientras mapeas los parámetros.
Más guías
Preguntas frecuentes
¿Puedo migrar cambiando solo la URL base?
Para una API compatible con OpenAI, la URL base, la clave y el ID del modelo son los cambios necesarios. Aún debes probar los prompts, ya que un modelo diferente responde de manera distinta.
¿Seguirán funcionando mis llamadas a funciones y el modo JSON?
Las llamadas a funciones y el modo JSON (response_format json_object) son compatibles. Valida tus esquemas con prompts reales antes del cambio.
¿Qué pasa si mi aplicación usa embeddings?
Esta API es solo de texto y no ofrece embeddings, generación de imágenes ni ajuste fino. Mantén esas llamadas en tu proveedor actual.
¿Cómo revertir rápidamente?
Enruta mediante una bandera de entorno como un porcentaje de lanzamiento gradual, y mantén el cliente antiguo configurado hasta que el nuevo enrutamiento haya funcionado limpiamente durante unos días.
Obtén tu clave de API
Regístrate, copia la clave, actualiza la URL base. La configuración está completa.