.
Düşünce imzaları, modelin dahili düşünce sürecinin şifrelenmiş temsilleridir ve çok adımlı etkileşimlerde akıl yürütme bağlamını korumak için kullanılır.
Düşünen modelleri (ör.Gemini 4, 3 ve 2.5 serisi) kullanırken API, yanıtın içerik bölümlerinde (ör. text veya functionCall bölümleri) bir thoughtSignature alanı döndürebilir.
Genel bir kural olarak, bir model yanıtında düşünce imzası alırsanız bir sonraki adımda sohbet geçmişini gönderirken bu imzayı tam olarak alındığı şekilde geri göndermeniz gerekir.
Gemini 4 ve Gemini 3 modellerini kullanırken işlev çağrısı sırasında düşünce imzalarını geri iletmeniz gerekir. Aksi takdirde doğrulama hatası (4xx durum kodu) alırsınız.
Gemini 3 Flash için minimal
düşünme düzeyi ayarını kullanırken de bu geçerlidir.
İşleyiş şekli
Aşağıdaki grafikte, Gemini API'deki işlev çağrısı ile ilgili "sıra" ve "adım" kavramlarının anlamı gösterilmektedir. "Dönüş", kullanıcı ile model arasındaki sohbetteki tek ve eksiksiz bir etkileşimdir. "Adım", model tarafından gerçekleştirilen daha ayrıntılı bir işlem veya operasyondur. Genellikle bir dönüşü tamamlamak için daha büyük bir sürecin parçası olarak gerçekleştirilir.

Bu belgede, Gemini 4 ve Gemini 3 modellerinde işlev çağrısının nasıl işleneceği ele alınmaktadır. 2.5 ile tutarsızlıklar için model davranışı bölümüne bakın.
Gemini 4 ve Gemini 3, işlev çağrısı içeren tüm model yanıtları (API'den gelen yanıtlar) için düşünce imzaları döndürür. Düşünce imzaları aşağıdaki durumlarda gösterilir:
- Paralel işlev çağrıları olduğunda, model yanıtı tarafından döndürülen ilk işlev çağrısı bölümünde düşünce imzası bulunur.
- Ardışık işlev çağrıları (çok adımlı) olduğunda her işlev çağrısının bir imzası olur ve tüm imzaları geri iletmeniz gerekir.
- İşlev çağrısı içermeyen model yanıtları, model tarafından döndürülen son bölümün içinde bir düşünce imzası döndürür.
Aşağıdaki tabloda, sıra ve adım tanımlarını yukarıda açıklanan imza kavramıyla birleştiren çok adımlı işlev çağrılarının görselleştirmesi yer almaktadır:
Sıra |
Step |
Kullanıcı isteği |
Model Yanıtı |
FunctionResponse |
1 |
1 |
request1 = user_prompt |
FC1 + signature |
FR1 |
1 |
2 |
request2 = request1 + (FC1 + signature) + FR1 |
FC2 + signature |
FR2 |
1 |
3 |
request3 = request2 + (FC2 + signature) + FR2 |
text_output
|
Yok |
İşlev çağırma bölümlerindeki imzalar
Gemini bir functionCall oluşturduğunda, aracın çıkışını bir sonraki adımda doğru şekilde işlemek için thought_signature kullanır.
- Davranış:
- Tek İşlev Çağrısı:
functionCallbölümündethought_signatureyer alır. - Paralel fonksiyon çağırma: Model, bir yanıtta paralel fonksiyon çağırma oluşturursa
thought_signatureyalnızca ilkfunctionCallparçaya eklenir. Aynı yanıttaki sonrakifunctionCallbölümlerde imza bulunmaz.
- Tek İşlev Çağrısı:
- Şart: Etkileşim geçmişini geri gönderirken bu imzayı, alındığı kısımla birlikte geri göndermeniz gerekir.
- Doğrulama: Geçerli dönüşteki tüm işlev çağrıları için katı doğrulama uygulanır . (Yalnızca mevcut sıra gereklidir; önceki sıralarda doğrulama yapmayız)
- API, standart içerik (ör.
text) içeren en yeni User mesajını bulmak için geçmişe (en yeni mesajdan en eski mesaja doğru) gider (bu, mevcut dönüşün başlangıcı olur). Bu işlem befunctionResponsedeğildir. - Bu özel kullanım mesajından sonra gerçekleşen tüm model
functionCallsıraları, sıranın bir parçası olarak kabul edilir. - Mevcut dönüşteki her adımda yer alan ilk
functionCallbölümü, içermelidir.thought_signature - Mevcut dönüşün herhangi bir adımında ilk
functionCallbölümü içinthought_signaturekarakterini atlarsanız istek 400 hatasıyla başarısız olur.
- API, standart içerik (ör.
- Doğru imzalar döndürülmezse aşağıdaki hata mesajını alırsınız
- Gemini 3 modelleri: İmzaların eklenmemesi 400 hatasına neden olur. İfade şu şekilde olacaktır:
<index of contents array>içerik bloğundaki<Function Call>işlev çağrısındathought_signatureeksik. Örneğin, Function callFC1in the1.content block is missing athought_signature. ("1.içerik bloğundaki Function callFC1işlevindethought_signatureeksik.")
- Gemini 3 modelleri: İmzaların eklenmemesi 400 hatasına neden olur. İfade şu şekilde olacaktır:
Ardışık fonksiyon çağırma örneği
Bu bölümde, kullanıcının birden fazla görev gerektiren karmaşık bir soru sorduğu birden fazla işlev çağrısı örneği gösterilmektedir.
Kullanıcının birden fazla görev gerektiren karmaşık bir soru sorduğu çok turlu işlev çağrısı örneğini inceleyelim: "Check flight status for AA100 and
book a taxi if delayed".
Dönüş (Turn) |
Step |
Kullanıcı isteği |
Model Yanıtı |
FunctionResponse |
1 |
1 |
request1="Check flight status for AA100 and book a taxi 2 hours before if delayed." |
FC1 ("check_flight") + signature |
FR1 |
1 |
2 |
request2 = request1 + FC1 ("check_flight") + signature + FR1 |
FC2("book_taxi") + signature |
FR2 |
1 |
3 |
request3 = request2 + FC2 ("book_taxi") + signature + FR2 |
text_output
|
None |
Aşağıdaki kod, yukarıdaki tablodaki sırayı gösterir.
1. Sıra, 1. Adım (Kullanıcı isteği)
{
"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"
]
}
}
]
}
]
}
1. tur, 1. adım (Model yanıtı)
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>"
}
]
}
}
1. tur, 2. adım (Kullanıcı yanıtı - Araç çıktılarını gönderme) Bu kullanıcı turunda yalnızca functionResponse olduğu için (yeni metin yok) hâlâ 1. turdayız. <Signature_A> korunmalıdır.
{
"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>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "check_flight",
"response": {
"status": "delayed",
"departure_time": "12 PM"
}
}
}
]
}
1. tur, 2. adım (Model) Model, önceki araç çıkışına göre taksi rezervasyonu yapmaya karar veriyor.
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "book_taxi",
"args": {
"time": "10 AM"
}
},
"thoughtSignature": "<Signature B>"
}
]
}
}
1. Tur, 3. Adım (Kullanıcı - Araç çıkışını gönderme) Taksi rezervasyonu onayını göndermek için bu döngüdeki (<Signature A> + <Signature B>) TÜM işlev çağrılarının imzalarını eklememiz gerekir.
{
"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>" //Required and Validated
}
]
},
{
"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>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "book_taxi",
"response": {
"booking_status": "success"
}
}
}
]
}
}
Paralel fonksiyon çağırma örneği
Kullanıcının "Check weather in Paris and London" sorduğu bir paralel işlev çağırma örneğini inceleyerek modelin doğrulamayı nerede yaptığını görelim.
Sıra |
Step |
Kullanıcı isteği |
Model Yanıtı |
FunctionResponse |
|---|---|---|---|---|
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 ("Paris") + imza FC2 ("Londra") |
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paris") + signature + FC2 ("London") |
text_output (FC yok) |
Yok |
Aşağıdaki kod, yukarıdaki tabloda yer alan sırayı göstermektedir.
1. Sıra, 1. Adım (Kullanıcı isteği)
{
"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"
]
}
}
]
}
]
}
1. Tur, 1. Adım (Model yanıt)
{
"content": {
"parts": [
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"location": "Paris"
}
},
"thoughtSignature": "<Signature_A>"// INCLUDED on First FC
},
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"location": "London"
}// NO signature on subsequent parallel FCs
}
}
]
}
}
1. Dönüş, 2. Adım (Kullanıcı yanıtı - Araç çıktılarını gönderme) İlk bölümdeki <Signature_A>, alındığı şekilde korunmalıdır.
[
{
"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>" // MUST BE INCLUDED
},
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"city": "London"
}
}
} // NO SIGNATURE FIELD
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_temperature",
"response": {
"temp": "15C"
}
}
},
{
"functionResponse": {
"name": "get_current_temperature",
"response": {
"temp": "12C"
}
}
}
]
}
]
functionCall dışındaki bölümlerdeki imzalar
Gemini, işlev çağrısı içermeyen bölümlerde yanıtın son kısmında thought_signatures da döndürebilir.
- Davranış: Model tarafından döndürülen son içerik bölümü (
text, inlineData…) birthought_signatureiçerebilir. - Öneri: Modelin, özellikle karmaşık talimatları takip etme veya simüle edilmiş temsilci iş akışları için yüksek kaliteli akıl yürütme özelliğini korumasını sağlamak amacıyla bu imzaların döndürülmesi önerilir.
- Doğrulama: API, doğrulamayı kesin olarak zorunlu kılmaz. Bunları atlarsanız engelleme hatası almazsınız ancak performans düşebilir.
Metin/Bağlam içi akıl yürütme (Doğrulama yok)
1. Tur, 1. Adım (Model yanıt)
{
"role": "model",
"parts": [
{
"text": "I need to calculate the risk. Let me think step-by-step...",
"thought_signature": "<Signature_C>" // OPTIONAL (Recommended)
}
]
}
2. Sıra, 1. Adım (Kullanıcı)
[
{ "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." }] }
]
OpenAI uyumluluğu için imzalar
Aşağıdaki örneklerde, OpenAI uyumluluğu kullanılarak bir sohbet tamamlama API'si için düşünce imzalarının nasıl işleneceği gösterilmektedir.
Ardışık fonksiyon çağırma örneği
Bu, kullanıcının birden fazla görev gerektiren karmaşık bir soru sorduğu çoklu işlev çağrısı örneğidir.
Kullanıcının soru sorduğu çok adımlı bir işlev çağrısı örneğini inceleyelim.
Check flight status for AA100 and book a taxi if delayed Kullanıcı birden fazla görev gerektiren karmaşık bir soru sorduğunda ne olduğunu görebilirsiniz.
Dönüş (Turn) |
Step |
Kullanıcı isteği |
Model Yanıtı |
FunctionResponse |
1 |
1 |
request1 = "Check flight status for AA100 and book a taxi 2 hours before if delayed." |
FC1 ("check_flight") + signature |
FR1 |
1 |
2 |
request2 = request1 + FC1 ("check_flight") + signature + FR1 |
FC2("book_taxi") + signature |
FR2 |
1 |
3 |
request3 = request2 + FC2 ("book_taxi") + signature + FR2 |
text_output
|
None |
Aşağıdaki kod, verilen sırayı takip eder.
1. Tur, 1. Adım (Kullanıcı İsteği)
{
"model": "google/gemini-4-argon",
"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"
]
}
}
}
]
}
1. Tur, 1. Adım (Model Yanıt)
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>"
}
},
"function": {
"arguments": "{\"flight\":\"AA100\"}",
"name": "check_flight"
},
"id": "function-call-1",
"type": "function"
}
]
}
1. Sıra, 2. Adım (Kullanıcı Yanıtı - Araç Çıkışlarını Gönderme)
Bu kullanıcı sırası yalnızca bir functionResponse içerdiğinden (yeni metin yok), hâlâ 1. sıradayız ve <Signature_A> değerini korumamız gerekiyor.
"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>" //Required and Validated
}
},
"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\"}"
}
]
1. Tur, 2. Adım (Model)
Model, önceki araç çıkışına göre taksi rezervasyonu yapmaya karar verir.
{
"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"
}
]
}
1. Tur, 3. Adım (Kullanıcı - Gönderme Aracı Çıktısı)
Taksi rezervasyonu onayını göndermek için bu döngüdeki TÜM işlev çağrılarının (<Signature A> + <Signature B>) imzalarını eklememiz gerekir.
"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>" //Required and Validated
}
},
"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>" //Required and Validated
}
},
"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\"}"
}
]
Paralel fonksiyon çağırma örneği
Kullanıcının "Check weather in Paris and London" sorduğu bir paralel fonksiyon çağırma örneğini inceleyelim. Modelin doğrulama yaptığı yeri görebilirsiniz.
Dönüş (Turn) |
Step |
Kullanıcı isteği |
Model Yanıtı |
FunctionResponse |
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 ("Paris") + signature
|
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paris") + signature + FC2 ("London") |
text_output
|
None |
Belirtilen sırayı incelemek için kodu aşağıda bulabilirsiniz.
1. Sıra, 1. Adım (Kullanıcı İsteği)
{
"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"
]
}
}
]
}
]
}
1. Tur, 1. Adım (Model Yanıt)
{
"role": "assistant",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Signature returned
}
},
"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" // No signature on Parallel FC
}
]
}
1. Sıra, 2. Adım (Kullanıcı Yanıtı - Araç Çıktılarını Gönderme)
İlk bölümdeki <Signature_A> öğesini, alındığı şekilde korumanız gerekir.
"messages": [
{
"role": "user",
"content": "Check the weather in Paris and London."
},
{
"role": "assistant",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Required
}
},
"function": {
"arguments": "{\"location\":\"Paris\"}",
"name": "get_current_temperature"
},
"id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01",
"type": "function"
},
{
"function": { //No Signature
"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\"}"
}
]
SSS
Geçerli dönüş ve adımda işlev çağrısı bölümü olan farklı bir modeldeki geçmişi Gemini 4 veya Gemini 3'e nasıl aktarabilirim? API tarafından oluşturulmadığı için ilişkili düşünce imzası olmayan işlev çağrısı bölümleri sağlamam gerekiyor mu?
İsteğe özel işlev çağrısı bloklarının isteğe eklenmesi kesinlikle önerilmese de kaçınılmaz olduğu durumlarda (ör. istemci tarafından deterministik olarak yürütülen işlev çağrıları ve yanıtları hakkında modele bilgi sağlama veya düşünce imzaları içermeyen farklı bir modelden izleme aktarma) doğrulamayı atlamak için düşünce imzası alanında
"context_engineering_is_the_way_to_go"veya"skip_thought_signature_validator"değerlerinden oluşan aşağıdaki sahte imzaları ayarlayabilirsiniz.İç içe yerleştirilmiş paralel fonksiyon çağrıları ve yanıtları gönderiyorum ancak API 400 hatası döndürüyor. Neden?
API, "FC1 + imza, FC2" paralel fonksiyon çağrılarını döndürdüğünde beklenen kullanıcı yanıtı "FC1+ imza, FC2, FR1, FR2" olur. Bunları "FC1 + imza, FR1, FC2, FR2" şeklinde sıralarsanız API, 400 hatası döndürür.
Yayın sırasında model, bulamadığım bir işlev çağrısı döndürmediğinde düşünce imzasını bulamıyorum
Akış isteği içeren bir FC içermeyen model yanıtı sırasında, model, düşünce imzasını boş metin içerikli bir bölümde döndürebilir. Model
finish_reasondöndürene kadar tüm isteği ayrıştırmanız önerilir.
Farklı modeller için düşünce imzaları
Gemini 4, Gemini 3 ve Gemini 2.5 modelleri işlev çağrılarında düşünce imzalarıyla farklı şekilde davranır:
- Yanıt içinde işlev çağrıları varsa,
- Gemini 4 ve Gemini 3'te imza her zaman ilk işlev çağrısı bölümünde yer alır. Bu parçanın iade edilmesi zorunludur.
- Gemini 2.5'te imza, ilk bölümde (türden bağımsız olarak) yer alır. Bu parçayı iade etmek isteğe bağlıdır.
- Yanıtta işlev çağrısı yoksa
- Model bir düşünce oluşturursa Gemini 4 ve Gemini 3'ün son bölümünde imza yer alır.
- Gemini 2.5'in hiçbir bölümünde imza bulunmaz.
Daha fazla karşılaştırma ayrıntısı için Düşünme sayfasına bakın. Gemini 3 Image modelleri için Görüntü üretme kılavuzunun düşünme süreci bölümüne bakın.