Alcuni job con gli LLM non sono chat. Hai 50.000 ticket di assistenza da etichettare, 200.000 descrizioni di prodotto da tradurre o un milione di recensioni da valutare. Provider come OpenAI e Anthropic vendono per questo una Batch API. Molte API compatibili con OpenAI, tra cui BroadNet Inference, non ce l’hanno. Questo articolo mostra come gestire il job da solo: calcolare quanto tempo richiederà, scrivere un runner che rispetti i limiti e renderlo sicuro da fermare e riavviare.
BroadRouter è il sito di BroadNet, quindi i numeri degli esempi usano i limiti pubblicati da BroadNet. Il metodo funziona con qualsiasi API chat completions; sostituisci i numeri del tuo provider.
BroadNet Inference ha una Batch API?
No. Il riferimento API, verificato il 15 novembre 2026, documenta POST /v1/chat/completions, POST /v1/audio/transcriptions e GET /v1/models (l’elenco dei modelli), più gli endpoint dell’account sotto /portal/. Non c’è un endpoint di batch o di caricamento file, né uno sconto batch. Un job massivo è un ciclo di richieste normali.
Ecco cosa ti dà una Batch API gestita, così sai cosa stai ricostruendo:
| Batch API di OpenAI | Message Batches di Anthropic | Il tuo runner | |
|---|---|---|---|
| Prezzo | 50% in meno rispetto alle chiamate sincrone | 50% in meno | Prezzo normale |
| Tempi di consegna | Entro 24 ore | La maggior parte entro 1 ora; scadenza dopo 24 | Dipendono dai tuoi rate limit |
| Dimensione per batch | 50.000 richieste o 200 MB | 100.000 richieste o 256 MB | Qualsiasi |
| Rate limit | Separati dai limiti per modello | Si applicano alle richieste in coda | I limiti della tua chiave |
| Ordine dei risultati | Può variare; abbina con custom_id |
Abbina con custom_id |
Tu indicizzi i risultati per ID |
Due lezioni valgono anche per te. Entrambi i provider ti fanno etichettare ogni richiesta con un ID, perché i risultati non tornano in ordine. Nessuno dei due promette una risposta in pochi secondi. Il tuo runner dovrebbe funzionare allo stesso modo: ID su tutto e una pianificazione misurata in ore.
Se uno sconto del 50% conta più dei tempi di consegna, e i modelli che ti servono sono disponibili, una Batch API gestita potrebbe essere lo strumento più economico. Fai i conti per entrambe le strade con il calcolatore dei costi delle API LLM prima di costruire.
Quanto tempo richiederà il job?
Calcolalo prima di scrivere codice. Due limiti fissano il throughput, e vince il più lento:
- Limite di richieste in corso ÷ latenza. Con 4 richieste in corso e 2 secondi per richiesta, ne completi 2 al secondo.
- Richieste al minuto. A 30 al minuto puoi avviarne 0,5 al secondo, per quanto veloce sia il modello.
Una chiave BroadNet a pagamento a consumo consente 4 richieste in corso e 30 al minuto. Con i valori del riferimento API al momento della verifica (30 al minuto e 4 in corso, 2026-11-15), il vincolo è il rate limit, a meno che ogni richiesta non richieda più di 8 secondi, e la tabella qui sotto usa 30 al minuto:
| Elementi | Un elemento per richiesta | 20 elementi per richiesta |
|---|---|---|
| 10.000 | 5,6 ore | 17 minuti |
| 100.000 | 2,3 giorni | 2,8 ore |
| 1.000.000 | 23 giorni | 28 ore |
A 30 richieste al minuto, una chiave fa 1.800 richieste all’ora, cioè 43.200 al giorno. Anche i retry contano: ogni 429 che provochi consuma uno slot.
La seconda colonna è la leva più potente. Gli elementi brevi, come recensioni o oggetti dei ticket, possono andare da 10 a 50 per richiesta sotto forma di elenco numerato, con un array JSON in risposta. Verifica che l’array abbia una voce per ogni input e che ognuna riporti il suo numero. L’articolo sulla classificazione di testi in arabo mostra lo schema. Gli elementi lunghi non si possono raggruppare: ogni richiesta deve comunque stare nella finestra di contesto del modello, e la qualità può calare man mano che l’elenco cresce. Prova il raggruppamento su 200 elementi prima di fidarti.
Non dividere un job su più chiavi per superare un limite per chiave senza chiedere. La Policy di utilizzo accettabile di BroadNet vieta di aggirare i limiti di frequenza, di concorrenza o di budget. Se ti serve di più, chiedi a BroadNet oppure usa le sessioni dei piani, più sotto. Il pianificatore di job batch fa questi conti per il tuo numero di elementi, la tua latenza e i tuoi limiti.
Com’è fatto un runner riprendibile?
Questo runner legge items.jsonl (un oggetto {"id", "text"} per riga) e aggiunge una riga di risultato per elemento a results.jsonl. Gli serve solo l’SDK Python di OpenAI.
import asyncio, json, os, random, time
from openai import AsyncOpenAI, APIStatusError, APIConnectionError, APITimeoutError
client = AsyncOpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"],
max_retries=0, # we retry ourselves, with a cap we can see
timeout=120)
MODEL = os.environ.get("MODEL", "broadnet/deepseek-v4.1-flash")
IN_FLIGHT = int(os.environ.get("IN_FLIGHT", "4")) # PAYG key: 4 in flight. Plan: 1 per session.
RPM = int(os.environ.get("RPM", "30")) # PAYG key: 30 requests a minute
MAX_ATTEMPTS = 6
class Pacer:
"""Spaces request starts at least 60/RPM seconds apart, across all workers."""
def __init__(self, rpm):
self.gap, self.next, self.lock = 60 / rpm, 0.0, asyncio.Lock()
async def wait(self):
async with self.lock:
now = time.monotonic()
delay = max(0.0, self.next - now)
self.next = max(now, self.next) + self.gap
await asyncio.sleep(delay)
def retryable(e):
if isinstance(e, (APIConnectionError, APITimeoutError)):
return True
return isinstance(e, APIStatusError) and e.status_code in (429, 500, 502, 503, 504)
async def call(item, pacer):
for attempt in range(MAX_ATTEMPTS):
await pacer.wait() # every attempt counts against the rate limit
try:
r = await client.chat.completions.create(
model=MODEL, max_tokens=1500, reasoning_effort="low",
messages=[{"role": "system", "content": "Classify the review as positive, negative or mixed. Reply with one word."},
{"role": "user", "content": item["text"]}])
c = r.choices[0]
return {"id": item["id"], "ok": True, "finish_reason": c.finish_reason,
"output": c.message.content, "usage": r.usage.model_dump() if r.usage else None}
except Exception as e:
if not retryable(e) or attempt == MAX_ATTEMPTS - 1:
return {"id": item["id"], "ok": False, "error": repr(e)[:300]}
await asyncio.sleep(random.uniform(0, min(60, 2 ** attempt))) # full jitter, capped
async def run(in_path, out_path):
done = set()
if os.path.exists(out_path): # resume: skip ids that already succeeded
with open(out_path) as f:
done = {json.loads(l)["id"] for l in f if l.strip() and json.loads(l).get("ok")}
todo = [it for it in map(json.loads, open(in_path)) if it["id"] not in done]
print(f"{len(done)} done, {len(todo)} to go")
pacer, queue = Pacer(RPM), asyncio.Queue()
for it in todo:
queue.put_nowait(it)
with open(out_path, "a") as out:
async def worker():
while True:
try:
it = queue.get_nowait()
except asyncio.QueueEmpty:
return
res = await call(it, pacer)
out.write(json.dumps(res, ensure_ascii=False) + "\n")
out.flush() # one line per finished item = the checkpoint
await asyncio.gather(*(worker() for _ in range(IN_FLIGHT)))
if __name__ == "__main__":
import sys
asyncio.run(run(sys.argv[1], sys.argv[2]))
Eseguilo con python batch_run.py items.jsonl results.jsonl. Abbiamo testato esattamente questo file contro un server mock locale che restituiva 429 casuali (8%) e 500 (5%) e rifiutava tutto oltre 4 richieste in corso o 30 avvii al minuto. 25 elementi sono stati completati in 55 secondi con 28 richieste (3 retry), e mai più di 30 avvii in una qualsiasi finestra di 60 secondi. Con il limite del mock alzato a 300 al minuto per risparmiare tempo, un’esecuzione da 120 elementi interrotta dopo 10 secondi è ripartita da 39 risultati salvati e ha terminato con 120 ID unici e nessun duplicato.
Perché un pool di worker e non asyncio.gather?
La guida al 429 usa un semaphore attorno ad asyncio.gather. Va bene per qualche centinaio di chiamate. Per un job grande è meglio un pool fisso di worker che pescano da una coda:
- Memoria.
gathercrea in anticipo un task per ogni elemento. Un pool tiene in memoria solo gli elementi in corso. - La concorrenza è la dimensione del pool. Quattro worker non possono mai avere cinque richieste aperte.
- I risultati vanno su disco in streaming man mano che finiscono, in qualsiasi ordine, con l’ID come chiave.
Il Pacer gestisce il secondo limite. Un semaphore da solo ti impedisce di superare le 4 richieste in corso, ma se le richieste durano un secondo, quattro worker ne avvierebbero 240 al minuto e la maggior parte riceverebbe un 429. Il pacer distanzia gli avvii di 2 secondi, su tutti i worker, retry compresi.
Come restano sicuri i retry?
Riprova solo ciò che può riuscire al secondo tentativo:
| Risposta | Azione |
|---|---|
| 429 | Attendi e riprova; la documentazione di BroadNet dice “use response details and bounded backoff” (traduzione: usa i dettagli della risposta e un backoff limitato) |
| 500, 502, 503, 504, timeout, connessioni interrotte | Riprova con backoff esponenziale limitato |
| 400, 422 | Correggi la richiesta; riprovare restituisce lo stesso errore |
| 401, 402, 403 | Ferma il job; chiave, saldo o policy richiedono attenzione |
| 413 | Accorcia l’elemento |
Il runner disattiva i retry dell’SDK (max_retries=0) così esiste una sola policy di retry, con un tetto visibile. Il backoff è esponenziale con full jitter, limitato a 60 secondi, così i worker che hanno fallito insieme non riprovano insieme. Dopo sei tentativi l’elemento viene scritto come "ok": false e il job va avanti. Un solo elemento difettoso non blocca mai un milione.
Una chiamata al modello non ha effetti collaterali, quindi qui la consegna è almeno una volta: se il processo muore a metà richiesta, quell’elemento viene inviato di nuovo al riavvio e lo paghi due volte. È l’unico spreco. Se il job scrive anche su un altro sistema, come ticket o email, rendi quella scrittura idempotente in base all’ID dell’elemento e falla in un passaggio separato su results.jsonl. L’articolo sugli agenti a lunga esecuzione approfondisce gli effetti collaterali idempotenti.
Come funziona il checkpointing?
Il file di output è il checkpoint. Ogni elemento completato è una riga già scritta su disco con il flush, quindi dopo un crash, un deploy o un Ctrl-C l’esecuzione successiva legge il file, raccoglie gli ID con "ok": true e mette in coda solo il resto. Gli elementi falliti in precedenza vengono riprovati all’esecuzione successiva, e la loro nuova riga viene aggiunta in fondo. Quando leggi i risultati, prendi l’ultima riga per ogni ID.
Tre abitudini rendono il sistema solido per giorni:
- ID stabili. Usa una chiave del database o un hash dell’input, mai un numero di riga che si sposta quando il file di input cambia.
- Controlla
finish_reason. Una risposta troncata amax_tokensè"ok": truema inutile. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max_tokens. Il runner impostareasoning_effort="low", documentato da BroadNet, e lascia 1.500 token. - Registra l’utilizzo su ogni riga. Sommando
usagedaresults.jsonlottieni la vera bolletta dei token da confrontare con la tua stima.
Quanto costa: pagamento a consumo o sessione di un piano?
Con il pagamento a consumo il costo sono i token. Prendi 100.000 recensioni, un system prompt da 150 token, una recensione da 150 token e 100 token di output con ragionamento basso. Fanno 30 milioni di token di input e 10 milioni di output. Su DeepSeek V4.1 Flash costa 30 × $0.175 + 10 × $0.52. Tieni il system prompt per primo e identico byte per byte, e i suoi 15 milioni di token possono essere fatturati alla tariffa dell’input in cache di $0.0055 per 1M dove la cache funziona. Le tue righe usage mostrano quanto spesso è successo.
Con un piano i token sono gratuiti e il costo è il tempo. Una sessione di un piano DeepSeek V4.1 Flash “runs one request at a time” (traduzione: esegue una richiesta alla volta), quindi imposta IN_FLIGHT=1 per sessione. Il throughput per sessione è 86.400 ÷ secondi per elemento, al giorno. BroadNet indica come velocità tipica circa 100 token al secondo, ma la tua latenza dipende dalla lunghezza del prompt e dal ragionamento, quindi misurala su 50 elementi. Se misuri 3 secondi a elemento, una sessione ne fa 28.800 al giorno:
| Job | Sessioni | Tempo a 3 s/elemento | Piano |
|---|---|---|---|
| 100.000 elementi | 1 | Circa 3,5 giorni | Una settimana Orbit, $15 per sessione |
| 100.000 elementi | 4 | Circa 21 ore | Quattro settimane Orbit, una per sessione; oppure circa 21 ore Meteor per sessione a $1 l’una |
| 1.000.000 di elementi | 6 | Circa 6 giorni | Sei settimane Orbit |
I piani sono forniti “best effort under fair use” (traduzione: al meglio delle possibilità, secondo il fair use), e BroadNet non pubblica un limite di richieste al minuto per le chiavi dei piani; il tuo account mostra i limiti che si applicano. Imposta RPM in base a quelli, non a occhio. La guida al pianificatore di sessioni spiega come distribuire le sessioni tra le chiavi.
Dove si colloca BroadNet Inference
BroadNet Inference non ha una Batch API, quindi è adatto ai job massivi quando preferisci controllare tu il runner e pagare i normali prezzi a token, oppure fissare il costo con le sessioni dei piani DeepSeek V4.1 Flash. Per job piccoli con poco budget, Gemma 4 VL 26B a $0.10 di input e $0.22 di output per 1M funziona con il credito iniziale di $5. Prompt e output non vengono conservati dopo ogni richiesta. Se il tuo job può aspettare un giorno e i modelli che ti servono sono su un provider con uno sconto batch del 50%, potrebbe costarti meno; confronta prima di impegnarti. Piani e limiti sono su inference.broadnet.ai/plans.
