Erste Schritte mit Azure OpenAI-Batchbereitstellungen

Die Azure OpenAI-Batch-API wurde entwickelt, um umfangreiche und umfangreiche Verarbeitungsaufgaben effizient zu verarbeiten. Verarbeiten Sie asynchrone Gruppen von Anforderungen mit separatem Kontingent mit 24-Stunden-Zielumlaufzeit bei 50% weniger Kosten als globaler Standard. Bei der Batchverarbeitung senden Sie nicht gleichzeitig eine Anforderung, sondern eine große Anzahl von Anforderungen in einer einzelnen Datei. Globale Batchanforderungen verfügen über ein separates enqueuiertes Tokenkontingent, um Unterbrechungen Ihrer Online-Workloads zu vermeiden.

Zu den wichtigsten Anwendungsfällen gehören:

  • Large-Scale-Datenverarbeitung: Analysieren Sie umfangreiche Datensätze schnell und parallel.

  • Inhaltsgenerierung: Erstellen Sie große Textmengen, z. B. Produktbeschreibungen oder Artikel.

  • Dokumentüberprüfung und Zusammenfassung: Automatisieren Sie die Überprüfung und Zusammenfassung von langwierigen Dokumenten.

  • Automatisierung des Kundensupports: Behandeln Sie zahlreiche Abfragen gleichzeitig für schnellere Antworten.

  • Datenextraktion und -analyse: Extrahieren und analysieren Sie Informationen aus großen Mengen unstrukturierter Daten.

  • NlP-Aufgaben (Natural Language Processing): Führen Sie Aufgaben wie die Stimmungsanalyse oder übersetzung in großen Datasets aus.

  • Marketing und Personalisierung: Generieren Sie personalisierte Inhalte und Empfehlungen im großen Maßstab.

Tipp

Wenn Ihre Batchaufträge so groß sind, dass Sie den Grenzwert für eingereihte Token auch nach dem Ausschöpfen des Kontingents für Ihre Bereitstellung erreichen, unterstützen einige Regionen jetzt eine neue Funktion, mit der Sie mehrere Batchaufträge mit exponentiellem Backoff in die Warteschlange stellen können.

Sobald Ihr Enqueued-Tokenkontingent verfügbar ist, kann der nächste Batchauftrag erstellt und automatisch gestartet werden. Weitere Informationen finden Sie unter Automatisieren von Wiederholversuchen großer Batch-Jobs mit exponentiellem Backoff.

Wichtig

Wir zielen darauf ab, Batchanforderungen innerhalb von 24 Stunden zu verarbeiten; die Aufträge, die länger dauern, laufen nicht ab. Sie können den Auftrag jederzeit abbrechen . Wenn Sie den Auftrag abbrechen, werden alle verbleibenden Arbeiten abgebrochen, und alle bereits abgeschlossenen Arbeiten werden zurückgegeben. Sie werden für alle abgeschlossenen Arbeiten in Rechnung gestellt.

Gespeicherte ruhende Daten verbleiben in der angegebenen Azure-Geografie, während Daten für Rückschlüsse an einem beliebigen Azure OpenAI-Standort verarbeitet werden können.  Erfahren Sie mehr über die Datenresidenz. 

Batchunterstützung

Verfügbarkeit des globalen Batchmodells

Region gpt-5.1, 2025-11-13 gpt-5, 2025-08-07 o3, 2025-04-16 o4-mini, 2025-04-16 gpt-4.1, 2025-04-14 gpt-4.1-nano, 2025-04-14 gpt-4.1-mini, 2025-04-14 o3-mini, 2025-01-31 gpt-4o, 2024-05-13 gpt-4o, 2024-08-06 gpt-4o, 2024-11-20 gpt-4o-mini, 2024-07-18
australiaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
brazilsouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
canadaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
centralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Deutschland Westzentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
japaneast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
koreacentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
norwayeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Polenzentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
südafricanorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Südindien ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
schwedencentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
schweiznord ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Westeuropa ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

Die Registrierung ist für den Zugriff auf gpt-5 und o3. Weitere Informationen finden Sie im Leitfaden zu Gründen von Modellen.

Hinweis

Während der globale Batch ältere API-Versionen unterstützt, erfordern einige Modelle neuere API-Versionen. Beispielsweise wird o3-mini nicht mit 2024-10-21 unterstützt, da es nach diesem Datum veröffentlicht wurde. Verwenden Sie die v1-API, um auf neuere Modelle mit globalen Batch zuzugreifen.

Featureunterstützung

Folgendes wird derzeit nicht unterstützt:

  • Integration in die Assistenten-API.
  • Integration mit Azure OpenAI On Your Data Feature.

Batchbereitstellung

Hinweis

Im Microsoft Foundry-Portal werden die Batchbereitstellungstypen als Global-Batch und Data Zone Batch angezeigt. Weitere Informationen zu Azure OpenAI-Bereitstellungstypen finden Sie im Leitfaden zu Deployment-Typen.

Tipp

Es wird empfohlen, das dynamische Kontingent für alle globalen Batchmodellimplementierungen zu aktivieren, um Auftragsfehler aufgrund unzureichender Kontingente für Token in der Warteschlange zu vermeiden. Bei der Verwendung dynamischer Kontingente kann Ihre Bereitstellung gegebenenfalls mehr Kontingente nutzen, wenn eine zusätzliche Kapazität zur Verfügung steht. Wenn das dynamische Kontingent deaktiviert ist, kann Ihre Bereitstellung nur Anforderungen bis zum enqueuierten Tokenlimit verarbeiten, das beim Erstellen der Bereitstellung definiert wurde.

Voraussetzungen

  • Ein Azure-Abonnement – Create one for free.
  • Eine Ressource mit einem Modell des Bereitstellungstyps GlobalBatch oder DataZoneBatch wurde bereitgestellt.

Vorbereiten der Batchdatei

Wie bei der Feinabstimmung verwendet Batch Dateien im JSON-Zeilen.jsonl-Format. Im Folgenden finden Sie einige Beispieldateien mit unterschiedlichen Typen von unterstützten Inhalten:

Eingabeformat

Antwort-API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API für Chatabschlusse

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

Dies custom_id ist erforderlich, damit Sie ermitteln können, welche einzelne Batchanforderung einer bestimmten Antwort entspricht. Antworten werden nicht in identischer Reihenfolge zurückgegeben, die in der .jsonl Batchdatei definiert ist.

model Attribut sollte so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, auf die Sie für Rückschlussantworten abzielen möchten.

Wichtig

Das model Attribut muss so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, die Sie für Rückschlussantworten verwenden möchten. Derselbe Globale Batchmodellbereitstellungsname muss in jeder Zeile der Batchdatei vorhanden sein. Wenn Sie auf eine andere Bereitstellung abzielen möchten, müssen Sie dies in einer separaten Batchdatei/einem separaten Batchauftrag tun.

Um eine optimale Leistung zu erzielen, empfehlen wir, große Dateien für die Batchverarbeitung zu übermitteln, anstatt eine große Anzahl kleiner Dateien mit nur wenigen Zeilen in jeder Datei.

Erstellen einer Eingabedatei

Für diesen Artikel erstellen wir eine Datei mit dem Namen test.jsonl und kopieren den Inhalt aus standardmäßigem Eingabecodeblock oben in die Datei. Sie müssen den Namen Ihrer globalen Batchbereitstellung ändern und jeder Zeile der Datei hinzufügen.

Batchauftrag erstellen

Nachdem Ihre Eingabedatei vorbereitet wurde, müssen Sie die Datei zuerst hochladen, um dann einen Batchauftrag initiieren zu können. Der Dateiupload kann sowohl programmgesteuert als auch über das Microsoft Foundry-Portal erfolgen. In diesem Beispiel wird das direkte Hochladen einer Datei in Ihre Azure OpenAI-Ressource veranschaulicht. Alternativ können Sie Azure Blob Storage für Azure OpenAI Batch konfigurieren.

  1. Melden Sie sich bei Microsoft Foundry an. Stellen Sie sicher, dass die Umschaltfläche "Neue Gießerei " aktiviert ist. Diese Schritte beziehen sich auf Foundry (neu).

  2. Wählen Sie oben rechts "Erstellen" aus.

  3. Wählen Sie im linken Bereich "Modelle" aus.

  4. Wählen Sie Batchaufträge>einen Batchauftrag erstellen

    Screenshot der neuen Foundry-Batcherstellungserfahrung.

Fortschritt des Batchauftrags nachverfolgen

Nachdem Ihr Auftrag erstellt wurde, können Sie den Fortschritt des Auftrags überwachen, indem Sie die Auftrags-ID für den zuletzt erstellten Auftrag auswählen. Standardmäßig werden Sie zur Statusseite für Den zuletzt erstellten Batchauftrag weitergeleitet.

Sie können den Auftragsstatus für Ihren Auftrag im rechten Bereich nachverfolgen:

Abrufen der Ausgabedatei eines Batchauftrags

Nachdem Ihr Auftrag abgeschlossen oder einen Terminalstatus erreicht hat, wird eine Fehlerdatei und eine Ausgabedatei generiert, die zur Überprüfung heruntergeladen werden kann, indem Sie die entsprechende Schaltfläche mit dem Pfeilsymbol nach unten auswählen.

Batch abbrechen

Bricht einen laufenden Batch ab. Der Batch befindet sich für bis zu 10 Minuten im Status cancelling, bevor er zu cancelled wechselt, und Teilergebnisse (falls vorhanden) in der Ausgabedatei verfügbar sein werden.

Voraussetzungen

Die Schritte in diesem Artikel sollen sequenziell in Jupyter-Notizbüchern ausgeführt werden. Aus diesem Grund instanziieren wir den Azure OpenAI-Client nur einmal am Anfang der Beispiele. Wenn Sie einen Schritt außerhalb der Reihenfolge ausführen möchten, müssen Sie häufig einen Azure OpenAI-Client als Teil dieses Aufrufs einrichten.

Auch wenn Sie die OpenAI-Python-Bibliothek bereits installiert haben, müssen Sie ihre Installation möglicherweise auf die neueste Version aktualisieren:

!pip install openai --upgrade

Vorbereiten der Batchdatei

Wie bei der Feinabstimmung verwendet der globale Batch Dateien im JSON-Zeilen.jsonlFormat. Im Folgenden finden Sie einige Beispieldateien mit unterschiedlichen Typen von unterstützten Inhalten:

Eingabeformat

Antwort-API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API für Chatabschlusse

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

Dies custom_id ist erforderlich, damit Sie ermitteln können, welche einzelne Batchanforderung einer bestimmten Antwort entspricht. Antworten werden nicht in identischer Reihenfolge zurückgegeben, die in der .jsonl Batchdatei definiert ist.

model Attribut sollte so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, auf die Sie für Rückschlussantworten abzielen möchten.

Wichtig

Das model Attribut muss so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, die Sie für Rückschlussantworten verwenden möchten. Derselbe Globale Batchmodellbereitstellungsname muss in jeder Zeile der Batchdatei vorhanden sein. Wenn Sie auf eine andere Bereitstellung abzielen möchten, müssen Sie dies in einer separaten Batchdatei/einem separaten Batchauftrag tun.

Um eine optimale Leistung zu erzielen, empfehlen wir, große Dateien für die Batchverarbeitung zu übermitteln, anstatt eine große Anzahl kleiner Dateien mit nur wenigen Zeilen in jeder Datei.

Erstellen einer Eingabedatei

Für diesen Artikel erstellen wir eine Datei mit dem Namen test.jsonl und kopieren den Inhalt aus standardmäßigem Eingabecodeblock oben in die Datei. Sie müssen den Namen Ihrer globalen Batchbereitstellung ändern und jeder Zeile der Datei hinzufügen. Speichern Sie diese Datei im selben Verzeichnis, in dem Sie Ihre Jupyter Notebook ausführen.

Batchdatei hochladen

Nachdem Ihre Eingabedatei vorbereitet wurde, müssen Sie die Datei zuerst hochladen, um dann einen Batchauftrag initiieren zu können. Der Dateiupload kann sowohl programmgesteuert als auch über das Microsoft Foundry-Portal erfolgen. In diesem Beispiel wird das direkte Hochladen einer Datei in Ihre Azure OpenAI-Ressource veranschaulicht. Alternativ können Sie Azure Blob Storage für Azure OpenAI Batch konfigurieren.

import os
from datetime import datetime
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch",
  extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)

print(file.model_dump_json(indent=2))

print(f"File expiration: {datetime.fromtimestamp(file.expires_at) if file.expires_at is not None else 'Not set'}")

file_id = file.id

Indem Sie die Kommentare entkommentieren und extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} hinzufügen, legen Sie fest, dass die Uploaddatei in 14 Tagen abläuft. Es gibt eine maximale Grenze von 500 Eingabebatchdateien pro Ressource, wenn kein Ablauf festgelegt ist. Durch Festlegen eines Werts für den Ablauf wird die Anzahl der Eingabebatchdateien pro Ressource auf 10.000 Dateien pro Ressource erhöht. Um Batcheingabedateibeschränkungen zu entfernen, verwenden Sie Batch mit Azure Blob Storage.

Ausgabe:

{
  "id": "file-655111ec9cfc44489d9af078f08116ef",
  "bytes": 176064,
  "created_at": 1743391067,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1744600667,
  "status_details": null
}
File expiration: 2025-04-13 23:17:47

Batchauftrag erstellen

Nachdem die Datei erfolgreich hochgeladen wurde, können Sie die Datei zur Batchverarbeitung übermitteln.

# Submit a batch job with the file
batch_response = client.batches.create(
    input_file_id=file_id,
    endpoint="/chat/completions", # While passing this parameter is required, the system will read your input file to determine if the chat completions or responses API is needed.  
    completion_window="24h",
    # extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)

# Save batch ID for later use
batch_id = batch_response.id

print(batch_response.model_dump_json(indent=2))

Hinweis

Derzeit muss das Fertigstellungsfenster auf 24h eingestellt werden. Wenn Sie einen anderen Wert als 24h einstellen, wird Ihr Auftrag fehlschlagen. Aufträge, die länger als 24 Stunden dauern, werden bis zur Stornierung weiter ausgeführt.

Ausgabe:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-655111ec9cfc44489d9af078f08116ef",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": null,
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": null,
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Wenn Ihre Batchaufträge so groß sind, dass Sie die enqueuierte Tokengrenze auch dann erreichen, wenn Sie das Kontingent für Ihre Bereitstellung vollständig ausgenutzt haben, unterstützen bestimmte Regionen jetzt eine neue Fail-Fast-Funktion, mit der Sie mehrere Batchaufträge mithilfe eines exponentiellen Backoffs in die Warteschlange stellen können, sodass, sobald ein großer Batchauftrag abgeschlossen ist, der nächste automatisch gestartet werden kann. Weitere Informationen dazu, welche Regionen dieses Feature unterstützen und wie Sie Ihren Code anpassen können, um es optimal zu nutzen, finden Sie unter Warteschlange von Batchaufträgen.

Fortschritt des Batchauftrags nachverfolgen

Nachdem Sie den Batchauftrag erfolgreich erstellt haben, können Sie den Fortschritt entweder im Studio oder programmgesteuert überwachen. Wir empfehlen, beim Überprüfen des Fortschritts von Batchaufträgen, zwischen den Statusabfragen mindestens 60 Sekunden zu warten.

import time
import datetime 

status = "validating"
while status not in ("completed", "failed", "canceled"):
    time.sleep(60)
    batch_response = client.batches.retrieve(batch_id)
    status = batch_response.status
    print(f"{datetime.datetime.now()} Batch Id: {batch_id},  Status: {status}")

if batch_response.status == "failed":
    for error in batch_response.errors.data:  
        print(f"Error code {error.code} Message {error.message}")

Ausgabe:

2024-07-31 21:48:32.556488 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: validating
2024-07-31 21:49:39.221560 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:50:53.383138 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:52:07.274570 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:53:21.149501 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:54:34.572508 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:55:35.304713 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:56:36.531816 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:57:37.414105 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: completed

Die folgenden Statuswerte sind möglich:

Status Beschreibung
validating Die Eingabedatei wird überprüft, bevor die Batchverarbeitung beginnen kann.
failed Die Eingabedatei hat den Überprüfungsprozess nicht bestanden.
in_progress Die Eingabedatei wurde erfolgreich überprüft, und der Batch wird zurzeit ausgeführt.
finalizing Der Batch wurde abgeschlossen, und die Ergebnisse werden vorbereitet.
completed Der Batch wurde abgeschlossen, und die Ergebnisse sind bereit.
expired Der Batch konnte nicht innerhalb des 24-Stunden-Zeitfensters abgeschlossen werden.
cancelling Der Batch wird cancelled (es kann bis zu zehn Minuten dauern, bis dies wirksam wird).
cancelled Der Batch ist cancelled.

Um die Details zum Auftragsstatus zu überprüfen, können Sie folgenden Befehl ausführen:

print(batch_response.model_dump_json(indent=2))

Ausgabe:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "completed",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": 1722477429,
  "error_file_id": "file-c795ae52-3ba7-417d-86ec-07eebca57d0b",
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": 1722477177,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "file-3304e310-3b39-4e34-9f1c-e1c1504b2b2a",
  "request_counts": {
    "completed": 3,
    "failed": 0,
    "total": 3
  }
}

Beachten Sie, dass es sowohl error_file_id als auch ein separates output_file_id gibt. Verwenden Sie das error_file_id, um beim Debuggen von Problemen zu helfen, die mit Ihrem Batchauftrag entstehen.

Abrufen der Ausgabedatei eines Batchauftrags

import json

output_file_id = batch_response.output_file_id

if not output_file_id:
    output_file_id = batch_response.error_file_id

if output_file_id:
    file_response = client.files.content(output_file_id)
    raw_responses = file_response.text.strip().split('\n')  

    for raw_response in raw_responses:  
        json_response = json.loads(raw_response)  
        formatted_json = json.dumps(json_response, indent=2)  
        print(formatted_json)

Ausgabe:

Der Kürze halber wird hier nur eine Chatvervollständigungsantwort der Ausgabe gezeigt. Wenn Sie die Schritte in diesem Artikel ausführen, sollten Sie drei Antworten haben, die dem folgenden entsprechen:

Chatvervollständigung

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "choices": [
        {
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          },
          "finish_reason": "stop",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": "Microsoft was founded on April 4, 1975, by Bill Gates and Paul Allen in Albuquerque, New Mexico.",
            "role": "assistant"
          }
        }
      ],
      "created": 1722477079,
      "id": "chatcmpl-9rFGJ9dh08Tw9WRKqaEHwrkqRa4DJ",
      "model": "gpt-4o-2024-05-13",
      "object": "chat.completion",
      "prompt_filter_results": [
        {
          "prompt_index": 0,
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "jailbreak": {
              "filtered": false,
              "detected": false
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          }
        }
      ],
      "system_fingerprint": "fp_a9bfe9d51d",
      "usage": {
        "completion_tokens": 24,
        "prompt_tokens": 27,
        "total_tokens": 51
      }
    },
    "request_id": "660b7424-b648-4b67-addc-862ba067d442",
    "status_code": 200
  },
  "error": null
}

Antwort-API

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "id": "resp_0e5c78eb05ee70cf00690cc6d988e4819587556df17436a206",
      "created_at": 1762445017.0,
      "error": null,
      "incomplete_details": null,
      "instructions": null,
      "metadata": {},
      "model": "gpt-4.1-batch",
      "object": "response",
      "output": [
        {
          "id": "msg_0e5c78eb05ee70cf00690cc6da3c548195aae483031113df16",
          "content": [
            {
              "annotations": [],
              "text": "Microsoft was founded on **April 4, 1975** by **Bill Gates** and **Paul Allen**.",
              "type": "output_text",
              "logprobs": []
            }
          ],
          "role": "assistant",
          "status": "completed",
          "type": "message"
        }
      ],
      "parallel_tool_calls": true,
      "temperature": 1.0,
      "tool_choice": "auto",
      "tools": [],
      "top_p": 1.0,
      "background": false,
      "max_output_tokens": null,
      "max_tool_calls": null,
      "previous_response_id": null,
      "prompt_cache_key": null,
      "reasoning": {
        "effort": null,
        "summary": null
      },
      "safety_identifier": null,
      "service_tier": "default",
      "status": "completed",
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "medium"
      },
      "top_logprobs": 0,
      "truncation": "disabled",
      "usage": {
        "input_tokens": 16,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 25,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 41
      },
      "user": null,
      "content_filters": null,
      "store": true
    },
    "request_id": "809b30c2-fa0b-4613-b5cc-c30f6b780c9a",
    "status_code": 200
  },
  "error": null
}

Zusätzliche Batchbefehle

Batch abbrechen

Bricht einen laufenden Batch ab. Der Batch befindet sich für bis zu 10 Minuten im Status cancelling, bevor er zu cancelled wechselt, und Teilergebnisse (falls vorhanden) in der Ausgabedatei verfügbar sein werden.

client.batches.cancel("batch_abc123") # set to your batch_id for the job you want to cancel

Batch anzeigen

Auflisten von Batchaufträgen für eine bestimmte Azure OpenAI-Ressource.

client.batches.list()

Listenmethoden in der Python Bibliothek werden paginiert.

So listen Sie alle Aufträge auf:

all_jobs = []
# Automatically fetches more pages as needed.
for job in client.batches.list(
    limit=20,
):
    # Do something with job here
    all_jobs.append(job)
print(all_jobs)

Auflisten von Batches (Vorschau)

Verwenden Sie die REST-API, um alle Batchaufträge mit zusätzlichen Sortier-/Filteroptionen auflisten.

In den folgenden Beispielen stellen wir die generate_time_filter Funktion bereit, um das Erstellen des Filters zu vereinfachen. Wenn Sie diese Funktion nicht verwenden möchten, würde das Format der Filterzeichenfolge wie folgt aussehen: created_at gt 1728860560 and status eq 'Completed'.

import requests
import json
from datetime import datetime, timedelta
from azure.identity import DefaultAzureCredential

token_credential = DefaultAzureCredential()
token = token_credential.get_token('https://ai.azure.com/.default')

endpoint = "https://{YOUR_RESOURCE_NAME}.openai.azure.com/"
api_version = "2025-03-01-preview"
url = f"{endpoint}openai/batches"
order = "created_at asc"
time_filter =  lambda: generate_time_filter("past 8 hours")

# Additional filter examples:
#time_filter =  lambda: generate_time_filter("past 1 day")
#time_filter =  lambda: generate_time_filter("past 3 days", status="Completed")

def generate_time_filter(time_range, status=None):
    now = datetime.now()
    
    if 'day' in time_range:
        days = int(time_range.split()[1])
        start_time = now - timedelta(days=days)
    elif 'hour' in time_range:
        hours = int(time_range.split()[1])
        start_time = now - timedelta(hours=hours)
    else:
        raise ValueError("Invalid time range format. Use 'past X day(s)' or 'past X hour(s)'")
    
    start_timestamp = int(start_time.timestamp())
    
    filter_string = f"created_at gt {start_timestamp}"
    
    if status:
        filter_string += f" and status eq '{status}'"
    
    return filter_string

filter = time_filter()

headers = {'Authorization': 'Bearer ' + token.token}

params = {
    "api-version": api_version,
    "$filter": filter,
    "$orderby": order
}

response = requests.get(url, headers=headers, params=params)

json_data = response.json()

if response.status_code == 200:
    print(json.dumps(json_data, indent=2))
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)

Ausgabe:

{
  "data": [
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729011896,
      "completion_window": "24h",
      "created_at": 1729011128,
      "error_file_id": "file-472c0626-4561-4327-9e4e-f41afbfb30e6",
      "expired_at": null,
      "expires_at": 1729097528,
      "failed_at": null,
      "finalizing_at": 1729011805,
      "id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
      "in_progress_at": 1729011493,
      "input_file_id": "file-f89384af0082485da43cb26b49dc25ce",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-62bebde8-e767-4cd3-a0a1-28b214dc8974",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    },
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729016366,
      "completion_window": "24h",
      "created_at": 1729015829,
      "error_file_id": "file-85ae1971-9957-4511-9eb4-4cc9f708b904",
      "expired_at": null,
      "expires_at": 1729102229,
      "failed_at": null,
      "finalizing_at": 1729016272,
      "id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43",
      "in_progress_at": 1729016126,
      "input_file_id": "file-686746fcb6bc47f495250191ffa8a28e",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-04399828-ae0b-4825-9b49-8976778918cb",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    }
  ],
  "first_id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
  "has_more": false,
  "last_id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43"
}

Einreihen von Batchaufträgen in die Warteschlange

Wenn Ihre Batchaufträge so groß sind, dass Sie den Grenzwert für eingereihte Token auch nach dem Ausschöpfen des Kontingents für Ihre Bereitstellung erreichen, unterstützen einige Regionen jetzt eine neue Fail-Fast-Funktion, mit der Sie mehrere Batchaufträge mit exponentiellem Backoff in die Warteschlange stellen können. Sobald ein großer Batchauftrag abgeschlossen ist und Ihr Enqueued Tokenkontingent erneut verfügbar ist, kann der nächste Batchauftrag erstellt und automatisch gestartet werden.

Altes Verhalten:

  1. Große Batchaufträge werden bereits ausgeführt und verwenden alle verfügbaren Token für Ihre Bereitstellung.
  2. Neuer Batchauftrag übermittelt.
  3. Der neue Batch-Job geht in die Validierungsphase, die einige Minuten dauern kann.
  4. Die Anzahl der Tokens für den neuen Job wird gegen das aktuell verfügbare Kontingent überprüft.
  5. Der neue Batchauftrag schlägt fehl mit der Fehlermeldung, dass das Tokenlimit überschritten wurde.

Neues Verhalten:

  1. Große Batchaufträge werden bereits ausgeführt und verwenden alle verfügbaren Token für Ihre Bereitstellung.
  2. Ein neuer Batchauftrag wird übermittelt.
  3. Die ungefähre Tokenanzahl des neuen Auftrags wird sofort mit dem aktuell verfügbaren Batchkontingent abgeglichen, und es wird ein Fail-Fast ausgeführt, damit Sie Wiederholungen einfacher programmgesteuert behandeln können.

Regionsunterstützung

Die folgenden Regionen unterstützen das neue Fail-Fast-Verhalten:

  • australiaeast
  • eastus
  • Deutschland Westzentral
  • Norditalien
  • Northcentralus
  • Polenzentral
  • schwedencentral
  • schweiznord
  • Eastus2
  • Westus

Der folgende Code veranschaulicht die grundlegende Mechanik der Behandlung des Fail-Fast-Verhaltens, um das Automatisieren von Wiederholungen und der Einreihung von Batchaufträgen in die Warteschlange mit exponentiellem Backoff zu ermöglichen.

Abhängig von der Größe Ihrer Batchaufträge müssen Sie möglicherweise erheblich das max_retries vergrößern oder dieses Beispiel weiter anpassen.

import time
from openai import BadRequestError

max_retries = 10
retries = 0
initial_delay = 5
delay = initial_delay

while True:
    try:
        batch_response = client.batches.create(
            input_file_id=file_id,
            endpoint="/chat/completions",
            completion_window="24h",
        )
        
        # Save batch ID for later use
        batch_id = batch_response.id
        
        print(f"✅ Batch created successfully after {retries} retries")
        print(batch_response.model_dump_json(indent=2))
        break  
        
    except BadRequestError as e:
        error_message = str(e)
        
        # Check if it's a token limit error
        if 'token_limit_exceeded' in error_message:
            retries += 1
            if retries >= max_retries:
                print(f"❌ Maximum retries ({max_retries}) reached. Giving up.")
                raise
            
            print(f"⏳ Token limit exceeded. Waiting {delay} seconds before retry {retries}/{max_retries}...")
            time.sleep(delay)
            
            # Exponential backoff - increase delay for next attempt
            delay *= 2
        else:
            # If it's a different error, raise it immediately
            print(f"❌ Encountered non-token limit error: {error_message}")
            raise

Ausgabe:

⏳ Token limit exceeded. Waiting 5 seconds before retry 1/10...
⏳ Token limit exceeded. Waiting 10 seconds before retry 2/10...
⏳ Token limit exceeded. Waiting 20 seconds before retry 3/10...
⏳ Token limit exceeded. Waiting 40 seconds before retry 4/10...
⏳ Token limit exceeded. Waiting 80 seconds before retry 5/10...
⏳ Token limit exceeded. Waiting 160 seconds before retry 6/10...
⏳ Token limit exceeded. Waiting 320 seconds before retry 7/10...
✅ Batch created successfully after 7 retries
{
  "id": "batch_1e1e7b9f-d4b4-41fa-bd2e-8d2ec50fb8cc",
  "completion_window": "24h",
  "created_at": 1744402048,
  "endpoint": "/chat/completions",
  "input_file_id": "file-e2ba4ccaa4a348e0976c6fe3c018ea92",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": "",
  "errors": null,
  "expired_at": null,
  "expires_at": 1744488444,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Voraussetzungen

Vorbereiten der Batchdatei

Wie bei der Feinabstimmung verwendet der globale Batch Dateien im JSON-Zeilen.jsonlFormat. Im Folgenden finden Sie einige Beispieldateien mit unterschiedlichen Typen von unterstützten Inhalten:

Eingabeformat

Antwort-API

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

API für Chatabschlusse

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

Dies custom_id ist erforderlich, damit Sie ermitteln können, welche einzelne Batchanforderung einer bestimmten Antwort entspricht. Antworten werden nicht in identischer Reihenfolge zurückgegeben, die in der .jsonl Batchdatei definiert ist.

model Attribut sollte so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, auf die Sie für Rückschlussantworten abzielen möchten.

Wichtig

Das model Attribut muss so festgelegt werden, dass er dem Namen der globalen Batchbereitstellung entspricht, die Sie für Rückschlussantworten verwenden möchten. Derselbe Globale Batchmodellbereitstellungsname muss in jeder Zeile der Batchdatei vorhanden sein. Wenn Sie auf eine andere Bereitstellung abzielen möchten, müssen Sie dies in einer separaten Batchdatei/einem separaten Batchauftrag tun.

Um eine optimale Leistung zu erzielen, empfehlen wir, große Dateien für die Batchverarbeitung zu übermitteln, anstatt eine große Anzahl kleiner Dateien mit nur wenigen Zeilen in jeder Datei.

Erstellen einer Eingabedatei

Für diesen Artikel erstellen wir eine Datei mit dem Namen test.jsonl und kopieren den Inhalt aus standardmäßigem Eingabecodeblock oben in die Datei. Sie müssen den Namen Ihrer globalen Batchbereitstellung ändern und jeder Zeile der Datei hinzufügen.

Batchdatei hochladen

Nachdem Ihre Eingabedatei vorbereitet wurde, müssen Sie die Datei zuerst hochladen, um dann einen Batchauftrag initiieren zu können. Der Dateiupload kann sowohl programmgesteuert als auch über das Microsoft Foundry-Portal erfolgen. In diesem Beispiel wird das direkte Hochladen einer Datei in Ihre Azure OpenAI-Ressource veranschaulicht. Alternativ können Sie Azure Blob Storage für Azure OpenAI Batch konfigurieren.

Wichtig

Verwenden Sie API-Schlüssel mit Vorsicht. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und veröffentlichen Sie ihn nie öffentlich. Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn sicher in Azure Key Vault. Weitere Informationen zur sicheren Verwendung von API-Schlüsseln in Ihren Apps finden Sie unter API-Schlüssel mit Azure Key Vault.

Weitere Informationen zur Sicherheit von AI-Diensten finden Sie unter Authenticate-Anforderungen an Azure KI Services.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -F "purpose=batch" \
  -F "file=@C:\\batch\\test.jsonl;type=application/json" \
  -F "expires_after.seconds=1209600" \
  -F "expires_after.anchor=created_at"

Im obigen Code wird ein bestimmter Dateipfad für die Datei "test.jsonl" vorausgesetzt. Passen Sie diesen Dateipfad nach Bedarf für Ihr lokales System an.

Durch das Hinzufügen der optionalen "expires_after.seconds=1209600" und "expires_after.anchor=created_at" Parameter legen Sie fest, dass die Upload-Datei in 14 Tagen abläuft. Es gibt maximal 500 Batcheingabedateien pro Ressource, wenn kein Ablauf festgelegt ist. Durch Festlegen eines Werts für den Ablauf wird die Anzahl der Batchdateien pro Ressource auf 10.000 Dateien pro Ressource erhöht. Sie können eine Zahl zwischen 1209600 und 2592000 festlegen. Dies entspricht 14-30 Tagen. Um Batcheingabedateibeschränkungen zu entfernen, verwenden Sie Batch mit Azure Blob Storage.

Ausgabe:

{
  "status": "processed",
  "bytes": 817,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1743398147,
  "object": "file"
}

Dateiuploadstatus nachverfolgen

Je nach Größe der Uploaddatei kann es einige Zeit dauern, bis sie vollständig hochgeladen und verarbeitet wird. Um den Status Ihres Dateiuploads zu überprüfen, führen Sie Folgendes aus:

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{file-id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Ausgabe:

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1721408291,
  "object": "file"
}

Batchauftrag erstellen

Nachdem die Datei erfolgreich hochgeladen wurde, können Sie die Datei zur Batchverarbeitung übermitteln.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h",
    "output_expires_after": {
        "seconds": 1209600
    },
    "anchor": "created_at"
  }'

Hier können Sie optional "output_expires_after":{"seconds": 1209600}, und "anchor": "created_at" hinzufügen, damit Ihre Ausgabedateien in 14 Tagen verfallen.

Hinweis

Derzeit muss das Fertigstellungsfenster auf 24h eingestellt werden. Wenn Sie einen anderen Wert als 24h einstellen, wird Ihr Auftrag fehlschlagen. Aufträge, die länger als 24 Stunden dauern, werden bis zur Stornierung weiter ausgeführt.

Ausgabe:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:13:57.2491382+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:13:57.1918498+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_fe3f047a-de39-4068-9008-346795bfc1db",
  "in_progress_at": null,
  "input_file_id": "file-21006e70789246658b86a1fc205899a4",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Fortschritt des Batchauftrags nachverfolgen

Nachdem Sie den Batchauftrag erfolgreich erstellt haben, können Sie den Fortschritt entweder im Studio oder programmgesteuert überwachen. Wir empfehlen, beim Überprüfen des Fortschritts von Batchaufträgen, zwischen den Statusabfragen mindestens 60 Sekunden zu warten.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches/{batch_id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Ausgabe:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:33:29.1619286+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:33:29.1578141+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_e0a7ee28-82c4-46a2-a3a0-c13b3c4e390b",
  "in_progress_at": null,
  "input_file_id": "file-c55ec4e859d54738a313d767718a2ac5",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Die folgenden Statuswerte sind möglich:

Status Beschreibung
validating Die Eingabedatei wird überprüft, bevor die Batchverarbeitung beginnen kann.
failed Die Eingabedatei hat den Überprüfungsprozess nicht bestanden.
in_progress Die Eingabedatei wurde erfolgreich überprüft, und der Batch wird zurzeit ausgeführt.
finalizing Der Batch wurde abgeschlossen, und die Ergebnisse werden vorbereitet.
completed Der Batch wurde abgeschlossen, und die Ergebnisse sind bereit.
expired Der Batch konnte nicht innerhalb des 24-Stunden-Zeitfensters abgeschlossen werden.
cancelling Der Batch wird cancelled (es kann bis zu 10 Minuten dauern, bis dies wirksam wird).
cancelled Der Batch ist cancelled.

Abrufen der Ausgabedatei eines Batchauftrags

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{output_file_id}/content \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

Zusätzliche Batchbefehle

Batch abbrechen

Bricht einen laufenden Batch ab. Der Batch befindet sich für bis zu 10 Minuten im Status cancelling, bevor er zu cancelled wechselt, und Teilergebnisse (falls vorhanden) in der Ausgabedatei verfügbar sein werden.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches/{batch_id}/cancel \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Batch anzeigen

Auflisten vorhandener Batchaufträge für eine bestimmte Azure OpenAI-Ressource.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Der Listen-API-Aufruf wird paginiert. Die Antwort enthält einen booleschen has_more Wert, der angibt, wann mehr Ergebnisse zum Durchlaufen vorhanden sind.

Auflisten von Batches (Vorschau)

Verwenden Sie die REST-API, um alle Batchaufträge mit zusätzlichen Sortier-/Filteroptionen auflisten.

curl "YOUR_RESOURCE_NAME.openai.azure.com/batches?api-version=2025-04-01-preview&$filter=created_at%20gt%201728773533%20and%20created_at%20lt%201729032733%20and%20status%20eq%20'Completed'&$orderby=created_at%20asc" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Um den Fehler URL rejected: Malformed input to a URL functionzu vermeiden, werden Leerzeichen durch %20 ersetzt.

Batchgrenzwerte

Name des Grenzwerts Grenzwert
Maximale Batcheingabedateien - (kein Ablauf) 500
Maximale Batch-Eingabedateien - (Ablauf festgelegt) 10.000
Maximale Größe der Eingabedatei 200 MB
Maximale Größe der Eingabedatei – Bring your own storage (BYOS) 1 GB
Maximale Anforderungen pro Datei 100,000

Hinweis

Batchdateigrenzwerte gelten nicht für Ausgabedateien (zum Beispiel result.jsonl und error.jsonl). Verwenden Sie Batch mit Azure Blob Storage, um Batcheingabedateibeschränkungen zu entfernen.

Stapelkontingent

Die Tabelle zeigt den Grenzwert für batchkontingente. Kontingentwerte für einen globalen Batch werden als Tokens in der Warteschlange dargestellt. Wenn Sie eine Datei für die Batchverarbeitung übermitteln, wird die Anzahl der Token in der Datei gezählt. Bis der Batchauftrag einen endgültigen Status erreicht, werden diese Tokens auf Ihren Gesamtgrenzwert der Tokens in der Warteschlange angerechnet.

Globaler Stapel

Modell Unternehmen und MCA-E Standard Monatliche Kreditkartenabonnements MSDN-Abonnements Azure für Studenten, kostenlose Testversionen
gpt-4.1 5B 200M 50M 90K N/A
gpt-4.1 mini 15B 1B 50M 90K N/A
gpt-4.1-nano 15B 1B 50M 90K N/A
gpt-4o 5B 200M 50M 90K N/A
gpt-4o-mini 15B 1B 50M 90K N/A
gpt-4-turbo 300 Mio. 80M 40M 90K N/A
gpt-4 150M 30 Mio. 5M 100K N/A
o3-mini 15B 1B 50M 90K N/A
o4-mini 15B 1B 50M 90K N/A
gpt-5 5B 200M 50M 90K N/A
gpt-5.1 5B 200M 50M 90K N/A

B = Milliarde | M = Million | K = Tausend

Datenzonenbatch

Modell Unternehmen und MCA-E Standard Monatliche Kreditkartenabonnements MSDN-Abonnements Azure für Studenten, kostenlose Testversionen
gpt-4.1 500M 30 Mio. 30 Mio. 90K N/A
gpt-4.1-mini 1,5 Mrd. 100 Mio. 50M 90K N/A
gpt-4o 500M 30 Mio. 30 Mio. 90K N/A
gpt-4o-mini 1,5 Mrd. 100 Mio. 50M 90K N/A
o3-mini 1,5 Mrd. 100 Mio. 50M 90K N/A
gpt-5 5B 200M 50M 90K N/A
gpt-5.1 5B 200M 50M 90K N/A

Batchobjekt

Eigenschaft Typ Definition
id Schnur Der Bezeichner des Batches.
object Schnur batch
endpoint Schnur Der vom Batch verwendete API-Endpunkt
errors Objekt Fehlerinformationen für den Batch, falls vorhanden.
input_file_id Schnur Die ID der Eingabedatei für den Batch
completion_window Schnur Der Zeitrahmen, in dem der Batch verarbeitet werden soll
status Schnur Der aktuelle Status des Batches. Mögliche Werte: validating, , failed, in_progress, finalizingcompleted, expired, , . cancellingcancelled
output_file_id Schnur Die ID der Datei, die die Ausgaben der erfolgreich ausgeführten Anforderungen enthält.
error_file_id Schnur Die ID der Datei, die die Ausgaben von Anforderungen mit Fehlern enthält.
created_at Ganzzahl Ein Zeitstempel, der angibt, wann dieser Batch erstellt wurde (in Sekunden seit der Unix-Epoche).
in_progress_at Ganzzahl Ein Zeitstempel, wann dieser Batch zu fortschreiten begann (in Unix-Epochen-Sekunden).
expires_at Ganzzahl Ein Zeitstempel des Zeitpunkts des Ablaufs dieses Batchs (in Unix Epochensekunden).
finalizing_at Ganzzahl Ein Zeitstempel des Finalisierungsstarts dieses Batchs (in Unix-Epochensekunden).
completed_at Ganzzahl Der Zeitstempel der Fertigstellung dieser Charge (in Unix-Epochensekunden).
failed_at Ganzzahl Ein Zeitstempel, wenn dieser Batch fehlgeschlagen ist (in Unix-Epochen-Sekunden).
expired_at Ganzzahl Ein Zeitstempel, wann diese Charge abgelaufen ist (in Unix-Epochen-Sekunden).
cancelling_at Ganzzahl Ein Zeitstempel, als dieser Batch gestartet wurde cancelling (in Unix-Epochen sekunden).
cancelled_at Ganzzahl Ein Zeitstempel, der angibt, wann dieser Batch cancelled wurde (in Sekunden seit der Unix-Epoche).
request_counts Objekt Objektstruktur:

total Ganzzahl
Die Gesamtanzahl der Anfragen im Batch.
completed Ganzzahl
Die Anzahl der Anforderungen im Batch, die erfolgreich abgeschlossen wurden.
failed Ganzzahl
Die Anzahl der Anforderungen im Batch, die fehlgeschlagen sind.
metadata Karte Eine Reihe von Schlüssel-Wert-Paaren, die an den Batch angefügt werden können. Diese Eigenschaft kann nützlich sein, um zusätzliche Informationen zum Batch in einem strukturierten Format zu speichern.

Häufig gestellte Fragen (FAQ)

Können Bilder mit der Batch-API verwendet werden?

Diese Funktion ist auf bestimmte multimodale Modelle beschränkt. Bilder können als Eingabe entweder über die Bild-URL oder eine base64-codierte Darstellung des Bilds bereitgestellt werden.

Kann ich die Batch-API mit fein abgestimmten Modellen verwenden?

Dies wird derzeit nicht unterstützt.

Kann ich die Batch-API für Einbettungsmodelle verwenden?

Dies wird derzeit nicht unterstützt.

Funktioniert die Inhaltsfilterung mit der globalen Batchbereitstellung?

Ja. Ähnlich wie bei anderen Bereitstellungstypen können Sie Inhaltsfilter erstellen und sie dem globalen Batchbereitstellungstyp zuordnen.

Kann ich zusätzliches Kontingent anfordern?

Ja, von der Kontingentseite im Foundry-Portal. Die Standardmäßige Kontingentzuweisung finden Sie im Artikel "Kontingent" und "Grenzwerte".

Was geschieht, wenn die API meine Anforderung nicht innerhalb des 24-Stunden-Zeitrahmens abschließt?

Wir wollen diese Anfragen innerhalb von 24 Stunden verarbeiten; die Aufträge, die länger dauern, laufen nicht ab. Sie können den Auftrag jederzeit abbrechen. Wenn Sie den Auftrag abbrechen, werden alle verbleibenden Arbeiten abgebrochen, und alle bereits abgeschlossenen Arbeiten werden zurückgegeben. Sie werden für alle abgeschlossenen Arbeiten in Rechnung gestellt.

Wie viele Anforderungen kann ich mithilfe von Batch in die Warteschlange stellen?

Für die Anzahl von Anforderungen, die Sie pro Batch verarbeiten können, gibt es keinen festen Grenzwert, sie hängt jedoch von Ihrem Kontingent für Token in der Warteschlange ab. Ihr Kontingent für Token in der Warteschlange schließt die maximale Anzahl von Eingabetoken ein, die Sie gleichzeitig in die Warteschlange einreihen können.

Sobald die Batchanforderung abgeschlossen ist, wird Ihr Batchratenlimit zurückgesetzt, da Ihre Eingabetoken gelöscht werden. Der Grenzwert hängt von der Anzahl der globalen Anforderungen in der Warteschlange ab. Wenn die Batch-API-Warteschlange Ihre Batches schnell verarbeitet, wird Ihr Batchratenlimit schneller zurückgesetzt.

Problembehandlung

Ein Auftrag ist erfolgreich, wenn status den Wert completed hat. Erfolgreiche Aufträge generieren weiterhin eine error_file_id, aber sie wird einer leeren Datei mit null Bytes zugeordnet.

Wenn ein Auftragsfehler auftritt, finden Sie in der errors-Eigenschaft Details:

{
  "value": [
    {
      "id": "batch_80f5ad38-e05b-49bf-b2d6-a799db8466da",
      "completion_window": "24h",
      "created_at": 1725419394,
      "endpoint": "/chat/completions",
      "input_file_id": "file-c2d9a7881c8a466285e6f76f6321a681",
      "object": "batch",
      "status": "failed",
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1725419955,
      "error_file_id": "file-3b0f9beb-11ce-4796-bc31-d54e675f28fb",
      "errors": {
        "object": "list",
        "data": [
          {
            "code": "empty_file",
            "message": "The input file is empty. Please ensure that the batch contains at least one request."
          }
        ]
      },
      "expired_at": null,
      "expires_at": 1725505794,
      "failed_at": null,
      "finalizing_at": 1725419710,
      "in_progress_at": 1725419572,
      "metadata": null,
      "output_file_id": "file-ef12af98-dbbc-4d27-8309-2df57feed572",
      "request_counts": {
        "total": 10,
        "completed": null,
        "failed": null
      }
    }
  ]
}

Fehlercodes

Fehlercode Definition
invalid_json_line Eine Zeile (oder mehrere) in Ihrer Eingabedatei konnte nicht als gültiges JSON analysiert werden.

Stellen Sie sicher, dass keine Tippfehler, ordnungsgemäße öffnende und schließende Klammern und Anführungszeichen gemäß JSON-Standard vorhanden sind, und übermitteln Sie die Anforderung erneut.
too_many_tasks Die Anzahl der Anforderungen in der Eingabedatei überschreitet den maximal zulässigen Wert von 100.000.

Stellen Sie sicher, dass Ihre Gesamtanforderungen unter 100.000 liegen und den Auftrag erneut übermitteln.
url_mismatch Eine Zeile in Der Eingabedatei weist entweder eine URL auf, die nicht mit den restlichen Zeilen übereinstimmt, oder die in der Eingabedatei angegebene URL stimmt nicht mit der erwarteten Endpunkt-URL überein.

Stellen Sie sicher, dass alle Anforderungs-URLs identisch sind und dass sie mit der Endpunkt-URL übereinstimmen, die Ihrer Azure OpenAI-Bereitstellung zugeordnet ist.
model_not_found Der Azure OpenAI-Modellbereitstellungsname, der in der eigenschaft model der Eingabedatei angegeben wurde, wurde nicht gefunden.

Stellen Sie sicher, dass dieser Name auf eine gültige Azure OpenAI-Modellbereitstellung verweist.
duplicate_custom_id Die benutzerdefinierte ID für diese Anforderung ist ein Duplikat der benutzerdefinierten ID in einer anderen Anforderung.
empty_file Die Eingabedatei ist leer. Stellen Sie sicher, dass der Batch mindestens eine Anforderung enthält.
model_mismatch Der Azure OpenAI-Modellbereitstellungsname, der in der Eigenschaft model dieser Anforderung in der Eingabedatei angegeben wurde, stimmt nicht mit dem Rest der Datei überein.

Stellen Sie sicher, dass alle Anforderungen im Batchpunkt auf dieselbe Azure OpenAI in Foundry Models-Modellimplementierungen in der Eigenschaft model der Anforderung angewendet werden.
invalid_request Das Schema der Eingabezeile ist ungültig, oder die Bereitstellungs-SKU ist ungültig.

Stellen Sie sicher, dass die Eigenschaften der Anforderung in Ihrer Eingabedatei den erwarteten Eingabeeigenschaften entsprechen und dass die Azure OpenAI-Bereitstellungs-SKU für Batch-API-Anforderungen globalbatch ist.
input_modified Die Blob-Eingabe wurde geändert, nachdem der Batch-Job übermittelt wurde.
input_no_permissions Es ist nicht möglich, auf das Eingabe-BLOB zuzugreifen. Überprüfen Sie permissions und den Netzwerkzugriff zwischen dem Azure OpenAI-Konto und Azure Storage Konto.

Bekannte Probleme

  • Ressourcen, die mit der Azure-Befehlszeilenschnittstelle (Command Line Interface, CLI) bereitgestellt werden, funktionieren nicht standardmäßig mit Azure OpenAI Global-Batch. Dies liegt an einem Problem, bei dem Ressourcen, die mit dieser Methode bereitgestellt werden, Endpunkt-Subdomains aufweisen, die nicht dem https://your-resource-name.openai.azure.com Muster folgen. Eine Problemumgehung für dieses Problem besteht darin, eine neue Azure OpenAI-Ressource mithilfe einer der anderen gängigen Bereitstellungsmethoden bereitzustellen, die das Unterdomänensetup im Rahmen des Bereitstellungsprozesses ordnungsgemäß verarbeiten.

  • UTF-8-BOM-codierte jsonl Dateien werden nicht unterstützt. JSON-Zeilendateien sollten mit UTF-8 codiert werden. Die Verwendung von byte-Order-Mark (BOM)-codierten Dateien wird von der JSON RFC-Spezifikation nicht offiziell unterstützt, und Azure OpenAI derzeit BOM-codierte Dateien als ungültig behandelt. Eine UTF-8-BOM-codierte Datei gibt derzeit die generische Fehlermeldung zurück: "Überprüfung fehlgeschlagen: Ein gültiger Modellbereitstellungsname konnte nicht aus der Eingabedatei extrahiert werden. Stellen Sie sicher, dass jede Zeile in der Eingabedatei über einen gültigen Bereitstellungsnamen verfügt, der im Feld "Modell" angegeben ist und dass der Bereitstellungsname in allen Zeilen konsistent ist."

  • Wenn Sie Ihren eigenen Speicher für Batcheingabedaten verwenden, tritt nach dem Übermitteln des Batchauftrags ein Fehler beim Bewertungsauftrag auf, wenn das Eingabeblob geändert wird.

Siehe auch

  • Last updated on