Le firme del pensiero sono rappresentazioni criptate del processo di pensiero interno del modello. Le firme del pensiero preservano lo stato di 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).
Gemini 3 Pro applica una convalida più rigorosa delle firme dei pensieri rispetto alle versioni precedenti di Gemini perché migliorano le prestazioni del modello per le chiamate di funzione. 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.
Se non viene restituita una firma del pensiero richiesta quando utilizzi Gemini 3 Pro,
il modello restituisce un errore 400.
Gemini 3 Pro Image non applica questa convalida. 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.
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, vedi
Esempio di modifica di immagini in più passaggi utilizzando le firme di pensiero.
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 Thinking 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 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 di svolgere attività in più passaggi in cui l'output di uno strumento influisce sul ragionamento per il passaggio 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 senza chiamate di funzioni a quel prompt.
- Un passaggio si verifica in un singolo turno quando il modello richiama una funzione e richiede una risposta alla funzione per continuare il processo di ragionamento. Come mostrato nel diagramma, un singolo turno può comportare più passaggi se il modello deve chiamare diverse funzioni in sequenza per soddisfare la richiesta dell'utente.
Come usare 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 della conversazione, devi assicurarti che le firme del pensiero vengano conservate e inviate di nuovo al modello.
Quando utilizzi Google Gen AI SDK (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ù
functionCallparti, è necessario unthought_signatureper l'elaborazione corretta. - Nei casi di chiamate di funzione parallele in una singola risposta, solo la parte prima
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 è stato 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ù
- Chiamata non funzione:
- Se la risposta 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 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. Questo interrompe 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 funzione sequenziale
L'esempio seguente mostra un esempio di 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 del pensiero 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 funzioni 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
Il seguente esempio 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-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 funzioni 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
Il seguente esempio 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 l'hai 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
Il seguente esempio mostra come gestire le firme dei pensieri in un flusso di lavoro di chiamata di funzioni parallela 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 l'hai 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 Part non functionCall
Gemini potrebbe anche restituire un thought_signature nel 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 di pensiero
Gli esempi riportati di seguito mostrano come recuperare e trasmettere le firme di pensiero 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
- Scopri di più su Thinking.
- Scopri di più sulla chiamata di funzione.
- Scopri come progettare prompt multimodali.