Le firme concettuali sono rappresentazioni criptate del processo di ragionamento interno del modello. Le firme concettuali conservano lo stato di ragionamento di Gemini durante
le conversazioni in più passaggi e in più fasi, il che può essere utile quando si utilizza
la chiamata di funzione. Le risposte possono includere un campo thought_signature in qualsiasi parte del contenuto (ad es. text, functionCall).
I modelli Gemini 3 applicano una convalida più rigorosa delle firme concettuali rispetto alle versioni precedenti di Gemini perché migliorano le prestazioni del modello per la chiamata di funzione. Per assicurarti che il modello mantenga il contesto completo in più passaggi di una conversazione, devi restituire le firme concettuali delle risposte precedenti nelle richieste successive, anche quando utilizzi i livelli di ragionamento MINIMAL. Se una firma concettuale obbligatoria 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 assicurarti che il modello mantenga il contesto completo in più passaggi di una conversazione, devi comunque restituire le firme concettuali delle risposte precedenti nelle richieste successive. Gemini 3 Pro Image non restituisce un errore 400 se non viene restituita una firma concettuale. Per esempi di codice relativi alla modifica di immagini multi-turno
utilizzando Gemini 3 Pro Image, consulta
Esempio di modifica di immagini multi-turno utilizzando le firme concettuali.
Se utilizzi l'SDK Google Gen AI ufficiale di Google (Python, Node.js, Go o Java) e le funzionalità standard della cronologia chat o aggiungi la risposta completa del modello alla cronologia, le firme concettuali vengono gestite automaticamente.
Perché sono importanti?
Quando un modello di ragionamento chiama uno strumento esterno, mette in pausa il processo di ragionamento interno. La firma concettuale funge da "stato di salvataggio", consentendo al modello di riprendere senza problemi la sua catena di ragionamento una volta fornito il risultato della funzione. Senza le firme concettuali, 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 dello strumento.
- Ragionamento complesso: consente attività in più fasi in cui l'output di uno strumento informa il ragionamento per il successivo.
Conservazione del ragionamento
Per i modelli Gemini 3.5 Flash e successivi, i ragionamenti dei passaggi precedenti vengono conservati per impostazione predefinita. Il servizio conserva la cronologia dei ragionamenti nel contesto della conversazione prima di passarla al modello.
Quando invii la cronologia delle conversazioni, mantieni la coerenza con i passaggi precedenti: includi il contesto completo (ragionamenti, chiamate di funzione e risposte) oppure omettilo completamente. Se fornisci un contesto parziale, le prestazioni del modello potrebbero peggiorare.
Passaggi e fasi
Nel contesto della chiamata di funzione, è importante comprendere la differenza tra passaggi e fasi:
- Un passaggio rappresenta uno scambio di conversazione completo, che inizia con il prompt di un utente e termina quando il modello fornisce una risposta finale che non è una chiamata di funzione a quel prompt.
- Una fase si verifica all'interno di un singolo passaggio quando il modello richiama una funzione e richiede una risposta della funzione per continuare il processo di ragionamento. Come mostrato nel diagramma, un singolo passaggio può comportare più fasi se il modello deve chiamare più funzioni in sequenza per soddisfare la richiesta dell'utente.
Come utilizzare le firme concettuali
Il modo più semplice per gestire le firme concettuali è includere tutte le Part di tutti i messaggi precedenti nella cronologia delle conversazioni quando invii una nuova richiesta, esattamente come sono state restituite dal modello.
Se non utilizzi uno degli SDK Google Gen AI di Google o devi modificare o tagliare la cronologia delle conversazioni, devi assicurarti che le firme concettuali vengano conservate e restituite al modello.
Quando utilizzi l'SDK Google Gen AI di Google (consigliato)
Quando utilizzi le funzionalità della cronologia chat degli SDK o aggiungi l'oggetto del modello
content 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-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, è necessaria unathought_signatureper l'elaborazione corretta. - Nei casi di chiamate di funzione parallele in una singola risposta, solo la prima parte
functionCallconterrà lathought_signature. - Nei casi di chiamate di funzione sequenziali in più fasi in un passaggio, ogni parte
functionCallconterrà unathought_signature. - Regola: quando crei la richiesta successiva, devi includere la
partcontenente lafunctionCalle la relativathought_signatureesattamente come è stata restituita dal modello. Per la chiamata di funzione sequenziale (in più fasi), la convalida viene eseguita su tutte le fasi del passaggio corrente e l'omissione di unathought_signatureobbligatoria per la prima partefunctionCallin qualsiasi fase del passaggio corrente genera un errore400. Un passaggio inizia con il messaggio utente più recente che non è unafunctionResponse. - Se il modello restituisce chiamate di funzione parallele (ad es.
FC1+signature,FC2), la risposta deve contenere tutte le chiamate di funzione seguite da tutte le risposte della funzione (FC1+signature,FC2,FR1,FR2). L'interleaving delle risposte (FC1+signature,FR1,FC2,FR2) genera un errore400. - In rari casi, devi fornire parti
functionCallche non sono state generate dall'API e che quindi non hanno una firma concettuale associata (ad esempio, quando trasferisci la cronologia da un modello che non include firme concettuali). Puoi impostarethought_signaturesuskip_thought_signature_validator, ma questa deve essere l'ultima risorsa in quanto influirà negativamente sulle prestazioni del modello.
- Se la risposta del modello contiene una o più parti
- Chiamata non di funzione:
- Se la risposta del modello non contiene una
functionCall, potrebbe includere unathought_signaturenell'ultimapartdella risposta (ad esempio, l'ultima partetext). - Regola: l'inclusione di questa firma nella richiesta successiva è
consigliata per prestazioni ottimali, 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 una
Segui queste regole per assicurarti che il contesto del modello venga conservato:
- Invia sempre la
thought_signatureal modello all'interno dellaPartoriginale. - Non unire una
Partcontenente una firma con una che non la contiene. In questo modo si interrompe il contesto posizionale del ragionamento. - Non combinare due
Partche contengono entrambe le 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ù fasi in cui l'utente chiede "Controlla lo stato del volo AA100 e prenota un taxi in caso di ritardo", che richiede più attività.
REST
L'esempio seguente mostra come gestire le firme concettuali in più fasi di un flusso di lavoro di chiamata di funzione sequenziale utilizzando l'API REST.
Passaggio 1, fase 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" ] } } ] } ] }
Passaggio 1, fase 1 (risposta del modello)
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] } }
Passaggio 1, fase 2 (risposta dell'utente - invio degli output dello strumento)
Poiché questo passaggio dell'utente contiene solo una functionResponse (nessun testo nuovo), siamo ancora nel passaggio 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" } } } ] }
Passaggio 1, fase 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>" } ] } }
Passaggio 1, fase 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 concettuali in più fasi di un flusso di lavoro di chiamata di funzione sequenziale utilizzando l'API Completamenti chat.
Passaggio 1, fase 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" ] } } } ] }
Passaggio 1, fase 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" } ] }
Passaggio 1, fase 2 (risposta dell'utente - invio degli output dello strumento)
Poiché questo passaggio dell'utente contiene solo una functionResponse (nessun testo nuovo), siamo ancora nel passaggio 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\"}" } ]
Passaggio 1, fase 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" } ] }
Passaggio 1, fase 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 concettuali in un flusso di lavoro di chiamata di funzione parallela utilizzando l'API REST.
Passaggio 1, fase 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" ] } } ] } ] }
Passaggio 1, fase 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" } } } ] } }
Passaggio 1, fase 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": { "functionResponse": { "name": "get_current_temperature", "response": { "temp": "12C" } } } ] } ]
Completamenti chat
L'esempio seguente mostra come gestire le firme concettuali in un flusso di lavoro di chiamata di funzione parallela utilizzando l'API Completamenti chat.
Passaggio 1, fase 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" ] } } ] } ] }
Passaggio 1, fase 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" } ] }
Passaggio 1, fase 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 può anche restituire una thought_signature nella Part finale di una risposta, anche se non è presente alcuna chiamata di funzione.
- Comportamento: la
Partdel contenuto finale (text,inlineDatae così via) restituita dal modello può contenere unathought_signature. - Requisito: la restituzione di questa firma è consigliata per assicurarsi che il modello mantenga un ragionamento di alta qualità, soprattutto per i flussi di lavoro di agenti simulati o di istruzioni complesse.
- Convalida: l'API non applica rigorosamente la convalida per le firme nelle parti non
functionCall. Non riceverai un errore di blocco se le ometti, anche se 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 una thought_signature è inclusa in una Part non functionCall e come gestirla in una richiesta successiva.
Passaggio 1, fase 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) } ] }
Passaggio 2, fase 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 multi-turno utilizzando le firme concettuali
Gli esempi seguenti illustrano come recuperare e passare le firme concettuali durante la creazione e la modifica di immagini in più passaggi con Gemini 3 Pro Image.
Passaggio 1: recupera la risposta e salva i dati che includono le firme concettuali
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))
Passaggio 2: passa i dati che includono le firme concettuali
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 le funzionalità di ragionamento di Gemini e come configurare i livelli di ragionamento.
Guida ai prompt di ragionamento
Scopri le tecniche di prompt engineering e le best practice personalizzate 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.