Canalización completa de extremo a extremo
En esta página
Curso 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-sdkoficial (client.batch.*; la API de lotes de xAI no coincide con el formato de OpenAI, por lo que el SDK de OpenAI no es aplicable), y la API de Respuestas tiene prioridad sobre Completaciones de Chat, un punto final heredado en xAI. Fuentes: API de lotes · Referencia REST · Precios de lotes.
Ensamblaje de las piezas
Las lecciones anteriores cubrieron cada paso de forma aislada. Esta lección las ensambla en una canalización completa, desde la preparación de datos hasta el procesamiento de los resultados. Al finalizar, dispondrás de un script que podrás adaptar a tu caso de uso.
Canalización completa en Python
import json
import time
from xai_sdk import Client
client = Client() # la clave se lee de XAI_API_KEY
# --- Paso 1: preparar datos ---
documents = [
{"id": f"doc-{i}", "text": f"Contenido del documento {i}..."}
for i in range(100)
]
# --- Paso 2: escribir el archivo JSONL ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Resume en dos frases."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Paso 3: subir el archivo ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Paso 4: crear el lote desde el archivo (ahora está sellado) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Lote creado: {batch.batch_id}")
# --- Paso 5: esperar a que finalice el procesamiento ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Lote cancelado por xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
break
print(f"{etat.num_success + etat.num_error}/{etat.num_requests} solicitudes procesadas")
time.sleep(300) # cada 5 minutos
# --- Paso 6: recuperar resultados, página a página ---
resultats, echecs = {}, []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=jeton
)
for r in page.succeeded:
resultats[r.batch_request_id] = r.response.content
echecs.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"{len(resultats)} resultados, {len(echecs)} fallos")
print("Coste total: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Tres detalles son cruciales. La condición de parada requiere num_requests > 0 porque un lote creado desde un archivo se lee en segundo plano: justo después de la creación, sus contadores pueden seguir siendo cero. El campo cancel_by_xai_message señala la cancelación por parte de xAI, por ejemplo, debido a una línea inválida. Y el coste se expresa en ticks, diez mil millonésimas de dólar.
Canalización paso a paso con cURL
Si prefieres la línea de comandos, aquí tienes el equivalente en cURL (usando jq para leer las respuestas):
# 1. Subir el archivo JSONL
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl" | jq -r '.id')
echo "Archivo: $FILE_ID"
# 2. Crear el lote desde el archivo
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Lote: $BATCH_ID"
# 3. Leer contadores
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Recuperar la primera página de resultados
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Obtén las páginas siguientes añadiendo &pagination_token=… con el valor devuelto por la página anterior.
Gestión de errores en producción
Una canalización robusta distingue tres familias de errores:
Errores de envío: falla la subida del archivo o la creación del lote. Reintenta los errores transitorios (tiempo de espera agotado, límite de tasa, error del servidor) con un retraso creciente: 1 s, 2 s, 4 s, 8 s.
Errores de procesamiento: algunas solicitudes fallan dentro del lote. Aparecen en page.failed con su mensaje; reenvíalas, y solo a ellas, en un nuevo lote.
Tiempo de espera y caducidad: la ventana de 24 horas es indicativa, no garantizada. Lo que es implacable es la caducidad (expire_time): tras este punto, los resultados ya no son accesibles. Recupéralos a medida que lleguen en lugar de hacerlo todos juntos al final.
# Solicitudes fallidas: identifícalas para reenviarlas en un nuevo lote
for r in echecs:
print(f"Fallo: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Optimización de costes
El ahorro se acumula a través de cuatro palancas. La elección del modelo es la primera y, con diferencia, la más potente: a la tarifa estándar del 2 de noviembre de 2026, grok-4.3 cuesta 1,25 $ por millón de tokens de entrada y 2,50 $ para la salida, frente a 2 $ y 6 $ para grok-4.7 (indicaciones inferiores a 200 000 tokens). Para clasificación o extracción breve, el modelo más ligero suele bastar, y el descuento del 20 % por lotes se aplica a ambos. La longitud de la respuesta es lo siguiente: max_output_tokens evita pagar por salidas innecesariamente largas; para clasificación, bastan unos pocos tokens. Las indicaciones: eliminar diez tokens de una indicación repetida 50 000 veces ahorra 500 000 tokens de entrada. Finalmente, la caché: xAI almacena en caché automáticamente los inicios idénticos de las solicitudes, y el descuento por lotes también se aplica a los tokens servidos desde la caché; por tanto, coloca las instrucciones comunes al inicio de cada solicitud, antes de la parte variable.
Puntos clave
- Una canalización completa abarca seis pasos: preparación, JSONL, subida, creación, supervisión, recuperación
- Un lote creado desde un archivo se lee en segundo plano: espera a que
num_requests > 0antes de concluir que ha terminado - Gestiona las tres familias de errores: envío, procesamiento, tiempo de espera y caducidad
- Recupera y guarda los resultados a medida que lleguen, antes de
expire_time - La elección del modelo, la longitud de salida, las indicaciones breves y los prefijos comunes maximizan el ahorro