Guida per gli sviluppatori a Gemini 4 Carbon

Gemini 4 Carbon è il modello pionieristico di Google che eccelle nel lavoro approfondito in attività complesse del mondo reale in vari ambiti, tra cui programmazione, finanza, diritto, cybersicurezza e scienza. Fa parte della famiglia Gemini 4. Gemini 4 Carbon è un modello pionieristico di Google soggetto alla Sezione 34 dei Termini specifici dei servizi (per maggiori dettagli, consulta Monitoraggio degli abusi).

Questo documento illustra le funzionalità principali di 4 Carbon, le convenzioni API che applica, come eseguire la migrazione e una guida rapida. Per una panoramica della famiglia Gemini 4, consulta Inizia a utilizzare Gemini 4.

Funzionalità chiave di Gemini 4 Carbon

Gemini 4 Carbon include le seguenti funzionalità:

  • Limite unificato di token di input e output: 4 Carbon ha un limite unificato di 1.048.576 token che include sia i token di input che quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale).
  • Decodifiche lunghe fino a 1.048.576 token: 4 Carbon estende la generazione oltre un singolo segmento in primo piano (65.536 token in streaming o 32.768 token non in streaming) fino a 1.048.576 token (meno i token di input) sia sull'API Interactions sia su GenerateContent (v1beta1). L'SDK Google Gen AI gestisce continuation_token automaticamente tra i segmenti oppure puoi eseguire decodifiche in background asincrone gestite dal server (background=true) o gestire continuation_token in un loop di continuazione personalizzato.
  • Livelli di ragionamento: 4 Carbon supporta LOW, MEDIUM (predefinito su gemini-4-carbon) e HIGH (predefinito su gemini-4-carbon-cyber-permissive).
  • Memorizzazione nella cache implicita con memorizzazione nella cache durevole: la memorizzazione nella cache implicita viene applicata automaticamente ai prefissi dei prompt condivisi di almeno 4096 token, con la memorizzazione nella cache durevole abilitata per impostazione predefinita. La memorizzazione nella cache del contesto esplicita non è supportata.
  • Input di file Office e OpenDocument: oltre ai PDF e al testo normale, 4 Carbon accetta file Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) e OpenDocument (.odt, .odp, .ods) in linea o da Cloud Storage sia su GenerateContent sia sull'API Interactions.
  • Comprensione dei video agentica: la comprensione dei video agentica è in disponibilità generale e disattivata per impostazione predefinita.

Guida rapida

Prima di iniziare, devi autenticarti su Gemini Enterprise Agent Platform utilizzando le credenziali predefinite dell'applicazione (ADC) o una chiave API. Per saperne di più, consulta Inizia a utilizzare Agent Platform.

Nei blocchi di codice seguenti, sostituisci PROJECT_ID con il tuo ID progetto.

Provalo in Agent Studio

Per testare i prompt e configurare gemini-4-carbon nell'interfaccia utente di Agent Studio, segui questi passaggi:

  1. Apri Agent Studio nel tuo progetto Google Cloud e seleziona gemini-4-carbon nel gruppo Gemini.
  2. In Impostazioni modello, configura le seguenti opzioni:
    • Livello di ragionamento: scegli Low, Medium (predefinito) o High.
    • Regione: seleziona Global, us o eu.
    • Limite token di output: imposta un valore compreso tra 32,768 e 1,048,576 (1,048,576 predefinito). Agent Studio gestisce automaticamente i token di continuazione per le risposte che superano il limite di una singola richiesta.

Installazione

Esegui l'upgrade all'SDK Google Gen AI più recente. La continuazione automatica nell'API Interactions richiede google-genai >= 2.34.0 per Python, @google/genai >= 2.32.0 per JavaScript/TypeScript, >= 1.77.0 per Go o >= 1.80.0 per Java (su GenerateContent, la continuazione automatica richiede >= 2.30.1 per Python, >= 2.29.1 per JavaScript/TypeScript, >= 1.74.0 per Go, >= 1.77.0 per Java, >= 1.26.0 per .NET o >= 1.6.0 per Kotlin):

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

Richiesta di base

Invia una richiesta a gemini-4-carbon utilizzando l'SDK Google Gen AI o REST:

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 (API Interactions)

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"
    }
  }
}'

Output strutturato

Per generare un output JSON conforme a uno schema, configura response_mime_type e 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)

Esempi di decodifica lunghi

Per impostazione predefinita, un singolo segmento API in primo piano genera fino a 65.536 token di output durante lo streaming o 32.768 token di output quando non è in streaming, dove l'output include il ragionamento, le chiamate di funzione e la risposta finale. Per generare completamenti fino a 1.048.576 token (meno i token di input), utilizza le decodifiche lunghe nell'API Interactions o in GenerateContent. Per le opzioni di continuazione, le transizioni di stato e le regole di convalida, consulta Decodifiche lunghe.

Utilizza decodifiche lunghe con l'API Interactions

In google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 e Java >= 1.80.0, interactions.create() segue automaticamente continuation_token tra i segmenti ogni volta che un segmento restituisce status="requires_continuation". Puoi anche disattivare l'opzione (automatic_continuation=False) per eseguire un loop personalizzato archiviato (store=True) o stateless (store=False):

Python (SDK automatico)

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 (loop personalizzato)

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 (Stored)

# 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 (stateless)

# 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"
    }
  }'

Per l'esecuzione asincrona gestita dal server (background=True con store=True) o il recupero dai checkpoint di streaming (eventi interaction.status_update emessi a 32.768 token di output e ogni 5000 token successivi), utilizza i seguenti pattern:

Python (background)

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 (Background)

# 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 (checkpoint di flussi di dati)

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 (checkpoint di streaming)

# 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"
    }
  }'

Utilizza decodifiche lunghe con GenerateContent

Su GenerateContent (v1beta1), imposta max_output_tokens su un valore superiore a 65.536 per le richieste di streaming o superiore a 32.768 per le richieste non di streaming (fino a 1.048.576). L'SDK Google Gen AI segue automaticamente continuation_token tra i segmenti quando finish_reason è CONTINUATION (imposta automatic_continuation=False in GenerateContentConfig per disattivare l'opzione) oppure puoi passare continuation_token in un loop personalizzato:

Python (SDK - Consigliato)

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 (loop di continuazione personalizzato)

# 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"}
    }
  }'

Regole obbligatorie per le API e convenzioni comportamentali

4 Carbon applica le convenzioni nelle sezioni seguenti per i livelli di pensiero, i limiti dei token, la memorizzazione nella cache, i parametri di generazione e l'esecuzione di strumenti multi-turn.

Livelli di ragionamento

4 Carbon supporta tre valori thinking_level (thinking_budget e MINIMAL restituiscono un errore di convalida HTTP 400). Passa i valori in maiuscolo ("LOW", "MEDIUM", "HIGH") su GenerateContent e i valori in minuscolo ("low", "medium", "high") sull'API Interactions. La tabella seguente elenca ogni livello di ragionamento e i relativi workload consigliati:

Livello di pensiero Workload consigliati
HIGH (valore predefinito su gemini-4-carbon-cyber-permissive) Software engineering multifile, prove formali, progettazione dell'architettura e rilevamento delle vulnerabilità.
MEDIUM (valore predefinito su gemini-4-carbon) Programmazione generale, utilizzo di strumenti, domande e risposte sui documenti e comprensione dei video.
LOW Classificazione, riepilogo ed estrazione dei metadati.

Limiti di token, memorizzazione nella cache e fatturazione

4 Carbon applica le seguenti regole relative a token, memorizzazione nella cache, contenuti multimediali e fatturazione:

  • Limite unificato dei token di input e output e budget di output predefiniti: I budget dei token e i limiti dei segmenti in primo piano funzionano come segue:
    • Il limite totale di token del modello è 1,048,576 token e include sia i token di input che quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale). max_output_tokens controlla il limite di token di output per la generazione (fino a 1,048,576 meno i token di input); l'impostazione di max_output_tokens maggiore di 1,048,576 restituisce un errore HTTP 400.
    • Se max_output_tokens viene omesso su GenerateContent o sull'API Interactions, il budget di output totale predefinito (ragionamento, chiamate di funzione e risposta) è di 65.536 token. Poiché un singolo segmento in primo piano genera fino a 65.536 token in modalità flusso o 32.768 token in modalità non flusso, l'SDK Google Gen AI (v1beta1) concatena automaticamente due segmenti da 32.768 token nelle chiamate non in modalità flusso, se necessario, mentre una singola richiesta REST non in modalità flusso si interrompe dopo un segmento in primo piano da 32.768 token. In Agent Studio, il limite di token di output è impostato su 1,048,576 per impostazione predefinita con continuazione automatica.
  • Decodifiche lunghe: un singolo segmento in primo piano genera fino a 65.536 token di output in modalità flusso o 32.768 token di output in modalità non flusso. Per estendere l'output single-turn fino a 1.048.576 token (meno i token di input) sull'API Interactions o su GenerateContent (v1beta1), consulta Decodifiche lunghe.
  • Memorizzazione nella cache del contesto: la memorizzazione nella cache del contesto esplicita non è supportata. La memorizzazione nella cache implicita (con la memorizzazione nella cache durevole abilitata per impostazione predefinita) si applica automaticamente ai prefissi dei prompt condivisi di almeno 4096 token, quindi inserisci i contenuti statici all'inizio del prompt.
  • Input Office e OpenDocument: passa i file 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) e i fogli di lavoro Excel o OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) in linea o tramite URI Cloud Storage (gs://) utilizzando inlineData o fileData sugli input GenerateContent e document (inclusi i risultati degli strumenti) nell'API Interactions.
  • Video agentico: i video caricati vengono impostati su media_processing="static" per impostazione predefinita. Imposta media_processing="agentic" per attivare l'elaborazione video agentica.
  • Conteggio e fatturazione dei token: ogni token elaborato dal modello viene conteggiato e fatturato, inclusi i token di ragionamento, le istruzioni di sistema degli strumenti interni e le dichiarazioni delle funzioni quando si utilizza il grounding. Anche il grounding con la Ricerca Google viene fatturato per query.

Parametri, chiamata di funzione e convalida della chat

4 Carbon applica le seguenti regole per i parametri di generazione, le chiamate agli strumenti e la cronologia chat:

  • Parametri di campionamento ignorati (temperature, top_k, top_p): il backend ignora i valori personalizzati. Controlla la profondità del ragionamento con thinking_level e il formato di output con response_schema.
  • Parametri non supportati (frequency_penalty, presence_penalty e candidate_count maggiori di 1): se passi frequency_penalty, presence_penalty o candidate_count maggiori di 1 (candidateCount è fissato a 1), viene restituito un errore HTTP 400. Rimuovi questi parametri dalle tue richieste.

  • Chiamata di funzione: le dichiarazioni degli strumenti e i turni di esecuzione seguono queste regole:

    • Simmetria di svolta: ogni FunctionResponse deve corrispondere a id, name e all'ordine del FunctionCall precedente.
    • Esecuzione sequenziale: preferisci i turni di esecuzione sequenziale degli strumenti nei loop di strumenti in più passaggi.

    • Formattazione pre-strumento: separa le istruzioni in linea con \n\n ed evita il testo non strutturato prima delle chiamate allo strumento. Per registrare lo stato intermedio prima di una chiamata allo strumento, utilizza una dichiarazione di funzione dedicata:

      {
  "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"]
  }
}

  • Convalida della sequenza di chat: i payload della chat a più turni applicano i seguenti vincoli:

    • I payload della cronologia non possono terminare con un turno del ruolo model.
    • I turni precompilati del modello non sono supportati.

Decodifiche lunghe

La decodifica lunga suddivide una generazione fino a 1.048.576 token (meno i token di input) in più segmenti nell'API Interactions o GenerateContent (v1beta1). Nell'API Interactions, ogni segmento in primo piano genera fino a 65.536 token di output durante lo streaming (stream=true) o 32.768 token di output quando non è in streaming (stream=false) e restituisce status="requires_continuation" con un continuation_token criptato oppure puoi impostare background=true (store=true) in modo che il server esegua il ciclo di continuazione in modo asincrono e memorizzi l'output unito in un Interaction. Su GenerateContent, i segmenti di streaming generano fino a 65.536 token di output e i segmenti non di streaming generano fino a 32.768 token di output prima di emettere finish_reason=CONTINUATION con continuation_token, continuando fino a finish_reason=STOP. In Agent Studio, l'impostazione del limite di token di output su un valore superiore a 65.536 fino a 1.048.576 gestisce automaticamente i token di continuazione. Per esempi di codice eseguibile, consulta gli esempi di avvio rapido per la decodifica lunga.

Quando utilizzare la decodifica lunga

La maggior parte delle richieste viene completata entro il budget di output predefinito di 65.536 token (o un singolo segmento in primo piano non in streaming di 32.768 token su REST). Utilizza la decodifica lunga solo quando una risposta richiede un output maggiore. La decodifica lunga offre al modello più spazio per ragionare, ma non rende le risposte più lunghe (utilizza thinking_level per controllare la profondità del ragionamento).

Workload Utilizzare la decodifica lunga? Perché
Matematica, scienze, ricerca e dimostrazioni formali complesse Sì Il modello può spendere più di 65.536 token per esplorare e verificare il suo ragionamento.
Le attività di programmazione e agentiche più difficili Sì Alcune attività richiedono più di 65.536 token di ragionamento e codice in un'unica risposta. La maggior parte delle attività di programmazione e agentiche viene completata con meno di 65.536 token.
Framework di valutazione che si fermano al limite di output Sì La decodifica lunga impedisce risposte incomplete quando il modello impiega un'intera richiesta di 65.536 o 32.768 token per il ragionamento.
Chat, domande e risposte, riepilogo, classificazione ed estrazione No Queste attività vengono completate con un numero di token ben inferiore a 32.768.
Richieste di una lunghezza fissa, ad esempio "scrivi un libro di 700.000 parole" No Il modello non segue i target di lunghezza.
Agenti che chiamano strumenti in molti turni brevi No Ogni turno è breve. Output di grandi dimensioni in ogni turno riempiono rapidamente il limite unificato di input e output di 1.048.576 token.
Prompt vicini al limite di input di 1.048.576 token No L'output può utilizzare solo 1.048.576 token meno l'input.
Richieste sensibili alla latenza No La decodifica lunga può richiedere diversi minuti.

Scegli un'opzione di continuazione

Seleziona un pattern di continuazione in base alla superficie dell'API, alla postura di archiviazione e all'ambiente di runtime. Tutte le opzioni nella tabella seguente raggiungono lo stesso limite di 1.048.576 token (meno i token di input) su gemini-4-carbon e gemini-4-carbon-cyber-permissive.

Opzione di continuazione Piattaforma API Chi inizia ogni segmento Token per segmento Limite di tempo per richiesta Spazio di archiviazione del server Ideale per
(Consigliato) Continuazione automatica dell'SDK Google Gen AI API Interactions (v1beta1) SDK Google Gen AI: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) e Java (>= 1.80.0) Fino a 65.536 (stream=true) o 32.768 (stream=false) 20 minuti per segmento Archiviazione sul server per 7 giorni per impostazione predefinita (store=true) o nessuna archiviazione (store=false) La maggior parte delle applicazioni API Interactions stateful o stateless
Loop in background gestito dal server (background=true) API Interactions (v1beta1) Loop del server Agent Platform; il tuo codice esegue il polling di get Gestito lato server fino a max_output_tokens Asincrona (non è richiesto uno stream client aperto) Spazio di archiviazione del server per 7 giorni (store=true richiesto) Job asincroni, chiamanti in altre lingue tramite REST e persistenza di un singolo record
Loop archiviato in primo piano personalizzato (store=true) API Interactions (v1beta1) Il tuo codice (previous_interaction_id + continuation_token, senza input) Fino a 65.536 (stream=true, checkpoint ogni 5000 token dopo 32.768) o 32.768 (stream=false) 20 minuti per segmento Spazio di archiviazione sul server per 7 giorni (store=true) Chiamanti REST e recupero di checkpoint personalizzati
Loop stateless in primo piano personalizzato (store=false) API Interactions (v1beta1) Il tuo codice (input originale + continuation_token, senza previous_interaction_id) Fino a 65.536 (stream=true, checkpoint ogni 5000 token dopo 32.768) o 32.768 (stream=false) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Harness REST personalizzati che richiedono l'esecuzione stateless
(Consigliato) Continuazione automatica dell'SDK Google Gen AI GenerateContent (v1beta1) SDK Google Gen AI: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) e Kotlin (>= 1.6.0) Fino a 65.536 (generate_content_stream) o 32.768 (generate_content) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Applicazioni GenerateContent esistenti
Loop di continuazione personalizzato GenerateContent (v1beta1) Il tuo codice (contents originale + continuation_token) Fino a 65.536 (streamGenerateContent, checkpoint ogni 5000 token dopo 32.768) o 32.768 (generateContent) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Chiamanti REST GenerateContent diretti e strumenti di valutazione

Requisiti relativi alla versione dell'API e all'SDK

Le decodifiche lunghe richiedono la seguente versione dell'API e le seguenti versioni minime dell'SDK:

  • Requisito dell'API v1beta1 (problema noto): la decodifica lunga (continuation_token) sia nell'API Interactions sia in GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1) su Agent Platform. L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che api_version='v1' non sia specificato in http_options (o api_version="v1" su interactions.create); per le chiamate REST dirette, utilizza il percorso dell'endpoint /v1beta1/.
  • Versioni dell'SDK e compatibilità con OpenAI: per la continuazione automatica nell'API Interactions, esegui l'upgrade a Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 o Java >= 1.80.0 (per altri linguaggi nell'API Interactions, chiama direttamente l'API REST con background=true o un loop di continuazione personalizzato). Per la continuazione automatica su GenerateContent, esegui l'upgrade a Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 o Kotlin >= 1.6.0. Le versioni precedenti dell'SDK e il livello di compatibilità con OpenAI non possono recuperare i completamenti lunghi utilizzando i token di continuazione.

Regole di continuazione dell'API Interactions

Le seguenti transizioni di stato, regole di concatenamento e comportamenti di archiviazione si applicano alle decodifiche lunghe nell'API Interactions.

Valori di stato e budget dei token di output

Quando generation_config.max_output_tokens viene omesso in una richiesta API Interactions, il budget di output totale viene impostato su 65.536 token (quindi una chiamata non in streaming si interrompe a 32.768 token con status="requires_continuation" e un secondo segmento può generare i restanti 32.768 token). Imposta generation_config.max_output_tokens su un valore massimo di 1,048,576 (meno i token di input) per decodifiche più lunghe sia in modalità in primo piano che background=true. Il server restituisce i seguenti valori di stato:

  • requires_continuation: il limite di output per segmento (32.768 non in streaming o 65.536 in streaming) è stato raggiunto prima di max_output_tokens; passa il continuation_token restituito alla richiesta successiva per continuare la decodifica.
  • incomplete: il budget totale di max_output_tokens è stato esaurito; se continui con continuation_token senza aumentare max_output_tokens, viene restituito un errore HTTP 400 (max_output_tokens has already been exhausted). Aumenta max_output_tokens nella richiesta successiva per riprendere la decodifica.
  • completed: la generazione è terminata naturalmente e continuation_token viene cancellato.

Concatenamento, cambio di modalità e archiviazione dei segmenti

Le richieste di continuazione nell'API Interactions applicano le seguenti regole:

  • Continuazione memorizzata (store=true, predefinita): passa previous_interaction_id impostato sul segmento id che ha emesso continuation_token insieme a continuation_token e ometti input (il segmento memorizzato contiene già l'input del turno). Associa sempre ogni continuation_token al previous_interaction_id del segmento che lo ha emesso; il passaggio di un continuation_token su un'interazione già completed restituisce un errore HTTP 400.
  • Continuazione stateless (store=false): ometti previous_interaction_id e invia nuovamente l'input originale insieme a continuation_token su ogni segmento.
  • Cambio delle modalità store tra i segmenti: puoi passare dalla modalità archiviata (store=true) a quella stateless (store=false) a metà decodifica omettendo previous_interaction_id e inviando nuovamente l'originale input con continuation_token. Il passaggio da stateless (store=false) a archiviata (store=true) non è supportato perché non esiste un'interazione principale archiviata per previous_interaction_id.
  • Cambio di modalità e branching in primo piano e background=true: le continuazioni archiviate (store=true) possono passare dall'esecuzione in primo piano (background=false) a quella in background (background=true) tra i segmenti, incluso il ripristino di un'interazione background=true annullata dal relativo checkpoint continuation_token (persistente dopo 32.768 token di output) in modalità in background o in primo piano. Il riutilizzo degli stessi previous_interaction_id e continuation_token crea continuazioni ramificate indipendenti.
  • Applicazione dei limiti dei turni: l'avvio di un nuovo turno utente (previous_interaction_id con un nuovo input e senza continuation_token) da un segmento il cui stato è requires_continuation o incomplete restituisce un errore HTTP 400. Completa la decodifica fino a completed o crea un ramo per il turno successivo dall'interazione completed più recente. Una volta che il segmento finale raggiunge completed, il passaggio di id di quel segmento finale come previous_interaction_id ricostruisce la cronologia completa della conversazione in tutti i segmenti precedenti.
  • Coerenza dei parametri tra i segmenti: la modifica di model, system_instruction o delle dichiarazioni di funzione (tools) in un segmento di continuazione restituisce un errore HTTP 400. Mantieni invariati anche thinking_level e gli strumenti integrati nei vari segmenti (consulta Problemi noti).
  • Comportamento di get, list e delete per un singolo segmento: in modalità in primo piano (background=false), ogni segmento viene archiviato come risorsa Interaction separata (interactions.get(id) restituisce solo quel segmento, interactions.list() elenca ogni segmento separatamente e interactions.delete(id) elimina solo quel segmento; quando elimini una catena di segmenti, eliminali in ordine inverso, dall'ultimo segmento indietro). Nell'SDK Google Gen AI con automatic_continuation=True (stream=False), interactions.create() unisce tutti i segmenti al ritorno e compila interaction.continuation_ids con gli ID segmento ordinati (che terminano con interaction.id). Se un segmento successivo non va a buon fine, supera un timeout numerico per chiamata o si interrompe a metà flusso dopo che è stato superato un checkpoint ripristinabile, l'SDK genera ContinuationInterruptedError con partial_interaction, continuation_token, interaction_id e continuation_ids in modo da poter riprendere da continuation_token.

Regole del loop personalizzato GenerateContent

In un loop di continuazione GenerateContent personalizzato, segui queste regole:

  • Imposta max_output_tokens su un valore superiore a 65.536 (streaming) o 32.768 (non streaming) fino a 1.048.576 e invia nuovamente i valori originali di contents, system_instruction e tools in ogni richiesta di continuazione insieme all'ultimo continuation_token (un campo di primo livello su GenerateContentRequest in REST o in GenerateContentConfig nell'SDK Google Gen AI).
  • Non aggiungere l'output parziale del modello a contents e non inviare un prompt aggiuntivo per chiedere al modello di continuare.
  • Continua il loop finché finish_reason è CONTINUATION e continuation_token è presente, anche se un segmento ha utilizzato tutti i 32.768 o 65.536 token per il ragionamento (parts: [{"text": ""}]). Se finish_reason è MAX_TOKENS quando continuation_token è presente, aumenta max_output_tokens nella richiesta successiva.
  • Combina le parti accumulate in un unico turno model per la cronologia multi-turno solo dopo STOP.

Conteggio dei token, compattazione e memorizzazione nella cache implicita

Il conteggio e la memorizzazione nella cache dei token nei segmenti di continuazione funzionano come segue:

  • Nell'API Interactions, le chiamate interactions.create() non in streaming con automatic_continuation=True e le interazioni background=true gestite dal server sommano i conteggi dei token in tutti i segmenti in usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), preservando il conteggio dei prompt del primo segmento in usage.initial_input_tokens. Nei loop in primo piano personalizzati e negli eventi interaction.completed in streaming, il campo usage di ogni segmento riporta solo il delta di quel segmento, quindi somma i campi usage tra i segmenti per ottenere i token fatturati totali.
  • Su GenerateContent, l'SDK Google Gen AI per Python (generate_content e generate_content_stream) accumula i token fatturati totali tra i segmenti nel usage_metadata finale e conserva initial_prompt_token_count. Nei loop REST personalizzati, somma i valori finali di prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count tra i segmenti.
  • Poiché ogni segmento di prosecuzione in primo piano precompila nuovamente la conversazione e i token generati in precedenza come input, usage.total_input_tokens (nell'API Interactions) e prompt_token_count (in GenerateContent) aumentano tra i segmenti. Non utilizzare i conteggi degli input cumulativi per attivare la compressione del contesto nelle infrastrutture agentiche; controlla invece usage.initial_input_tokens (o initial_prompt_token_count su GenerateContent) e comprimi solo dopo il completamento del turno (status="completed" o nessun continuation_token).
  • Ogni segmento di continuazione precompila nuovamente il prompt e i token decodificati in precedenza e si qualifica automaticamente per la memorizzazione nella cache del contesto implicita (minimo 4096 token, con memorizzazione nella cache durevole abilitata per impostazione predefinita) quando i segmenti vengono eseguiti uno dopo l'altro. I segmenti completati vengono fatturati alla fine di ogni segmento, anche se un segmento successivo non va a buon fine o viene annullato.

Esegui la migrazione a 4 Carbon da 3.1 Pro

Il seguente comportamento è diverso da gemini-3.1-pro-preview:

  • 4 Carbon ha un limite unificato di 1.048.576 token per input e output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale), anziché limiti di input e output separati. Un singolo segmento in primo piano ha un limite di 65.536 token durante lo streaming (o 32.768 token quando non è in streaming) e l'output può essere esteso fino a 1.048.576 token utilizzando le decodifiche lunghe sull'API Interactions o GenerateContent (gestite automaticamente nell'SDK Google Gen AI, con background=true sull'API Interactions o utilizzando continuation_token in loop personalizzati).
  • thinking_budget restituisce un errore HTTP 400 anziché essere mappato a un livello di ragionamento. Anche MINIMAL restituisce un errore.
  • La memorizzazione nella cache del contesto esplicita non è supportata.
  • Ogni token elaborato dal modello viene fatturato, incluse le istruzioni di sistema dello strumento interno e le dichiarazioni delle funzioni quando si utilizza il grounding.

Per un confronto fianco a fianco, consulta Esegui la migrazione da Gemini 3.1 Pro.

 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"
         ),
     ),
 )

Per eseguire la migrazione da gemini-3.1-pro-preview, segui questi passaggi:

  1. Aggiorna l'ID modello in gemini-4-carbon (o gemini-4-carbon-cyber-permissive per i workload di cybersicurezza approvati tramite il programma Fairwind).
  2. Esegui l'upgrade all'SDK Google Gen AI più recente e tieni conto del limite unificato di token di input e output: esegui l'upgrade a google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 o Java >= 1.80.0 per la continuazione automatica dell'API Interactions (o >= 2.30.1 Python/>= 2.29.1 JavaScript su GenerateContent). I token di input e output (incluse le chiamate di funzione e di ragionamento) condividono il limite unificato di 1.048.576 token. Per output superiori a 65.536 token (fino a 1.048.576 token) nell'API Interactions o GenerateContent, imposta max_output_tokens su un valore superiore a 65.536 in modo che l'SDK Google Gen AI continui automaticamente tra i segmenti (o utilizza background=true o un ciclo continuation_token personalizzato).
  3. Sostituisci il parametro del budget di ragionamento: sostituisci thinking_budget e MINIMAL con thinking_level impostato su LOW, MEDIUM (predefinito su gemini-4-carbon) o HIGH (predefinito su gemini-4-carbon-cyber-permissive) (utilizza "low", "medium" o "high" in minuscolo nell'API Interactions).
  4. Rimuovi la memorizzazione nella cache esplicita e carica in anticipo i contenuti statici del prompt (4096 token o più) per la memorizzazione nella cache implicita automatica.
  5. Rimuovi i parametri che non hanno effetto o non sono supportati: rimuovi i campi di generazione ignorati e rifiutati come segue:
    • Rimuovi temperature, top_p e top_k, che vengono ignorati.
    • Rimuovi frequency_penalty, presence_penalty e qualsiasi valore candidate_count maggiore di 1.
    • Rimuovi eventuali turni precompilati del modello dalle cronologie delle conversazioni.

Elenco di controllo di riepilogo per gli sviluppatori

Utilizza il seguente elenco di controllo per verificare l'integrazione di 4 Carbon:

Problemi noti

I seguenti problemi noti si applicano alle decodifiche lunghe di 4 Carbon:

  • Le decodifiche lunghe richiedono v1beta1: la decodifica lunga (continuation_token) sia sull'API Interactions sia sull'API GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1) su Agent Platform. L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che api_version='v1' non sia impostato in http_options (o api_version="v1" su interactions.create); per le chiamate REST dirette, utilizza il percorso dell'endpoint /v1beta1/.
  • Modifiche ai parametri nei segmenti di continuazione dell'API Interactions: la modifica di model, system_instruction o delle dichiarazioni delle funzioni nei segmenti di continuazione restituisce un errore HTTP 400, mentre le modifiche a metà decodifica di generation_config.thinking_level o degli strumenti integrati (google_search, code_execution, url_context) non vengono rifiutate dalla convalida del server. Mantieni invariati thinking_level e gli strumenti integrati in tutti i segmenti di un loop di continuazione.

Risorse aggiuntive

Per ulteriori informazioni su 4 Carbon, consulta le seguenti risorse: