Ragionamento di Gemini

I modelli della serie Gemini 3 e 2.5 utilizzano un "processo di ragionamento" che migliora notevolmente le loro capacità di ragionamento e pianificazione in più fasi, rendendoli altamente efficaci per attività complesse come la programmazione, la matematica avanzata e l'analisi dei dati.

Quando utilizzi un modello di ragionamento, Gemini ragiona internamente prima di rispondere. L'API Interactions mostra questo ragionamento tramite passaggi thought, passaggi dedicati che vengono visualizzati in ordine cronologico insieme alle chiamate di funzione, agli input dell'utente o agli output del modello nell'array steps.

Ogni passaggio di ragionamento contiene due campi:

Interazioni con il ragionamento

L'avvio di un'interazione con un modello di ragionamento è simile a qualsiasi altra richiesta di interazione. Specifica uno dei modelli con supporto per il ragionamento nel campo model:

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

Puoi eseguire lo streaming delle interazioni di ragionamento per ricevere riepiloghi e firme di ragionamento incrementali durante la generazione. Per una guida completa che illustra i tipi di eventi, i tipi di delta e gli esempi di codice, consulta la guida Interazioni di streaming.

Riepiloghi di ragionamento

I riepiloghi di ragionamento forniscono insight sul processo di ragionamento interno del modello. Per impostazione predefinita, viene restituito solo l'output finale. Puoi attivare i riepiloghi di ragionamento con thinking_summaries:

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        if step.summary:
            for content_block in step.summary:
                if content_block.type == "text":
                    print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the sum of the first 50 prime numbers?",
    generation_config: {
        thinking_summaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        if (step.summary) {
            for (const contentBlock of step.summary) {
                if (contentBlock.type === "text") console.log(contentBlock.text);
            }
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'

In questi casi, un blocco di ragionamento può contenere solo una firma senza riepilogo:

• Richieste semplici, in cui il modello non ha ragionato abbastanza per generare un riepilogo
• thinking_summaries: "none", dove i riepiloghi sono disattivati in modo esplicito
• Alcuni tipi di contenuti di ragionamento, come le immagini, potrebbero non avere riepiloghi di testo

Il codice deve sempre gestire i blocchi di ragionamento in cui summary è vuoto o assente.

Controllo del ragionamento

Per impostazione predefinita, i modelli Gemini eseguono un ragionamento dinamico, regolando automaticamente la quantità di ragionamento in base alla complessità della richiesta. Puoi controllare questo comportamento utilizzando il parametro thinking_level.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generation_config: {
        thinking_level: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Firme di ragionamento

Le firme di ragionamento sono rappresentazioni criptate del ragionamento interno del modello. Sono necessarie per mantenere la continuità del ragionamento nelle interazioni a più turni.

L'API Interactions semplifica notevolmente la gestione delle firme di ragionamento rispetto all'API generateContent.

Modalità con stato (consigliata)

Per impostazione predefinita, quando utilizzi l'API Interactions in modalità con stato (impostando store: true e passando previous_interaction_id nei turni successivi), il server gestisce automaticamente lo stato della conversazione, inclusi tutti i blocchi di ragionamento e le firme. In questa modalità non devi fare nulla per quanto riguarda le firme. Vengono gestite interamente sul lato server.

Modalità senza stato

Se gestisci autonomamente lo stato della conversazione (modalità senza stato) e passi la cronologia completa di input e output in ogni richiesta:

• Devi SEMPRE inviare di nuovo tutti i blocchi thought esattamente come li hai ricevuti dal modello.
• Non devi NON rimuovere o modificare i blocchi di ragionamento dalla cronologia, in quanto contengono le firme necessarie al modello per continuare il ragionamento.
• Quando passi da un modello all'altro all'interno di una sessione, devi comunque inviare di nuovo i blocchi di ragionamento del modello precedente. Il backend gestisce la compatibilità.

Prezzi

Quando il ragionamento è attivo, il prezzo della risposta è la somma dei token di output e dei token di ragionamento. Puoi ottenere il numero totale di token di ragionamento generati dal campo total_thought_tokens.

# This will only work for SDK newer than 2.0.0
# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

// This will only work for SDK newer than 2.0.0
// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

I modelli di ragionamento generano ragionamenti completi per migliorare la qualità della risposta finale, quindi restituiscono i riepiloghi per fornire insight sul processo di ragionamento. Il prezzo si basa sui token di ragionamento completi che il modello deve generare, anche se dall'API viene restituito solo il riepilogo.

Puoi scoprire di più sui token nella guida Conteggio dei token.

Best practice

Utilizza i modelli di ragionamento in modo efficiente seguendo queste linee guida.

• Esamina il ragionamento: analizza i riepiloghi di ragionamento per comprendere gli errori e migliorare i prompt.
• Controlla il budget di ragionamento: chiedi al modello di ragionare meno per gli output lunghi per risparmiare token.
• Attività semplici: utilizza un ragionamento minimo per il recupero o la classificazione dei fatti (ad es. "Dove è stata fondata DeepMind?").
• Attività moderate: utilizza il ragionamento predefinito per confrontare concetti o ragionamenti creativi (ad es. confronta auto elettriche e ibride).
• Attività complesse: utilizza il ragionamento massimo per la programmazione avanzata, la matematica o la pianificazione in più fasi (ad es. risolvi i problemi di matematica AIME).

Passaggi successivi

• Generazione di testo: risposte di testo di base
• Chiamata di funzione: connettiti agli strumenti
• Guida a Gemini 3: funzionalità specifiche del modello