Gedankensignaturen sind verschlüsselte Darstellungen des internen Denkprozesses des Modells. Durch die Verwendung von „Thought Signatures“ wird der Reasoning-Status von Gemini bei Unterhaltungen mit mehreren Zügen und Schritten beibehalten. Das kann nützlich sein, wenn Sie Funktionsaufrufe verwenden. Antworten können in jedem Inhaltsteil ein thought_signature-Feld enthalten, z.B. text, functionCall).
Gemini 3 Pro erzwingt eine strengere Validierung von Thought-Signaturen als frühere Gemini-Versionen, da sie die Modellleistung für Funktionsaufrufe verbessern. Damit das Modell den vollständigen Kontext über mehrere Gesprächsrunden hinweg beibehält, müssen Sie die Gedanken-Signaturen aus früheren Antworten in Ihren nachfolgenden Anfragen zurückgeben.
Wenn bei der Verwendung von Gemini 3 Pro keine erforderliche Gedanken-Signatur zurückgegeben wird, gibt das Modell einen 400-Fehler zurück.
Gemini 3 Pro Image erzwingt diese Validierung nicht. Damit das Modell den vollständigen Kontext über mehrere Gesprächsrunden hinweg beibehält, müssen Sie die Gedanken-Signaturen aus früheren Antworten in Ihren nachfolgenden Anfragen zurückgeben.
Gemini 3 Pro Image gibt keinen 400-Fehler zurück, wenn keine Gedanken-Signatur zurückgegeben wird. Codebeispiele für die Multi-Turn-Bildbearbeitung mit Gemini 3 Pro Image finden Sie unter Beispiel für die Multi-Turn-Bildbearbeitung mit Gedanken-Signaturen.
Wenn Sie das offizielle Google Gen AI SDK (Python, Node.js, Go oder Java) verwenden und die Standardfunktionen für den Chatverlauf nutzen oder die vollständige Modellantwort an den Verlauf anhängen, werden Gedanken-Signaturen automatisch verarbeitet.
Warum sind sie wichtig?
Wenn ein Thinking-Modell ein externes Tool aufruft, wird der interne Denkprozess unterbrochen. Die Gedanken-Signatur fungiert als „Speicherpunkt“, sodass das Modell seinen Gedankengang nahtlos fortsetzen kann, sobald Sie das Ergebnis der Funktion bereitstellen. Ohne Thought-Signaturen „vergisst“ das Modell seine spezifischen Denkschritte während der Tool-Ausführungsphase. Durch die Rückgabe der Signatur wird Folgendes sichergestellt:
- Kontinuität des Kontexts:Das Modell behält die Begründungsschritte bei, die den Aufruf des Tools gerechtfertigt haben, und kann sie überprüfen.
- Komplexes Reasoning:Ermöglicht Aufgaben mit mehreren Schritten, bei denen die Ausgabe eines Tools das Reasoning für das nächste beeinflusst.
Abbiegungen und Schritte
Im Kontext von Funktionsaufrufen ist es wichtig, den Unterschied zwischen Turns und Schritten zu verstehen:
- Ein Turn stellt einen vollständigen Austausch in einer Unterhaltung dar, der mit einem Nutzer-Prompt beginnt und endet, wenn das Modell eine endgültige Antwort auf diesen Prompt liefert, die keinen Funktionsaufruf enthält.
- Ein Schritt erfolgt innerhalb eines einzelnen Turns, wenn das Modell eine Funktion aufruft und eine Funktionsantwort benötigt, um den Denkprozess fortzusetzen. Wie im Diagramm dargestellt, kann ein einzelner Turn mehrere Schritte umfassen, wenn das Modell mehrere Funktionen nacheinander aufrufen muss, um die Anfrage des Nutzers zu erfüllen.
Gedankensignaturen verwenden
Die einfachste Möglichkeit, Gedanken-Signaturen zu verarbeiten, besteht darin, alle Part aus allen vorherigen Nachrichten im Unterhaltungsverlauf beim Senden einer neuen Anfrage einzufügen, genau wie sie vom Modell zurückgegeben wurden.
Wenn Sie keines der Google Gen AI SDKs verwenden oder den Unterhaltungsverlauf ändern oder kürzen müssen, müssen Sie dafür sorgen, dass die Gedanken-Signaturen beibehalten und an das Modell zurückgesendet werden.
Bei Verwendung des Google Gen AI SDK (empfohlen)
Wenn Sie die Funktionen für den Chathistorie der SDKs verwenden oder das content-Objekt des Modells aus der vorherigen Antwort an das contents der nächsten Anfrage anhängen, werden Signaturen automatisch verarbeitet.
Das folgende Python-Beispiel zeigt die automatische Verarbeitung:
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}")
Bei Verwendung von REST oder manueller Verarbeitung
Wenn Sie direkt mit der API interagieren, müssen Sie die Signaturverarbeitung gemäß den folgenden Regeln für Gemini 3 Pro implementieren:
- Funktionsaufrufe:
- Wenn die Modellantwort einen oder mehrere
functionCall-Teile enthält, ist einthought_signaturefür die korrekte Verarbeitung erforderlich. - Bei parallelen Funktionsaufrufen in einer einzelnen Antwort enthält nur der erste
functionCall-Teil diethought_signature. - Bei sequenziellen Funktionsaufrufen über mehrere Schritte in einem Turn enthält jeder
functionCall-Teil einthought_signature. - Regel: Wenn Sie die nächste Anfrage erstellen, müssen Sie das
partmit demfunctionCallund seinemthought_signaturegenau so einfügen, wie es vom Modell zurückgegeben wurde. Bei sequenziellen (mehrstufigen) Funktionsaufrufen wird die Validierung für alle Schritte im aktuellen Turn durchgeführt. Wenn Sie in einem Schritt des aktuellen Turns ein erforderlichesthought_signaturefür den erstenfunctionCall-Teil weglassen, führt dies zu einem400-Fehler. Ein Turn beginnt mit der letzten Nutzernachricht, die keinfunctionResponseist. - Wenn das Modell parallele Funktionsaufrufe zurückgibt (z. B.
FC1+signature,FC2), muss Ihre Antwort alle Funktionsaufrufe gefolgt von allen Funktionsantworten (FC1+signature,FC2,FR1,FR2) enthalten. Wenn Sie Antworten verschachteln (FC1+signature,FR1,FC2,FR2), führt dies zu einem400-Fehler. - In seltenen Fällen müssen Sie
functionCall-Teile angeben, die nicht von der API generiert wurden und daher keine zugehörige Gedanken-Signatur haben, z. B. wenn Sie den Verlauf von einem Modell übertragen, das keine Gedanken-Signaturen enthält. Sie könnenthought_signatureaufskip_thought_signature_validatorfestlegen. Das sollte jedoch nur als letzter Ausweg in Betracht gezogen werden, da es sich negativ auf die Modellleistung auswirkt.
- Wenn die Modellantwort einen oder mehrere
- Aufruf einer Nicht-Funktion:
- Wenn die Modellantwort kein
functionCallenthält, kann sie einthought_signatureim letztenpartder Antwort enthalten (z. B. im letztentext-Teil). - Regel: Es wird empfohlen, diese Signatur in die nächste Anfrage aufzunehmen, um eine optimale Leistung zu erzielen. Wenn Sie sie weglassen, wird kein Fehler ausgegeben. Beim Streamen kann diese Signatur in einem Teil mit leerem Textinhalt zurückgegeben werden. Achten Sie daher darauf, alle Teile zu parsen, bis
finish_reasonvom Modell zurückgegeben wird.
- Wenn die Modellantwort kein
Beachten Sie die folgenden Regeln, damit der Kontext des Modells erhalten bleibt:
- Senden Sie den
thought_signatureimmer innerhalb des ursprünglichenPartzurück an das Modell. - Führen Sie kein
Partmit einer Signatur mit einem ohne Signatur zusammen. Dadurch wird der Positionskontext des Gedankens unterbrochen. - Kombinieren Sie nicht zwei
Part-Elemente, die beide Signaturen enthalten, da die Signaturstrings nicht zusammengeführt werden können.
Beispiel für sequenziellen Funktionsaufruf
Das folgende Beispiel zeigt einen Funktionsaufruf in mehreren Schritten, bei dem der Nutzer fragt: „Check flight status for AA100 and book a taxi if delayed“ (Prüfe den Flugstatus für AA100 und buche ein Taxi, wenn es zu einer Verspätung kommt). Dafür sind mehrere Aufgaben erforderlich.
REST
Das folgende Beispiel zeigt, wie Sie Gedanken-Signaturen in mehreren Schritten eines sequenziellen Workflows mit Funktionsaufrufen mithilfe der REST API verarbeiten.
Zug 1, Schritt 1 (Nutzeranfrage)
{ "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" ] } } ] } ] }
Runde 1, Schritt 1 (Antwort des Modells)
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] } }
Runde 1, Schritt 2 (Nutzerantwort – Senden von Tool-Ausgaben)
Da dieser Nutzerzug nur functionResponse enthält (kein neuer Text), befinden wir uns weiterhin in Zug 1. Sie müssen <SIGNATURE_A> beibehalten.
{ "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" } } } ] }
Runde 1, Schritt 2 (Modellantwort)
Das Modell entscheidet sich nun, basierend auf der vorherigen Tool-Ausgabe ein Taxi zu buchen.
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "book_taxi", "args": { "time": "10 AM" } }, "thoughtSignature": "<SIGNATURE_B>" } ] } }
Runde 1, Schritt 3 (Nutzerantwort – Senden der Tool-Ausgabe)
Um die Bestätigung der Taxibuchung zu senden, müssen Sie Signaturen für alle Funktionsaufrufe in dieser Schleife (<SIGNATURE_A> und <SIGNATURE_B>) einfügen.
{ "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" } } } ] } }
Chat-Vervollständigungen
Im folgenden Beispiel wird gezeigt, wie Sie Gedanken-Signaturen in einem sequenziellen Workflow mit Funktionsaufrufen über mehrere Schritte hinweg mit der Chat Completions API verarbeiten.
Zug 1, Schritt 1 (Nutzeranfrage)
{ "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" ] } } } ] }
Runde 1, Schritt 1 (Antwort des Modells)
{ "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1", "type": "function" } ] }
Runde 1, Schritt 2 (Nutzerantwort – Senden von Tool-Ausgaben)
Da dieser Nutzerzug nur functionResponse enthält (kein neuer Text), befinden wir uns weiterhin in Zug 1. Sie müssen <SIGNATURE_A> beibehalten.
"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\"}" } ]
Runde 1, Schritt 2 (Modellantwort)
Das Modell entscheidet sich nun, basierend auf der vorherigen Tool-Ausgabe ein Taxi zu buchen.
{ "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" } ] }
Runde 1, Schritt 3 (Nutzerantwort – Senden der Tool-Ausgabe)
Um die Bestätigung der Taxibuchung zu senden, müssen Sie Signaturen für alle Funktionsaufrufe in dieser Schleife (<SIGNATURE_A> und <SIGNATURE_B>) einfügen.
"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\"}" } ]
Beispiel für parallele Funktionsaufrufe
Das folgende Beispiel zeigt einen parallelen Funktionsaufruf, bei dem der Nutzer fragt: „Wie ist das Wetter in Paris und London?“.
REST
Das folgende Beispiel zeigt, wie Sie Gedanken-Signaturen in einem parallelen Workflow mit Funktionsaufrufen mithilfe der REST API verarbeiten.
Zug 1, Schritt 1 (Nutzeranfrage)
{ "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" ] } } ] } ] }
Runde 1, Schritt 1 (Antwort des Modells)
{ "content": { "parts": [ { "functionCall": { "name": "get_current_temperature", "args": { "location": "Paris" } }, "thoughtSignature": "<SIGNATURE_A>" }, { "functionCall": { "name": "get_current_temperature", "args": { "location": "London" } } } ] } }
Zug 1, Schritt 2 (Nutzerantwort – Senden von Tool-Ausgaben)
Sie müssen <SIGNATURE_A> im ersten Teil genau so beibehalten, wie Sie es erhalten haben.
[ { "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" } } } ] } ]
Chat-Vervollständigungen
Das folgende Beispiel zeigt, wie Sie Gedanken-Signaturen in einem parallelen Workflow mit Funktionsaufrufen mithilfe der Chat Completions API verarbeiten.
Runde 1, Schritt 1 (Nutzeranfrage)
{ "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" ] } } ] } ] }
Runde 1, Schritt 1 (Antwort des Modells)
{ "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" } ] }
Zug 1, Schritt 2 (Nutzerantwort – Senden von Tool-Ausgaben)
Sie müssen <SIGNATURE_A> im ersten Teil genau so beibehalten, wie Sie es erhalten haben.
"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\"}" } ]
Signaturen in Nicht-functionCall-Parts
Gemini kann auch ein thought_signature im letzten Part einer Antwort zurückgeben, auch wenn kein Funktionsaufruf vorhanden ist.
- Verhalten:Die endgültigen Inhalte
Part(text,inlineDatausw.), die vom Modell zurückgegeben werden, können einethought_signatureenthalten. - Anforderung:Die Rückgabe dieser Signatur wird empfohlen, um sicherzustellen, dass das Modell eine hohe Qualität beibehält, insbesondere bei komplexen Anweisungen oder simulierten agentischen Workflows.
- Validierung:Die API erzwingt die Validierung von Signaturen in Nicht-
functionCall-Teilen nicht strikt. Wenn Sie sie weglassen, erhalten Sie keinen blockierenden Fehler, die Leistung kann sich jedoch verschlechtern.
Beispiel für eine Modellantwort mit Signatur im Textteil:
Die folgenden Beispiele zeigen eine Modellantwort, in der ein thought_signature in einem nicht functionCall Part enthalten ist, und wie Sie es in einer nachfolgenden Anfrage verarbeiten.
Runde 1, Schritt 1 (Antwort des Modells)
{ "role": "model", "parts": [ { "text": "I need to calculate the risk. Let me think step-by-step...", "thought_signature": "<SIGNATURE_C>" // OPTIONAL (Recommended) } ] }
2. Zug, Schritt 1 (Nutzer)
[ { "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." }] } ]
Beispiel für die Multi-Turn-Bildbearbeitung mit Gedanken-Signaturen
Die folgenden Beispiele veranschaulichen, wie Sie bei der Erstellung und Bearbeitung von Bildern in mehreren Schritten mit Gemini 3 Pro Image Gedanken-Signaturen abrufen und übergeben.
Schritt 1: Antwort abrufen und Daten mit Gedanken-Signaturen speichern
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))
Zug 2: Daten mit Gedanken-Signaturen übergeben
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))