Veo 3 è ora disponibile nell'API Gemini. Scopri di più

Questa pagina è stata tradotta dall'API Cloud Translation.

Pensiero di Gemini

I modelli della serie Gemini 2.5 utilizzano un "processo di pensiero" interno che migliora significativamente le loro capacità di ragionamento e pianificazione in più passaggi, rendendoli altamente 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.

Prima di iniziare

Assicurati di utilizzare un modello della serie 2.5 supportato per la generazione. Potrebbe essere utile esplorare questi modelli in AI Studio prima di approfondire l'API:

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

Vai

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."
         }
       ]
     }
   ]
 }'
 ```

Budget di pensiero

Il parametro thinkingBudget indica al modello il numero di token di pensiero da utilizzare durante la generazione di una risposta. Un numero di token più elevato generalmente consente un ragionamento più dettagliato, il che può essere utile per affrontare attività più complesse. Se la latenza è più importante, utilizza un budget inferiore o disattiva la generazione di risposte impostando thinkingBudget su 0. L'impostazione di thinkingBudget su -1 attiva il pensiero dinamico, il che significa che il modello adeguerà il budget in base alla complessità della richiesta.

L'thinkingBudget è supportato solo in Gemini 2.5 Flash, 2.5 Pro e 2.5 Flash-Lite. A seconda del prompt, il modello potrebbe superare o non raggiungere il budget di token.

Di seguito sono riportati i dettagli di configurazione di thinkingBudget per ogni tipo di modello.

Modello	Impostazione predefinita (il budget di pensiero non è impostato)	Intervallo	Disattiva il processo elaborativo	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 Lite	Il modello non pensa	Da `512` 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();

Vai

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
          # Thinking off:
          # "thinkingBudget": 0
          # Turn on dynamic thinking:
          # "thinkingBudget": -1
    }
  }
}'

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 budget di pensiero 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();

Vai

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 del pensiero con lo 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();

Vai

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

Firme dei pensieri

Poiché le chiamate standard di generazione di testo e contenuti dell'API Gemini sono stateless, quando si utilizza il pensiero nelle interazioni a più turni (come la chat), il modello non ha accesso al contesto del pensiero dei turni precedenti.

Puoi mantenere il contesto del pensiero utilizzando le firme del pensiero, che sono rappresentazioni criptate del processo di pensiero interno del modello. Il modello restituisce le firme del pensiero nell'oggetto della risposta quando sono attive le funzionalità di pensiero e chiamata di funzione. Per garantire che il modello mantenga il contesto in più turni di una conversazione, devi fornire nuovamente le firme del pensiero al modello nelle richieste successive.

Riceverai le firme dei pensieri quando:

La funzionalità di pensiero è abilitata e i pensieri vengono generati.
La richiesta include dichiarazioni di funzione.

Puoi trovare un esempio di pensiero con le chiamate di funzioni nella pagina Chiamata di funzioni.

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

Vai

// ...
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.

Modelli supportati

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

Best practice

Questa sezione include alcuni suggerimenti 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, 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à Pensa può essere disattivata): per le richieste semplici in cui non è necessario un ragionamento complesso, come il recupero di fatti o la classificazione, la funzionalità Pensa non è necessaria. 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:
- Fai un'analogia tra 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 cui 17_b è un divisore di 97_b.
- 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.

Pensare con strumenti e funzionalità

I modelli di pensiero funzionano con tutti gli strumenti e le funzionalità di Gemini. Ciò consente ai modelli di interagire con sistemi esterni, eseguire codice o accedere a informazioni in tempo reale, incorporando i risultati nel loro ragionamento e nella risposta finale.

Lo strumento di ricerca consente al modello di eseguire query nella Ricerca Google per trovare informazioni aggiornate o informazioni che non rientrano nei dati di addestramento. Questo è utile per domande su eventi recenti o argomenti molto specifici.
Lo strumento di esecuzione del codice consente al modello di generare ed eseguire codice Python per eseguire calcoli, manipolare dati o risolvere problemi che vengono gestiti meglio in modo algoritmico. Il modello riceve l'output del codice e può utilizzarlo nella sua risposta.
Con l'output strutturato, puoi vincolare Gemini a rispondere con JSON. Ciò è particolarmente utile per integrare l'output del modello nelle applicazioni.
La chiamata di funzione connette il modello di pensiero a strumenti e API esterni, in modo che possa ragionare su quando chiamare la funzione giusta e quali parametri fornire.
Contesto URL fornisce al modello gli URL come contesto aggiuntivo per il prompt. Il modello può quindi recuperare i contenuti dagli URL e utilizzarli per informare e modellare la sua risposta.

Puoi provare esempi di utilizzo di strumenti con modelli di pensiero nel cookbook del pensiero.

Passaggi successivi

Per esaminare esempi più approfonditi, ad esempio:
- Utilizzare gli strumenti con il pensiero
- Streaming con pensiero
- Modificare il budget di pensiero per ottenere risultati diversi
e altro ancora, prova il nostro ricettario di pensieri.
La copertura del pensiero è ora disponibile nella nostra guida alla compatibilità con OpenAI.
Per saperne di più su Gemini 2.5 Pro, Gemini Flash 2.5 e Gemini 2.5 Flash-Lite, visita la pagina del modello.