Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Limiti di frequenza e best practice

Lezione 12 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Vincoli da conoscere
  2. Limiti di frequenza
  3. Limiti dei file JSONL
  4. Scadenza degli URL
  5. Best practice per la produzione
  6. Checklist pre-produzione
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

Aggiornato il 2 novembre 2026. Basato sulla documentazione xAI: lo sconto batch è del 20% sui modelli di testo idonei, gli esempi seguono l’API REST e l’SDK ufficiale xai-sdk (client.batch.*; l’API Batch di xAI non utilizza il formato di OpenAI, quindi l’SDK OpenAI non si applica), e l’API Responses ha la precedenza su Chat Completions, un endpoint legacy presso xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.

Vincoli da conoscere

L’API Batch impone limiti tecnici che devi considerare nella tua architettura. Ignorarli porta a rifiuti, batch annullati o risultati persi. Questa lezione riassume i vincoli documentati da xAI e le best practice per l’uso in produzione.

Limiti di frequenza

VincoloValoreAmbito
Creazione batch2 al secondoPer team
Numero di batchIllimitatoPer team
Chiamate di aggiunta richieste1.000 ogni 30 secondiFinestra scorrevole, condivisa tra tutti i batch del team
Dimensione richiesta25 MBPer singola richiesta
Richieste per batchTeoricamente illimitateOltre 100.000, l’elaborazione potrebbe essere più lenta

Creazione batch: il limite di 2 creazioni al secondo raramente costituisce un problema, dato che generalmente crei un batch per operazione.

Aggiunta richieste: il limite si applica alle chiamate e ogni chiamata trasporta un elenco di richieste. Con blocchi di 100 richieste, ciò consente già più di 3.000 richieste al secondo.

Dimensione richiesta: il limite di 25 MB riguarda principalmente le richieste caricate con immagini codificate in base64; una richiesta di testo raramente supera pochi kilobyte.

Al contrario, le richieste batch non contano verso i limiti di frequenza dell’API in tempo reale: un batch di grandi dimensioni non rallenta la tua applicazione interattiva.

Limiti dei file JSONL

VincoloValore
Richieste per fileMassimo 50.000
Dimensione fileMassimo 200 MB
Aggiunte dopo la creazioneNon possibili: il batch viene sigillato

Se il tuo batch supera questi limiti, dividilo in più file e crea un batch per file; aggregherai i risultati successivamente.

Scadenza degli URL

Gli URL firmati per i risultati di immagini e video scadono dopo un’ora. Questo è il vincolo più critico da gestire in produzione: il tuo processo di recupero deve scaricare immediatamente i media, senza intervento manuale (la funzione telecharger_medias della lezione 9). Per il batch, monitora anche expire_time, dopo il quale nessun risultato è accessibile.

Best practice per la produzione

ID deterministici

Deriva gli ID delle tue richieste (batch_request_id, o custom_id in JSONL) dai tuoi dati di input. Se devi reinviare un batch, gli stessi dati produrranno gli stessi ID, rendendo più facile la deduplicazione:

import hashlib


def identifiant_requete(document_id: str, operation: str) -> str:
    """Genera un ID richiesta deterministico."""
    brut = f"{document_id}:{operation}"
    return hashlib.sha256(brut.encode()).hexdigest()[:16]

Gestione dei fallimenti parziali

Un batch completamente elaborato può comunque contenere richieste fallite. Controlla sempre ogni risultato:

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)} richieste fallite da reinviare in un nuovo batch")

Tracciamento dei costi

Ogni batch tiene traccia del suo costo totale in tick (decimiliardesimi di dollaro):

batch = client.batch.get(batch_id=batch_id)
print("Costo totale: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Tramite l’API REST, il costo di ogni richiesta di testo appare nel suo risultato, nel campo usage.cost_in_usd_ticks.

Log e tracciabilità

Registra ogni operazione per poter diagnosticare i problemi:

import logging

logger = logging.getLogger("batch_api")

logger.info("Batch creato: %s", batch_id)
logger.info("File caricato: %s, %d richieste", file_id, len(documents))
logger.info("Risultati: %d riusciti, %d falliti", len(reussies), len(echouees))

Retry con backoff

Per errori transitori (timeout, limite di frequenza, errore server), riprova con un ritardo crescente:

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"Riprovo tra {attente} s: {e}")
            time.sleep(attente)

Checklist pre-produzione

Prima di distribuire una pipeline API Batch in produzione, verifica:

  • Il modello accetta l’elaborazione batch e appare nell’elenco dei modelli scontati se il costo è rilevante
  • Gli ID richiesta sono unici e deterministici
  • Il file JSONL è convalidato prima del caricamento (una riga non valida annulla il batch)
  • Il download dei risultati multimodali è automatizzato, entro un’ora
  • I fallimenti parziali sono rilevati e reinviati in un nuovo batch
  • I risultati sono recuperati prima di expire_time
  • I log coprono ogni fase del flusso di lavoro
  • La chiave API è letta da una variabile d’ambiente, mai hardcoded

Punti chiave

  • Limiti: 2 creazioni al secondo, 1.000 chiamate di aggiunta richieste ogni 30 secondi, 25 MB per richiesta
  • File JSONL: massimo 50.000 richieste e 200 MB, un batch per file
  • Gli URL di immagini e video scadono in un’ora: scaricali immediatamente
  • ID deterministici, controllo di ogni risultato, tracciamento costi in tick
  • Log, retry con backoff e un timeout massimo per la produzione

Metti alla prova le tue conoscenze

Elaborazione in blocco: l’API Batch senza zone d’ombra.

1. Quando è la scelta giusta l'API Batch?

Risposta: Per grandi volumi senza vincoli di tempo reale: classificazione, arricchimento, valutazioni, generazione in blocco. Le richieste batch non contano verso i limiti di frequenza e i modelli di testo idonei ottengono uno sconto del 20%.

2. Qual è il flusso di lavoro in quattro passaggi?

Risposta: Crea un batch denominato, aggiungi le richieste (tramite API o creando il batch da un file JSONL caricato), monitora i suoi contatori, quindi recupera i risultati man mano che arrivano o alla fine. L’elaborazione inizia autonomamente, senza un passaggio di avvio.

3. Cosa puoi inserire in un batch?

Risposta: Richieste Responses (consigliate) e Chat Completions (legacy), con strumenti server e function calling, nonché generazioni ed editing di immagini e video, ed estensioni video. Solo i token di testo per i modelli idonei ottengono lo sconto.

4. Come monitori l'esecuzione?

Risposta: Tramite i contatori del batch (num_pending, num_success, num_error…), lo stato di ogni richiesta (pending, succeeded, failed, cancelled) e i risultati paginati, che separano i successi dai fallimenti. Il batch è completamente elaborato quando num_pending è zero.

5. Quali best practice si applicano ai limiti?

Risposta: Aggiungi le richieste a blocchi, dividi i file grandi in un batch per file, scarica i media entro un’ora, recupera i risultati prima di expire_time e reinvia i fallimenti in un nuovo batch: progetta il batch come una pipeline robusta, non come una sottomissione in blocco cieca.

Batch ben formati, contatori monitorati, fallimenti ritentati: l’API Batch trasforma il volume in routine, al miglior costo.