DE ▾

Batch-Anfragen in Python für eine OpenAI-kompatible LLM-API

Für LLM-API-Batcharbeit in Python brauchst du keinen speziellen Batch-Endpunkt: Du brauchst einen Worker-Pool, der die Ratenlimits einhält, eine Retry-Regel für HTTP 429 und eine Ergebnisdatei, von der du fortsetzen kannst. Dieser Leitfaden baut alle drei Komponenten mit dem OpenAI SDK auf, das auf deine Basis-URL zeigt.

Aktualisiert

Parallele Leitungen, die Datenwürfel in einen Verarbeitungskern leiten, veranschaulichen parallele Batch-Anfragen in Python

Wichtige Punkte

  • Die API hat zwei Methoden, Chat-Vervollständigungen und Modelle, daher wird das Batching auf deiner Seite mit einem Pool paralleler Anfragen durchgeführt.
  • Ein vollständiger Schlüssel erlaubt 8 parallele Anfragen und 300 pro Minute; ein Test-Schlüssel erlaubt 2 und 60. Passe die Größe deines Pools entsprechend an.
  • Führe einen Retry bei 429 unter Verwendung des Retry-After-Headers durch und unterscheide die Ratenbegrenzung von der Parallelität.
  • Schreibe jedes Ergebnis in eine JSONL-Datei, sobald es fertig ist, damit ein Absturz nur Minuten kostet und nicht den gesamten Durchlauf.

So funktioniert Batching hier

Der Endpunkt ist OpenAI-kompatibel und bietet POST /v1/chat/completions und GET /v1/models an. Es gibt keinen separaten Endpunkt zur Auftragsübermittlung, der eine Datei entgegennimmt und später zurückgibt. Ein Batch ist daher eine Schleife über normale Anfragen, parallel ausgeführt, mit den Grenzen, die in deinem Code eingebaut sind. Das ist einfacher, als es klingt, und es liefert dir Ergebnisse, sobald sie fertig sind, statt erst am Ende.

Die Zahlen, die das Design bestimmen, sind die Limits. Ein vollständiger Schlüssel erlaubt 8 parallele Anfragen und 300 Anfragen pro Minute. Ein Test-Schlüssel erlaubt 2 parallel und 60 pro Minute. Der maximale Anforderungstext beträgt 8 MB. Eine gestreamte Anfrage belegt ihren Parallelitätsplatz, bis der Stream endet, also schalte für Batch-Arbeiten das Streaming aus.

Warum nicht einfach alles auf einmal abfeuern? Weil ein Batch ein Durchsatzproblem mit einer Obergrenze ist, und diese Obergrenze musst du respektieren. Eine Schleife, die 5.000 Anfragen so schnell sendet, wie Python sie erstellen kann, erhält eine Wand aus 429-Fehlerantworten, verschwendet Zeit bei Wiederholungen und begräbt die nützlichen Fehler im Rauschen. Ein Pool, der maximal 8 gleichzeitige Anfragen hält, lässt die Leitung mit der Geschwindigkeit weiterlaufen, die der Dienst erlaubt, und der Code ist derselbe, ob du 50 Zeilen oder 500.000 hast. Plane drei Dinge: einen begrenzten Pool, eine Wiederholungsregel und eine nur-append-Ergebnisdatei.

Die Modell-ID ist uncensored, die Authentifizierung ist Authorization: Bearer <key>, und die Base URL ist https://api.unfilteredvideo.com/v1. Falls du noch keinen Schlüssel hast, hat die API-Schlüssel-Seite ein Ein-Klick-$0,50-Testguthaben.

Installation und Einrichtung

Du benötigst Python 3.9 oder neuer und das offizielle openai-Paket. Lege den Schlüssel in einer Umgebungsvariable statt im Skript ab.

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"

Die Modellliste sollte uncensored anzeigen. Bereite nun deine Eingabe als JSONL-Datei vor, ein Objekt pro Zeile mit einer id und dem zu verarbeitenden Text. Die id ist das, was dir später das Fortsetzen ermöglicht.

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

Ein Thread-Pool, der innerhalb der Grenzen bleibt

Für die meisten Skripte ist ein ThreadPoolExecutor der kürzeste Weg. Der OpenAI-Client ist sicher zwischen Threads teilbar, und die Arbeit ist netzgebunden, daher passen Threads. Stelle die Poolgröße auf dein Concurrency-Limit ein, nicht höher: zusätzliche Worker sammeln nur 429-Fehler ein.

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

Diese Version hat keinen Retry und keine Fortsetzung, also ist sie ein Ausgangspunkt. Der Client wird mit max_retries=0 erstellt, da das SDK standardmäßig selbstständig wiederholt, und du möchtest eine Stelle, die die Retry-Regel besitzt. Die nächsten beiden Abschnitte fügen diese Regel und die Fortsetzungslogik hinzu.

Behandle 429 richtig

Es gibt drei Arten von 429 in dieser API, die leicht unterschiedliche Reaktionen erfordern:

  • rate_limited: Du hast zu viele Anfragen in einer Minute gesendet. Verlangsame. Ein Pool mit weniger Workern oder ein kurzer Sleep behebt das.
  • concurrency: Zu viele Anfragen waren gleichzeitig im Flug. Dein Pool ist größer als dein Limit, oder du hast offene Streams, die du vergessen hast.
  • Temporäre Überlastung: ein 429 mit einem Retry-After: 5-Header. An deinem Code ist nichts falsch. Warte die angegebene Zeit und versuche es erneut.

Ein einzelner Retry-Helfer deckt alle drei Fälle ab. Er wartet auf Retry-After, wenn vorhanden, und verzögert andernfalls exponentiell mit etwas Jitter. Fehlgeschlagene und abgelehnte Anfragen werden nicht berechnet, daher ist Wiederholen kostenlos.

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)

Wiederhole nicht blind bei jedem Fehler. Ein 400 bedeutet, dass deine Anfrage falsch ist, zum Beispiel ein Text über 8 MB oder eine fehlerhafte Nachricht, und das erneute Senden wird auf dieselbe Weise fehlschlagen. Logge es mit der Zeilen-ID und fahre fort.

Eine Async-Version mit einem Semaphore

Wenn dein Skript bereits in einer Event-Schleife läuft oder du einen Webdienst speisen möchtest, verwende AsyncOpenAI und ein asyncio.Semaphore, das die Anzahl der gleichzeitig laufenden Anfragen begrenzt. Das Semaphore übernimmt die Rolle der Pool-Größe.

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

Verpacke den Aufruf in dieselbe Retry-Logik wie oben, verwende anstelle von time.sleep await asyncio.sleep. Eine Vorsicht: gather mit zehntausenden Coroutinen erstellt sie alle auf einmal. Verarbeite bei sehr großen Eingaben die Datei in Slices von einigen tausend Zeilen.

Den Durchlauf fortsetzbar machen

Lange Jobs fallen auf langweilige Weise aus: Ein Laptop schläft ein, eine Verbindung bricht ab, du drückst Strg+C. Da jede fertige Zeile mit ihrer id an output.jsonl angehängt wird, bedeutet Fortsetzen, IDs zu überspringen, die du bereits hast.

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

Füttere todo in einen der beiden Pools. Öffne die Ausgabedatei im Append-Modus, niemals im Schreibmodus, sonst wird bei einem Neustart dein Fortschritt gelöscht. Schreibe auch Fehler in eine zweite Datei, errors.jsonl, damit du nur die Fehlschläge erneut ausführen kannst, nachdem du gelesen hast, warum sie fehlgeschlagen sind.

Für wiederholbare Ausgaben bei Wiederholungen übergebe einen festen seed zusammen mit einem niedrigen temperature. Der Seed wird zusammen mit top_p, stop und den Strafen an das Modell weitergegeben.

Zuerst an einem kleinen Ausschnitt testen

Führe 20 Zeilen aus, bevor du 20.000 ausführst. Wähle Zeilen, die deine Worst-Case-Szenarien enthalten: die längste Eingabe, eine mit seltsamen Zeichen, eine, die leer ist. Lies die Ausgaben mit den Augen, prüfe, ob usage deiner Kostenschätzung entspricht, und bestätige das Verhalten des Retry-Helfers, indem du die Worker-Anzahl vorübergehend über dein Limit erhöhst. Du solltest eine 429 mit dem Code concurrency im Log sehen, eine Wartezeit und einen erfolgreichen Retry. Es ist besser, das auf 20 Zeilen zu sehen, als es bei Zeile 9.000 zu entdecken.

Wenn der Job strukturierte Ausgaben benötigt, füge den JSON-Modus mit response_format={"type": "json_object"} hinzu, beschreibe die Schlüssel im Prompt und analysiere jede Antwort innerhalb eines try-Blocks. Zähle Parsing-Fehler während des Test-Slices. Eine Rate über einem oder zwei Prozent bedeutet normalerweise, dass der Prompt ein klareres Schema benötigt, und das ist jetzt günstiger zu beheben als später erneut auszuführen. Zeilen, die nicht geparst werden können, gehen mit ihrer ID in errors.jsonl, und die Fortsetzungslogik behandelt sie als nicht erledigt.

Lege schließlich ein Client-Timeout fest, das zu deiner längsten erwarteten Ausgabe passt. Das SDK akzeptiert timeout=60 auf dem Client oder pro Anfrage; eine steckengebliebene Anfrage, die nie zurückkehrt, belegt sonst einen deiner 8 Slots, solange sie dort sitzt.

Pool-Größe dimensionieren und Zeit schätzen

Der Durchsatz wird durch zwei Dinge begrenzt: Parallelität geteilt durch die Zeit, die eine Anfrage benötigt, und die Anfragen-pro-Minute-Grenze. Bei einem vollständigen Schlüssel beträgt das Limit 300 pro Minute, also 5 pro Sekunde. Wenn eine typische Anfrage 2 Sekunden dauert, produzieren 8 Worker 8 / 2 = 4 Anfragen pro Sekunde oder 240 pro Minute, was unter dem Limit liegt. Wenn Anfragen 1 Sekunde dauern, würden 8 Worker 8 pro Sekunde versuchen und das Limit erreichen, also füge eine kleine Verzögerung hinzu oder akzeptiere gelegentliche 429, die dein Wiederholungshelfer absorbiert.

Mit 4 pro Sekunde dauern 10.000 Zeilen 2.500 Sekunden, etwa 42 Minuten. Mit einem Testguthaben, 2 gleichzeitigen Anfragen und 60 pro Minute liegt die Obergrenze bei 1 pro Sekunde, sodass die gleichen 10.000 Zeilen 10.000 Sekunden, fast 2 Stunden und 47 Minuten dauern würden. In der Praxis geht das $0,50-Testguthaben vorher aus, was es zu einem guten Ort macht, um das Skript an einigen hundert Zeilen zu testen, und nicht zu einem Ort für die Produktion.

Was ein großer Batch kostet

Die Preise betragen $0,15 pro 1M Input-Token und $0,50 pro 1M Output-Token. Nimm einen Job im Klassifizierungsstil: 50.000 Zeilen, jede etwa 200 Input-Token und 100 Output-Token.

  • Input: 50.000 × 200 = 10.000.000 Token, was 10 × $0,15 = $1,50 entspricht.
  • Output: 50.000 × 100 = 5.000.000 Token, was 5 × $0,50 = $2,50 entspricht.
  • Gesamt: $4,00 oder $0,00008 pro Zeile.

Das obige Skript zeichnet in und out für jede Zeile auf, sodass du dieselbe Zahl aus deiner echten Ausführung berechnen kannst. Der Response-Header X-Balance-USD zeigt auch das verbleibende Guthaben an, und X-Request-Id ist das, was du zitieren solltest, wenn du auf den Support-Seiten oder im docs um Hilfe bittest.

Das Guthaben wird in ganzen Dollar-Aufladungen von $20 bis $500 vorausbezahlt, mit +5% ab $50, +10% ab $100 und +15% ab $200, bezahlt in Krypto (USDT auf TRC20 oder USDC auf Base). Es verfällt nie. Die Preisseite enthält die vollständigen Details. Ein Hinweis für sensible Datensätze: Prompts werden nicht zum Training verwendet.

Fragen und Antworten

Hat die API einen Batch-Endpunkt?

Nein. Es bietet Chat-Vervollständigungen und eine Modellliste. Du führst Batches aus, indem du viele normale Anfragen parallel aus deinem eigenen Code heraus ausführst, innerhalb von 8 parallelen Anfragen und 300 pro Minute bei einem Vollschlüssel.

Wie viele Threads sollte ich verwenden?

Verwende 8 Worker auf einem Vollschlüssel und 2 auf einem Versuchsschlüssel, angepasst an die Parallelitätslimits. Mehr Worker erzeugen nur 429-Fehler mit dem Code concurrency.

Was soll ich tun, wenn ich HTTP 429 erhalte?

Warte auf den Retry-After-Wert, falls die Antwort einen enthält, andernfalls warte einige Sekunden und versuche es erneut. Fehlgeschlagene Anfragen werden nicht berechnet, daher kostet das Wiederholen nichts.

Kann ich Antworten in einem Batch-Job streamen?

Du kannst, aber du solltest es nicht. Eine gestreamte Anfrage belegt ihren Parallelitätsplatz, bis der Stream endet, was den Durchsatz verringert. Lass das Streaming für Batch-Arbeit ausgeschaltet.

Dein Schlüssel ist nur einen Schritt entfernt

Erstelle ein Konto, kopiere den Schlüssel, ändere die Basis-URL. Das ist die gesamte Einrichtung.

API-Schlüssel erhalten