Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API Batch e Checklist di Produzione

Lezione 12 di 12 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. L’alternativa dell’API Batch: 20% di sconto sui token
  2. Confronto degli approcci
  3. Checklist di Produzione
  4. Architettura Consigliata
  5. Punti chiave
  6. Metti alla prova le tue conoscenze

L’alternativa dell’API Batch: 20% di sconto sui token

Quando l’elaborazione in tempo reale non è un vincolo, l’API Batch di xAI offre una riduzione del 20% su tutti i token per i modelli di testo idonei (da grok-4.3 a grok-4.7 al 2 novembre 2026, secondo i prezzi dell’API batch di xAI). Invece di inviare le richieste una per una e gestire la concorrenza, invii le tue richieste in batch tramite l’API o in un file JSONL e recuperi i risultati al termine dell’elaborazione, tipicamente entro 24 ore. Le richieste batch non contano ai fini dei limiti di frequenza. Il corso API Batch: Elaborazione in blocco dettaglia il flusso di lavoro.

Quando utilizzare l’API Batch

  • Elaborazione di cataloghi prodotti (migliaia di descrizioni)
  • Classificazione in blocco di ticket di supporto
  • Generazione di riassunti per una base documentale
  • Qualsiasi compito per cui un ritardo di alcune ore è accettabile

Quando attenersi all’Async classico

  • Chatbot interattivo (risposta in tempo reale)
  • Pipeline in cui ogni passaggio dipende dal precedente
  • Monitoraggio e alert in tempo reale
  • Qualsiasi caso in cui il ritardo dell’API Batch sia inaccettabile

Confronto degli approcci

Criterio Async + Semaforo API Batch
Costo Tariffa standard -20% sui token per i modelli idonei
Latenza Da secondi a minuti Da minuti a ore
Controllo Tempo reale, errori immediati Risultati al termine dell'elaborazione, errori per singola richiesta
Complessità Semaforo, backoff, gather Batch di richieste o file JSONL, tracciamento contatori
Limiti di frequenza Soggetti a RPM/TPM Gestiti da xAI

Checklist di Produzione

Prima di distribuire il tuo sistema di richieste asincrone in produzione, verifica ogni punto di questa lista:

Configurazione

  • Il timeout è impostato a 3600 secondi per i modelli di ragionamento
  • Il semaforo è dimensionato in base ai tuoi effettivi limiti di frequenza (non a stime)
  • Il backoff esponenziale è implementato con jitter per gli errori 429
  • Le chiavi API sono caricate dalle variabili d’ambiente, mai hardcoded nel codice
  • L’header x-grok-conv-id è utilizzato per le conversazioni multi-turno

Gestione degli errori

  • return_exceptions=True è usato in asyncio.gather per isolare gli errori
  • Gli errori 429, di timeout e di connessione attivano un nuovo tentativo
  • Gli errori di richiesta non valida (BadRequestError) non attivano un nuovo tentativo
  • Le richieste fallite sono identificate e possono essere ritentate
  • I log includono il tipo di errore, il numero del tentativo e il ritardo di ritento

Monitoraggio

  • Il numero di token consumati è tracciato tramite response.usage
  • Il tasso di hit della cache è misurato per validare l’uso di x-grok-conv-id
  • I costi sono stimati in tempo reale con cost_in_usd_ticks
  • I limiti di frequenza rimanenti sono monitorati per regolare dinamicamente il semaforo

Prestazioni

  • Il chunking è utilizzato per batch superiori a 100 richieste
  • I risultati intermedi sono salvati tra i sotto-batch
  • Il progresso è visualizzato per i lavori di lunga durata
  • Il semaforo è regolato in base al modello utilizzato (ragionamento = inferiore)

Sicurezza

  • Le chiavi API non sono esposte nei log o nei messaggi di errore
  • Le risposte contenenti dati sensibili sono elaborate in memoria, non scritte su disco
  • L’archiviazione remota (store_messages) è disabilitata per i dati confidenziali
  • use_encrypted_content è abilitato quando è richiesta la riservatezza del ragionamento

Architettura Consigliata

import os
import asyncio
import uuid
from asyncio import Semaphore
from openai import AsyncOpenAI, RateLimitError, APITimeoutError
import httpx

class GrokAsyncProcessor:
    def __init__(self, max_concurrent: int = 5):
        self.client = AsyncOpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1",
            timeout=httpx.Timeout(3600.0)
        )
        self.sem = Semaphore(max_concurrent)
        self.conv_id = str(uuid.uuid4())

    async def request(self, prompt: str, max_retries: int = 5) -> str:
        async with self.sem:
            for attempt in range(max_retries):
                try:
                    response = await self.client.chat.completions.create(
                        model="grok-4.5",
                        messages=[{"role": "user", "content": prompt}],
                        extra_headers={"x-grok-conv-id": self.conv_id}
                    )
                    return response.choices[0].message.content
                except RateLimitError:
                    if attempt == max_retries - 1:
                        raise
                    await asyncio.sleep(2 ** attempt)
                except APITimeoutError:
                    if attempt == max_retries - 1:
                        raise
                    await asyncio.sleep(2 ** attempt)

    async def batch(self, prompts: list[str]) -> list[str | Exception]:
        tasks = [self.request(p) for p in prompts]
        return await asyncio.gather(*tasks, return_exceptions=True)

Questa classe incapsula tutti i pattern trattati in questo corso: client async, semaforo, backoff, cache e gestione degli errori. Fornisce un punto di partenza solido per i tuoi progetti in produzione.

Punti chiave

  • L’API Batch offre il 20% di sconto sui modelli idonei ma impone un ritardo di elaborazione
  • Scegli tra async in tempo reale e batch in base ai tuoi vincoli di latenza
  • La checklist di produzione copre configurazione, errori, monitoraggio, prestazioni e sicurezza
  • La classe GrokAsyncProcessor incapsula tutti i pattern del corso in un’unica astrazione
  • Testa sempre la tua configurazione con un piccolo batch prima di lanciare l’elaborazione in blocco

Metti alla prova le tue conoscenze

Async, limiti, cache: pattern di produzione in cinque domande.

1. Quando prevale l'async sul sync?

Risposta: Ogni volta che gestisci più richieste indipendenti: l’AsyncClient (o AsyncOpenAI) sovrappone le attese di rete—il throughput si moltiplica senza moltiplicare i thread.

2. Come elabori un batch senza superare i limiti?

Risposta: asyncio.gather per il parallelismo, un semaforo per limitare le richieste concorrenti e un backoff esponenziale sugli HTTP 429, rispettando i limiti RPM/TPM della console.

3. Come gestisci il contesto multi-turno su larga scala?

Risposta: Tramite l’archiviazione lato server delle risposte e il riutilizzo del ragionamento cifrato: lo stato risiede lato API, il tuo codice traccia solo gli identificatori.

4. Cosa devi sapere su cache e timeout?

Risposta: La cache delle conversazioni (x-grok-conv-id) accelera i thread successivi e le richieste di ragionamento richiedono timeout adattati: due impostazioni che trasformano la produzione.

5. Cosa contiene la checklist di produzione del corso?

Risposta: Async padroneggiato, limiti rispettati (semaforo + backoff), batch per volumi freddi, timeout e ritenti configurati, costi tracciati: robustezza come checklist.

Concorrenza limitata, guasti pianificati, stato lato server: i pattern async trasformano i tuoi script in servizi—la checklist finale li mette in sicurezza.