Entwicklerhandbuch für Gemini 4 Carbon

Gemini 4 Carbon ist das Frontier-Modell von Google, das sich durch seine Fähigkeit auszeichnet, komplexe, reale Aufgaben in verschiedenen Bereichen wie Programmierung, Finanzen, Recht, Cybersicherheit und Wissenschaft zu lösen. Es ist Teil der Gemini 4-Familie. Gemini 4 Carbon ist ein Google Frontier-Modell, das Abschnitt 34 der dienstspezifischen Nutzungsbedingungen unterliegt. Weitere Informationen finden Sie unter Missbrauchsmonitoring.

In diesem Dokument werden die wichtigsten Funktionen von 4 Carbon, die API-Konventionen, die Migration und eine Kurzanleitung beschrieben. Eine Übersicht über die Gemini 4-Familie finden Sie unter Erste Schritte mit Gemini 4.

Wichtige Funktionen in Gemini 4 Carbon

Gemini 4 Carbon bietet die folgenden Funktionen:

  • Einheitliches Limit für Eingabe- und Ausgabetokens: 4 Carbon hat ein einheitliches Limit von 1.048.576 Tokens, das sowohl Eingabe- als auch Ausgabetokens umfasst. Die Ausgabe umfasst dabei Denkprozesse, Funktionsaufrufe und die endgültige Antwort.
  • Lange Decodierungen mit bis zu 1.048.576 Tokens: 4 Carbon erweitert die Generierung über ein einzelnes Vordergrundsegment (65.536 Tokens beim Streaming oder 32.768 Tokens ohne Streaming) hinaus auf bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabe-Tokens) sowohl in der Interactions API als auch in GenerateContent (v1beta1). Das Google Gen AI SDK verarbeitet continuation_token automatisch über Segmente hinweg. Alternativ können Sie asynchrone, vom Server verwaltete Hintergrunddecodierungen (background=true) ausführen oder continuation_token in einer benutzerdefinierten Fortsetzungsschleife verwalten.
  • Denkstufen: 4 Carbon unterstützt LOW, MEDIUM (Standardeinstellung für gemini-4-carbon) und HIGH (Standardeinstellung für gemini-4-carbon-cyber-permissive).
  • Implizites Caching mit langlebigem Caching: Implizites Caching wird automatisch auf freigegebene Prompt-Präfixe mit 4.096 Tokens oder mehr angewendet. Langlebiges Caching ist standardmäßig aktiviert. Explizites Kontext-Caching wird nicht unterstützt.
  • Office- und OpenDocument-Dateieingaben: Neben PDF- und Nur-Text-Dateien akzeptiert 4 Carbon auch Microsoft Office- (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) und OpenDocument-Dateien (.odt, .odp, .ods) inline oder aus Cloud Storage, sowohl in GenerateContent als auch in der Interactions API.
  • Agentisches Videoverständnis: Das agentische Videoverständnis ist allgemein verfügbar und standardmäßig deaktiviert.

Kurzanleitung

Bevor Sie beginnen, müssen Sie sich bei der Gemini Enterprise Agent Platform mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) oder einem API-Schlüssel authentifizieren. Weitere Informationen finden Sie unter Erste Schritte mit der Agent Platform.

Ersetzen Sie in den folgenden Codeblöcken PROJECT_ID durch Ihre Projekt-ID.

In Agent Studio ausprobieren

So testen Sie Prompts und konfigurieren gemini-4-carbon in der Agent Studio-Benutzeroberfläche:

  1. Öffnen Sie Agent Studio in Ihrem Projekt in Google Cloud und wählen Sie gemini-4-carbon unter der Gemini-Gruppe aus.
  2. Konfigurieren Sie unter Modelleinstellungen die folgenden Optionen:
    • Denkaufwand: Wählen Sie Low, Medium (Standard) oder High aus.
    • Region: Wählen Sie Global, us oder eu aus.
    • Tokenausgabelimit: Legen Sie einen Wert zwischen 32,768 und 1,048,576 fest (Standardwert: 1,048,576). Agent Studio verarbeitet Fortsetzungstokens automatisch für Antworten, die das Limit für einzelne Anfragen überschreiten.

Installation

Führen Sie ein Upgrade auf das neueste Google Gen AI SDK durch. Für die automatische Fortsetzung in der Interactions API ist google-genai >= 2.34.0 für Python, @google/genai >= 2.32.0 für JavaScript/TypeScript, >= 1.77.0 für Go oder >= 1.80.0 für Java erforderlich (auf GenerateContent ist für die automatische Fortsetzung >= 2.30.1 für Python, >= 2.29.1 für JavaScript/TypeScript, >= 1.74.0 für Go, >= 1.77.0 für Java, >= 1.26.0 für .NET oder >= 1.6.0 für Kotlin erforderlich):

pip install --upgrade "google-genai>=2.34.0"

Einfache Anfrage

Senden Sie mit dem Google Gen AI SDK oder REST eine Anfrage an gemini-4-carbon:

Python (GenerateContent)

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
print(response.text)

Python (Interactions API)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-carbon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-carbon",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

Strukturierte Ausgabe

Wenn Sie eine JSON-Ausgabe generieren möchten, die einem Schema entspricht, konfigurieren Sie response_mime_type und response_schema:

from pydantic import BaseModel, Field
from google import genai
from google.genai import types

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

Beispiele für lange Decodierungen

Standardmäßig generiert ein einzelnes Vordergrund-API-Segment bis zu 65.536 Ausgabetokens beim Streaming oder 32.768 Ausgabetokens beim Nicht-Streaming. Die Ausgabe umfasst dabei Denkprozesse, Funktionsaufrufe und die endgültige Antwort. Wenn Sie Vervollständigungen mit bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabe-Tokens) generieren möchten, verwenden Sie lange Decodierungen entweder mit der Interactions API oder mit GenerateContent. Informationen zu Fortsetzungsoptionen, Statusübergängen und Validierungsregeln finden Sie unter Lange Decodierungen.

Lange Decodierungen mit der Interactions API verwenden

In google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 und Java >= 1.80.0 folgt interactions.create() automatisch continuation_token über Segmente hinweg, wenn ein Segment status="requires_continuation" zurückgibt. Sie können auch die Option automatic_continuation=False deaktivieren, um eine benutzerdefinierte gespeicherte (store=True) oder zustandslose (store=False) Schleife auszuführen:

Python (SDK automatisch)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

Python (benutzerdefinierte Schleife)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens
# to continue (leaving default automatic_continuation=True lets the SDK finish remaining segments).
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-carbon",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

REST (gespeichert)

# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

REST (zustandslos)

# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

Verwenden Sie für die asynchrone, vom Server verwaltete Ausführung (background=True mit store=True) oder die Wiederherstellung von Streaming-Prüfpunkten (interaction.status_update-Ereignisse, die bei 32.768 Ausgabetokens und danach alle 5.000 Tokens ausgegeben werden) die folgenden Muster:

Python (Hintergrund)

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 32,768 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-carbon",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

REST (Hintergrund)

# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Python (Streaming-Prüfpunkte)

from google import genai
from google.genai import errors

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (32,768
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-carbon",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

REST (Streaming-Prüfpunkte)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Lange Decodierungen mit GenerateContent verwenden

Legen Sie auf GenerateContent (v1beta1) für max_output_tokens einen Wert größer als 65.536 für Streaminganfragen oder größer als 32.768 für Nicht-Streaming-Anfragen (bis zu 1.048.576) fest. Das Google Gen AI SDK folgt automatisch continuation_token über Segmente hinweg, wenn finish_reason auf CONTINUATION gesetzt ist (setzen Sie automatic_continuation=False in GenerateContentConfig, um dies zu deaktivieren). Alternativ können Sie continuation_token in einer benutzerdefinierten Schleife übergeben:

Python (SDK – empfohlen)

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
):
    print(chunk.text, end="")

REST (benutzerdefinierte Fortsetzungsschleife)

# Request 1: Initial request with maxOutputTokens > 32,768
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Obligatorische API-Regeln und Verhaltenskonventionen

4 Carbon erzwingt die Konventionen in den folgenden Abschnitten für Denkebenen, Tokenlimits, Caching, Generierungsparameter und die Ausführung von Tools mit mehreren Durchgängen.

Denkaufwand

4 Carbon unterstützt drei thinking_level-Werte (thinking_budget und MINIMAL geben einen HTTP-400-Validierungsfehler zurück). Übergeben Sie Großbuchstaben ("LOW", "MEDIUM", "HIGH") an GenerateContent und Kleinbuchstaben ("low", "medium", "high") an die Interactions API. In der folgenden Tabelle sind die einzelnen Denkebenen und die empfohlenen Arbeitslasten aufgeführt:

Denkaufwand Empfohlene Arbeitslasten
HIGH (Standardeinstellung auf gemini-4-carbon-cyber-permissive) Softwareentwicklung mit mehreren Dateien, formale Beweise, Architekturdesign und Erkennung von Sicherheitslücken.
MEDIUM (Standardeinstellung auf gemini-4-carbon) Allgemeines Programmieren, Toolnutzung, Fragen und Antworten zu Dokumenten und Videoverständnis.
LOW Klassifizierung, Zusammenfassung und Metadatenextraktion.

Tokenlimits, Caching und Abrechnung

4 Carbon wendet die folgenden Token-, Caching-, Medien- und Abrechnungsregeln an:

  • Einheitliches Limit für Eingabe- und Ausgabetokens und Standardausgabebudgets: Tokenbudgets und Limits für Vordergrundsegmente funktionieren so:
    • Das Gesamt-Tokenlimit des Modells beträgt 1,048,576 Tokens und umfasst sowohl Eingabe- als auch Ausgabe-Tokens (wobei die Ausgabe Thinking, Funktionsaufrufe und die endgültige Antwort umfasst). max_output_tokens steuert die Obergrenze für die Ausgabe-Tokens für die Generierung (bis zu 1,048,576 minus Ihrer Eingabe-Tokens). Wenn Sie max_output_tokens auf einen Wert größer als 1,048,576 setzen, wird ein HTTP-400-Fehler zurückgegeben.
    • Wenn max_output_tokens bei GenerateContent oder der Interactions API weggelassen wird, beträgt das standardmäßige Gesamtbudget für die Ausgabe (Thinking, Funktionsaufrufe und Antwort) 65.536 Tokens. Da ein einzelnes Vordergrundsegment beim Streaming bis zu 65.536 Tokens oder beim Nicht-Streaming 32.768 Tokens generiert, verkettet das Google Gen AI SDK (v1beta1) bei Bedarf automatisch zwei 32.768-Token-Segmente bei Nicht-Streaming-Aufrufen. Eine einzelne Nicht-Streaming-REST-Anfrage wird dagegen nach einem 32.768-Token-Vordergrundsegment beendet. In Agent Studio ist das Ausgabetokenlimit standardmäßig auf 1,048,576 mit automatischer Fortsetzung festgelegt.
  • Lange Decodierungen: Ein einzelnes Vordergrundsegment generiert bis zu 65.536 Ausgabetokens beim Streaming oder 32.768 Ausgabetokens beim Nicht-Streaming. Wenn Sie die Ausgabe für eine einzelne Anfrage in der Interactions API oder GenerateContent (v1beta1) auf bis zu 1.048.576 Tokens (abzüglich der Eingabetokens) erweitern möchten, lesen Sie den Abschnitt Lange Decodierungen.
  • Kontext-Caching: Explizites Kontext-Caching wird nicht unterstützt. Implizites Caching (mit standardmäßig aktiviertem langlebigem Caching) wird automatisch auf freigegebene Prompt-Präfixe mit mindestens 4.096 Tokens angewendet. Platzieren Sie statische Inhalte daher am Anfang Ihres Prompts.
  • Office- und OpenDocument-Eingaben: Word- (application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template, application/msword, application/vnd.oasis.opendocument.text), PowerPoint- (application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation) und Excel- oder OpenDocument-Tabellendateien (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) inline oder per Cloud Storage-URI (gs://) mit inlineData oder fileData für GenerateContent- und document-Eingaben (einschließlich Toolergebnissen) in der Interactions API übergeben.
  • Agentisches Video: Hochgeladene Videos werden standardmäßig auf media_processing="static" gesetzt. Legen Sie media_processing="agentic" fest, um die agentische Videoverarbeitung zu aktivieren.
  • Tokenzählung und Abrechnung: Jedes vom Modell verarbeitete Token wird gezählt und abgerechnet, einschließlich Thinking-Tokens und interner Toolsystemanweisungen und Funktionsdeklarationen bei der Verwendung von Fundierung. Die Fundierung mit der Google Suche wird weiterhin pro Abfrage abgerechnet.

Parameter, Funktionsaufrufe und Chatvalidierung

4 Carbon erzwingt die folgenden Regeln für Generierungsparameter, Toolaufrufe und den Chatverlauf:

  • Ignorierte Sampling-Parameter (temperature, top_k, top_p): Das Backend ignoriert benutzerdefinierte Werte. Mit thinking_level können Sie den Detailgrad der Problemlösung und mit response_schema das Ausgabeformat steuern.
  • Nicht unterstützte Parameter (frequency_penalty, presence_penalty und candidate_count größer als 1): Wenn Sie frequency_penalty, presence_penalty oder candidate_count größer als 1 übergeben (candidateCount ist auf 1 festgelegt), wird ein HTTP-Fehler 400 zurückgegeben. Entfernen Sie diese Parameter aus Ihren Anfragen.

  • Funktionsaufrufe: Tooldeklarationen und Ausführungsrunden folgen diesen Regeln:

    • Symmetrie der Drehungen: Jede FunctionResponse muss mit der id, name und der Reihenfolge der vorherigen FunctionCall übereinstimmen.
    • Sequenzielle Ausführung: Bevorzugen Sie sequenzielle Toolausführungsrunden in mehrstufigen Toolschleifen.

    • Formatierung vor dem Toolaufruf: Trennen Sie Inline-Anweisungen mit \n\n und vermeiden Sie unstrukturierten Text vor Toolaufrufen. Wenn Sie den Zwischenstatus vor einem Toolaufruf protokollieren möchten, verwenden Sie eine dedizierte Funktionsdeklaration:

      {
  "name": "update",
  "description": "Update working notes before tool execution",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {"type": "STRING"},
      "plan": {"type": "STRING"},
      "next_step": {"type": "STRING"}
    },
    "required": ["previous_step", "plan", "next_step"]
  }
}

  • Validierung der Chatsequenz: Für Multi-Turn-Chat-Nutzlasten gelten die folgenden Einschränkungen:

    • Verlaufsnutzlasten dürfen nicht mit einem Rollenwechsel zu model enden.
    • Vorausgefüllte Modellantworten werden nicht unterstützt.

Lange Decodierungen

Bei der langen Decodierung wird eine Generierung von bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabetokens) auf mehrere Segmente aufgeteilt, entweder über die Interactions API oder GenerateContent (v1beta1). Bei der Interactions API generiert jedes Vordergrundsegment bis zu 65.536 Ausgabetokens beim Streaming (stream=true) oder 32.768 Ausgabetokens beim Nicht-Streaming (stream=false) und gibt status="requires_continuation" mit einem verschlüsselten continuation_token zurück. Alternativ können Sie background=true (store=true) festlegen, damit der Server die Fortsetzungsschleife asynchron ausführt und die zusammengeführte Ausgabe in einem Interaction speichert. Bei GenerateContent generieren Streamingsegmente bis zu 65.536 Ausgabetokens und Nicht-Streamingsegmente bis zu 32.768 Ausgabetokens, bevor finish_reason=CONTINUATION mit continuation_token ausgegeben wird. Dies wird bis finish_reason=STOP fortgesetzt. Wenn Sie in Agent Studio das Tokenausgabelimit auf einen Wert zwischen 65.536 und 1.048.576 festlegen, werden Fortsetzungstokens automatisch verarbeitet. Ausführbare Codebeispiele finden Sie in den Beispielen der Kurzanleitung für die lange Decodierung.

Wann sollte die lange Decodierung verwendet werden?

Die meisten Anfragen werden innerhalb des Standardausgabebudgets von 65.536 Tokens (oder eines einzelnen nicht-streaming-basierten Vordergrundsegments mit 32.768 Tokens über REST) abgeschlossen. Verwenden Sie die lange Decodierung nur, wenn eine Antwort mehr Ausgabe erfordert. Die lange Decodierung gibt dem Modell mehr Raum für die Argumentation. Die Antworten werden dadurch nicht länger. Verwenden Sie thinking_level, um die Tiefe der Argumentation zu steuern.

Arbeitslast Lange Decodierung verwenden? Warum
Schwierige Mathematik, Naturwissenschaften, Forschung und formale Beweise Ja Das Modell kann mehr als 65.536 Tokens verwenden,um seine Argumentation zu prüfen und zu verfeinern.
Die schwierigsten Coding- und agentischen Aufgaben Ja Für manche Aufgaben sind mehr als 65.536 Tokens für Denkprozesse und Code in einer Antwort erforderlich. Die meisten Coding- und agentischen Aufgaben werden mit weniger als 65.536 Tokens abgeschlossen.
Evaluierungsumgebungen, die beim Ausgabelimit beendet werden Ja Die lange Decodierung verhindert abgeschnittene Antworten, wenn das Modell eine gesamte Anfrage mit 65.536 oder 32.768 Tokens für den Thinking-Modus verwendet.
Chat, Fragen und Antworten, Zusammenfassung, Klassifizierung und Extraktion Nein Diese Aufgaben werden mit deutlich weniger als 32.768 Tokens abgeschlossen.
Anfragen nach einer festen Länge, z. B. „Schreib ein Buch mit 700.000 Wörtern“ Nein Das Modell hält sich nicht an die Längenvorgaben.
Für KI-Agenten, die Tools in vielen kurzen Schritten aufrufen Nein Jeder Zug ist kurz. Große Ausgaben in jeder Runde füllen das einheitliche Eingabe- und Ausgabelimit von 1.048.576 Tokens schnell.
Prompts, die das Eingabelimit von 1.048.576 Tokens fast erreichen Nein Die Ausgabe kann nur 1.048.576 Tokens abzüglich Ihrer Eingabe verwenden.
Latenzempfindliche Anfragen Nein Die lange Decodierung kann mehrere Minuten dauern.

Fortsetzungsoption auswählen

Wählen Sie ein Fortsetzungsmuster basierend auf Ihrer API-Oberfläche, Ihrem Speicherstatus und Ihrer Laufzeitumgebung aus. Alle Optionen in der folgenden Tabelle erreichen das gleiche Limit von 1.048.576 Tokens (abzüglich Eingabe-Tokens) für gemini-4-carbon und gemini-4-carbon-cyber-permissive.

Fortsetzungsoption API-Oberfläche Wer startet die einzelnen Segmente? Tokens pro Segment Zeitlimit pro Anfrage Serverspeicher Optimal für
Automatische Fortsetzung des Google Gen AI SDK (empfohlen) Interactions API (v1beta1) Google Gen AI SDKs: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) und Java (>= 1.80.0) Bis zu 65.536 (stream=true) oder 32.768 (stream=false) 20 Minuten pro Segment Standardmäßig 7 Tage Serverspeicher (store=true) oder kein Serverspeicher (store=false) Die meisten zustandsorientierten oder zustandslosen Interactions API-Anwendungen
Vom Server verwaltete Schleife im Hintergrund (background=true) Interactions API (v1beta1) Agent Platform-Serverschleife; Ihr Code fragt get ab Serverseitig verwaltet bis zu max_output_tokens Asynchron (kein offener Clientstream erforderlich) 7-Tage-Serverspeicher (store=true erforderlich) Asynchrone Jobs, Aufrufer in anderen Sprachen über REST und Persistenz einzelner Datensätze
Benutzerdefinierte gespeicherte Schleife im Vordergrund (store=true) Interactions API (v1beta1) Ihr Code (previous_interaction_id + continuation_token, kein input) Bis zu 65.536 (stream=true, Prüfpunkte alle 5.000 Tokens nach 32.768) oder 32.768 (stream=false) 20 Minuten pro Segment 7 Tage Serverspeicher (store=true) REST-Aufrufer und benutzerdefinierte Prüfpunktwiederherstellung
Benutzerdefinierte zustandslose Schleife im Vordergrund (store=false) Interactions API (v1beta1) Ihr Code (ursprünglicher input + continuation_token, kein previous_interaction_id) Bis zu 65.536 (stream=true, Prüfpunkte alle 5.000 Tokens nach 32.768) oder 32.768 (stream=false) 20 Minuten pro Segment Keine Serverspeicherung (Zero Data Retention-Workflows) Benutzerdefinierte REST-Harnesses, die eine zustandslose Ausführung erfordern
Automatische Fortsetzung des Google Gen AI SDK (empfohlen) GenerateContent (v1beta1) Google Gen AI SDKs: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) und Kotlin (>= 1.6.0) Bis zu 65.536 (generate_content_stream) oder 32.768 (generate_content) 20 Minuten pro Segment Keine Serverspeicherung (Zero Data Retention-Workflows) Vorhandene GenerateContent-Anwendungen
Benutzerdefinierte Fortsetzungsschleife GenerateContent (v1beta1) Ihr Code (ursprünglicher contents + continuation_token) Bis zu 65.536 (streamGenerateContent, Prüfpunkte alle 5.000 Tokens nach 32.768) oder 32.768 (generateContent) 20 Minuten pro Segment Keine Serverspeicherung (Zero Data Retention-Workflows) Direkte REST-GenerateContent-Aufrufer und Bewertungstestsysteme

API-Version und SDK-Anforderungen

Für lange Decodierungen sind die folgende API-Version und die folgenden SDK-Mindestversionen erforderlich:

  • v1beta1 API-Anforderung (bekanntes Problem): Die lange Decodierung (continuation_token) sowohl für die Interactions API als auch für GenerateContent (generateContent und streamGenerateContent) wird auf der Agent Platform nur in der v1beta1 API (nicht in der v1) unterstützt. Das Google Gen AI SDK verwendet standardmäßig v1beta1, es sei denn, api_version='v1' wird in http_options (oder api_version="v1" auf interactions.create) angegeben. Verwenden Sie für direkte REST-Aufrufe den Endpunktpfad /v1beta1/.
  • SDK-Versionen und OpenAI-Kompatibilität: Für die automatische Fortsetzung in der Interactions API müssen Sie ein Upgrade auf Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 oder Java >= 1.80.0 durchführen. Für andere Sprachen in der Interactions API rufen Sie die REST API direkt mit background=true oder einer benutzerdefinierten Fortsetzungsschleife auf. Wenn Sie GenerateContent automatisch weiterverwenden möchten, führen Sie ein Upgrade auf Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 oder Kotlin >= 1.6.0 durch. Ältere SDK-Versionen und die OpenAI-Kompatibilitätsschicht können keine langen Vervollständigungen mit Fortsetzungstokens abrufen.

Fortsetzungsregeln für die Interactions API

Für lange Decodierungen in der Interactions API gelten die folgenden Statusübergänge, Verkettungsregeln und Speicherverhalten.

Statuswerte und Ausgabetokenbudget

Wenn generation_config.max_output_tokens in einer Interactions API-Anfrage weggelassen wird, beträgt das Standard-Gesamtausgabebudget 65.536 Tokens. Ein nicht-streaming-Aufruf stoppt also bei 32.768 Tokens mit status="requires_continuation" und ein zweites Segment kann die verbleibenden 32.768 Tokens generieren. Legen Sie generation_config.max_output_tokens auf bis zu 1,048,576 (minus Eingabe-Tokens) für längere Decodierungen im Vordergrund- und background=true-Modus fest. Der Server gibt die folgenden Statuswerte zurück:

  • requires_continuation: Das Ausgabelimit pro Segment (32.768 Nicht-Streaming oder 65.536 Streaming) wurde vor max_output_tokens erreicht. Übergeben Sie den zurückgegebenen continuation_token bei der nächsten Anfrage, um mit der Decodierung fortzufahren.
  • incomplete: Das gesamte max_output_tokens-Budget wurde aufgebraucht. Wenn Sie mit continuation_token fortfahren, ohne max_output_tokens zu erhöhen, wird ein HTTP-400-Fehler (max_output_tokens has already been exhausted) zurückgegeben. Erhöhen Sie max_output_tokens bei der nächsten Anfrage, um die Decodierung fortzusetzen.
  • completed: Die Generierung wurde normal abgeschlossen und continuation_token wird gelöscht.

Verkettung, Moduswechsel und Segmentspeicherung

Für Fortsetzungsanfragen an die Interactions API gelten die folgenden Regeln:

  • Gespeicherte Fortsetzung (store=true, Standard): Übergeben Sie previous_interaction_id, festgelegt auf das Segment id, das die continuation_token ausgegeben hat, zusammen mit continuation_token und lassen Sie input weg (das gespeicherte Segment enthält bereits die Eingabe für die Runde). Kombinieren Sie jedes continuation_token immer mit der previous_interaction_id des Segments, von dem es ausgegeben wurde. Wenn Sie ein continuation_token für eine bereits completed Interaktion übergeben, wird ein HTTP-Fehler 400 zurückgegeben.
  • Zustandslose Fortsetzung (store=false): Lassen Sie previous_interaction_id weg und senden Sie die ursprüngliche input zusammen mit continuation_token für jedes Segment noch einmal.
  • store-Modi zwischen Segmenten wechseln: Sie können während der Decodierung vom gespeicherten (store=true) zum zustandslosen (store=false) Modus wechseln, indem Sie previous_interaction_id weglassen und die ursprüngliche input mit continuation_token noch einmal senden. Der Wechsel von zustandslos (store=false) zu gespeichert (store=true) wird nicht unterstützt, da für previous_interaction_id keine gespeicherte übergeordnete Interaktion vorhanden ist.
  • Wechsel zwischen Vordergrund- und background=true-Modus und Verzweigung: Gespeicherte Fortsetzungen (store=true) können zwischen der Ausführung im Vordergrund (background=false) und im Hintergrund (background=true) über Segmente hinweg wechseln. Dazu gehört auch die Wiederaufnahme einer abgebrochenen background=true-Interaktion von ihrem Prüfpunkt continuation_token (nach 32.768 Ausgabetokens beibehalten) im Hintergrund- oder Vordergrundmodus. Wenn Sie dieselben previous_interaction_id und continuation_token wiederverwenden, werden unabhängige verzweigte Fortsetzungen erstellt.
  • Erzwingung von Turn-Grenzen: Wenn Sie einen neuen Nutzer-Turn (previous_interaction_id mit neuem input und ohne continuation_token) aus einem Segment starten, dessen Status requires_continuation oder incomplete ist, wird ein HTTP-Fehler 400 zurückgegeben. Schließen Sie die Decodierung bis completed ab oder verzweigen Sie Ihren nächsten Turn von der letzten completed-Interaktion. Sobald das letzte Segment completed erreicht, wird durch die Übergabe der id des letzten Segments als previous_interaction_id der gesamte Unterhaltungsverlauf über alle vorherigen Segmente hinweg rekonstruiert.
  • Parameterkonsistenz über Segmente hinweg: Wenn Sie model, system_instruction oder Funktionsdeklarationen (tools) in einem Fortsetzungssegment ändern, wird ein HTTP-400-Fehler zurückgegeben. Behalten Sie thinking_level und integrierte Tools auch segmentübergreifend unverändert bei (siehe Bekannte Probleme).
  • Verhalten von get, list und delete für einzelne Segmente: Im Vordergrundmodus (background=false) wird jedes Segment als separate Interaction-Ressource gespeichert. interactions.get(id) gibt nur dieses Segment zurück, interactions.list() listet jedes Segment separat auf und interactions.delete(id) löscht nur dieses Segment. Wenn Sie eine Kette von Segmenten löschen, löschen Sie sie in umgekehrter Reihenfolge, beginnend mit dem letzten Segment. Im Google Gen AI SDK mit automatic_continuation=True (stream=False) führt interactions.create() alle Segmente bei der Rückgabe zusammen und füllt interaction.continuation_ids mit den geordneten Segment-IDs (die mit interaction.id enden). Wenn ein späteres Segment fehlschlägt, ein numerisches timeout pro Aufruf überschreitet oder mitten im Stream abbricht, nachdem ein fortsetzbarer Prüfpunkt erreicht wurde, löst das SDK ContinuationInterruptedError mit partial_interaction, continuation_token, interaction_id und continuation_ids aus, sodass Sie ab continuation_token fortfahren können.

GenerateContent-Regeln für benutzerdefinierte Schleifen

Beachten Sie in einer benutzerdefinierten GenerateContent-Fortsetzungsschleife die folgenden Regeln:

  • Legen Sie max_output_tokens auf einen Wert größer als 65.536 (Streaming) oder 32.768 (Nicht-Streaming) bis zu 1.048.576 fest und senden Sie die ursprünglichen Werte für contents, system_instruction und tools bei jeder Fortsetzungsanfrage zusammen mit dem neuesten continuation_token (ein Feld auf oberster Ebene in GenerateContentRequest in REST oder in GenerateContentConfig im Google Gen AI SDK) noch einmal.
  • Hängen Sie keine unvollständige Modellausgabe an contents an und senden Sie keinen Folgeprompt, in dem Sie das Modell auffordern, fortzufahren.
  • Setzen Sie die Schleife fort, solange finish_reason den Wert CONTINUATION hat und continuation_token vorhanden ist,auch wenn ein Segment alle 32.768 oder 65.536 Tokens für das Nachdenken (parts: [{"text": ""}]) verbraucht hat. Wenn finish_reason den Wert MAX_TOKENS hat,wenn continuation_token vorhanden ist, erhöhen Sie max_output_tokens in der nächsten Anfrage.
  • Kombiniert akkumulierte Teile erst nach STOP zu einer einzelnen model-Runde für den Verlauf mit mehreren Runden.

Tokenzählung, Komprimierung und implizites Caching

Die Tokenabrechnung und das Caching über Fortsetzungssegmente hinweg funktionieren so:

  • In der Interactions API werden bei nicht-streamingbasierten interactions.create()-Aufrufen mit automatic_continuation=True und vom Server verwalteten background=true-Interaktionen die Tokenzahlen über alle Segmente in usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens) hinweg summiert. Die Prompt-Anzahl des ersten Segments wird in usage.initial_input_tokens beibehalten. In benutzerdefinierten Vordergrundschleifen und gestreamten interaction.completed-Ereignissen wird in der usage jedes Segments nur das Delta dieses Segments gemeldet. Addieren Sie daher die usage-Felder über die Segmente hinweg, um die Gesamtzahl der abgerechneten Tokens zu erhalten.
  • Am GenerateContent akkumuliert das Python Google Gen AI SDK (generate_content und generate_content_stream) die Gesamtzahl der abgerechneten Tokens über Segmente hinweg im endgültigen usage_metadata und behält initial_prompt_token_count bei. In benutzerdefinierten REST-Schleifen werden die endgültigen Werte für prompt_token_count, cached_content_token_count, candidates_token_count und thoughts_token_count über die Segmente hinweg summiert.
  • Da jedes Segment zur Fortsetzung im Vordergrund die Unterhaltung und zuvor generierte Tokens als Eingabe neu vorbefüllt, steigen usage.total_input_tokens (in der Interactions API) und prompt_token_count (in GenerateContent) über die Segmente hinweg an. Verwenden Sie keine kumulativen Eingabezahlen, um die Kontextkomprimierung in Agenten-Frameworks auszulösen. Prüfen Sie stattdessen usage.initial_input_tokens (oder initial_prompt_token_count auf GenerateContent) und komprimieren Sie erst, nachdem die Runde beendet ist (status="completed" oder kein continuation_token).
  • In jedem Fortsetzungssegment wird der Prompt sowie zuvor decodierte Tokens noch einmal vorab ausgefüllt. Außerdem wird automatisch das implizite Kontext-Caching (mindestens 4.096 Tokens,wobei das dauerhafte Caching standardmäßig aktiviert ist) angewendet, wenn Segmente nacheinander ausgeführt werden. Abgeschlossene Segmente werden am Ende jedes Segments abgerechnet, auch wenn ein späteres Segment fehlschlägt oder abgebrochen wird.

Von 3.1 Pro zu 4 Carbon migrieren

Das folgende Verhalten unterscheidet sich von gemini-3.1-pro-preview:

  • 4 Carbon hat ein einheitliches Limit von 1.048.576 Tokens für Eingabe und Ausgabe (wobei die Ausgabe den Thinking-Modus, Funktionsaufrufe und die endgültige Antwort umfasst), anstatt separater Limits für Eingabe und Ausgabe. Ein einzelnes Vordergrundsegment ist beim Streaming auf 65.536 Tokens (oder 32.768 Tokens ohne Streaming) begrenzt. Die Ausgabe kann mit langen Decodierungen in der Interactions API oder GenerateContent auf bis zu 1.048.576 Tokens erweitert werden (wird automatisch im Google Gen AI SDK, mit background=true in der Interactions API oder mit continuation_token in benutzerdefinierten Schleifen verarbeitet).
  • thinking_budget gibt einen HTTP-400-Fehler zurück, anstatt einer Denkebene zugeordnet zu werden. MINIMAL gibt ebenfalls einen Fehler zurück.
  • Explizites Kontext-Caching wird nicht unterstützt.
  • Jedes vom Modell verarbeitete Token wird in Rechnung gestellt, einschließlich interner Systemanweisungen für Tools und Funktionsdeklarationen bei der Verwendung von Fundierung.

Einen direkten Vergleich finden Sie unter Von Gemini 3.1 Pro migrieren.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu" ("global" and "us" for cyber)
 )

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-carbon",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Carbon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

So migrieren Sie von gemini-3.1-pro-preview:

  1. Aktualisieren Sie die Modell-ID auf gemini-4-carbon (oder gemini-4-carbon-cyber-permissive für Cybersicherheits-Arbeitslasten, die im Rahmen des Fairwind-Programms genehmigt wurden).
  2. Auf das neueste Google Gen AI SDK upgraden und das einheitliche Limit für Eingabe- und Ausgabetokens berücksichtigen: Führen Sie ein Upgrade auf google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 oder Java >= 1.80.0 durch, um die automatische Fortsetzung der Interactions API zu nutzen (oder >= 2.30.1 Python / >= 2.29.1 JavaScript auf GenerateContent). Eingabe- und Ausgabetokens (einschließlich Denkprozessen und Funktionsaufrufen) teilen sich das einheitliche Limit von 1.048.576 Tokens. Für Ausgaben mit mehr als 65.536 Tokens (bis zu 1.048.576 Tokens) in der Interactions API oder GenerateContent legen Sie max_output_tokens auf einen Wert über 65.536 fest, damit das Google Gen AI SDK automatisch über Segmente hinweg fortgesetzt wird (oder verwenden Sie background=true oder eine benutzerdefinierte continuation_token-Schleife).
  3. Parameter für das Reasoning-Budget ersetzen: Ersetzen Sie thinking_budget und MINIMAL durch thinking_level, wobei der Wert auf LOW, MEDIUM (Standardwert für gemini-4-carbon) oder HIGH (Standardwert für gemini-4-carbon-cyber-permissive) festgelegt ist. Verwenden Sie in der Interactions API die kleingeschriebenen Werte "low", "medium" oder "high".
  4. Entfernen Sie das explizite Caching und laden Sie statische Prompt-Inhalte (4.096 Tokens oder mehr) vorab,um das automatische implizite Caching zu ermöglichen.
  5. Parameter entfernen, die keine Auswirkungen haben oder nicht unterstützt werden: Entfernen Sie ignorierte und abgelehnte Generierungsfelder so:
    • Entfernen Sie temperature, top_p und top_k, da sie ignoriert werden.
    • Entfernen Sie frequency_penalty, presence_penalty und alle candidate_count-Werte, die größer als 1 sind.
    • Entfernen Sie alle vorausgefüllten Modellantworten aus dem Unterhaltungsverlauf.

Zusammenfassende Checkliste für Entwickler

Anhand der folgenden Checkliste können Sie Ihre 4 Carbon-Integration überprüfen:

Bekannte Probleme

Die folgenden bekannten Probleme gelten für 4 Carbon Long-Decodierungen:

  • Lange Decodierungen erfordern v1beta1: Lange Decodierungen (continuation_token) werden sowohl in der Interactions API als auch in der GenerateContent API (generateContent und streamGenerateContent) nur in der v1beta1 API (nicht v1) auf der Agent Platform unterstützt. Das Google Gen AI SDK verwendet standardmäßig v1beta1, es sei denn, api_version='v1' ist in http_options (oder api_version="v1" auf interactions.create) festgelegt. Verwenden Sie für direkte REST-Aufrufe den Endpunktpfad /v1beta1/.
  • Parameteränderungen über Fortsetzungssegmente der Interactions API hinweg: Wenn Sie model, system_instruction oder Funktionsdeklarationen über Fortsetzungssegmente hinweg ändern, wird ein HTTP-Fehler 400 zurückgegeben. Änderungen an generation_config.thinking_level oder integrierten Tools (google_search, code_execution, url_context) während der Decodierung werden dagegen nicht von der Servervalidierung abgelehnt. Lassen Sie thinking_level und integrierte Tools in allen Segmenten einer Fortsetzungsschleife unverändert.

Zusätzliche Ressourcen

Weitere Informationen zu 4 Carbon finden Sie in den folgenden Ressourcen: