Gemini sta pensando

I modelli delle serie Gemini 3 e 2.5 utilizzano un "processo di pensiero" interno che migliora notevolmente le loro capacità di ragionamento e pianificazione in più passaggi, rendendoli molto efficaci per attività complesse come programmazione, matematica avanzata e analisi dei dati.

Questa guida mostra come utilizzare le funzionalità di pensiero di Gemini utilizzando l'API Gemini.

Generare contenuti con il pensiero

Avviare una richiesta con un modello di ragionamento è simile a qualsiasi altra richiesta di generazione di contenuti. La differenza principale consiste nello specificare uno dei modelli con supporto del pensiero nel campo model:

Python

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)

JavaScript

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);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

Riepiloghi dei pensieri

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

Python

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:")
        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()

JavaScript

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?",
    generationConfig: {
        thinkingSummaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought 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);
            }
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generationConfig": {
      "thinkingSummaries": "auto"
    }
  }'

Stream with thinking

Utilizza lo streaming per ricevere riepiloghi incrementali dei pensieri durante la generazione. Vengono restituiti riepiloghi incrementali man mano che vengono generati:

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

thoughts = ""
answer = ""

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought":
            if not thoughts:
                print("Thinking...")
            summary_text = getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generationConfig: {
        thinkingSummaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.type === "step.delta") {
        if (event.delta.type === "thought") {
            if (!thoughts) console.log("Thinking...");
            process.stdout.write(`[Thought] ${event.delta.text || ""}`);
            thoughts += event.delta.text || "";
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

Pensiero di controllo

I modelli Gemini si impegnano nel pensiero dinamico per impostazione predefinita, regolando automaticamente la quantità di ragionamento in base alla complessità della richiesta. Tuttavia, puoi controllare questo comportamento utilizzando i parametri di configurazione.

Livelli di ragionamento (Gemini 3)

Il parametro thinking_level, consigliato per i modelli Gemini 3 e successivi, consente di controllare il comportamento di ragionamento.

Livello di ragionamento Gemini 3.1 Pro Gemini 3 Pro (ritirato) Gemini 3 Flash Descrizione
minimal Non supportato Non supportato Supportato Corrisponde all'impostazione "nessun pensiero" per la maggior parte delle query. Il modello potrebbe pensare in modo molto minimale per attività di programmazione complesse. Riduce al minimo la latenza per le applicazioni di chat o a throughput elevato. Tieni presente che minimal non garantisce che il pensiero sia disattivato.
low Supportato Supportato Supportato Riduce al minimo la latenza e i costi. Ideale per seguire istruzioni, chat o applicazioni con throughput elevato.
medium Supportato Non supportato Supportato Pensiero equilibrato per la maggior parte delle attività.
high Supportato (predefinito, dinamico) Supportato (predefinito, dinamico) Supportato (predefinito, dinamico) Massimizza la profondità del ragionamento. Il modello potrebbe impiegare molto più tempo per raggiungere un primo token di output (non di pensiero), ma l'output sarà più ragionato.

Python

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)

JavaScript

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",
    generationConfig: {
        thinkingLevel: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -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"
    }
  }'

Non puoi disattivare la funzionalità di ragionamento per Gemini 3 Pro. Gemini 3 Flash non supporta nemmeno la disattivazione completa della funzionalità di ragionamento, ma l'impostazione minimal indica che il modello probabilmente non ragionerà (anche se potrebbe comunque farlo).

Firme dei pensieri

L'API Gemini è stateless, quindi il modello tratta ogni richiesta API in modo indipendente e non ha accesso al contesto di pensiero dei turni precedenti nelle interazioni multiturno.

Per consentire il mantenimento del contesto del pensiero nelle interazioni multi-turno, Gemini restituisce le firme del pensiero, che sono rappresentazioni criptate del processo di pensiero interno del modello.

  • I modelli Gemini 2.5 restituiscono firme di pensiero quando il pensiero è abilitato e la richiesta include chiamate di funzione, in particolare dichiarazioni di funzioni.
  • I modelli Gemini 3 potrebbero restituire firme di pensiero per tutti i tipi di parti. Ti consigliamo di restituire sempre tutte le firme così come sono state ricevute, ma è un'operazione obbligatoria per le firme di chiamata di funzione. Per saperne di più, consulta la pagina Firme del pensiero.
  • Le firme vengono restituite dal modello all'interno di altre parti della risposta, ad esempio chiamate di funzioni o parti di testo. Restituisci l'intera risposta con tutte le parti al modello nei turni successivi.
  • Non concatenare le parti con le firme.
  • Non unire una parte con una firma a un'altra parte senza firma.

Prezzi

Quando la funzionalità di pensiero è attiva, il prezzo della risposta è la somma dei token di output e dei token di pensiero. Puoi ottenere il numero totale di token di pensiero generati dal campo total_thought_tokens.

Python

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// ...
console.log(`Thoughts tokens: ${interaction.usage.totalThoughtTokens}`);
console.log(`Output tokens: ${interaction.usage.totalOutputTokens}`);

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

Per saperne di più sui token, consulta la guida Conteggio dei token.

Best practice

Questa sezione include indicazioni per l'utilizzo efficiente dei modelli di pensiero.

Debug e guida

  • Esamina il ragionamento: quando non ricevi la risposta che ti aspetti dai modelli di pensiero, può essere utile analizzare attentamente i riepiloghi del pensiero di Gemini. Puoi vedere come ha suddiviso l'attività e come è giunto alla conclusione e utilizzare queste informazioni per correggere i risultati.

  • Fornisci indicazioni nel ragionamento: se speri di ottenere un output particolarmente lungo, potresti fornire indicazioni nel prompt per limitare la quantità di ragionamento utilizzata dal modello. In questo modo puoi riservare più token di output per la tua risposta.

Complessità dell'attività

  • Attività semplici (la funzionalità di pensiero può essere DISATTIVATA): per le richieste semplici in cui non è necessario un ragionamento complesso, la funzionalità di pensiero non è necessaria. Esempi:
    • "Dove è stata fondata DeepMind?"
    • "Questa email richiede una riunione o fornisce solo informazioni?"
  • Attività medie (impostazione predefinita/qualche riflessione): molte richieste comuni traggono vantaggio da un'elaborazione passo passo o da una comprensione più approfondita. Esempi:
    • Paragona la fotosintesi alla crescita.
    • Confronta e contrapponi le auto elettriche e le auto ibride.
  • Attività difficili (massima capacità di ragionamento): per sfide davvero complesse, ti consigliamo di impostare un budget di ragionamento elevato. Questi tipi di attività richiedono al modello di utilizzare tutte le sue capacità di ragionamento e pianificazione. Esempi:
    • Risolvi il problema 1 dell'AIME 2025: trova la somma di tutte le basi intere b > 9...
    • Scrivi codice Python per un'applicazione web che visualizza dati di mercato azionari in tempo reale, inclusa l'autenticazione utente. Rendilo il più efficiente possibile.

Modelli supportati

Modello Default Thinking Livelli supportati
gemini-3.1-pro-preview On (alto) basso, medio, alto
gemini-3-flash-preview On (alto) minima, bassa, media, alta
gemini-3-pro-preview On (alto) basso, alto
gemini-2.5-pro On Budget: 128-32768
gemini-2.5-flash On Budget: 0-24576
gemini-2.5-flash-lite Off Budget: 0-24576

I modelli di ragionamento funzionano con tutti gli strumenti e le funzionalità di Gemini. In questo modo, i modelli possono interagire con sistemi esterni, eseguire codice o accedere a informazioni in tempo reale, incorporando i risultati nel loro ragionamento.

Passaggi successivi