Ir al contenido principal
Español— Elegir un idioma
Menú

Migración desde sistemas heredados y buenas prácticas

Lección 14 de 14 Actualizado el 29 de julio de 2026 Avanzado
En esta página
  1. De chat/completions a responses
  2. Por qué abandonar el endpoint heredado
  3. Qué cambia entre los dos endpoints
  4. Ejecución de la migración
  5. Prácticas que sobreviven a las migraciones
  6. Puntos clave
  7. Pon a prueba tus conocimientos

De chat/completions a responses

Muchas integraciones de Grok en producción siguen dependiendo de /v1/chat/completions, a menudo sin una decisión explícita: el SDK de OpenAI ya estaba implementado, solo tuviste que cambiar la URL base y la clave para que todo funcionara. Esta lección te guía en la transición a /v1/responses, el endpoint principal, y amplía luego el alcance hacia prácticas que mantienen una integración sana a largo plazo, haya migración o no.

Por qué abandonar el endpoint heredado

/v1/chat/completions sigue manteniéndose y tus peticiones seguirán funcionando. El problema no es una interrupción del servicio, sino el estancamiento: el desarrollo futuro se centra exclusivamente en /v1/responses, las correcciones específicas para el endpoint heredado tienen menor prioridad y ciertas capacidades avanzadas —agentes, herramientas nativas— simplemente no están disponibles allí.

Así que no hay urgencia si tu aplicación funciona correctamente hoy. Sin embargo, existe una fecha límite implícita: cada funcionalidad que quieras adoptar en los próximos meses requerirá haber migrado. Es mejor abordar este trabajo con calma que cuando una necesidad del producto lo fuerce.

Qué cambia entre los dos endpoints

El endpoint heredado espera el formato clásico de messages que ya conoces:

# Heredado: /v1/chat/completions
payload = {
    "model": "grok-4.20-0309",
    "messages": [
        {"role": "system", "content": "Instrucciones..."},
        {"role": "user", "content": "Pregunta"}
    ]
}

/v1/responses adopta un formato enriquecido que soporta nativamente herramientas, agentes y flujos conversacionales complejos; la documentación de xAI proporciona los detalles. En la práctica, la principal consecuencia recae en el lado del cliente: si usas el SDK de OpenAI para hablar con la API de Grok, la migración podría implicar cambiar de SDK o pasarte al SDK nativo de xAI. Verifica este punto antes de estimar la carga de trabajo, porque a menudo desplaza el proyecto de «sustituir una URL» a «sustituir una dependencia».

Ejecución de la migración

Comienza con un inventario, y tómatelo en serio. Las llamadas HTTP directas son fáciles de encontrar, pero la API rara vez se invoca desde un único lugar: los SDK —OpenAI, xAI nativo— suelen coexistir en la misma base de código, servicios intermedios como proxies o pasarelas pueden reescribir peticiones, y scripts por lotes o tuberías de datos viven su vida lejos del código de la aplicación. Estos son los que olvidas, y son los que fallan tres semanas después de la migración.

Luego migra en pequeños fragmentos, empezando por las integraciones menos críticas. Una bandera de funcionalidad (feature flag) te permite cambiar una ruta de código a la vez y, lo que es más importante, revertir el cambio sin necesidad de un nuevo despliegue:

# Bandera de funcionalidad para migración progresiva
if feature_flags.get("use_responses_api"):
    response = call_responses_api(prompt)
else:
    response = call_chat_completions(prompt)

Esta bandera solo tiene sentido si el resto de tu código ignora qué endpoint respondió. De ahí la tercera pieza de la configuración: una función de normalización que devuelva ambos formatos de respuesta a una única estructura, de modo que la migración permanezca confinada a una sola capa.

def normalize_response(raw_response, endpoint):
    """Normaliza las respuestas independientemente del endpoint utilizado."""
    if endpoint == "responses":
        return {
            "content": raw_response["output"]["content"],
            "usage": raw_response["usage"]
        }
    else:  # chat/completions
        return {
            "content": raw_response["choices"][0]["message"]["content"],
            "usage": raw_response["usage"]
        }

Prácticas que sobreviven a las migraciones

Esta función de normalización ilustra un principio más amplio: aísla tu código tras una interfaz abstracta, incluso si solo usas un proveedor. Lo que cuesta caro durante un cambio de endpoint, versión o proveedor nunca es la llamada en sí, sino el número de lugares que dependen de ella.

class ClientLLM:
    def completer(self, messages, model=None):
        """Interfaz abstracta para llamadas a LLM."""
        raise NotImplementedError

class ClientGrok(ClientLLM):
    def completer(self, messages, model=None):
        model = model or GROK_MODEL
        # Implementación específica de Grok
        pass

A continuación, registra cada llamada de forma estructurada. Cinco puntos de metadatos bastan, y solo tienen valor juntos: el modelo utilizado y su versión, el número de tokens de entrada, salida y servidos desde caché, el coste de la petición, la latencia —TTFT y duración total— y, finalmente, el código de estado HTTP. Sin estos rastros, un incidente de calidad tras la migración se convierte en un debate de impresiones. Con ellos, comparas dos poblaciones de peticiones y decides en diez minutos.

Por último, construye un conjunto de pruebas de regresión para tus prompts críticos, para ejecutar antes de cualquier cambio de modelo o endpoint. Comprueba tres cosas distintas: que la respuesta respeta el formato esperado, JSON o Markdown según corresponda; que la información clave aparece realmente allí; y que tus barreras de seguridad (guardrails) siguen vigentes. Un modelo más rendidor que elude sutilmente tus instrucciones de seguridad es una regresión, incluso si sus respuestas parecen mejores.

En estado estable, cuatro señales merecen monitorización permanente: la tasa de error por endpoint y por modelo, la deriva de calidad medida por evaluación automática o humana, los avisos de obsolescencia publicados por xAI y tu consumo en relación con los límites de tu nivel actual. Los dos últimos son los únicos que te avisan antes del incidente en lugar de después.

Puntos clave

  • El endpoint /v1/chat/completions es heredado y ya no recibe nuevas funcionalidades
  • Migra progresivamente a /v1/responses utilizando banderas de funcionalidad
  • Crea una capa de abstracción para normalizar las respuestas entre los dos endpoints
  • Usa versiones fijadas en producción y alias en desarrollo
  • Mantén pruebas de regresión de prompts y monitorización continua
  • Centraliza la configuración del modelo para facilitar futuras migraciones

Pon a prueba tus conocimientos

Niveles, tokens, caché, ciclo de vida: operación de Grok en producción.

1. ¿Cómo evolucionan los límites de tasa de la cuenta?

Respuesta: Mediante niveles automáticos: el consumo impulsa al alza las RPM/TPM por modelo —y Enterprise negocia más allá—; algunos saltos de nivel son irreversibles.

2. ¿Cuáles son los cuatro tipos de tokens facturables?

Respuesta: Tokens de entrada, salida, razonamiento y caché (leídos de caché); los campos de coste de la respuesta los detallan, el endpoint tokenize ayuda a preverlos.

3. ¿Cómo funciona la caché automática de la API?

Respuesta: Los prefijos repetidos se sirven desde la caché a una tarifa reducida: mantener los prompts estables al inicio de la petición maximiza la tasa de aciertos de caché, una palanca de costes mayor.

4. ¿Qué necesitas saber sobre los ciclos de vida de los modelos?

Respuesta: Los alias (latest) siguen las actualizaciones, las versiones fijadas garantizan la reproducibilidad; eliges uno u otro según el caso de uso y rastreas las obsolescencias.

5. ¿Cómo gestionar una migración desde un modelo heredado?

Respuesta: Inventario de uso, cambio al rango actual volviendo a probar los prompts críticos, y luego monitorización de costes y calidad tras el cambio; la migración es un proyecto, no un sed.

Con los límites comprendidos, los tokens contados, la caché explotada y las versiones gestionadas: unas operaciones serenas descansan sobre estas cuatro disciplinas.