Batch-Inferenz

Die Batch API für Large Language Models ermöglicht die asynchrone Verarbeitung zahlreicher Inferenzanfragen und ist vollständig mit dem OpenAI API-Standard kompatibel. Die Batch API ist eine kosteneffiziente Lösung, wenn sofortige Inferenzergebnisse nicht erforderlich sind. Sie bietet höhere Ratenlimits als Online-Aufrufe und stellt sicher, dass Ergebnisse innerhalb eines angemessenen Zeitrahmens von 24 Stunden bereitgestellt werden. Diese API ist ideal für:

Durchführen von Auswertungen und Datenanalysen.
Klassifizieren umfangreicher Datensätze.
Generieren von Dokumentzusammenfassungen im Offline-Modus.

Unterstützte Modelle:

Schnellstart

1. Batch-Dateien vorbereiten

Die Batch API verwendet Dateien im .jsonl-Format als Eingabe, wobei jede Zeile die Details einer API-Inferenzanfrage darstellt. Verfügbare Endpunkte umfassen /v1/chat/completions und /v1/completions.

Setzen Sie den Parameter endpoint auf /v1/chat/completions oder /v1/completions für OpenAI API-Kompatibilität.

Jede Anfrage muss eine eindeutige custom_id enthalten, um die Inferenzergebnisse nach Abschluss des Batchs in der Ausgabedatei zu finden. Parameter im Feld body jeder Zeile werden als tatsächliche Inferenzanfrageparameter an den Endpunkt gesendet.

Alle Anfragen innerhalb einer einzelnen Batch-JSONL-Datei müssen dasselbe Modell adressieren. Mischen Sie keine Anfragen für unterschiedliche Modelle in einem Batch.

Unten sehen Sie eine Beispiel-Eingabedatei mit 2 Anfragen:

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. Batch-Eingabedatei hochladen

Laden Sie die Batch-Eingabedatei hoch, um sicherzustellen, dass sie beim Erstellen eines Batchs korrekt referenziert werden kann. Verwenden Sie die Files API, um Ihre .jsonl-Datei hochzuladen, und setzen Sie den Zweck auf batch. Beachten Sie, dass die Datei 15 Tage lang aufbewahrt wird.

Informationen zum Abrufen eines API-Schlüssels finden Sie unter API-Schlüsselverwaltung.

Codebeispiel Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

Beispielantwort nach erfolgreichem Datei-Upload:

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. Einen Batch erstellen

Sobald die Eingabedatei erfolgreich hochgeladen wurde, können Sie einen Batch mit der ID des hochgeladenen File-Objekts starten. Das Abschlussfenster ist fest auf 24h gesetzt und derzeit nicht anpassbar. Codebeispiel Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

Diese Anfrage gibt ein Batch-Objekt zurück, das Metadaten zu Ihrem Batch enthält, wie im folgenden Beispiel dargestellt:

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. Status eines Batchs prüfen

Sie können den Status eines Batchs jederzeit prüfen, um die neuesten Batch-Informationen zu erhalten. Die Status-Enumerationswerte des Batch-Objekts lauten wie folgt:

Status	Beschreibung
VALIDATING	Die Eingabedatei wird validiert, bevor der Batch beginnen kann
PROGRESS	Batch wird ausgeführt
COMPLETED	Batch-Verarbeitung erfolgreich abgeschlossen
FAILED	Batch-Verarbeitung fehlgeschlagen
EXPIRED	Batch hat die Frist überschritten
CANCELLING	Batch wird abgebrochen
CANCELLED	Batch wurde abgebrochen

Codebeispiel Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. Ergebnisse abrufen

Sobald die Batch-Inferenz abgeschlossen ist, können Sie die Ergebnis-Ausgabedatei über das Feld output_file_id aus dem Batch-Objekt herunterladen. Die Ergebnis-Ausgabedatei wird 30 Tage nach Abschluss der Batch-Inferenz gelöscht. Rufen Sie sie daher bitte zeitnah über die Schnittstelle ab. Codebeispiel Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

Die Antwort gibt den rohen Dateiinhalt zurück. Bei Batch-Ausgabedateien enthält jede Zeile eine Antwort wie diese:

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

Anweisungen

Einschränkungen

Jeder Batch kann bis zu 50.000 Anfragen enthalten.
Die maximale Eingabedateigröße pro Batch beträgt 100 MB.

Fehlerbehandlung

Fehler, die während der Batch-Verarbeitung auftreten, werden in einer separaten Fehlerdatei aufgezeichnet, die über das Feld error_file_id zugänglich ist. Häufige Fehlercodes umfassen:

Fehlercode	Beschreibung	Lösung
400	Ungültiges Anfrageformat	JSONL-Syntax und erforderliche Felder prüfen
401	Authentifizierung fehlgeschlagen	API-Schlüssel überprüfen
404	Batch nicht gefunden	Batch-ID prüfen
429	Ratenlimit überschritten	Anfragehäufigkeit reduzieren
500	Serverfehler	Kontaktieren Sie uns

Batch-Ablauf

Batchs, die nicht innerhalb von 24 Stunden abgeschlossen werden, wechseln in den Status EXPIRED. Nicht abgeschlossene Anfragen werden abgebrochen, während abgeschlossene Anfragen über eine Ausgabedatei bereitgestellt werden. Sie zahlen nur für Tokens, die von abgeschlossenen Anfragen verbraucht wurden. Der Batch unternimmt alle Anstrengungen, um innerhalb von 24 Stunden abgeschlossen zu werden.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Schnellstart

1. Batch-Dateien vorbereiten

2. Batch-Eingabedatei hochladen

3. Einen Batch erstellen

4. Status eines Batchs prüfen

5. Ergebnisse abrufen

Anweisungen

Einschränkungen

Fehlerbehandlung

Batch-Ablauf

Alle Batch APIs

​Schnellstart

​1. Batch-Dateien vorbereiten

​2. Batch-Eingabedatei hochladen

​3. Einen Batch erstellen

​4. Status eines Batchs prüfen

​5. Ergebnisse abrufen

​Anweisungen

​Einschränkungen

​Fehlerbehandlung

​Batch-Ablauf

​Alle Batch APIs

Schnellstart

1. Batch-Dateien vorbereiten

2. Batch-Eingabedatei hochladen

3. Einen Batch erstellen

4. Status eines Batchs prüfen

5. Ergebnisse abrufen

Anweisungen

Einschränkungen

Fehlerbehandlung

Batch-Ablauf

Alle Batch APIs