Tanda tangan pemikiran adalah representasi terenkripsi dari proses pemikiran internal model. Tanda tangan pemikiran mempertahankan status penalaran Gemini selama percakapan multi-giliran dan multi-langkah, yang dapat berguna saat menggunakan panggilan fungsi. Respons dapat menyertakan kolom
thought_signature dalam bagian konten apa pun (misalnya, text, functionCall).
Gemini 3 Pro menerapkan validasi yang lebih ketat pada tanda tangan pemikiran daripada
versi Gemini sebelumnya
karena tanda tangan pemikiran meningkatkan performa model untuk panggilan fungsi. Untuk memastikan model mempertahankan konteks penuh di beberapa giliran percakapan, Anda harus menampilkan tanda tangan pemikiran dari respons sebelumnya dalam permintaan berikutnya.
Jika tanda tangan pemikiran yang diperlukan tidak ditampilkan saat menggunakan Gemini 3 Pro, model akan menampilkan error 400.
Gambar Gemini 3 Pro tidak menerapkan validasi ini. Untuk memastikan model mempertahankan konteks penuh di beberapa giliran percakapan, Anda harus menampilkan tanda tangan pemikiran dari respons sebelumnya dalam permintaan berikutnya.
Gambar Gemini 3 Pro tidak menampilkan error 400 jika tanda tangan pemikiran tidak ditampilkan. Untuk contoh kode terkait pengeditan gambar multi-turn menggunakan
Gemini 3 Pro Image, lihat
Contoh pengeditan gambar multi-turn menggunakan tanda tangan pemikiran.
Jika Anda menggunakan Gen AI SDK Google resmi (Python, Node.js, Go, atau Java) dan menggunakan fitur histori chat standar atau menambahkan respons model lengkap ke histori, tanda tangan pemikiran akan ditangani secara otomatis.
Mengapa hal ini penting?
Saat Model pemikiran memanggil alat eksternal, model tersebut akan menjeda proses penalaran internalnya. Tanda tangan pemikiran berfungsi sebagai "status penyimpanan", yang memungkinkan model melanjutkan rantai pemikirannya dengan lancar setelah Anda memberikan hasil fungsi. Tanpa tanda tangan pemikiran, model "melupakan" langkah-langkah penalaran spesifiknya selama fase eksekusi alat. Mengirimkan kembali tanda tangan memastikan:
- Kontinuitas konteks: Model mempertahankan dan dapat memeriksa langkah-langkah penalaran yang membenarkan pemanggilan alat.
- Penalaran kompleks: Memungkinkan tugas multi-langkah di mana output satu alat memberikan informasi penalaran untuk alat berikutnya.
Belokan dan langkah
Dalam konteks panggilan fungsi, penting untuk memahami perbedaan antara giliran dan langkah:
- Giliran mewakili pertukaran percakapan yang lengkap, dimulai dengan perintah pengguna dan berakhir saat model memberikan respons akhir non-panggilan fungsi terhadap perintah tersebut.
- Langkah terjadi dalam satu giliran saat model memanggil fungsi dan memerlukan respons fungsi untuk melanjutkan proses penalaran. Seperti yang ditunjukkan dalam diagram, satu giliran dapat melibatkan beberapa langkah jika model perlu memanggil beberapa fungsi secara berurutan untuk memenuhi permintaan pengguna.
Cara menggunakan tanda tangan pemikiran
Cara paling sederhana untuk menangani tanda tangan pemikiran adalah dengan menyertakan semua
Parts dari semua pesan sebelumnya dalam histori percakapan saat mengirim permintaan baru, persis seperti yang ditampilkan oleh model.
Jika Anda tidak menggunakan salah satu SDK AI Generatif Google, atau Anda perlu mengubah atau memangkas histori percakapan, Anda harus memastikan bahwa tanda tangan pemikiran dipertahankan dan dikirim kembali ke model.
Saat menggunakan Google Gen AI SDK (direkomendasikan)
Saat menggunakan fitur histori chat SDK atau menambahkan objek content model
dari respons sebelumnya ke contents permintaan berikutnya, tanda tangan akan ditangani secara otomatis.
Contoh Python berikut menunjukkan penanganan otomatis:
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}")
Saat menggunakan REST atau penanganan manual
Jika berinteraksi dengan API secara langsung, Anda harus menerapkan penanganan tanda tangan berdasarkan aturan berikut untuk Gemini 3 Pro:
- Panggilan fungsi:
- Jika respons model berisi satu atau beberapa bagian
functionCall,thought_signaturediperlukan agar pemrosesan berjalan dengan benar. - Dalam kasus panggilan fungsi paralel dalam satu respons, hanya bagian
functionCallpertama yang akan berisithought_signature. - Dalam kasus panggilan fungsi berurutan di beberapa langkah dalam giliran,
setiap bagian
functionCallakan berisithought_signature. - Aturan: Saat membuat permintaan berikutnya, Anda harus menyertakan
partyang berisifunctionCalldanthought_signature-nya persis seperti yang ditampilkan oleh model. Untuk panggilan fungsi berurutan (multi-langkah), validasi dilakukan pada semua langkah dalam giliran saat ini, dan menghilangkanthought_signatureyang diperlukan untuk bagianfunctionCallpertama dalam langkah apa pun pada giliran saat ini akan menghasilkan error400. Giliran dimulai dengan pesan pengguna terbaru yang bukan merupakanfunctionResponse. - Jika model menampilkan panggilan fungsi paralel (misalnya,
FC1+signature,FC2), respons Anda harus berisi semua panggilan fungsi yang diikuti dengan semua respons fungsi (FC1+signature,FC2,FR1,FR2). Respons yang diselingi (FC1+signature,FR1,FC2,FR2) akan menghasilkan error400. - Ada kasus yang jarang terjadi saat Anda perlu memberikan bagian
functionCallyang tidak dihasilkan oleh API dan oleh karena itu tidak memiliki tanda tangan pemikiran terkait (misalnya, saat mentransfer histori dari model yang tidak menyertakan tanda tangan pemikiran). Anda dapat menyetelthought_signaturekeskip_thought_signature_validator, tetapi tindakan ini harus dilakukan sebagai upaya terakhir karena akan berdampak negatif pada performa model.
- Jika respons model berisi satu atau beberapa bagian
- Panggilan non-fungsi:
- Jika respons model tidak berisi
functionCall, respons tersebut mungkin menyertakanthought_signaturedi akhirpartrespons (misalnya, bagiantextterakhir). - Aturan: Menyertakan tanda tangan ini dalam permintaan berikutnya
direkomendasikan untuk performa terbaik, tetapi menghilangkannya tidak akan menyebabkan
error. Saat streaming, tanda tangan ini mungkin ditampilkan di
bagian dengan konten teks kosong, jadi pastikan untuk mengurai semua bagian hingga
finish_reasonditampilkan oleh model.
- Jika respons model tidak berisi
Ikuti aturan berikut untuk memastikan konteks model dipertahankan:
- Selalu kirim
thought_signaturekembali ke model di dalamPartaslinya. - Jangan gabungkan
Partyang berisi tanda tangan denganPartyang tidak berisi tanda tangan. Hal ini merusak konteks posisi pemikiran. - Jangan menggabungkan dua
Partyang keduanya berisi tanda tangan, karena string tanda tangan tidak dapat digabungkan.
Contoh panggilan fungsi berurutan
Contoh berikut menunjukkan contoh panggilan fungsi multi-langkah saat pengguna meminta "Periksa status penerbangan AA100 dan pesan taksi jika penerbangan ditunda", yang memerlukan beberapa tugas.
REST
Contoh berikut menunjukkan cara menangani tanda tangan pemikiran di beberapa langkah dalam alur kerja panggilan fungsi berurutan menggunakan REST API.
Turn 1, Step 1 (permintaan pengguna)
{ "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" ] } } ] } ] }
Giliran 1, Langkah 1 (respons model)
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] } }
Turn 1, Step 2 (respons pengguna - mengirim output alat)
Karena giliran pengguna ini hanya berisi functionResponse (tanpa teks baru), kita masih berada di Giliran 1. Anda harus mempertahankan <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" } } } ] }
Giliran 1, Langkah 2 (respons model)
Model kini memutuskan untuk memesan taksi berdasarkan output alat sebelumnya.
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "book_taxi", "args": { "time": "10 AM" } }, "thoughtSignature": "<SIGNATURE_B>" } ] } }
Turn 1, Langkah 3 (respons pengguna - mengirim output alat)
Untuk mengirim konfirmasi pemesanan taksi, Anda harus menyertakan tanda tangan untuk semua
panggilan fungsi dalam loop ini (<SIGNATURE_A> dan <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" } } } ] } }
Penyelesaian Chat
Contoh berikut menunjukkan cara menangani tanda tangan pemikiran di beberapa langkah dalam alur kerja panggilan fungsi berurutan menggunakan Chat Completions API.
Turn 1, Step 1 (permintaan pengguna)
{ "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" ] } } } ] }
Giliran 1, Langkah 1 (respons model)
{ "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1", "type": "function" } ] }
Turn 1, Step 2 (respons pengguna - mengirim output alat)
Karena giliran pengguna ini hanya berisi functionResponse (tanpa teks baru), kita masih berada di Giliran 1. Anda harus mempertahankan <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\"}" } ]
Giliran 1, Langkah 2 (respons model)
Model kini memutuskan untuk memesan taksi berdasarkan output alat sebelumnya.
{ "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" } ] }
Turn 1, Langkah 3 (respons pengguna - mengirim output alat)
Untuk mengirim konfirmasi pemesanan taksi, Anda harus menyertakan tanda tangan untuk semua
panggilan fungsi dalam loop ini (<SIGNATURE_A> dan <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\"}" } ]
Contoh panggilan fungsi paralel
Contoh berikut menunjukkan contoh panggilan fungsi paralel saat pengguna meminta "Cek cuaca di Paris dan London".
REST
Contoh berikut menunjukkan cara menangani tanda tangan pemikiran dalam alur kerja panggilan fungsi paralel menggunakan REST API.
Turn 1, Step 1 (permintaan pengguna)
{ "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" ] } } ] } ] }
Giliran 1, Langkah 1 (respons model)
{ "content": { "parts": [ { "functionCall": { "name": "get_current_temperature", "args": { "location": "Paris" } }, "thoughtSignature": "<SIGNATURE_A>" }, { "functionCall": { "name": "get_current_temperature", "args": { "location": "London" } } } ] } }
Turn 1, Step 2 (respons pengguna - mengirim output alat)
Anda harus mempertahankan <SIGNATURE_A> di bagian pertama persis seperti yang diterima.
[ { "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" } } } ] } ]
Penyelesaian Chat
Contoh berikut menunjukkan cara menangani tanda tangan pemikiran dalam alur kerja panggilan fungsi paralel menggunakan Chat Completions API.
Turn 1, Step 1 (permintaan pengguna)
{ "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" ] } } ] } ] }
Giliran 1, Langkah 1 (respons model)
{ "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" } ] }
Turn 1, Step 2 (respons pengguna - mengirim output alat)
Anda harus mempertahankan <SIGNATURE_A> di bagian pertama persis seperti yang diterima.
"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\"}" } ]
Tanda tangan di Part non-functionCall
Gemini juga dapat menampilkan thought_signature di Part akhir respons, meskipun tidak ada panggilan fungsi.
- Perilaku: Konten akhir
Part(text,inlineData, dll.) yang ditampilkan oleh model mungkin berisithought_signature. - Persyaratan: Menampilkan tanda tangan ini direkomendasikan untuk memastikan model mempertahankan penalaran berkualitas tinggi, terutama untuk alur kerja agentik yang disimulasikan atau mengikuti petunjuk yang kompleks.
- Validasi: API tidak secara ketat menerapkan validasi untuk tanda tangan di bagian non-
functionCall. Anda tidak akan menerima error pemblokiran jika Anda menghapusnya, meskipun performa mungkin menurun.
Contoh respons model dengan tanda tangan di bagian teks:
Contoh berikut menunjukkan respons model yang menyertakan thought_signature dalam Part non-functionCall dan cara menanganinya dalam permintaan berikutnya.
Giliran 1, Langkah 1 (respons model)
{ "role": "model", "parts": [ { "text": "I need to calculate the risk. Let me think step-by-step...", "thought_signature": "<SIGNATURE_C>" // OPTIONAL (Recommended) } ] }
Giliran 2, Langkah 1 (pengguna)
[ { "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." }] } ]
Contoh pengeditan gambar multi-turn menggunakan tanda tangan pemikiran
Contoh berikut menggambarkan cara mengambil dan meneruskan tanda tangan pemikiran selama pembuatan dan pengeditan gambar multi-turn dengan Gemini 3 Pro Image.
Turn 1: Mendapatkan respons dan menyimpan data yang mencakup tanda tangan pemikiran
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))
Giliran 2: meneruskan data yang mencakup tanda tangan pemikiran
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))
Langkah berikutnya
- Pelajari lebih lanjut Pemikiran.
- Pelajari lebih lanjut Panggilan fungsi.
- Pelajari cara Mendesain perintah multimodal.