Pensiero di Gemini

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 pensiero è 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, come mostrato nel seguente esempio di generazione di testo:

Python

from google import genai

client = genai.Client()
prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example."
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=prompt
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example.";

  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: prompt,
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  prompt := "Explain the concept of Occam's Razor and provide a simple, everyday example."
  model := "gemini-2.5-pro"

  resp, _ := client.Models.GenerateContent(ctx, model, genai.Text(prompt), nil)

  fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent" \
 -H "x-goog-api-key: $GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -X POST \
 -d '{
   "contents": [
     {
       "parts": [
         {
           "text": "Explain the concept of Occam\'s Razor and provide a simple, everyday example."
         }
       ]
     }
   ]
 }'
 ```

Riepiloghi dei pensieri

I riepiloghi dei pensieri sono versioni sintetizzate dei pensieri grezzi del modello e offrono approfondimenti sul processo di ragionamento interno del modello. Tieni presente che i livelli di pensiero e i budget si applicano ai pensieri grezzi del modello e non ai riepiloghi dei pensieri.

Puoi attivare i riepiloghi dei pensieri impostando includeThoughts su true nella configurazione della richiesta. Puoi quindi accedere al riepilogo scorrendo il parametro response, controllando parts e il valore booleano thought.

Ecco un esempio che mostra come attivare e recuperare i riepiloghi dei pensieri senza streaming, che restituisce un singolo riepilogo finale dei pensieri con la risposta:

Python

from google import genai
from google.genai import types

client = genai.Client()
prompt = "What is the sum of the first 50 prime numbers?"
response = client.models.generate_content(
  model="gemini-2.5-pro",
  contents=prompt,
  config=types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
      include_thoughts=True
    )
  )
)

for part in response.candidates[0].content.parts:
  if not part.text:
    continue
  if part.thought:
    print("Thought summary:")
    print(part.text)
    print()
  else:
    print("Answer:")
    print(part.text)
    print()

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "What is the sum of the first 50 prime numbers?",
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for (const part of response.candidates[0].content.parts) {
    if (!part.text) {
      continue;
    }
    else if (part.thought) {
      console.log("Thoughts summary:");
      console.log(part.text);
    }
    else {
      console.log("Answer:");
      console.log(part.text);
    }
  }
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text("What is the sum of the first 50 prime numbers?")
  model := "gemini-2.5-pro"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for _, part := range resp.Candidates[0].Content.Parts {
    if part.Text != "" {
      if part.Thought {
        fmt.Println("Thoughts Summary:")
        fmt.Println(part.Text)
      } else {
        fmt.Println("Answer:")
        fmt.Println(part.Text)
      }
    }
  }
}

Ecco un esempio di utilizzo della generazione di contenuti in streaming, che restituisce riepiloghi incrementali durante la generazione:

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
"""

thoughts = ""
answer = ""

for chunk in client.models.generate_content_stream(
    model="gemini-2.5-pro",
    contents=prompt,
    config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
        include_thoughts=True
      )
    )
):
  for part in chunk.candidates[0].content.parts:
    if not part.text:
      continue
    elif part.thought:
      if not thoughts:
        print("Thoughts summary:")
      print(part.text)
      thoughts += part.text
    else:
      if not answer:
        print("Answer:")
      print(part.text)
      answer += part.text

JavaScript

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

const ai = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. The person who lives in the red house owns a cat.
Bob does not live in the green house. Carol owns a dog. The green house is to
the left of the red house. Alice does not own a cat. Who lives in each house,
and what pet do they own?`;

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

async function main() {
  const response = await ai.models.generateContentStream({
    model: "gemini-2.5-pro",
    contents: prompt,
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for await (const chunk of response) {
    for (const part of chunk.candidates[0].content.parts) {
      if (!part.text) {
        continue;
      } else if (part.thought) {
        if (!thoughts) {
          console.log("Thoughts summary:");
        }
        console.log(part.text);
        thoughts = thoughts + part.text;
      } else {
        if (!answer) {
          console.log("Answer:");
        }
        console.log(part.text);
        answer = answer + part.text;
      }
    }
  }
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

const prompt = `
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
`

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text(prompt)
  model := "gemini-2.5-pro"

  resp := client.Models.GenerateContentStream(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for chunk := range resp {
    for _, part := range chunk.Candidates[0].Content.Parts {
      if len(part.Text) == 0 {
        continue
      }

      if part.Thought {
        fmt.Printf("Thought: %s\n", part.Text)
      } else {
        fmt.Printf("Answer: %s\n", part.Text)
      }
    }
  }
}

Controllare il pensiero

I modelli Gemini si impegnano nel pensiero dinamico per impostazione predefinita, regolando automaticamente la quantità di ragionamento in base alla complessità della richiesta dell'utente. Tuttavia, se hai vincoli di latenza specifici o richiedi che il modello si impegni in un ragionamento più approfondito del solito, puoi utilizzare facoltativamente i parametri per controllare il comportamento di pensiero.

Livelli di pensiero (Gemini 3)

Il parametro thinkingLevel, consigliato per i modelli Gemini 3 e successivi, ti consente di controllare il comportamento di ragionamento. Puoi impostare il livello di ragionamento su "low" o "high" per Gemini 3 Pro e su "minimal", "low", "medium" e "high" per Gemini 3 Flash.

Livelli di pensiero di Gemini 3 Pro e Flash:

  • low: riduce al minimo la latenza e i costi. Ideale per applicazioni semplici di follow-up delle istruzioni, chat o ad alto rendimento
  • high (valore predefinito, dinamico): massimizza la profondità del ragionamento. Il modello potrebbe impiegare molto più tempo per raggiungere il primo token, ma l'output sarà più ragionato.

Livelli di pensiero di Gemini 3 Flash

Oltre ai livelli precedenti, Gemini 3 Flash supporta anche i seguenti livelli di pensiero attualmente non supportati da Gemini 3 Pro:

  • medium: pensiero equilibrato per la maggior parte delle attività.

  • minimal: 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 ad alto throughput.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingLevel: "low",
      },
    },
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingLevelVal := "low"

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-3-flash-preview"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingLevel: &thinkingLevelVal,
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [
    {
      "parts": [
        {
          "text": "Provide a list of 3 famous physicists and their key contributions"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
          "thinkingLevel": "low"
    }
  }
}'

Non puoi disattivare la funzionalità di ragionamento per Gemini 3 Pro. Gemini 3 Flash inoltre non supporta la disattivazione completa della modalità di pensiero, ma l'impostazione minimal indica che il modello probabilmente non penserà (anche se potrebbe comunque farlo). Se non specifichi un livello di ragionamento, Gemini utilizzerà il livello di ragionamento dinamico predefinito dei modelli Gemini 3, "high".

I modelli della serie Gemini 2.5 non supportano thinkingLevel; utilizza thinkingBudget in alternativa.

Budget di pensiero

Il parametro thinkingBudget, introdotto con la serie Gemini 2.5, indica al modello il numero specifico di token di pensiero da utilizzare per il ragionamento.

Di seguito sono riportati i dettagli di configurazione di thinkingBudget per ogni tipo di modello. Puoi disattivare il pensiero impostando thinkingBudget su 0. Se imposti thinkingBudget su -1, viene attivato il pensiero dinamico, il che significa che il modello adeguerà il budget in base alla complessità della richiesta.

Modello Impostazione predefinita
(il budget di pensiero non è impostato)		 Intervallo Disattivare la funzionalità di pensiero Attivare il pensiero dinamico
2.5 Pro Pensiero dinamico: il modello decide quando e quanto pensare Da 128 a 32768 N/A: Impossibile disattivare la generazione thinkingBudget = -1
2.5 Flash Pensiero dinamico: il modello decide quando e quanto pensare Da 0 a 24576 thinkingBudget = 0 thinkingBudget = -1
2.5 Flash Preview Pensiero dinamico: il modello decide quando e quanto pensare Da 0 a 24576 thinkingBudget = 0 thinkingBudget = -1
2.5 Flash Lite Il modello non pensa Da 512 a 24576 thinkingBudget = 0 thinkingBudget = -1
2.5 Flash Lite Preview Il modello non pensa Da 512 a 24576 thinkingBudget = 0 thinkingBudget = -1
Anteprima di Robotics-ER 1.5 Pensiero dinamico: il modello decide quando e quanto pensare Da 0 a 24576 thinkingBudget = 0 thinkingBudget = -1
2.5 Flash Live Native Audio Preview (09-2025) Pensiero dinamico: il modello decide quando e quanto pensare Da 0 a 24576 thinkingBudget = 0 thinkingBudget = -1

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=1024)
        # Turn off thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=0)
        # Turn on dynamic thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=-1)
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingBudget: 1024,
        // Turn off thinking:
        // thinkingBudget: 0
        // Turn on dynamic thinking:
        // thinkingBudget: -1
      },
    },
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingBudgetVal := int32(1024)

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-2.5-flash"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingBudget: &thinkingBudgetVal,
      // Turn off thinking:
      // ThinkingBudget: int32(0),
      // Turn on dynamic thinking:
      // ThinkingBudget: int32(-1),
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [
    {
      "parts": [
        {
          "text": "Provide a list of 3 famous physicists and their key contributions"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
          "thinkingBudget": 1024
    }
  }
}'

A seconda del prompt, il modello potrebbe superare o non raggiungere il budget di token.

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 possono 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 delle chiamate di funzione. Per saperne di più, consulta la pagina Firme del pensiero.

L'SDK Google GenAI gestisce automaticamente il ritorno delle firme del pensiero. Devi gestire manualmente le firme dei pensieri solo se modifichi la cronologia delle conversazioni o utilizzi l'API REST.

Altre limitazioni di utilizzo da considerare con la chiamata di funzioni includono:

  • 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 thoughtsTokenCount.

Python

# ...
print("Thoughts tokens:",response.usage_metadata.thoughts_token_count)
print("Output tokens:",response.usage_metadata.candidates_token_count)

JavaScript

// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);

Go

// ...
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println("Thoughts tokens:", string(usageMetadata.thoughts_token_count))
fmt.Println("Output tokens:", string(usageMetadata.candidates_token_count))

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. Pertanto, i prezzi si basano sui token di pensiero completi che il modello deve generare per creare un riepilogo, anche se solo il riepilogo viene restituito dall'API.

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

Best practice

Questa sezione include alcune indicazioni per utilizzare in modo efficiente i modelli di pensiero. Come sempre, seguire le nostre indicazioni e best practice per i prompt ti aiuterà a ottenere i risultati migliori.

Debug e controllo

  • 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, ti consigliamo di 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 (il pensiero può essere disattivato): per richieste semplici in cui non è necessario un ragionamento complesso, ad esempio il recupero di fatti o la classificazione, il pensiero non è necessario. Ecco alcuni esempi:
    • "Dove è stata fondata DeepMind?"
    • "Questa email richiede una riunione o fornisce solo informazioni?"
  • Attività medie (predefinite/richiedono un po' di riflessione): molte richieste comuni traggono vantaggio da un'elaborazione passo passo o da una comprensione più approfondita. Gemini può utilizzare in modo flessibile la capacità di pensiero per attività come:
    • 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, come la risoluzione di problemi matematici complessi o attività di programmazione, 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, spesso coinvolgendo molti passaggi interni prima di fornire una risposta. Ecco alcuni esempi:
    • Risolvi il problema 1 dell'AIME 2025: trova la somma di tutte le basi intere b > 9 per le quali 17b è un divisore di 97b.
    • 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, strumenti e funzionalità supportati

Le funzionalità di pensiero sono supportate su tutti i modelli delle serie 3 e 2.5. Puoi trovare tutte le funzionalità del modello nella pagina Panoramica del modello.

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 e nella risposta finale.

Puoi provare esempi di utilizzo degli strumenti con i modelli pensanti nel cookbook di Thinking.

Passaggi successivi