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

Límites de tasa y buenas prácticas

Lección 12 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Restricciones que debes conocer
  2. Límites de tasa
  3. Límites de archivos JSONL
  4. Caducidad de URL
  5. Buenas prácticas para producción
  6. Lista de comprobación previa a producción
  7. Puntos clave
  8. Pon a prueba tus conocimientos

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-sdk oficial (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ónValorÁmbito
Creación de lotes2 por segundoPor equipo
Número de lotesIlimitadoPor equipo
Llamadas de adición de solicitudes1.000 cada 30 segundosVentana deslizante, compartida entre todos los lotes del equipo
Tamaño de solicitud25 MBPor solicitud individual
Solicitudes por loteIlimitado en teoríaPor 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ónValor
Solicitudes por archivo50.000 máximo
Tamaño de archivo200 MB máximo
Adiciones tras la creaciónNo 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.