Batch-Modus

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 von inlineResponse-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 ein GenerateContentResponse 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 auf failedRequestCount. Wenn Sie die Dateiausgabe verwenden, parsen Sie jede Zeile, um zu prüfen, ob es sich um ein GenerateContentResponse- 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.