Entwickler haben oft mit langsamen Antwortzeiten und hohen Netzwerkkosten zu kämpfen, wenn sie Tausende separater API-Aufrufe senden. Die Batch-API löst dieses Problem, indem sie mehrere unabhängige Anfragen zu einem einzigen Vorgang zusammenfasst, was Latenz, Bandbreitennutzung und Verbindungs-Overhead reduziert.
Dieser Artikel erklärt, was die Batch-API ist, wie sie sich von Standard-APIs unterscheidet und wie Novita AIs Batch-API großangelegte asynchrone Inferenz durch strukturierte JSONL-Eingaben, effiziente Dateiverarbeitung und zuverlässige Fehlerverfolgung ermöglicht. Außerdem werden wichtige Effizienzfaktoren wie Kosten, Latenz und Durchsatz erläutert sowie eine kurze Anleitung zu Implementierung und Überwachung bereitgestellt.
[Testen Sie Batch-Inferenz mit 50 % Rabatt
Führen Sie großangelegte Vorhersagen schneller und günstiger mit unterstützten Modellen durch:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8.](https://novita.ai/docs/guides/llm-batch-api)
Testen Sie Batch-Inferenz mit 50 % Rabatt
Führen Sie großangelegte Vorhersagen schneller und günstiger mit unterstützten Modellen durch:
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
Was ist die Batch-API？
Batch-API: Fasst mehrere unabhängige API-Aufrufe (z. B. GET, POST, PUT, DELETE) zu einer einzigen HTTP-Anfrage zusammen.
Antwortstruktur: Der Server gibt die Ergebnisse aller Teil-Anfragen in Reihenfolge zurück und gibt für jede den Erfolg oder Fehler an.
Wichtiger Unterschied zwischen Batch-API und Standard-API
Normale Anfragen
Client
├──► Request 1 (/user/1)
│ └──► Server Response 1
├──► Request 2 (/user/2)
│ └──► Server Response 2
└──► Request 3 (/order)
└──► Server Response 3
Batch-Anfrage
Client
└──► Single Request (/batch)
├─ Sub-request 1: GET /user/1
├─ Sub-request 2: GET /user/2
└──► Sub-request 3: POST /order
↓
Server processes all
↓
Combined Response:
[Result1, Result2, Result3]
Die Batch-API kann helfen:
Netzwerklatenz reduzieren, indem eine einzige kombinierte Anfrage statt vieler einzelner gesendet wird.
Bandbreite und Verbindungs-Overhead senken, da Header und Handshakes gemeinsam genutzt werden.
Client-Performance verbessern, insbesondere auf Mobilgeräten oder langsamen Netzwerken.
Transaktionslogik vereinfachen, indem einheitliche Fehlerbehandlung oder Rollbacks ermöglicht werden.
API-Gateway-Durchsatz optimieren, um Anfragefluten zu verhindern.
Typische Anwendungsfälle der Batch-API
| Szenario | Beschreibung |
|---|---|
| 1. Massenabfragen | Rufen Sie mehrere Benutzer, Produkte oder Beiträge auf einmal ab, um wiederholte Anfragen zu vermeiden. |
| 2. Massenschreib- oder -aktualisierungsvorgänge | Erstellen oder aktualisieren Sie mehrere Datensätze in einem einzigen Vorgang (z. B. Batch-Upload, Bestandsaktualisierung). |
| 3. Frontend-Performance-Optimierung | Reduzieren Sie die Anzahl der HTTP-Aufrufe von Browsern oder mobilen Apps für schnellere Ladezeiten. |
| 4. Backend-Aufgabenaggregation | Führen Sie in Microservice-Systemen mehrere interne API-Aufrufe zu einem einzigen externen Aufruf zusammen. |
| 5. Datensynchronisation | Synchronisieren Sie den Status mehrerer Ressourcen oder führen Sie Batch-Vorgänge durch (z. B. Tagging, Löschung). |
| 6. Rate-Limit-Optimierung | Senken Sie die Last des API-Gateways und sparen Sie Bandbreite, indem Sie Anfragen zusammenfassen. |
Wichtige Faktoren für die Effizienz der Batch-API
Wie viel Kosten können Batch-APIs im Vergleich zu Echtzeit-APIs einsparen? Branchenanalysen (Growth-onomics) zeigen Kosteneinsparungen von etwa 20–45 %, die hauptsächlich aus weniger Netzwerk-Roundtrips, geringerem Verbindungs-Overhead und konzentrierter Verarbeitung resultieren. Die genauen Einsparungen hängen jedoch von der Aufrufhäufigkeit, der Batch-Größe und dem Systemdesign ab.
Was ist mit der Latenz – können Batch-APIs wirklich „innerhalb von 24 Stunden“ abgeschlossen werden? Batch-APIs werden normalerweise asynchron ausgeführt und haben eine deutlich höhere Latenz als Echtzeit-APIs. Viele Systeme führen stündlich oder täglich aus, also hängt „innerhalb von 24 Stunden“ von der SLA ab und ist nicht garantiert.
Beeinflussen Batch-Größe oder Dateigröße die Geschwindigkeit? Ja. Größere Batches (z. B. mehr JSONL-Zeilen) erhöhen Übertragungs- und Parsing-Zeit fast linear; während der Durchsatz steigt, wächst die gesamte Abschlusszeit pro Batch.
Warum sind Batch-APIs besser für Arbeitslasten mit hohem Durchsatz geeignet? Durch die Aggregation von Tausenden von Anfragen zu einem einzigen Vorgang reduzieren Batch-APIs den Overhead pro Aufruf und ermöglichen parallele Ausführung oder Wiederverwendung von Caches, was den Durchsatz bei großangelegten Vorgängen oft um 17–92 % verbessert. Dies geht jedoch mit höherer Latenz einher.
Wie verwendet man die Batch-API？
Novitas Batch-API ist hochkompatibel mit der OpenAI-Schnittstelle und unterstützt
/v1/chat/completionssowie/v1/completions, sodass vorhandener Code mit minimalen Änderungen wiederverwendet werden kann. Sie akzeptiert.jsonl-Eingabedateien, bei denen jede Zeile eine einzelne Anfrage an dasselbe Modell darstellt, die durch eine eindeutigecustom_idzur einfachen Nachverfolgung identifiziert wird. Die Ausgabe ist ebenfalls im JSONL-Format, was die großangelegte Nachverarbeitung, Analyse und Integration einfach und effizient macht.
1. Bereiten Sie Ihre Batch-Eingabedatei vor
Erstellen Sie eine .jsonl-Datei, in der jede Zeile eine einzelne API-Anfrage im JSON-Format ist.
Beispiel (batch_input.jsonl):
{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}
Regeln:
- Eine Anfrage pro Zeile.
- Alle Anfragen müssen dasselbe Modell verwenden.
- Jede Zeile muss eine eindeutige
custom_identhalten.
2. Laden Sie die Eingabedatei hoch und erstellen Sie einen Batch Verwenden Sie Python oder curl, um die Datei hochzuladen und den Batch-Job sofort zu starten.
Python
from openai import OpenAI
client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")
# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="48h"
)
print("file_id:", uploaded.id)
print("batch_id:", batch.id)
curl
export API_KEY="YOUR_API_KEY"
# Upload file
upload_response=$(curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@batch_input.jsonl' -F 'purpose=batch' \
https://api.novita.ai/openai/v1/files)
# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')
curl -X POST https://api.novita.ai/openai/v1/batches \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"
Überprüfen Sie Ihren API-Schlüssel
3. Überprüfen Sie den Batch-Status Sie können den Fortschritt jederzeit anhand der Batch-ID überprüfen.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
Status umfassen:
VALIDATING– Eingabedatei wird überprüftPROGRESS– läuftCOMPLETED– erfolgreich abgeschlossenFAILED– fehlgeschlagenEXPIRED– 48-Stunden-Fenster überschritten
4. Ergebnisse abrufen
Nach Abschluss laden Sie die Ergebnisdatei über output_file_id herunter:
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
Jede Zeile in der Ausgabe entspricht einer Eingabe, abgeglichen über die custom_id.
Tipps:
Es wird nur
deepseek/deepseek-r1-0528unterstütztBis zu 50 000 Anfragen pro Batch
Eingabedatei ≤ 100 MB
Abschlussfenster fest auf 48 Stunden
Ausgabe wird für 30 Tage aufbewahrt
Wie sollten fehlgeschlagene Anfragen in einer Batch-API behandelt werden?
Fehler, die während der Batch-Verarbeitung auftreten, werden in einer separaten Fehlerdatei protokolliert, auf die über das Feld error_file_id zugegriffen werden kann. Jede fehlgeschlagene Teil-Anfrage enthält einen Fehlercode und eine Beschreibung. Häufige Beispiele:
| Fehlercode | Beschreibung | Lösung |
|---|---|---|
| 400 | Ungültiges Anfrageformat | Überprüfen Sie die JSONL-Syntax und erforderliche Felder |
| 401 | Authentifizierung fehlgeschlagen | Überprüfen Sie den API-Schlüssel |
| 404 | Batch nicht gefunden | Überprüfen Sie die Batch-ID |
| 429 | Rate-Limit überschritten | Reduzieren Sie die Anfragehäufigkeit |
| 500 | Serverfehler | Kontaktieren Sie den Anbieter oder versuchen Sie es später erneut |
Entwickler sollten nur die fehlgeschlagenen Einträge mithilfe einer Wiederholungswarteschlange oder eines kleineren Folge-Batches erneut verarbeiten, anstatt die gesamte ursprüngliche Datei erneut einzureichen.
Welche Endpunkte stellt Novita AI für Batch-API-Vorgänge bereit?
| Endpunkt | Zweck |
|---|---|
| Batch erstellen | Einen neuen Batch-Job mit mehreren Anfragen einreichen. |
| Batch abrufen | Den Status oder die Ergebnisse eines bestimmten Batches anhand seiner ID abrufen. |
| Batch abbrechen | Einen laufenden Batch-Job vor Abschluss stoppen. |
| Batch auflisten | Alle eingereichten Batch-Jobs für das Konto auflisten. |
| Datei hochladen | Eingabedatendateien (z. B. JSONL) hochladen. |
| Dateien auflisten | Alle hochgeladenen Dateien anzeigen. |
| Datei abrufen | Dateimetadaten anhand der Datei-ID abrufen. |
| Datei löschen | Eine hochgeladene Datei entfernen. |
| Dateiinhalt abrufen | Den tatsächlichen Inhalt einer Datei herunterladen (z. B. Ergebnisse oder Fehlerprotokoll). |
Die Batch-API fasst viele kleine Anfragen zu einem effizienten Workflow zusammen. Durch die Verwendung von Novita AIs Batch-API können Entwickler Netzwerkkosten um bis zu 45 % senken, den Durchsatz auf bis zu 50 000 Anfragen pro Batch skalieren und die Fehlerbehandlung durch integrierte Protokollierungs- und Abrufendpunkte vereinfachen. Auch wenn sie Echtzeitgeschwindigkeit opfert, bietet sie außergewöhnliche Effizienz für Masseninferenz, Synchronisation und Datenverarbeitungs-Arbeitslasten.
Novita AI ist eine KI-Cloud-Plattform, die Entwicklern eine einfache Möglichkeit bietet, KI-Modelle über unsere einfache API bereitzustellen, und gleichzeitig eine erschwingliche und zuverlässige GPU-Cloud zum Erstellen und Skalieren bereitstellt.
