NL ▾

Betch-verzoeken in Python voor een OpenAI-compatible LLM API

Voor LLM-API-batchwerk in Python heb je geen speciaal batch endpoint nodig: je hebt een worker pool nodig die de rate limits respecteert, een retry regel voor HTTP 429, en een resultatenbestand waar je vanaf kunt hervatten. Deze gids bouwt alle drie met de OpenAI SDK die op je base URL wijst.

Bijgewerkt

Parallelle leidingen die datakubussen naar een verwerkingskern sturen, illustratie van gelijktijdige batchverzoeken in Python

Belangrijkste punten

  • De API heeft twee methoden, chat completions en modellen, dus batching wordt aan jouw kant gedaan met een pool van gelijktijdige verzoeken.
  • Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 per minuut toe; een proefsleutel staat 2 en 60 toe. Pas de grootte van je pool hierop aan.
  • Probeer opnieuw bij 429 met behulp van de Retry-After header, en onderscheid rate_limited van concurrency.
  • Schrijf elk resultaat naar een JSONL-bestand zodra het klaar is, zodat een crash slechts minuten werk kost en niet de hele run.

Hoe batching hier werkt

Het endpoint is OpenAI-compatible en exposeert POST /v1/chat/completions en GET /v1/models. Er is geen apart job-submission endpoint dat een bestand accepteert en later resultaten teruggeeft. Een batch is daarom een lus over normale verzoeken, gelijktijdig uitgevoerd, met de limieten ingebouwd in je code. Dat is eenvoudiger dan het klinkt, en het geeft je resultaten zodra ze klaar zijn in plaats van aan het einde.

De cijfers die het ontwerp bepalen zijn de limieten. Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 verzoeken per minuut toe. Een proefsleutel staat 2 gelijktijdige en 60 per minuut toe. De maximale request body is 8 MB. Een gestreamd verzoek houdt zijn concurrency slot vast tot de stream eindigt, dus zet streaming uit voor batchwerk.

Waarom niet gewoon alles in één keer versturen? Omdat een batch een throughput-probleem is met een plafond, en het plafond is van jou om te respecteren. Een lus die 5.000 verzoeken zo snel mogelijk verstuurt zoals Python ze kan aanmaken, krijgt een muur van 429-responses, verspillt tijd aan retries, en begraaft de nuttige fouten in ruis. Een pool die maximaal 8 verzoeken in vlucht houdt, houdt de lijn gaande op de snelheid die de service toelaat, en het is dezelfde code of je nu 50 rijen of 500.000 hebt. Plan voor drie onderdelen: een gebonden pool, één retry-regel, en een append-only resultatenbestand.

De model ID is uncensored, authenticatie is Authorization: Bearer <key>, en de base URL is https://api.unfilteredvideo.com/v1. Als je nog geen sleutel hebt, heeft de API key pagina een one-click $0.50 trial.

Installeren en instellen

Je hebt Python 3.9 of nieuwer en het officiële openai pakket nodig. Zet de sleutel in een omgevingsvariabele in plaats van in het 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"

De model lijst moet uncensored tonen. Bereid nu je input voor als een JSONL-bestand, één object per regel met een id en de tekst om te verwerken. De id is wat je later laat hervatten.

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

Een thread pool die binnen de limieten blijft

Voor de meeste scripts is een ThreadPoolExecutor de kortste weg. De OpenAI client is veilig om te delen tussen threads, en het werk is netwerkgebonden, dus threads passen. Stel de poolgrootte in op je concurrency limiet, niet hoger: extra workers verzamelen alleen 429 fouten.

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()

Deze versie heeft geen retry en geen resume, dus het is een startpunt. De client wordt aangemaakt met max_retries=0 op de client omdat de SDK standaard zelf retryt, en je wilt één plek die de retry-regel bezit. De volgende twee secties voegen die regel en de resume logica toe.

429 op de juiste manier afhandelen

Er zijn drie soorten 429 op deze API, en ze vragen om licht verschillende reacties:

  • rate_limited: je hebt te veel verzoeken in een minuut verstuurd. Vertraag. Een pool met minder workers, of een korte sleep, lost het op.
  • concurrency: er waren te veel verzoeken tegelijk in vlucht. Je pool is groter dan je limiet, of je hebt open streams die je bent vergeten.
  • Tijdelijke overbelasting: een 429 met een Retry-After: 5 header. Er is niets mis met je code. Wacht de opgegeven tijd en probeer het opnieuw.

Eén retry helper dekt alle drie. Het wacht op Retry-After als die aanwezig is en anders trekt het exponentieel terug met een kleine jitter. Mislukte en geweigerde verzoeken worden niet in rekening gebracht, dus opnieuw proberen is gratis.

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)

Probeer niet blindelings bij elke fout opnieuw. Een 400 betekent dat je verzoek verkeerd is, bijvoorbeeld een body boven de 8 MB of een slecht gevormd bericht, en het opnieuw versturen zal op dezelfde manier falen. Log het met de row id en ga verder.

Een async versie met een semaphore

Als je script al in een event loop draait, of je wilt een web service voeden, gebruik dan AsyncOpenAI en een asyncio.Semaphore die in-flight verzoeken beperkt. De semaphore speelt de rol van de pool grootte.

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())

Wikkel de functieaanroep in dezelfde retry-logica als hierboven, met behulp van await asyncio.sleep in plaats van time.sleep. Een waarschuwing: gather met tienduizenden coroutines maakt ze allemaal tegelijk aan. Voor zeer grote inputs verwerk je het bestand in slices van een paar duizend rijen.

Maak de run hervatbaar

Lange jobs falen op saaie manieren: een laptop gaat in slaapstand, een verbinding valt weg, je drukt op Ctrl+C. Omdat elke voltooide rij wordt toegevoegd aan output.jsonl met zijn id, betekent hervatten id's overslaan die je al hebt.

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")

Voer todo in aan een van beide pools hierboven. Open het uitvoerbestand in append mode, nooit write mode, anders wist een restart je voortgang. Schrijf ook fouten naar een tweede bestand, errors.jsonl, zodat je alleen de mislukkingen opnieuw kunt uitvoeren na het lezen van de oorzaak.

Voor herhaalbare output over reruns heen, geef een vaste seed mee samen met een lage temperature. De seed wordt doorgegeven aan het model samen met top_p, stop en de penalties.

Eerst testen op een kleine slice

Voer 20 rijen uit voordat je 20.000 uitvoert. Kies rijen die je ergste gevallen bevatten: de langste input, één met vreemde tekens, één die leeg is. Lees de outputs met het oog, controleer of usage overeenkomt met je kosteninschatting, en bevestig dat de retry helper zich gedraagt door tijdelijk het aantal workers boven je limiet te verhogen. Je zou een 429 moeten zien met de code concurrency in de log, een wacht, en een succesvolle retry. Het is beter om dat op 20 rijen te zien dan het te ontdekken bij rij 9.000.

Als de taak gestructureerde output nodig heeft, voeg dan JSON-modus toe met response_format={"type": "json_object"}, beschrijf de keys in de prompt en parse elke reply binnen een try-block. Tel de parse-mislukkingen tijdens de teststeekproef. Een percentage boven de één of twee procent betekent meestal dat de prompt een duidelijker schema nodig heeft, en dat is goedkoper om nu op te lossen dan om het later opnieuw uit te voeren. Rijen die niet kunnen worden geparsed gaan naar errors.jsonl met hun id, en de resume-logica behandelt ze als niet-klaar.

Stel tot slot een client-timeout in die past bij je langst verwachte output. De SDK accepteert timeout=60 op de client of per verzoek; een vastgelopen verzoek dat nooit terugkomt houdt anders een van je 8 slots vast zolang het daar blijft.

De pool dimensioneren en tijd schatten

De doorvoer wordt begrensd door twee dingen: de concurrency gedeeld door de tijd die één verzoek kost, en de requests-per-minute cap. Op een volledige sleutel is de cap 300 per minuut, wat 5 per seconde is. Als een typisch verzoek 2 seconden duurt, produceren 8 workers 8 / 2 = 4 verzoeken per seconde, of 240 per minuut, wat onder de cap ligt. Als verzoeken 1 seconde duren, zouden 8 workers proberen voor 8 per seconde en de cap raken, dus voeg een kleine vertraging toe of accepteer af en toe 429s die je retry-helper absorbeert.

Bij 4 per seconde nemen 10.000 rijen 2.500 seconden, ongeveer 42 minuten. Op een proefsleutel, met 2 gelijktijdige verzoeken en 60 per minuut, is het plafond 1 per seconde, dus dezelfde 10.000 rijen zouden 10.000 seconden duren, bijna 2 uur 47 minuten. In de praktijk zal het $0.50 proeftegoed daarvoor al op zijn, wat het een goede plek maakt om het script op een paar honderd rijen te testen en geen plek om productie uit te voeren.

Wat een grote batch kost

Prijzen zijn $0.15 per 1M input tokens en $0.50 per 1M output tokens. Neem een classificatie-style taak: 50.000 rijen, elk ongeveer 200 input tokens en 100 output tokens.

  • Input: 50.000 × 200 = 10.000.000 tokens, wat 10 × $0.15 = $1,50 is.
  • Output: 50.000 × 100 = 5.000.000 tokens, wat 5 × $0.50 = $2,50 is.
  • Totaal: $4,00, of $0,00008 per rij.

Het script hierboven registreert in en out voor elke rij, zodat je dezelfde figuur kunt berekenen vanuit je echte run. De X-Balance-USD response header toont ook resterend tegoed, en X-Request-Id is wat je moet citeren als je om hulp vraagt op de docs of support pagina's.

Tegoed wordt vooruitbetaald met opwaarderingen in hele dollars van $20 tot $500, met +5% vanaf $50, +10% vanaf $100 en +15% vanaf $200, betaald in crypto (USDT op TRC20 of USDC op Base). Het verloopt nooit. De prijspagina heeft de volledige details. Een opmerking voor gevoelige datasets: prompts worden niet gebruikt voor training.

Vragen en antwoorden

Heeft de API een batch-endpoint?

Nee. Het exposeert chat-completions en een model lijst. Je batch door vanuit je eigen code meerdere normale verzoeken gelijktijdig uit te voeren, binnen 8 gelijktijdige en 300 per minuut op een volledige sleutel.

Hoeveel threads moet ik gebruiken?

Gebruik 8 workers op een volledige sleutel en 2 op een proefsleutel, passend bij de concurrency limieten. Meer workers produceren alleen 429 fouten met de code concurrency.

Wat moet ik doen als ik HTTP 429 krijg?

Wacht op de Retry-After waarde als die er is, anders wacht je een paar seconden en probeer je het opnieuw. Mislukte verzoeken worden niet in rekening gebracht, dus opnieuw proberen kost niets.

Kan ik responses streamen in een batch-job?

Dat kan, maar dat moet je niet doen. Een gestreamd verzoek houdt zijn concurrency-slot vast tot de stream eindigt, wat de doorvoer verlaagt. Zet streaming uit voor batchwerk.

Je sleutel is nog maar één formulier verwijderd

Maak een account aan, kopieer de sleutel, pas de base URL aan. Dat is de hele setup.

API-sleutel aanvragen