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

Seguimiento, estado y cancelación

Lección 11 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Gestión del ciclo de vida del lote
  2. Dos niveles de estado
  3. Consulta de contadores
  4. Listado de lotes
  5. Recuperación de resultados
  6. Consulta de metadatos de la solicitud
  7. Cancelación de un lote
  8. Estrategia de sondeo (polling)
  9. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %), los ejemplos siguen la API REST y el xai-sdk oficial (client.batch.*; la API de lotes de xAI no coincide con el formato de OpenAI, por lo que el SDK de OpenAI no aplica), y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: Batch API · REST Reference · Batch Pricing.

Gestión del ciclo de vida del lote

Una vez enviadas las solicitudes, debes hacer un seguimiento del progreso del procesamiento, consultar los estados y saber cuándo y cómo cancelar un lote. Esta lección cubre todas las operaciones de gestión disponibles.

Dos niveles de estado

xAI realiza el seguimiento del progreso en dos niveles. El lote en sí no tiene un estado global como «completado» o «fallido»: contiene contadores en su objeto state. Cada solicitud, sin embargo, tiene su propio estado:

Estado de la solicitudSignificadoAcción
pendingEn colaEsperar
succeededProcesada, resultado disponibleRecuperar resultado
failedError durante el procesamientoLeer mensaje, reintentar si procede
cancelledCancelada, por ejemplo con su loteReenviar si es necesario

El lote se procesa por completo cuando su contador num_pending baja a cero. También puede cancelarse o caducar: tras el expire_time, sus resultados dejan de ser accesibles.

Consulta de contadores

La llamada GET /v1/batches/{batch_id} devuelve el lote y sus contadores:

curl "https://api.x.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"

La respuesta incluye:

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "analyse_avis_clients",
  "state": {
    "num_requests": 500,
    "num_pending": 155,
    "num_success": 342,
    "num_error": 3,
    "num_cancelled": 0
  }
}

Estos contadores rastrean el progreso en tiempo real, sin esperar a que finalice el procesamiento. Con el SDK, léelos en client.batch.get(batch_id=...).state.

Listado de lotes

Para encontrar un lote o consultar el historial:

curl "https://api.x.ai/v1/batches?limit=20" \
  -H "Authorization: Bearer $XAI_API_KEY"

La lista se pagina mediante limit y pagination_token. Los lotes permanecen ahí hasta su caducidad. Con el SDK, client.batch.list(limit=20) devuelve una lista batches donde cada elemento contiene su name, batch_id y state. La consola de xAI ofrece la misma vista, pero en formato visual.

Recuperación de resultados

Puedes recuperar los resultados en cualquier momento, incluso durante el procesamiento:

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Cada resultado incluye el batch_request_id de su solicitud. Las solicitudes fallidas aparecen aquí con su mensaje; con el SDK, las propiedades succeeded y failed de cada página las separan.

Consulta de metadatos de la solicitud

Para rastrear el estado de cada solicitud:

curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
  -H "Authorization: Bearer $XAI_API_KEY"

Cada entrada proporciona el identificador de la solicitud, su punto final, modelo, estado, y fechas de creación y finalización. Esta es la herramienta de diagnóstico cuando un contador se estanca, o para verificar qué se añadió correctamente.

Cancelación de un lote

Si necesitas detener un procesamiento en curso:

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
  -H "Authorization: Bearer $XAI_API_KEY"

La cancelación es definitiva: las solicitudes pendientes no se procesarán y ya no podrás añadir solicitudes al lote. Las solicitudes ya procesadas, sin embargo, siguen disponibles en los resultados. Cancela si:

  • Detectas un error en tus solicitudes tras el envío
  • El lote ya no es necesario (cambio de prioridad)
  • Quieres reenviar un lote corregido

Con el SDK: client.batch.cancel(batch_id=...), que devuelve el lote y sus contadores en el momento de la cancelación.

Estrategia de sondeo (polling)

En producción, espera a la finalización con un sondeo espaciado y un retraso máximo:

import time


def esperar_lote(client, batch_id, intervalo=300, retraso_max=2 * 86400):
    """Espera hasta que se procesen todas las solicitudes del lote."""
    inicio = time.monotonic()
    while time.monotonic() - inicio < retraso_max:
        lote = client.batch.get(batch_id=batch_id)
        estado = lote.state
        if lote.cancel_by_xai_message:
            raise RuntimeError(f"Cancelado por xAI: {lote.cancel_by_xai_message}")
        if estado.num_requests > 0 and estado.num_pending == 0:
            return lote
        print(f"{estado.num_success} correctas, {estado.num_error} fallidas, "
              f"{estado.num_pending} pendientes de {estado.num_requests}")
        time.sleep(intervalo)
    raise TimeoutError(f"Lote no finalizado tras {retraso_max} s")

Un intervalo de unos pocos minutos es adecuado para lotes grandes; la documentación de xAI sondea cada pocos segundos en sus ejemplos, que cubren lotes pequeños. Y dado que los resultados están disponibles a medida que llegan, nada impide recuperarlos durante la espera.

Puntos clave

  • Lee el lote por sus contadores (num_pending, num_success, num_error…); cada solicitud tiene su estado: pending, succeeded, failed, cancelled
  • GET /v1/batches/{id} ofrece el progreso, /results los resultados, /requests el detalle de la solicitud
  • La cancelación (POST /v1/batches/{id}:cancel) es irreversible, pero conserva los resultados ya producidos
  • Las listas y resultados se pagan con limit y pagination_token
  • Realiza sondeos a intervalos de unos pocos minutos, con un retraso máximo, y recupera los datos antes de expire_time