Le firme del pensiero sono rappresentazioni criptate del processo di pensiero interno del modello. Le firme del pensiero preservano lo stato del ragionamento di Gemini durante le conversazioni
a più turni e più passaggi, il che può essere utile quando si utilizza la
chiamata di funzione. Le risposte possono includere un campo thought_signature all'interno di qualsiasi parte del contenuto (ad es. text, functionCall).
I modelli Gemini 3 applicano una convalida più rigorosa delle firme del pensiero rispetto alle versioni precedenti di Gemini perché migliorano le prestazioni del modello per la chiamata di funzioni. Per garantire che il modello mantenga il contesto completo in più turni di una conversazione, devi restituire le firme del pensiero delle risposte precedenti nelle richieste successive, anche quando utilizzi i livelli di pensiero MINIMAL. Se una firma del pensiero richiesta non viene restituita quando utilizzi i modelli Gemini 3, il modello restituirà un errore 400.
Sebbene Gemini 3 Pro Image non applichi questa convalida, per garantire che il modello mantenga il contesto completo in più turni di una conversazione, devi comunque restituire le firme del pensiero delle risposte precedenti nelle richieste successive. Gemini 3 Pro Image non restituisce un errore 400 se non viene restituita una firma
del pensiero. Per esempi di codice relativi alla modifica di immagini in più passaggi
utilizzando Gemini 3 Pro Image, consulta
Esempio di modifica di immagini in più passaggi utilizzando le firme concettuali.
Se utilizzi l'SDK Google Gen AI ufficiale (Python, Node.js, Go o Java) e le funzionalità standard della cronologia della chat o aggiungi la risposta completa del modello alla cronologia, le firme del pensiero vengono gestite automaticamente.
Perché sono importanti?
Quando un modello di ragionamento chiama uno strumento esterno, mette in pausa il suo processo di ragionamento interno. La firma del pensiero funge da "stato di salvataggio", consentendo al modello di riprendere la catena di pensiero senza problemi una volta fornito il risultato della funzione. Senza le firme del pensiero, il modello "dimentica" i suoi passaggi di ragionamento specifici durante la fase di esecuzione dello strumento. La restituzione della firma garantisce:
- Continuità del contesto:il modello conserva e può controllare i passaggi di ragionamento che hanno giustificato la chiamata allo strumento.
- Ragionamento complesso: consente attività in più fasi in cui l'output di uno strumento influisce sul ragionamento per il successivo.
Svolte e passi
Nel contesto della chiamata di funzioni, è importante comprendere la differenza tra turni e passaggi:
- Un turno rappresenta uno scambio completo di conversazione, a partire dal prompt di un utente e terminando quando il modello fornisce una risposta finale, non di chiamata di funzione, a quel prompt.
- Un passaggio si verifica all'interno di un singolo turno quando il modello richiama una funzione e richiede una risposta della funzione per continuare il suo processo di ragionamento. Come mostrato nel diagramma, un singolo turno può comportare più passaggi se il modello deve chiamare più funzioni in sequenza per soddisfare la richiesta dell'utente.
Come utilizzare le firme dei pensieri
Il modo più semplice per gestire le firme del pensiero è includere tutti i
Partdi tutti i messaggi precedenti nella cronologia della conversazione quando invii una
nuova richiesta, esattamente come sono stati restituiti dal modello.
Se non utilizzi uno degli SDK Google Gen AI o devi modificare o tagliare la cronologia delle conversazioni, devi assicurarti che le firme dei pensieri vengano conservate e inviate di nuovo al modello.
Quando utilizzi l'SDK Google Gen AI (consigliato)
Quando utilizzi le funzionalità della cronologia della chat degli SDK o aggiungi l'oggetto content del modello dalla risposta precedente a contents della richiesta successiva, le firme vengono gestite automaticamente.
Il seguente esempio Python mostra la gestione automatica:
from google import genai
from google.genai.types import Content, FunctionDeclaration, GenerateContentConfig, Part, ThinkingConfig, Tool
client = genai.Client()
# 1. Define your tool
get_weather_declaration = FunctionDeclaration(
name="get_weather",
description="Gets the current weather temperature for a given location.",
parameters={
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
)
get_weather_tool = Tool(function_declarations=[get_weather_declaration])
# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=prompt,
config=GenerateContentConfig(
tools=[get_weather_tool],
thinking_config=ThinkingConfig(include_thoughts=True)
),
)
# 3. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")
# Execute your tool (for example, call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
"location": location,
"temperature": "30C",
}
# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
Content(role="user", parts=[Part(text=prompt)]),
response.candidates[0].content, # Signature preserved here
Content(
role="tool",
parts=[
Part.from_function_response(
name=function_call.name,
response=function_response_data,
)
],
)
]
response_2 = client.models.generate_content(
model="gemini-2.5-flash",
contents=history,
config=GenerateContentConfig(
tools=[get_weather_tool],
thinking_config=ThinkingConfig(include_thoughts=True)
),
)
# 5. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")
Quando utilizzi REST o la gestione manuale
Se interagisci direttamente con l'API, devi implementare la gestione delle firme in base alle seguenti regole per Gemini 3 Pro:
- Chiamata di funzioni:
- Se la risposta del modello contiene una o più parti
functionCall, è necessario unthought_signatureper l'elaborazione corretta. - Nei casi di chiamate di funzione parallele in una singola risposta, solo la
prima parte
functionCallconterràthought_signature. - Nei casi di chiamate di funzioni sequenziali in più passaggi di un turno,
ogni parte
functionCallconterrà unthought_signature. - Regola: quando crei la richiesta successiva, devi includere
partcontenentefunctionCalle il relativothought_signatureesattamente come restituito dal modello. Per la chiamata di funzioni sequenziale (multistep), la convalida viene eseguita su tutti i passaggi del turno corrente e l'omissione di unthought_signatureobbligatorio per la prima partefunctionCallin qualsiasi passaggio del turno corrente genera un errore400. Un turno inizia con il messaggio più recente dell'utente che non è unfunctionResponse. - Se il modello restituisce chiamate di funzioni parallele (ad esempio
FC1+signature,FC2), la risposta deve contenere tutte le chiamate di funzioni seguite da tutte le risposte delle funzioni (FC1+signature,FC2,FR1,FR2). L'interleaving delle risposte (FC1+signature,FR1,FC2,FR2) genera un errore400. - Esistono rari casi in cui devi fornire parti
functionCallche non sono state generate dall'API e pertanto non hanno una firma del pensiero associata (ad esempio, quando trasferisci la cronologia da un modello che non include firme del pensiero). Puoi impostarethought_signaturesuskip_thought_signature_validator, ma questa deve essere l'ultima risorsa, in quanto influirà negativamente sul rendimento del modello.
- Se la risposta del modello contiene una o più parti
- Chiamata non funzione:
- Se la risposta del modello non contiene un
functionCall, potrebbe includere unthought_signaturenell'ultimapartdella risposta (ad esempio, l'ultima partetext). - Regola: l'inclusione di questa firma nella richiesta successiva è
consigliata per un rendimento ottimale, ma la sua omissione non causerà un
errore. Durante lo streaming, questa firma potrebbe essere restituita in una
parte con contenuti di testo vuoti, quindi assicurati di analizzare tutte le parti finché
il modello non restituisce
finish_reason.
- Se la risposta del modello non contiene un
Segui queste regole per assicurarti che il contesto del modello venga preservato:
- Restituisci sempre il
thought_signatureal modello all'interno del suoPartoriginale. - Non unire un
Partcontenente una firma con uno che non la contiene. In questo modo viene interrotto il contesto posizionale del pensiero. - Non combinare due
Partche contengono entrambe firme, perché le stringhe della firma non possono essere unite.
Esempio di chiamata di funzioni sequenziale
L'esempio seguente mostra una chiamata di funzione in più passaggi in cui l'utente chiede "Controlla lo stato del volo AA100 e prenota un taxi in caso di ritardo", che richiede più attività.
REST
Il seguente esempio mostra come gestire le firme dei pensieri in più passaggi di un flusso di lavoro di chiamata di funzione sequenziale utilizzando l'API REST.
Turno 1, passaggio 1 (richiesta dell'utente)
{ "contents": [ { "role": "user", "parts": [ { "text": "Check flight status for AA100 and book a taxi 2 hours before if delayed." } ] } ], "tools": [ { "functionDeclarations": [ { "name": "check_flight", "description": "Gets the current status of a flight", "parameters": { "type": "object", "properties": { "flight": { "type": "string", "description": "The flight number to check" } }, "required": [ "flight" ] } }, { "name": "book_taxi", "description": "Book a taxi", "parameters": { "type": "object", "properties": { "time": { "type": "string", "description": "time to book the taxi" } }, "required": [ "time" ] } } ] } ] }
Turno 1, passaggio 1 (risposta del modello)
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] } }
Turno 1, passaggio 2 (risposta dell'utente - invio degli output dello strumento)
Poiché questo turno dell'utente contiene solo un functionResponse (nessun testo nuovo), siamo ancora al turno 1. Devi conservare <SIGNATURE_A>.
{ "role": "user", "parts": [ { "text": "Check flight status for AA100 and book a taxi 2 hours before if delayed." } ] }, { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "check_flight", "response": { "status": "delayed", "departure_time": "12 PM" } } } ] }
Turno 1, passaggio 2 (risposta del modello)
Il modello ora decide di prenotare un taxi in base all'output precedente dello strumento.
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "book_taxi", "args": { "time": "10 AM" } }, "thoughtSignature": "<SIGNATURE_B>" } ] } }
Turno 1, passaggio 3 (risposta dell'utente - invio dell'output dello strumento)
Per inviare la conferma della prenotazione del taxi, devi includere le firme per tutte
le chiamate di funzione in questo ciclo (<SIGNATURE_A> e <SIGNATURE_B>).
{ "role": "user", "parts": [ { "text": "Check flight status for AA100 and book a taxi 2 hours before if delayed." } ] }, { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "check_flight", "response": { "status": "delayed", "departure_time": "12 PM" } } } ] }, { "role": "model", "parts": [ { "functionCall": { "name": "book_taxi", "args": { "time": "10 AM" } }, "thoughtSignature": "<SIGNATURE_B>" } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "book_taxi", "response": { "booking_status": "success" } } } ] } }
Completamenti della chat
L'esempio seguente mostra come gestire le firme dei pensieri in più passaggi di un flusso di lavoro di chiamata di funzioni sequenziale utilizzando l'API Chat Completions.
Turno 1, passaggio 1 (richiesta dell'utente)
{ "model": "google/gemini-3.1-pro-preview", "messages": [ { "role": "user", "content": "Check flight status for AA100 and book a taxi 2 hours before if delayed." } ], "tools": [ { "type": "function", "function": { "name": "check_flight", "description": "Gets the current status of a flight", "parameters": { "type": "object", "properties": { "flight": { "type": "string", "description": "The flight number to check." } }, "required": [ "flight" ] } } }, { "type": "function", "function": { "name": "book_taxi", "description": "Book a taxi", "parameters": { "type": "object", "properties": { "time": { "type": "string", "description": "time to book the taxi" } }, "required": [ "time" ] } } } ] }
Turno 1, passaggio 1 (risposta del modello)
{ "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1", "type": "function" } ] }
Turno 1, passaggio 2 (risposta dell'utente - invio degli output dello strumento)
Poiché questo turno dell'utente contiene solo un functionResponse (nessun testo nuovo), siamo ancora al turno 1. Devi conservare <SIGNATURE_A>.
"messages": [ { "role": "user", "content": "Check flight status for AA100 and book a taxi 2 hours before if delayed." }, { "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1", "type": "function" } ] }, { "role": "tool", "name": "check_flight", "tool_call_id": "function-call-1", "content": "{\"status\":\"delayed\",\"departure_time\":\"12 PM\"}" } ]
Turno 1, passaggio 2 (risposta del modello)
Il modello ora decide di prenotare un taxi in base all'output precedente dello strumento.
{ "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_B>" } }, "function": { "arguments": "{\"time\":\"10 AM\"}", "name": "book_taxi" }, "id": "function-call-2", "type": "function" } ] }
Turno 1, passaggio 3 (risposta dell'utente - invio dell'output dello strumento)
Per inviare la conferma della prenotazione del taxi, devi includere le firme per tutte
le chiamate di funzione in questo ciclo (<SIGNATURE_A> e <SIGNATURE_B>).
"messages": [ { "role": "user", "content": "Check flight status for AA100 and book a taxi 2 hours before if delayed." }, { "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1d6a1a61-6f4f-4029-80ce-61586bd86da5", "type": "function" } ] }, { "role": "tool", "name": "check_flight", "tool_call_id": "function-call-1d6a1a61-6f4f-4029-80ce-61586bd86da5", "content": "{\"status\":\"delayed\",\"departure_time\":\"12 PM\"}" }, { "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_B>" } }, "function": { "arguments": "{\"time\":\"10 AM\"}", "name": "book_taxi" }, "id": "function-call-65b325ba-9b40-4003-9535-8c7137b35634", "type": "function" } ] }, { "role": "tool", "name": "book_taxi", "tool_call_id": "function-call-65b325ba-9b40-4003-9535-8c7137b35634", "content": "{\"booking_status\":\"success\"}" } ]
Esempio di chiamata di funzione parallela
L'esempio seguente mostra una chiamata di funzione parallela in cui l'utente chiede "Controlla il meteo a Parigi e Londra".
REST
L'esempio seguente mostra come gestire le firme dei pensieri in un flusso di lavoro di chiamata di funzione parallela utilizzando l'API REST.
Turno 1, passaggio 1 (richiesta dell'utente)
{ "contents": [ { "role": "user", "parts": [ { "text": "Check the weather in Paris and London." } ] } ], "tools": [ { "functionDeclarations": [ { "name": "get_current_temperature", "description": "Gets the current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city name, e.g. San Francisco" } }, "required": [ "location" ] } } ] } ] }
Turno 1, passaggio 1 (risposta del modello)
{ "content": { "parts": [ { "functionCall": { "name": "get_current_temperature", "args": { "location": "Paris" } }, "thoughtSignature": "<SIGNATURE_A>" }, { "functionCall": { "name": "get_current_temperature", "args": { "location": "London" } } } ] } }
Turno 1, passaggio 2 (risposta dell'utente - invio degli output dello strumento)
Devi conservare <SIGNATURE_A> nella prima parte esattamente come ricevuto.
[ { "role": "user", "parts": [ { "text": "Check the weather in Paris and London." } ] }, { "role": "model", "parts": [ { "functionCall": { "name": "get_current_temperature", "args": { "city": "Paris" } }, "thought_signature": "<SIGNATURE_A>" }, { "functionCall": { "name": "get_current_temperature", "args": { "city": "London" } } } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "get_current_temperature", "response": { "temp": "15C" } } }, { "functionResponse": { "name": "get_current_temperature", "response": { "temp": "12C" } } } ] } ]
Completamenti della chat
L'esempio seguente mostra come gestire le firme di pensiero in un flusso di lavoro di chiamata di funzioni parallelo utilizzando l'API Chat Completions.
Turno 1, passaggio 1 (richiesta dell'utente)
{ "contents": [ { "role": "user", "parts": [ { "text": "Check the weather in Paris and London." } ] } ], "tools": [ { "functionDeclarations": [ { "name": "get_current_temperature", "description": "Gets the current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city name, e.g. San Francisco" } }, "required": [ "location" ] } } ] } ] }
Turno 1, passaggio 1 (risposta del modello)
{ "role": "assistant", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"location\":\"Paris\"}", "name": "get_current_temperature" }, "id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01", "type": "function" }, { "function": { "arguments": "{\"location\":\"London\"}", "name": "get_current_temperature" }, "id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44", "type": "function" } ] }
Turno 1, passaggio 2 (risposta dell'utente - invio degli output dello strumento)
Devi conservare <SIGNATURE_A> nella prima parte esattamente come ricevuto.
"messages": [ { "role": "user", "content": "Check the weather in Paris and London." }, { "role": "assistant", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"location\":\"Paris\"}", "name": "get_current_temperature" }, "id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01", "type": "function" }, { "function": { "arguments": "{\"location\":\"London\"}", "name": "get_current_temperature" }, "id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44", "type": "function" } ] }, { "role":"tool", "name": "get_current_temperature", "tool_call_id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01", "content": "{\"temp\":\"15C\"}" }, { "role":"tool", "name": "get_current_temperature", "tool_call_id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44", "content": "{\"temp\":\"12C\"}" } ]
Firme in functionCall non Part
Gemini potrebbe anche restituire un thought_signature nell'Part finale di una
risposta, anche se non è presente alcuna chiamata di funzione.
- Comportamento:i contenuti finali
Part(text,inlineDatae così via) restituiti dal modello potrebbero contenere unthought_signature. - Requisito:la restituzione di questa firma è consigliata per garantire che il modello mantenga un ragionamento di alta qualità, soprattutto per istruzioni complesse o workflow agentici simulati.
- Convalida:l'API non applica rigorosamente la convalida per
le firme nelle parti non
functionCall. Se li ometti, non riceverai un errore di blocco, anche se il rendimento potrebbe peggiorare.
Esempio di risposta del modello con firma nella parte di testo:
Gli esempi seguenti mostrano una risposta del modello in cui è incluso un thought_signature in un Part non functionCall e come gestirlo in una richiesta successiva.
Turno 1, passaggio 1 (risposta del modello)
{ "role": "model", "parts": [ { "text": "I need to calculate the risk. Let me think step-by-step...", "thought_signature": "<SIGNATURE_C>" // OPTIONAL (Recommended) } ] }
Turno 2, passaggio 1 (utente)
[ { "role": "user", "parts": [{ "text": "What is the risk?" }] }, { "role": "model", "parts": [ { "text": "I need to calculate the risk. Let me think step-by-step...", // If you omit <SIGNATURE_C> here, no error will occur. } ] }, { "role": "user", "parts": [{ "text": "Summarize it." }] } ]
Esempio di modifica di immagini in più passaggi utilizzando le firme concettuali
Gli esempi riportati di seguito mostrano come recuperare e passare le firme concettuali durante la creazione e la modifica di immagini in più passaggi con Gemini 3 Pro Image.
Turno 1: ricevi la risposta e salva i dati che includono le firme dei pensieri
chat = client.chats.create( model="gemini-3-pro-image-preview", config=types.GenerateContentConfig( response_modalities=['TEXT', 'IMAGE'] ) ) message = "Create an image of a clear perfume bottle sitting on a vanity." response = chat.send_message(message) data = b'' for part in response.candidates[0].content.parts: if part.text: display(Markdown(part.text)) if part.inline_data: data = part.inline_data.data display(Image(data=data, width=500))
Turno 2: passa i dati che includono le firme del pensiero
response = chat.send_message( message=[ types.Part.from_bytes( data=data, mime_type="image/png", ), "Make the perfume bottle purple and add a vase of hydrangeas next to the bottle.", ], ) for part in response.candidates[0].content.parts: if part.text: display(Markdown(part.text)) if part.inline_data: display(Image(data=part.inline_data.data, width=500))
Passaggi successivi
Pensiero
La capacità di ragionamento di Gemini aiuta il modello a fornire risposte più pertinenti al contesto e registra il processo di ragionamento del modello come parte della risposta. Scopri le funzionalità incluse in Pensiero, inclusi i modelli supportati e come controllare l'output del modello.
Introduzione alla chiamata di funzione
Scopri come consentire ai modelli Gemini di utilizzare strumenti esterni durante la generazione di risposte utilizzando le chiamate di funzione.
Panoramica della messa a terra
Il grounding è la capacità di collegare l'output del modello a fonti di informazione verificabili. Scopri le varie origini dati (come la Ricerca Google, Google Maps e la ricerca di Agent Platform) disponibili per il grounding quando utilizzi Agent Platform.