Pensiero di Gemini

I modelli delle serie Gemini 3 e 2.5 utilizzano un "processo di pensiero" interno che migliora significativamente 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 per il 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 verificando 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 in un 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 Pro)

Il parametro thinkingLevel, consigliato per i modelli Gemini 3 e successivi, ti consente di controllare il comportamento di ragionamento. Puoi impostare il livello di pensiero su "low" o "high". Se non specifichi un livello di ragionamento, Gemini utilizzerà il livello di ragionamento dinamico predefinito del modello, "high", per Gemini 3 Pro Preview.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-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-pro-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-pro-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-pro-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 pensiero per Gemini 3 Pro. 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 la funzionalità di 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 Disattiva il ragionamento 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 funzionalità di pensiero 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-pro",
    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-pro",
    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-pro"
  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-pro: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 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 è obbligatorio per le firme di chiamata di funzione. Per saperne di più, consulta la pagina Firme di 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 linee guida 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, 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 richieste semplici in cui non è necessario un ragionamento complesso, ad esempio il recupero o la classificazione di fatti, la funzionalità di pensiero non è necessaria. Ecco alcuni esempi:
    • "Dove è stata fondata DeepMind?"
    • "Questa email richiede una riunione o fornisce solo informazioni?"
  • Attività medie (impostazione predefinita/richiedono un po' di ragionamento): 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:
    • Paragonare la fotosintesi e la 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 in tempo reale del mercato azionario, 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 pensanti 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 alcuni esempi di utilizzo degli strumenti con i modelli pensanti nel cookbook di Thinking.

Passaggi successivi