Le firme dei pensieri sono rappresentazioni criptate del processo di pensiero interno del modello. Le firme di pensiero preservano lo stato di ragionamento di Gemini durante le conversazioni multi-turno e multi-step, 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 dei contenuti (ad es. text, functionCall).
I modelli Gemini 3 applicano una convalida più rigorosa alle firme di pensiero 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, anche quando utilizzi i livelli di pensiero MINIMAL. Se non viene restituita una firma del pensiero richiesta 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 chat o aggiungi la risposta completa del modello alla cronologia, le firme dei pensieri 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 sua catena di pensiero senza problemi una volta fornito il risultato della funzione. Senza le firme dei pensieri, 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 dello strumento.
- Ragionamento complesso: consente di eseguire attività in più passaggi in cui l'output di uno strumento fornisce informazioni per il ragionamento di quello successivo.
Conservazione del ragionamento
Per Gemini 3.5 Flash e i modelli più recenti, i pensieri dei turni precedenti vengono conservati per impostazione predefinita. Il servizio conserva la cronologia dei pensieri nel contesto della conversazione prima di passarla al modello.
Quando invii la cronologia delle conversazioni, mantieni la coerenza con i turni precedenti: includi il contesto completo (pensieri, chiamate di funzione e risposte) o omettilo del tutto. Fornire un contesto parziale può ridurre le prestazioni del modello.
Firme del pensiero di altri modelli
I modelli Flash-Lite non possono leggere i pensieri generati da modelli non Flash-Lite. Se una richiesta a un modello Flash-Lite include firme di pensiero generate da un modello non Flash-Lite, la richiesta non avrà esito negativo. Il servizio, invece, elimina questi pensieri dal contesto del modello. Ad esempio, questo accade quando invii una richiesta a un modello Flash-Lite con la cronologia di un modello Gemini Flash o Pro.
Svolte e passaggi
Nel contesto della chiamata di funzione, è importante comprendere la differenza tra turni e passaggi:
- Un turno rappresenta uno scambio di conversazione completo, che inizia con un prompt dell'utente e termina quando il modello fornisce una risposta finale, non una 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 di pensiero
Il modo più semplice per gestire le firme dei pensieri è includere tutti i
Part di tutti i messaggi precedenti nella cronologia delle conversazioni quando invii una
nuova richiesta, esattamente come sono stati restituiti dal modello.
Se non utilizzi uno degli SDK Google Gen AI di Google o se devi modificare o tagliare la cronologia delle conversazioni, devi assicurarti che le firme dei pensieri vengano conservate e inviate nuovamente al modello.
Quando utilizzi l'SDK Google Gen AI (consigliato)
Quando utilizzi le funzionalità della cronologia chat degli SDK o aggiungi l'oggetto content del modello dalla risposta precedente all'oggetto contents della richiesta successiva, le firme vengono gestite automaticamente.
Il seguente esempio di 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-3.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-3.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 funzione:
- Se la risposta del modello contiene una o più parti
functionCall, è necessario unthought_signatureper un'elaborazione corretta. - In caso di chiamate di funzione parallele in una singola risposta, solo la prima parte
functionCallconterràthought_signature. - In caso di chiamate di funzione sequenziali in più passaggi di un turno,
ogni parte
functionCallconterrà unthought_signature. - Regola: quando crei la richiesta successiva, devi includere l'oggetto
partcontenentefunctionCalle il relativothought_signatureesattamente come è stato restituito dal modello. Per la chiamata di funzione sequenziale (in più passaggi), 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 utente più recente che non è unfunctionResponse. - Se il modello restituisce chiamate di funzione parallele (ad esempio
FC1+signature,FC2), la risposta deve contenere tutte le chiamate di funzione seguite da tutte le risposte alle funzioni (FC1+signature,FC2,FR1,FR2). L'interfoliazione delle risposte (FC1+signature,FR1,FC2,FR2) genera un errore400. Restituisce le partifunctionResponsenello stesso ordine delle partifunctionCallcorrispondenti. L'API associa le risposte delle funzioni parallele alle chiamate di funzione tramiteid(se fornito inv1beta1) o tramitenamee l'ordine sequenziale nell'arrayparts. - In rari casi, devi fornire parti
functionCallche non sono state generate dall'API e che quindi 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 dovrebbe essere l'ultima risorsa, in quanto influirà negativamente sulle prestazioni del modello.
- Se la risposta del modello contiene una o più parti
- Senza chiamata di funzione:
- Se la risposta del modello non contiene un
functionCall, potrebbe includere unthought_signaturenell'ultimopartdella risposta (ad esempio, l'ultima partetext). - Regola: l'inclusione di questa firma nella richiesta successiva è consigliata per ottenere prestazioni ottimali, ma l'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:
- Invia 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 delle firme 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 se è in ritardo", il che richiede più attività.
REST
L'esempio seguente mostra come gestire le firme di pensiero in più passaggi di un workflow 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 nel 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 dello strumento precedente.
{ "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 loop (<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 chat
L'esempio seguente mostra come gestire le firme di pensiero in più passaggi di un workflow di chiamata di funzione 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 nel 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 dello strumento precedente.
{ "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 loop (<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 un esempio di 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 di pensiero in un workflow 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 ricevuta.
[ { "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 chat
L'esempio seguente mostra come gestire le firme di pensiero in un workflow di chiamata di funzione 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 ricevuta.
"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 possono contenere unthought_signature. - Requisito: la restituzione di questa firma è consigliata per garantire che il modello mantenga un ragionamento di alta qualità, in particolare per l'esecuzione di istruzioni complesse o Agentic Workflows simulati.
- Convalida: l'API non applica rigorosamente la convalida per le firme in parti non
functionCall. Se li ometti, non riceverai un errore di blocco, ma le prestazioni potrebbero peggiorare.
Esempio di risposta del modello con firma nella parte di testo:
Gli esempi seguenti mostrano una risposta del modello in cui un thought_signature è incluso 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 editing di immagini in più passaggi utilizzando le firme concettuali
I seguenti esempi illustrano 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 di pensiero
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 di 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
Ragionamento
Scopri di più sulle funzionalità di ragionamento di Gemini e su come configurare i livelli di ragionamento.
Guida ai prompt di ragionamento
Esplora le tecniche di prompt engineering e le best practice su misura per i modelli di ragionamento di Gemini.
Introduzione alla chiamata di funzione
Scopri come consentire ai modelli Gemini di utilizzare strumenti esterni durante la generazione delle risposte utilizzando la chiamata di funzione.