Guida per sviluppatori a Gemini 4 Argon

Gemini 4 Argon è il modello pioneristico di Google che eccelle nel lavoro approfondito in attività complesse del mondo reale in vari ambiti, tra cui programmazione, finanza, legale, cybersicurezza e scienza. È il primo modello della famiglia Gemini 4.

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

Novità in Gemini 4 Argon

  • Finestra contestuale: la finestra contestuale da 1.048.576 token è condivisa tra i token di input, ragionamento e output.
  • Decodifiche lunghe fino a 1.048.576 token: estende la generazione oltre il limite di output di una singola richiesta (65.536 token per le richieste di streaming o 32.768 token per le richieste HTTP dirette non di streaming) fino a 1.048.576 token su GenerateContent. L'SDK Google Gen AI gestisce automaticamente continuation_token tra le richieste oppure puoi gestire continuation_token nel tuo loop di continuazione.
  • Livelli di ragionamento: LOW, MEDIUM (impostazione predefinita su gemini-4-argon) e HIGH (impostazione predefinita su gemini-4-argon-cyber-permissive).
  • Memorizzazione nella cache implicita con memorizzazione nella cache durevole: la memorizzazione nella cache implicita viene applicata automaticamente ai prefissi di prompt condivisi di 6144 token o più, con la memorizzazione nella cache durevole abilitata per impostazione predefinita. La memorizzazione nella cache del contesto esplicita non è supportata.
  • Comprensione dei video agentica: disponibilità generale e disattivata per impostazione predefinita.

Guida rapida

Prima di iniziare, devi eseguire l'autenticazione ad Agent Platform utilizzando le credenziali predefinite dell'applicazione (ADC) o una chiave API. Per maggiori informazioni, vedi Inizia a utilizzare la piattaforma agentica Gemini Enterprise.

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

Installazione

Esegui l'upgrade all'ultima versione dell'SDK Google Gen AI (google-genai >= 2.30.1 per Python, @google/genai >= 2.29.1 per JavaScript, >= 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.30.1"

Richiesta di base

Python (GenerateContent)

from google import genai

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

response = client.models.generate_content(
  model="gemini-4-argon",
  contents="How does AI work?",
)
print(response.text)

Python (API Interactions)

from google import genai

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

turn1 = client.interactions.create(
    model="gemini-4-argon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

turn2 = client.interactions.create(
    model="gemini-4-argon",
    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 print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" }
  }
}'

Output strutturato

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

Decodifiche lunghe

Per impostazione predefinita, una singola richiesta API genera fino a 65.536 token di ragionamento e output (o 32.768 token per le richieste HTTP dirette non di streaming). Per generare completamenti fino a 1.048.576 token su GenerateContent (v1beta1), imposta max_output_tokens su un valore superiore a 65.536 (fino a 1.048.576). L'SDK Google Gen AI segue automaticamente continuation_token tra le richieste quando finish_reason è CONTINUATION (imposta automatic_continuation=False in GenerateContentConfig per disattivare la continuazione automatica) 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-argon",
    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
# and stop at a single request.
single_request_response = client.models.generate_content(
    model="gemini-4-argon",
    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(single_request_response.text)

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-argon: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-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN_FROM_REQUEST_1",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Regole API e convenzioni comportamentali obbligatorie

Gemini 4 Argon applica le seguenti convenzioni:

  • Finestra contestuale e limiti di output di una singola richiesta:
    • La finestra contestuale da 1.048.576 token è condivisa tra i token di input, ragionamento e output. L'impostazione di max_output_tokens su un valore superiore a 1,048,576 restituisce un errore HTTP 400.
    • Per evitare completamenti lunghi non intenzionali, il limite di output predefinito di una singola richiesta (ragionamento + risposta del modello) è di 65.536 token (o 32.768 token per le richieste HTTP dirette non di streaming).

  • Decodifiche lunghe:

    • Come funziona la decodifica lunga: la decodifica lunga suddivide una generazione fino a 1.048.576 token in più inferenze GenerateContent. Quando una richiesta raggiunge il limite di output per richiesta prima di terminare, l'API restituisce finish_reason=CONTINUATION e un continuation_token criptato contenente un hash del prompt originale e lo stato di generazione fino a quel punto. Includi continuation_token nelle richieste successive con il prompt originale finché continuation_token non viene più emesso e 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.)
    • Quando utilizzare la decodifica lunga: la maggior parte delle richieste termina entro il limite per richiesta (65.536 token o 32.768 token per le chiamate REST non di streaming). La decodifica lunga offre al modello più spazio per ragionare; non allunga le risposte (utilizza thinking_level per controllare la profondità del ragionamento).
    Workload Utilizzare la decodifica lunga? Perché
    Matematica, scienza, ricerca e prove formali difficili Sì Il modello può utilizzare più di 65.536 token per esplorare e controllare 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 una risposta. La maggior parte delle attività di programmazione e agentiche termina con meno di 65.536 token.
    Utilizzi di valutazione che si interrompono al limite di output Sì La decodifica lunga impedisce che le risposte vengano troncate quando il modello utilizza un'intera richiesta di 65.536 o 32.768 token per il ragionamento.
    Chat, domande e risposte, riepilogo, classificazione ed estrazione No Queste attività terminano con meno di 32.768 token.
    Richieste di una lunghezza fissa, ad esempio "scrivi un libro di 700.000 parole" No Il modello non segue gli obiettivi di lunghezza.
    Agenti che chiamano gli strumenti in molti turni brevi No Ogni turno è breve. Gli output di grandi dimensioni in ogni turno riempiono rapidamente la finestra di input e output condivisa da 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ò essere eseguita per diversi minuti.
    • Scelta di un'opzione di continuazione: tutte le opzioni raggiungono lo stesso limite di 1.048.576 token su gemini-4-argon e gemini-4-argon-cyber-permissive.
    Dimensioni Opzione 1: SDK Google Gen AI (consigliata) Opzione 2: loop di streaming personalizzato (streamGenerateContent) Opzione 2: loop non di streaming personalizzato (generateContent)
    Chi inizia ogni segmento L'SDK (automatic_continuation=True per impostazione predefinita). Imposta max_output_tokens su un valore superiore a 65.536 (fino a 1.048.576) per gli output superiori a 65.536 token. Il codice, a ogni checkpoint o dopo un flusso interrotto Il codice, ogni 32.768 token
    Token per richiesta Fino a 65.536 per segmento 65.536 per stream 32.768 per richiesta
    Limite di tempo per richiesta 20 minuti 20 minuti 20 minuti
    Spazio di archiviazione e ZDR Nessuno spazio di archiviazione del server (conforme a ZDR) Nessuno spazio di archiviazione del server (conforme a ZDR) Nessuno spazio di archiviazione del server (conforme a ZDR)
    Ideale per La maggior parte delle applicazioni Chiamanti REST e utilizzi personalizzati che eseguono lo streaming Utilizzi di valutazione semplici
    • Regole e limitazioni di implementazione:
      • v1beta1 requisito API (problema noto): la decodifica lunga (continuation_token) su GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1). L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che non venga specificato api_version='v1' in http_options; per le chiamate REST dirette, utilizza il percorso dell'endpoint v1beta1. La decodifica lunga non è supportata nell'API Interactions.
      • Versioni dell'SDK e compatibilità con OpenAI: esegui l'upgrade all'ultima versione dell' SDK Google Gen AI (google-genai >= 2.30.1 per Python, @google/genai >= 2.29.1 per JavaScript, >= 1.74.0 per Go, >= 1.77.0 per Java, >= 1.26.0 per .NET o >= 1.6.0 per Kotlin). Le versioni precedenti dell'SDK e il livello di compatibilità con OpenAI non possono recuperare i completamenti lunghi utilizzando i token di continuazione. Per le implementazioni client personalizzate, consulta l'implementazione di riferimento dell'SDK Google Gen AI.
      • Invia di nuovo la richiesta originale con continuation_token: in un loop personalizzato, imposta max_output_tokens su un valore superiore a 65.536 (streaming) o 32.768 (unario) fino a 1.048.576 e invia di nuovo contents, system_instruction e tools originali in ogni richiesta di continuazione insieme all'ultimo continuation_token (un campo di primo livello in GenerateContentRequest in REST o in GenerateContentConfig nell'SDK Google Gen AI). Non aggiungere l'output parziale del modello a contents né inviare un prompt di follow-up chiedendo al modello di continuare.
      • Continua con le richieste di solo ragionamento: esegui il loop mentre finish_reason è CONTINUATION e continuation_token è presente, anche se una richiesta ha utilizzato tutti i 32.768 o 65.536 token per il ragionamento (parts: [{"text": ""}]). Se finish_reason è MAX_TOKENS quando continuation_token è presente, la generazione ha raggiunto il limite max_output_tokens richiesto. Aumenta max_output_tokens nella richiesta. Combina le parti accumulate in un singolo turno model per la cronologia a più turni solo dopo STOP.
      • Conteggio dei token, compattazione e sconto del 95% sulla cache implicita:
        • Nell'SDK Google Gen AI per Python (generate_content e generate_content_stream), usage_metadata della risposta o del blocco finale accumula i token fatturati totali nelle richieste di continuazione. Poiché ogni richiesta di continuazione riempie nuovamente i completamenti parziali precedenti come token di input, prompt_token_count aumenta cumulativamente nelle richieste di continuazione. Non utilizzare prompt_token_count per attivare la compattazione del contesto nelle infrastrutture agentiche. Leggi invece initial_prompt_token_count (in GenerateContentResponse o usage_metadata) e attendi il completamento di GenerateContent (nessun continuation_token presente) prima di compattare.
        • Nei loop REST personalizzati, usage_metadata è cumulativo all'interno di ogni richiesta; somma i valori finali di prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count tra le richieste.
        • Ogni richiesta di continuazione riempie nuovamente il prompt più i token decodificati precedenti e riceve automaticamente lo sconto del 95% sulla memorizzazione nella cache del contesto implicita (minimo 6144 token) quando le richieste vengono eseguite in sequenza entro il TTL della cache di 15-20 minuti.
        • streamGenerateContent e generateContent restituiscono continuation_token e usage_metadata alla fine di ogni richiesta (65.536 streaming / 32.768 unari) e la fatturazione avviene alla fine della richiesta.

  • 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, candidate_count): questi restituiscono un errore HTTP 400. Rimuovili dalle richieste.

  • 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) viene applicata automaticamente ai prefissi di prompt condivisi di 6144 token o più, quindi inserisci i contenuti statici all'inizio del prompt.

  • Video agentici: per impostazione predefinita, i video caricati sono impostati su media_processing="static". Imposta media_processing="agentic" per attivare l'elaborazione dei video agentici.

  • Conteggio dei token e fatturazione: ogni token elaborato dal modello viene conteggiato e fatturato, inclusi i token di ragionamento e le istruzioni di sistema degli strumenti interni e le dichiarazioni di funzione quando si utilizza il grounding. Anche il grounding con la Ricerca Google rimane fatturato per query.

  • Chiamata di funzione:

    • Simmetria dei turni: 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 a più passaggi.
    • Formattazione pre-strumento: separa le istruzioni in linea con \n\n e evita il testo non strutturato prima delle chiamate agli strumenti.

  • Convalida della sequenza di chat:

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

Eseguire la migrazione a 4 Argon da 3.1 Pro

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

  • La finestra contestuale è una finestra da 1.048.576 token condivisa da input, ragionamento e output, anziché limiti di input e output separati. L'output di una singola richiesta è limitato a 65.536 token (o 32.768 token per le richieste HTTP dirette non di streaming) e può essere esteso fino a 1.048.576 token utilizzando le decodifiche lunghe su GenerateContent (gestite automaticamente nell' SDK Google Gen AI o utilizzando continuation_token nei 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 e le dichiarazioni di funzione degli strumenti interni quando si utilizza il grounding.

Per un confronto fianco a fianco, vedi Eseguire la migrazione da Gemini 3.1 Pro.

Per eseguire la migrazione da gemini-3.1-pro-preview:

  1. Aggiorna l'ID modello a gemini-4-argon (o gemini-4-argon-cyber-permissive per i workload di cybersicurezza approvati da Fairwind).
  2. Esegui l'upgrade all'ultima versione dell'SDK Google Gen AI e tieni conto della finestra contestuale condivisa: esegui l'upgrade a google-genai >= 2.30.1 (Python) o all' ultima versione equivalente dell'SDK Google Gen AI. I token di input, ragionamento e output condividono la finestra contestuale da 1.048.576 token. Per gli output che superano i 65.536 token (fino a 1.048.576 token) su GenerateContent, imposta max_output_tokens su un valore superiore a 65.536 in modo che l'SDK Google Gen AI continui automaticamente tra le richieste (o gestisci continuation_token nel tuo loop REST).
  3. Sostituisci il parametro del budget di ragionamento: sostituisci thinking_budget e MINIMAL con thinking_level impostato su uno dei seguenti valori:
    • HIGH: impostazione predefinita su gemini-4-argon-cyber-permissive. Ingegneria del software multi-file, prove formali, progettazione dell'architettura e rilevamento delle vulnerabilità.
    • MEDIUM: impostazione predefinita su gemini-4-argon. Programmazione generale, utilizzo degli strumenti, domande e risposte sui documenti e comprensione dei video.
    • LOW: classificazione, riepilogo ed estrazione dei metadati.
  4. Rimuovi la memorizzazione nella cache esplicita e carica in anticipo i contenuti statici del prompt (6144 token o più) per la memorizzazione nella cache implicita automatica.
  5. Rimuovi i parametri che non hanno effetto o non sono supportati:
    • Rimuovi temperature, top_p e top_k, che vengono ignorati.
    • Rimuovi candidate_count, frequency_penalty e presence_penalty.
    • Rimuovi eventuali turni precompilati del modello dalle cronologie delle conversazioni.

Elenco di controllo riepilogativo per gli sviluppatori

Problemi noti

  • Le decodifiche lunghe su GenerateContent richiedono v1beta1: la decodifica lunga (continuation_token) sull'API GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1). L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che non venga impostato api_version='v1' in http_options; per le chiamate REST dirette, utilizza il percorso dell'endpoint v1beta1.

Risorse aggiuntive