Límites de tasa y buenas prácticas
En esta página
Actualizado el 2 de noviembre de 2026. Basado en la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles, los ejemplos siguen la API REST y el
xai-sdkoficial (client.batch.*; la API de lotes de xAI no usa el formato de OpenAI, por lo que el SDK de OpenAI no aplica), y la API de Responses tiene prioridad sobre Chat Completions, un endpoint heredado en xAI. Fuentes: Batch API · Referencia REST · Precios de lotes.
Restricciones que debes conocer
La API de lotes impone límites técnicos que debes tener en cuenta en tu arquitectura. Ignorarlos provoca rechazos, cancelaciones de lotes o pérdida de resultados. Esta lección resume las restricciones documentadas por xAI y las buenas prácticas para entornos de producción.
Límites de tasa
| Restricción | Valor | Ámbito |
|---|---|---|
| Creación de lotes | 2 por segundo | Por equipo |
| Número de lotes | Ilimitado | Por equipo |
| Llamadas de adición de solicitudes | 1.000 cada 30 segundos | Ventana deslizante, compartida entre todos los lotes del equipo |
| Tamaño de solicitud | 25 MB | Por solicitud individual |
| Solicitudes por lote | Ilimitado en teoría | Por encima de 100.000, el procesamiento puede ser más lento |
Creación de lotes: el límite de 2 creaciones por segundo rara vez es un problema, ya que normalmente se crea un lote por operación.
Adición de solicitudes: el límite se aplica a las llamadas, y cada llamada transporta una lista de solicitudes. Con bloques de 100 solicitudes, ya permite más de 3.000 solicitudes por segundo.
Tamaño de solicitud: el límite de 25 MB afecta principalmente a solicitudes cargadas con imágenes codificadas en base64; una solicitud de texto rara vez supera unos pocos kilobytes.
Por el contrario, las solicitudes de lote no cuentan para los límites de tasa de la API en tiempo real: un lote grande no ralentiza tu aplicación interactiva.
Límites de archivos JSONL
| Restricción | Valor |
|---|---|
| Solicitudes por archivo | 50.000 máximo |
| Tamaño de archivo | 200 MB máximo |
| Adiciones tras la creación | No posible: el lote se sella |
Si tu lote excede estos límites, divídelo en varios archivos y crea un lote por archivo; agregarás los resultados después.
Caducidad de URL
Las URL firmadas para resultados de imagen y vídeo caducan tras una hora. Esta es la restricción más crítica que gestionar en producción: tu proceso de recuperación debe descargar los medios inmediatamente, sin intervención manual (la función telecharger_medias de la lección 9). Para el lote, vigila también expire_time, tras el cual ningún resultado es accesible.
Buenas prácticas para producción
IDs deterministas
Deriva tus IDs de solicitud (batch_request_id, o custom_id en JSONL) de tus datos de entrada. Si necesitas reenviar un lote, los mismos datos producirán los mismos IDs, lo que facilita la deduplicación:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Genera un ID de solicitud determinista."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Gestión de fallos parciales
Un lote totalmente procesado puede contener aún solicitudes fallidas. Comprueba siempre cada resultado:
reussies, echouees = [], []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch_id, limit=1000, pagination_token=jeton
)
reussies.extend(page.succeeded)
echouees.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
if echouees:
print(f"{len(echouees)} solicitudes fallidas para reenviar en un nuevo lote")
Seguimiento de costes
Cada lote mantiene un registro de su coste total en ticks (diezmilmillonésimas de dólar):
batch = client.batch.get(batch_id=batch_id)
print("Coste total: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
A través de la API REST, el coste de cada solicitud de texto aparece en su resultado, en el campo usage.cost_in_usd_ticks.
Registros y trazabilidad
Registra cada operación para poder diagnosticar problemas:
import logging
logger = logging.getLogger("batch_api")
logger.info("Lote creado: %s", batch_id)
logger.info("Archivo subido: %s, %d solicitudes", file_id, len(documents))
logger.info("Resultados: %d exitosas, %d fallidas", len(reussies), len(echouees))
Reintento con retroceso exponencial
Para errores transitorios (tiempo de espera agotado, límite de tasa, error de servidor), reintenta con un retraso creciente:
import time
def appel_avec_retry(fonction, max_essais=3):
for essai in range(max_essais):
try:
return fonction()
except Exception as e:
if essai == max_essais - 1:
raise
attente = 2 ** essai
print(f"Reintentando en {attente} s: {e}")
time.sleep(attente)
Lista de comprobación previa a producción
Antes de desplegar una canalización de la API de lotes en producción, verifica:
- El modelo acepta procesamiento por lotes y aparece en la lista de modelos con descuento si el coste es relevante
- Los IDs de solicitud son únicos y deterministas
- El archivo JSONL se valida antes de la subida (una línea inválida cancela el lote)
- La descarga de resultados multimodales está automatizada, dentro de una hora
- Los fallos parciales se detectan y reenvían en un nuevo lote
- Los resultados se recuperan antes de
expire_time - Los registros cubren cada paso del flujo de trabajo
- La clave de API se lee desde una variable de entorno, nunca hardcodeada
Puntos clave
- Límites: 2 creaciones por segundo, 1.000 llamadas de adición de solicitudes cada 30 segundos, 25 MB por solicitud
- Archivos JSONL: 50.000 solicitudes y 200 MB máximo, un lote por archivo
- Las URL de imagen y vídeo caducan en una hora: descarga inmediatamente
- IDs deterministas, comprobación de cada resultado, seguimiento de costes en ticks
- Registros, reintento con retroceso exponencial y un tiempo de espera máximo para producción
Pon a prueba tus conocimientos
Procesamiento por lotes: la API de lotes sin zonas grises.
1. ¿Cuándo es la opción correcta la API de lotes?
Respuesta: Para grandes volúmenes sin restricciones de tiempo real: clasificación, enriquecimiento, evaluaciones, generación masiva. Las solicitudes de lote no cuentan para los límites de tasa, y los modelos de texto elegibles obtienen un descuento del 20 %.
2. ¿Cuál es el flujo de trabajo de cuatro pasos?
Respuesta: Crear un lote con nombre, añadir solicitudes al mismo (mediante la API, o creando el lote desde un archivo JSONL subido), rastrear sus contadores y, finalmente, recuperar los resultados, según lleguen o al final. El procesamiento comienza por sí solo, sin paso de lanzamiento.
3. ¿Qué puedes incluir en un lote?
Respuesta: Solicitudes de Responses (recomendado) y Chat Completions (heredado), con herramientas de servidor y llamada a funciones, así como generaciones y ediciones de imagen y vídeo, y extensiones de vídeo. Solo los tokens de texto para modelos elegibles obtienen el descuento.
4. ¿Cómo se rastrea la ejecución?
Respuesta: Mediante los contadores del lote (num_pending, num_success, num_error…), el estado de cada solicitud (pending, succeeded, failed, cancelled) y los resultados paginados, que separan éxitos de fallos. El lote está totalmente procesado cuando num_pending es cero.
5. ¿Qué buenas prácticas aplican a los límites?
Respuesta: Añade solicitudes en bloques, divide archivos grandes en un lote por archivo, descarga los medios en una hora, recupera los resultados antes de expire_time y reenvía los fallos en un nuevo lote: diseña el lote como una canalización robusta, no como un envío masivo ciego.
Lotes bien formados, contadores rastreados, fallos reintentados: la API de lotes convierte el volumen en rutina, al mejor coste.