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

Flujo de trabajo en cuatro pasos

Lección 2 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. El ciclo de vida de un lote
  2. Paso 1: Crear un lote
  3. Paso 2: Añadir solicitudes
  4. Paso 3: Supervisar el progreso
  5. Paso 4: Recuperar resultados
  6. El flujo de trabajo en la práctica
  7. Gestión de errores en el flujo de trabajo
  8. 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 utilizan la API REST y el xai-sdk oficial (client.batch.*; la API de lotes de xAI no sigue el formato de OpenAI, por lo que el SDK de OpenAI no es aplicable); y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: Batch API · Referencia REST · Precios de lotes.

El ciclo de vida de un lote

Todo lote sigue el mismo ciclo: crear, añadir solicitudes, procesar y recuperar resultados. Comprender este ciclo es esencial antes de pasar a la implementación, ya que cada paso tiene sus propias restricciones y mejores prácticas.

Paso 1: Crear un lote

Todo comienza con una llamada POST /v1/batches, con un campo obligatorio: el nombre del lote. La API devuelve un identificador único (batch_id) que utilizarás para todas las operaciones posteriores.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

La respuesta también contiene las fechas de creación y caducidad del lote (create_time, expire_time) y un objeto state cuyos contadores están aún a cero.

Paso 2: Añadir solicitudes

Existen dos métodos:

A través de la API: envías solicitudes con POST /v1/batches/{batch_id}/requests. Cada llamada transporta una lista de solicitudes y puedes seguir añadiéndolas mientras el lote no se cancele. Esta es la vía para lotes que se construyen de forma incremental.

Mediante un archivo JSONL: preparas un archivo que contiene todas tus solicitudes, lo subes a través de la API de Files y luego creas el lote a partir de ese archivo. El lote queda entonces sellado: no es posible añadir más elementos. Esta es la vía para grandes volúmenes preparados con antelación.

Cada solicitud lleva un identificador único dentro del lote: batch_request_id en la API, custom_id en el archivo JSONL. Si lo omites en la API, xAI genera un UUID; proporciona el tuyo propio (un ID de base de datos, por ejemplo): sirve como clave de coincidencia entre tus datos y los resultados, y garantiza que una solicitud se procese solo una vez.

Paso 3: Supervisar el progreso

El procesamiento comienza en cuanto llegan las solicitudes; no existe un paso de “inicio”. Mientras tanto, GET /v1/batches/{batch_id} devuelve el objeto state y sus contadores: num_requests (total), num_pending (pendientes), num_success (correctas), num_error (fallidas) y num_cancelled (canceladas).

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

Cuando num_pending baja a cero, todas las solicitudes han sido procesadas, con éxito o no. El sondeo periódico es suficiente: unos segundos para un lote de prueba pequeño, unos minutos para un lote grande.

Paso 4: Recuperar resultados

Los resultados se leen con GET /v1/batches/{batch_id}/results, sin esperar a que el lote termine: cada solicitud está disponible en cuanto se procesa. La respuesta está paginada: limit establece el tamaño de la página (máximo 1.000) y el pagination_token devuelto se utiliza para solicitar la página siguiente; está vacío en la última página.

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

Cada resultado lleva el batch_request_id de su solicitud: esto te permite reconstruir la correspondencia entre tus datos de entrada y las respuestas de Grok.

El flujo de trabajo en la práctica

En una canalización de producción, el flujo de trabajo se traduce generalmente en dos procesos separados:

  • Un proceso de envío que crea el lote, prepara y añade solicitudes, y luego almacena el batch_id
  • Un proceso de recuperación que comprueba periódicamente los contadores y descarga los resultados a medida que están disponibles

Esta separación te permite integrar la API de lotes en arquitecturas dirigidas por eventos o en canalizaciones de datos existentes (tareas cron, Apache Airflow, colas).

Gestión de errores en el flujo de trabajo

Un lote no tiene un estado global de “correcto” o “fallido”: se lee a través de sus contadores. Una solicitud fallida incrementa num_error y aparece en los resultados con su mensaje de error, sin bloquear a las demás. Por tanto, debes examinar cada resultado y gestionar los fallos caso por caso.

Dos eventos afectan a todo el lote. El primero es la cancelación, por tu parte o por parte de xAI, que entonces lo explica en el campo cancel_by_xai_message. Esto ocurre en particular cuando una línea de un archivo JSONL no es válida. El otro es la caducidad (expire_time), tras la cual los resultados ya no son accesibles: recuéperalos con prontitud.

Puntos clave

  • El flujo de trabajo sigue el orden: crear (con un nombre), añadir, supervisar, recuperar
  • El identificador de solicitud (batch_request_id, o custom_id en JSONL) es tu clave de coincidencia
  • El progreso se lee en los contadores de state; todo está procesado cuando num_pending es cero
  • Los resultados están paginados (limit, pagination_token) y disponibles a medida que se procesan
  • Los errores se gestionan solicitud por solicitud; la cancelación y la caducidad afectan a todo el lote