Der Batchmodus der Gemini API wurde entwickelt, um große Mengen von Anfragen asynchron zu verarbeiten und dabei 50% der Standardkosten zu berechnen. Die angestrebte Bearbeitungszeit beträgt 24 Stunden, in den meisten Fällen geht es aber viel schneller.
Verwenden Sie den Batchmodus für umfangreiche, nicht dringende Aufgaben wie die Vorverarbeitung von Daten oder die Durchführung von Auswertungen, bei denen keine sofortige Antwort erforderlich ist.
Batchjob erstellen
Es gibt zwei Möglichkeiten, Anfragen im Batch-Modus zu senden:
- Inline-Anfragen:Eine Liste von
GenerateContentRequest
-Objekten, die direkt in Ihre Batcherstellungsanfrage aufgenommen werden. Diese Methode eignet sich für kleinere Batches, bei denen die Gesamtgröße der Anfrage unter 20 MB bleibt. Die vom Modell zurückgegebene Ausgabe ist eine Liste voninlineResponse
-Objekten. - Eingabedatei:Eine JSON Lines-Datei (JSONL), in der jede Zeile ein vollständiges
GenerateContentRequest
-Objekt enthält. Diese Methode wird für größere Anfragen empfohlen. Die vom Modell zurückgegebene Ausgabe ist eine JSONL-Datei, in der jede Zeile entweder einGenerateContentResponse
oder ein Statusobjekt ist.
Inline-Anfragen
Bei einer geringen Anzahl von Anfragen können Sie die GenerateContentRequest
-Objekte direkt in Ihre BatchGenerateContentRequest
einbetten. Im folgenden Beispiel wird die Methode BatchGenerateContent
mit Inline-Anfragen aufgerufen:
Python
from google import genai
from google.genai import types
client = genai.Client()
# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
{
'contents': [{
'parts': [{'text': 'Tell me a one-sentence joke.'}],
'role': 'user'
}]
},
{
'contents': [{
'parts': [{'text': 'Why is the sky blue?'}],
'role': 'user'
}]
}
]
inline_batch_job = client.batches.create(
model="models/gemini-2.5-flash",
src=inline_requests,
config={
'display_name': "inlined-requests-job-1",
},
)
print(f"Created batch job: {inline_batch_job.name}")
REST
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:batchGenerateContent \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type:application/json" \
-d '{
"batch": {
"display_name": "my-batch-requests",
"input_config": {
"requests": {
"requests": [
{
"request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
"metadata": {
"key": "request-1"
}
},
{
"request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]},
"metadata": {
"key": "request-2"
}
}
]
}
}
}
}'
Eingabedatei
Bei größeren Anfragesätzen sollten Sie eine JSON-Lines-Datei (JSONL) vorbereiten. Jede Zeile in dieser Datei muss ein JSON-Objekt mit einem benutzerdefinierten Schlüssel und einem Anfrageobjekt sein, wobei die Anfrage ein gültiges GenerateContentRequest
-Objekt ist. Der benutzerdefinierte Schlüssel wird in der Antwort verwendet, um anzugeben, welche Ausgabe das Ergebnis welcher Anfrage ist. Wenn der Schlüssel beispielsweise als request-1
definiert ist, wird die Antwort auf die Anfrage mit demselben Schlüsselnamen annotiert.
Diese Datei wird über die File API hochgeladen. Die maximal zulässige Dateigröße für eine Eingabedatei beträgt 2 GB.
Im Folgenden finden Sie ein Beispiel für eine JSONL-Datei. Sie können es in einer Datei mit dem Namen my-batch-requests.json
speichern:
{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generation_config": {"temperature": 0.7}}}
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
Ähnlich wie bei Inline-Anfragen können Sie in jedem Anfrage-JSON andere Parameter wie Systemanweisungen, Tools oder andere Konfigurationen angeben.
Sie können diese Datei mit der File API hochladen, wie im folgenden Beispiel gezeigt. Wenn Sie multimodalen Input verwenden, können Sie in Ihrer JSONL-Datei auf andere hochgeladene Dateien verweisen.
Python
from google import genai
from google.genai import types
client = genai.Client()
# Create a sample JSONL file
with open("my-batch-requests.jsonl", "w") as f:
requests = [
{"key": "request-1", "request": {"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}]}},
{"key": "request-2", "request": {"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}}
]
for req in requests:
f.write(json.dumps(req) + "\n")
# Upload the file to the File API
uploaded_file = client.files.upload(
file='my-batch-requests.jsonl',
config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)
print(f"Uploaded file: {uploaded_file.name}")
REST
tmp_batch_input_file=batch_input.tmp
echo -e '{"contents": [{"parts": [{"text": "Describe the process of photosynthesis."}]}], "generationConfig": {"temperature": 0.7}}\n{"contents": [{"parts": [{"text": "What are the main ingredients in a Margherita pizza?"}]}]}' > batch_input.tmp
MIME_TYPE=$(file -b --mime-type "${tmp_batch_input_file}")
NUM_BYTES=$(wc -c < "${tmp_batch_input_file}")
DISPLAY_NAME=BatchInput
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files \
-D "${tmp_header_file}" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/jsonl" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${tmp_batch_input_file}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
Im folgenden Beispiel wird die Methode BatchGenerateContent
mit der Eingabedatei aufgerufen, die mit der File API hochgeladen wurde:
Python
# Assumes `uploaded_file` is the file object from the previous step
file_batch_job = client.batches.create(
model="gemini-2.5-flash",
src=uploaded_file.name,
config={
'display_name': "file-upload-job-1",
},
)
print(f"Created batch job: {file_batch_job.name}")
REST
BATCH_INPUT_FILE='files/123456' # File ID
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:batchGenerateContent \
-X POST \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" \
-d "{
'batch': {
'display_name': 'my-batch-requests',
'input_config': {
'requests': {
'file_name': ${BATCH_INPUT_FILE}
}
}
}
}"
Wenn Sie einen Batchjob erstellen, wird ein Jobname zurückgegeben. Verwenden Sie diesen Namen, um den Jobstatus zu überwachen und die Ergebnisse abzurufen, sobald der Job abgeschlossen ist.
Hier ein Beispiel für eine Ausgabe, die einen Jobnamen enthält:
Created batch job from file: batches/123456789
Anfragekonfiguration
Sie können alle Anfragekonfigurationen einfügen, die Sie in einer standardmäßigen Anfrage ohne Batch verwenden würden. Sie können beispielsweise die Temperatur oder Systemanweisungen angeben oder sogar andere Modalitäten übergeben. Das folgende Beispiel zeigt eine Inline-Anfrage, die eine Systemanweisung für eine der Anfragen enthält:
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Write a short poem about a cloud.'}]}]},
{'contents': [{'parts': [{'text': 'Write a short poem about a cat.'}]}], 'system_instructions': {'parts': [{'text': 'You are a cat. Your name is Neko.'}]}}
]
Sie können auch angeben, welche Tools für eine Anfrage verwendet werden sollen. Das folgende Beispiel zeigt eine Anfrage, mit der das Google Suche-Tool aktiviert wird:
inline_requests_list = [
{'contents': [{'parts': [{'text': 'Who won the euro 1998?'}]}]},
{'contents': [{'parts': [{'text': 'Who won the euro 2025?'}]}], 'tools': [{'google_search ': {}}]}
]
Sie können auch strukturierte Ausgabe angeben. Das folgende Beispiel zeigt, wie Sie Batchanfragen angeben.
from google import genai
from pydantic import BaseModel, TypeAdapter
class Recipe(BaseModel):
recipe_name: str
ingredients: list[str]
client = genai.Client()
# A list of dictionaries, where each is a GenerateContentRequest
inline_requests = [
{
'contents': [{
'parts': [{'text': 'List a few popular cookie recipes, and include the amounts of ingredients.'}],
'role': 'user'
}],
'config': {
'response_mime_type': 'application/json',
'response_schema': list[Recipe]
}
},
{
'contents': [{
'parts': [{'text': 'List a few popular gluten free cookie recipes, and include the amounts of ingredients.'}],
'role': 'user'
}],
'config': {
'response_mime_type': 'application/json',
'response_schema': list[Recipe]
}
}
]
inline_batch_job = client.batches.create(
model="models/gemini-2.5-flash",
src=inline_requests,
config={
'display_name': "structured-output-job-1"
},
)
# wait for the job to finish
job_name = inline_batch_job.name
print(f"Polling status for job: {job_name}")
while True:
batch_job_inline = client.batches.get(name=job_name)
if batch_job_inline.state.name in ('JOB_STATE_SUCCEEDED', 'JOB_STATE_FAILED', 'JOB_STATE_CANCELLED'):
break
print(f"Job not finished. Current state: {batch_job.state.name}. Waiting 30 seconds...")
time.sleep(30)
print(f"Job finished with state: {batch_job.state.name}")
# print the response
for i, inline_response in enumerate(batch_job_inline.dest.inlined_responses):
print(f"\n--- Response {i+1} ---")
# Check for a successful response
if inline_response.response:
# The .text property is a shortcut to the generated text.
print(inline_response.response.text)
Jobstatus überwachen
Verwenden Sie den Vorgangsnamen, den Sie beim Erstellen des Batchjobs erhalten haben, um den Status abzufragen. Im Feld „Status“ des Batchjobs wird der aktuelle Status angezeigt. Ein Batchjob kann einen der folgenden Status haben:
JOB_STATE_PENDING
: Der Job wurde erstellt und wartet darauf, vom Dienst verarbeitet zu werden.JOB_STATE_SUCCEEDED
: Der Job wurde erfolgreich abgeschlossen. Sie können die Ergebnisse jetzt abrufen.JOB_STATE_FAILED
: Der Job ist fehlgeschlagen. Weitere Informationen finden Sie in den Fehlerdetails.JOB_STATE_CANCELLED
: Der Job wurde vom Nutzer abgebrochen.
Sie können den Jobstatus regelmäßig abfragen, um zu prüfen, ob der Job abgeschlossen ist.
Python
# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME" # (e.g. 'batches/your-batch-id')
batch_job = client.batches.get(name=job_name)
completed_states = set([
'JOB_STATE_SUCCEEDED',
'JOB_STATE_FAILED',
'JOB_STATE_CANCELLED',
])
print(f"Polling status for job: {job_name}")
batch_job = client.batches.get(name=job_name) # Initial get
while batch_job.state.name not in completed_states:
print(f"Current state: {batch_job.state.name}")
time.sleep(30) # Wait for 30 seconds before polling again
batch_job = client.batches.get(name=job_name)
print(f"Job finished with state: {batch_job.state.name}")
if batch_job.state.name == 'JOB_STATE_FAILED':
print(f"Error: {batch_job.error}")
Ergebnisse abrufen
Sobald der Jobstatus angibt, dass Ihr Batchjob erfolgreich ausgeführt wurde, sind die Ergebnisse im Feld response
verfügbar.
Python
import json
# Use the name of the job you want to check
# e.g., inline_batch_job.name from the previous step
job_name = "YOUR_BATCH_JOB_NAME"
batch_job = client.batches.get(name=job_name)
if batch_job.state.name == 'JOB_STATE_SUCCEEDED':
# If batch job was created with a file
if batch_job.dest and batch_job.dest.file_name:
# Results are in a file
result_file_name = batch_job.dest.file_name
print(f"Results are in file: {result_file_name}")
print("Downloading result file content...")
file_content = client.files.download(file=result_file_name)
# Process file_content (bytes) as needed
print(file_content.decode('utf-8'))
# If batch job was created with inline request
elif batch_job.dest and batch_job.dest.inlined_responses:
# Results are inline
print("Results are inline:")
for i, inline_response in enumerate(batch_job.dest.inlined_responses):
print(f"Response {i+1}:")
if inline_response.response:
# Accessing response, structure may vary.
try:
print(inline_response.response.text)
except AttributeError:
print(inline_response.response) # Fallback
elif inline_response.error:
print(f"Error: {inline_response.error}")
else:
print("No results found (neither file nor inline).")
else:
print(f"Job did not succeed. Final state: {batch_job.state.name}")
if batch_job.error:
print(f"Error: {batch_job.error}")
REST
BATCH_NAME="batches/123456" # Your batch job name
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null > batch_status.json
if jq -r '.done' batch_status.json | grep -q "false"; then
echo "Batch has not finished processing"
fi
batch_state=$(jq -r '.metadata.state' batch_status.json)
if [[ $batch_state = "JOB_STATE_SUCCEEDED" ]]; then
if [[ $(jq '.response | has("inlinedResponses")' batch_status.json) = "true" ]]; then
jq -r '.response.inlinedResponses' batch_status.json
exit
fi
responses_file_name=$(jq -r '.response.responsesFile' batch_status.json)
curl https://generativelanguage.googleapis.com/download/v1beta/$responses_file_name:download?alt=media \
-H "x-goog-api-key: $GEMINI_API_KEY" 2> /dev/null
elif [[ $batch_state = "JOB_STATE_FAILED" ]]; then
jq '.error' batch_status.json
elif [[ $batch_state == "JOB_STATE_CANCELLED" ]]; then
echo "Batch was cancelled by the user"
fi
Batchjob abbrechen
Sie können einen laufenden Batchjob anhand seines Namens abbrechen. Wenn ein Job abgebrochen wird, werden keine neuen Anfragen mehr verarbeitet.
Python
# Cancel a batch job
client.batches.cancel(name=batch_job_to_cancel.name)
REST
BATCH_NAME="batches/123456" # Your batch job name
# Cancel the batch
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:cancel \
-H "x-goog-api-key: $GEMINI_API_KEY" \
# Confirm that the status of the batch after cancellation is JOB_STATE_CANCELLED
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type:application/json" 2> /dev/null | jq -r '.metadata.state'
Batchjob löschen
Sie können einen vorhandenen Batchjob anhand seines Namens löschen. Wenn ein Job gelöscht wird, werden keine neuen Anfragen mehr verarbeitet und er wird aus der Liste der Batchjobs entfernt.
Python
# Delete a batch job
client.batches.delete(name=batch_job_to_delete.name)
REST
BATCH_NAME="batches/123456" # Your batch job name
# Cancel the batch
curl https://generativelanguage.googleapis.com/v1beta/$BATCH_NAME:delete \
-H "x-goog-api-key: $GEMINI_API_KEY" \
Technische Details
- Unterstützte Modelle:Der Batchmodus unterstützt eine Reihe von Gemini-Modellen. Informationen zur Unterstützung des Batch-Modus für die einzelnen Modelle finden Sie auf der Seite Modelle. Die unterstützten Modalitäten für den Batchmodus sind dieselben wie für die interaktive API (oder API ohne Batchmodus).
- Preise:Die Nutzung des Batchmodus wird mit 50% der standardmäßigen interaktiven API-Kosten für das entsprechende Modell berechnet. Weitere Informationen finden Sie auf der Preisseite. Weitere Informationen zu Ratenlimits für diese Funktion finden Sie auf der Seite zu Ratenlimits.
- Service Level Objective (SLO): Batch-Jobs sind so konzipiert, dass sie innerhalb von 24 Stunden abgeschlossen werden. Viele Jobs können je nach Größe und aktueller Systemlast viel schneller abgeschlossen werden.
- Caching:Kontext-Caching ist für Batchanfragen aktiviert. Wenn eine Anfrage in Ihrem Batch zu einem Cache-Treffer führt, werden die im Cache gespeicherten Tokens genauso berechnet wie bei Traffic im Nicht-Batch-Modus.
Best Practices
- Eingabedateien für große Anfragen verwenden:Bei einer großen Anzahl von Anfragen sollten Sie immer die Dateieingabemethode verwenden, um die Verwaltung zu vereinfachen und die Größenbeschränkungen für die
BatchGenerateContent
-Anfrage selbst zu vermeiden. Beachten Sie, dass die maximale Dateigröße pro Eingabedatei 2 GB beträgt. - Fehlerbehandlung:Prüfen Sie
batchStats
nach Abschluss eines Jobs auffailedRequestCount
. Wenn Sie die Dateiausgabe verwenden, parsen Sie jede Zeile, um zu prüfen, ob es sich um einGenerateContentResponse
- oder ein Statusobjekt handelt, das einen Fehler für die jeweilige Anfrage angibt. Eine vollständige Liste der Fehlercodes finden Sie in der Anleitung zur Fehlerbehebung. - Jobs nur einmal senden:Das Erstellen eines Batchjobs ist nicht idempotent. Wenn Sie dieselbe Erstellungsanfrage zweimal senden, werden zwei separate Batchjobs erstellt.
- Sehr große Batches aufteilen:Die angestrebte Bearbeitungszeit beträgt 24 Stunden. Die tatsächliche Bearbeitungszeit kann jedoch je nach Systemlast und Jobgröße variieren. Bei großen Jobs sollten Sie sie in kleinere Batches aufteilen, wenn Zwischenergebnisse früher benötigt werden.
Nächste Schritte
Weitere Beispiele finden Sie im Notebook für den Batchmodus.