IT ▾

Richieste batch in Python per un'API LLM compatibile con OpenAI

Per i lavori batch Python con l'API LLM, non hai bisogno di un endpoint batch speciale: ti serve un pool di worker che rispetti i limiti di velocità, una regola di retry per l'HTTP 429 e un file dei risultati da cui riprendere. Questa guida implementa tutti e tre con l'SDK OpenAI puntato al tuo URL di base.

Aggiornato

Tubi paralleli che trasportano cubi di dati verso un nucleo di elaborazione, illustrando le richieste batch concorrenti in Python

Punti chiave

  • L'API ha due metodi, chat completions e models, quindi il batch viene eseguito lato client con un pool di richieste concorrenti.
  • Una chiave completa permette 8 richieste concorrenti e 300 al minuto; una chiave di prova ne permette 2 e 60. Dimensiona il tuo pool di conseguenza.
  • Riprova in caso di 429 usando l'intestazione Retry-After e distingue rate_limited dalla concorrenza.
  • Scrivi ogni risultato in un file JSONL man mano che termina, così un crash costa minuti, non l'intera esecuzione.

Come funziona il batching qui

L'endpoint è compatibile con OpenAI ed espone POST /v1/chat/completions e GET /v1/models. Non c'è un endpoint separato per l'invio di job che accetta un file e restituisce dopo. Un batch è quindi un ciclo su richieste normali, eseguite in parallelo, con i limiti integrati nel tuo codice. È più semplice di quanto sembri e ti dà i risultati man mano che terminano invece che alla fine.

I numeri che definiscono il design sono i limiti. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova ne permette 2 concorrenti e 60 al minuto. Il corpo massimo della richiesta è 8 MB. Una richiesta in streaming occupa la sua slot di concorrenza fino alla fine dello streaming, quindi per il lavoro batch, disattiva lo streaming.

Perché non inviare tutto subito? Perché un batch è un problema di throughput con un soffitto, e il soffitto è tuo da rispettare. Un ciclo che invia 5.000 richieste il più velocemente possibile crea un muro di risposte 429, spreca tempo nei retry e seppellisce gli errori utili nel rumore. Un pool che mantiene al massimo 8 richieste in volo mantiene la linea in movimento alla velocità consentita dal servizio, ed è lo stesso codice che hai 50 righe o 500.000. Pianifica tre elementi: un pool limitato, una regola di retry e un file dei risultati append-only.

L'ID del modello è uncensored, l'autenticazione è Authorization: Bearer <key>, e l'URL di base è https://api.unfilteredvideo.com/v1. Se non hai ancora una chiave, la pagina chiave API offre una prova da $0,50 con un clic.

Installazione e configurazione

Ti servono Python 3.9 o superiore e il pacchetto ufficiale openai. Metti la chiave in una variabile d'ambiente invece che nello script.

pip install openai
export API_KEY="paste-your-key-here"

# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"

L'elenco dei modelli dovrebbe mostrare uncensored. Ora prepara il tuo input come file JSONL, un oggetto per riga con un id e il testo da elaborare. L'id è ciò che ti permette di riprendere più tardi.

{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}

Un pool di thread che rimane entro i limiti

Per la maggior parte degli script, un ThreadPoolExecutor è la via più breve. Il client OpenAI è sicuro da condividere tra thread e il lavoro è legato alla rete, quindi i thread sono adatti. Imposta la dimensione del pool al tuo limite di concorrenza, non di più: worker extra raccolgono solo errori 429.

import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI

client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8          # use 2 on a trial key

def run_one(row):
    resp = client.chat.completions.create(
        model=MODEL,
        temperature=0.2,
        max_tokens=200,
        messages=[{"role": "user", "content": row["text"]}],
    )
    return {
        "id": row["id"],
        "output": resp.choices[0].message.content,
        "in": resp.usage.prompt_tokens,
        "out": resp.usage.completion_tokens,
    }

rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
    futures = [pool.submit(run_one, r) for r in rows]
    for f in as_completed(futures):
        out.write(json.dumps(f.result()) + "\n")
        out.flush()

Questa versione non ha retry né resume, quindi è un punto di partenza. Il client è creato con max_retries=0 sul client perché l'SDK ritenta da solo per impostazione predefinita e vuoi un unico punto che gestisca la regola di retry. Le due sezioni successive aggiungono quella regola e la logica di resume.

Gestisci il 429 nel modo giusto

Ci sono tre tipi di 429 su questa API e richiedono reazioni leggermente diverse:

  • rate_limited: hai inviato troppe richieste in un minuto. Rallenta. Un pool con meno worker o una breve pausa lo risolvono.
  • concurrency: troppe richieste erano in volo contemporaneamente. Il tuo pool è più grande del tuo limite, o hai stream aperti che hai dimenticato.
  • Sovraccarico temporaneo: un 429 con un'intestazione Retry-After: 5. Non c'è niente di sbagliato nel tuo codice. Attendi il tempo indicato e riprova.

Un helper di retry copre tutti e tre. Attende Retry-After quando presente e altrimenti rallenta esponenzialmente con un po' di jitter. Le richieste fallite e rifiutate non vengono addebitate, quindi il retry è gratuito.

import random, time
import openai
from openai import OpenAI

client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"

def call_with_retry(messages, attempts=6):
    for n in range(attempts):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
        except openai.RateLimitError as e:
            wait = e.response.headers.get("Retry-After")
            delay = float(wait) if wait else min(60, 2 ** n) + random.random()
            print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
            time.sleep(delay)
        except (openai.APIConnectionError, openai.APITimeoutError):
            time.sleep(min(30, 2 ** n))
    raise RuntimeError("gave up after %d attempts" % attempts)

Non ritentare ciecamente su ogni errore. Un 400 significa che la tua richiesta è sbagliata, ad esempio un corpo oltre 8 MB o un messaggio malformato, e inviarlo di nuovo fallirà allo stesso modo. Registralo con l'id riga e passa oltre.

Una versione async con un semaphore

Se il tuo script gira già in un event loop, o vuoi alimentare un servizio web, usa AsyncOpenAI e un asyncio.Semaphore che limiti le richieste in volo. Il semaphore svolge il ruolo della dimensione del pool.

import asyncio, json, os
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)

async def run_one(row, out):
    async with sem:
        resp = await client.chat.completions.create(
            model=MODEL,
            max_tokens=200,
            messages=[{"role": "user", "content": row["text"]}],
        )
    out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
    out.flush()

async def main():
    rows = [json.loads(l) for l in open("input.jsonl")]
    with open("output.jsonl", "a") as out:
        await asyncio.gather(*(run_one(r, out) for r in rows))

asyncio.run(main())

Avvolgi la chiamata nella stessa logica di retry di cui sopra, usando await asyncio.sleep invece di time.sleep. Un avvertimento: gather con decine di migliaia di coroutine le crea tutte insieme. Per input molto grandi, elabora il file in slice di poche migliaia di righe.

Rendi l'esecuzione riprendibile

I lavori lunghi falliscono in modi noiosi: un laptop va in sospensione, una connessione cade, premi Ctrl+C. Poiché ogni riga completata viene aggiunta a output.jsonl con il suo id, riprendere significa saltare gli id che hai già.

import json, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"

def done_ids(path="output.jsonl"):
    if not os.path.exists(path):
        return set()
    return {json.loads(line)["id"] for line in open(path) if line.strip()}

finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")

Alimenta todo a entrambi i pool sopra. Apri il file di output in modalità append, mai in modalità write, o un riavvio cancellerà i tuoi progressi. Scrivi anche gli errori in un secondo file, errors.jsonl, così puoi riavviare solo i fallimenti dopo aver letto il motivo.

Per output ripetibili tra i riavvii, passa un seed fisso insieme a un temperature basso. Il seed viene passato al modello insieme a top_p, stop e alle penalità.

Fai un test su una piccola fetta prima

Esegui 20 righe prima di eseguire 20.000. Scegli righe che includano i tuoi casi peggiori: l'input più lungo, uno con caratteri strani, uno vuoto. Leggi gli output a occhio, controlla che usage corrisponda alla tua stima dei costi e conferma che l'helper di retry si comporta correttamente alzando temporaneamente il numero di worker sopra il tuo limite. Dovresti vedere un 429 con il codice concurrency nel log, un'attesa e un retry riuscito. È meglio vederlo su 20 righe che scoprirlo alla riga 9.000.

Se il lavoro richiede output strutturato, aggiungi la modalità JSON con response_format={"type": "json_object"}, descrivi le chiavi nel prompt e analizza ogni risposta all'interno di un blocco try. Conta i fallimenti di parsing durante la fetta di test. Un tasso sopra un percento o due di solito significa che il prompt ha bisogno di uno schema più chiaro, ed è più economico correggerlo ora che riavviare più tardi. Le righe che non riescono a essere analizzate vanno a errors.jsonl con il loro id e la logica di resume le tratta come non completate.

Infine, imposta un timeout del client che si adatti alla tua uscita massima prevista. L'SDK accetta timeout=60 sul client o per richiesta; una richiesta bloccata che non restituisce nulla altrimenti terrà uno dei tuoi 8 slot per tutto il tempo in cui rimane lì.

Dimensionamento del pool e stima dei tempi

Il throughput è limitato da due cose: la concorrenza divisa per il tempo che impiega una richiesta e il limite di richieste al minuto. Su una chiave completa il limite è 300 al minuto, che sono 5 al secondo. Se una richiesta tipica impiega 2 secondi, 8 worker producono 8 / 2 = 4 richieste al secondo, o 240 al minuto, che è sotto il limite. Se le richieste impiegano 1 secondo, 8 worker cercherebbero 8 al secondo e colpirebbero il limite, quindi aggiungi un piccolo ritardo o accetta 429 occasionali che il tuo helper di retry assorbe.

A 4 al secondo, 10.000 righe richiedono 2.500 secondi, circa 42 minuti. Con una chiave di prova, con 2 richieste concorrenti e 60 al minuto, il limite è 1 al secondo, quindi le stesse 10.000 righe richiederebbero 10.000 secondi, quasi 2 ore e 47 minuti. In pratica, il credito di prova da $0,50 si esaurirà prima, il che lo rende un buon punto per testare lo script su poche centinaia di righe e non un luogo per eseguire la produzione.

Quanto costa un grande batch

I prezzi sono $0,15 per 1M di token di input e $0,50 per 1M di token di output. Prendi un lavoro di tipo classificazione: 50.000 righe, ciascuna con circa 200 token di input e 100 token di output.

  • Input: 50.000 × 200 = 10.000.000 token, che sono 10 × $0,15 = $1,50.
  • Output: 50.000 × 100 = 5.000.000 token, che sono 5 × $0,50 = $2,50.
  • Totale: $4,00, o $0,00008 per riga.

Lo script sopra registra in e out per ogni riga, così puoi calcolare la stessa cifra dalla tua esecuzione reale. L'intestazione di risposta X-Balance-USD mostra anche il credito rimanente, e X-Request-Id è ciò che citare se chiedi aiuto nelle pagine docs o di supporto.

Il credito è prepagato con ricariche intere da $20 a $500, con un bonus del +5% da $50, +10% da $100 e +15% da $200, pagato in cripto (USDT su TRC20 o USDC su Base). Non scade mai. La pagina dei prezzi ha tutti i dettagli. Una nota per i dataset sensibili: i prompt non vengono usati per l'addestramento.

Domande e risposte

L'API ha un endpoint batch?

No. Espone le chat completions e un elenco di modelli. Fai il batch eseguendo molte richieste normali in parallelo dal tuo codice, entro 8 concorrenti e 300 al minuto con una chiave completa.

Quanti thread devo usare?

Usa 8 worker con una chiave completa e 2 con una chiave di prova, in linea con i limiti di concorrenza. Più worker generano solo errori 429 con il codice concurrency.

Cosa devo fare quando ricevo un HTTP 429?

Attendi il valore Retry-After se presente nella risposta, altrimenti riduci la frequenza per alcuni secondi, poi riprova. Le richieste fallite non vengono addebitate, quindi riprovare non costa nulla.

Posso fare lo streaming delle risposte in un lavoro batch?

Puoi, ma non dovresti. Una richiesta in streaming occupa il suo slot di concorrenza fino alla fine dello streaming, il che riduce il throughput. Disattiva lo streaming per i lavori batch.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.

Ottieni la chiave API