Düşünce imzaları, modelin dahili düşünce sürecinin şifrelenmiş temsilleridir ve çok turlu etkileşimlerde akıl yürütme bağlamını korumak için kullanılır.
Düşünme modelleri (ör.Gemini 3 ve 2.5 serisi) kullanılırken API, yanıtın content_parts bölümünde thoughtSignature alanı döndürebilir (ör. text veya functionCall bölümler).
Genel bir kural olarak, model yanıtında düşünce imzası alırsanız konuşma geçmişini bir sonraki turda gönderirken bu imzayı aynen iletmeniz gerekir. Gemini 3 Pro'yu 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.
İşleyiş şekli
Aşağıdaki grafik, Gemini API'deki işlev çağrısı ile ilgili olarak "dönüş" ve "adım"ın anlamını görselleştirir. "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 3 Pro için işlev çağrısının nasıl işleneceği açıklanmaktadır. 2.5 ile ilgili tutarsızlıklar için model davranışı bölümüne bakın.
Gemini 3 Pro, 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.
- Sıralı 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ı, modelin döndürdüğü son kısımda bir düşünce imzası döndürür.
Aşağıdaki tabloda, yukarıda bahsedilen imzalar kavramıyla birlikte dönüş ve adım tanımlarını birleştiren çok adımlı işlev çağrıları için bir görselleştirme sunulmaktadır:
Dönüş (Turn) |
Step |
Kullanıcı İsteği (User Request) |
Model Response (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ğrısı bölümlerindeki imzalar
Gemini, functionCall oluşturduğunda bir sonraki turda aracın çıkışını doğru şekilde işlemek için thought_signature kullanır.
- Davranış:
- Tek İşlev Çağrısı:
functionCallbölümüthought_signatureiçerecektir. - Paralel İşlev Çağrıları: Model, yanıtta paralel işlev çağrıları oluşturursa
thought_signatureyalnızca ilkfunctionCallbölüme eklenir. Aynı yanıttaki sonrakifunctionCallbölümleri imza içermez.
- Tek İşlev Çağrısı:
- Şart: Görüşme geçmişini geri gönderirken bu imzayı, alındığı kısımla birlikte döndürmeniz 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 dönüş gereklidir; önceki dönüşler doğrulanmaz)
- API, standart içerik (ör.
text) ( bu, mevcut sıranın başlangıcı olur). Bu işlem befunctionResponsedeğildir. - Bu belirli kullanım mesajından sonraki tüm model
functionCalldönüşleri, dönüşün bir parçası olarak kabul edilir. - Mevcut dönüşteki her adımda yer alan ilk
functionCallbölümü,thought_signatureiçermelidir. - 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.
- Uygun imzalar döndürülmezse hata nasıl oluşur?
gemini-3-pro-preview: İmzaların eklenmemesi 400 hatasına neden olur. İfade şu biçimde olacaktır:<index of contents array>içerik bloğundaki<Function Call>işlev çağrısındathought_signatureeksik. Örneğin,1.içerik bloğundaki Function callFC1ifadesindethought_signatureeksik.
Sıralı işlev çağrısı ö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 bir 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ı İsteği (User Request) |
Model Response (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. Tur, 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ı turu yalnızca functionResponse içerdiğinden (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ç çıktısı gönderme) Taksi rezervasyonu onayını göndermek için bu döngüdeki TÜM işlev çağrılarına (<Signature A> + <Signature B>) imza 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 işlev çağrısı örneği
Kullanıcının modele doğrulama yaptığı yeri görmeyi istediği paralel işlev çağrısı örneğini inceleyelim.
"Check weather in Paris and London"
Dönüş (Turn) |
Step |
Kullanıcı İsteği (User Request) |
Model Response (Model Yanıtı) |
FunctionResponse |
|---|---|---|---|---|
1 |
1 |
request1="Paris ve Londra'daki hava durumunu kontrol et" |
FC1 ("Paris") + imza FC2 ("London") |
FR1 |
1 |
2 |
istek 2 = istek1 + FC1 ("Paris") + imza + FC2 ("London") |
text_output (FC yok) |
Yok |
Aşağıdaki kod, yukarıdaki tablodaki sırayı gösterir.
1. Tur, 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. Tur, 2. Adım (Kullanıcı yanıtı - Araç çıktılarını gönderme) İlk bölümdeki <Signature_A> karakterini olduğu gibi korumalıyız.
[
{
"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…)thought_signatureiçerebilir. - Öneri: Özellikle karmaşık talimatları takip etme veya simüle edilmiş aracı iş akışları için modelin 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ı katı bir şekilde zorunlu kılmaz. Bu alanları atladığınızda 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. Tur, 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.
Sıralı işlev çağrısı ö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 Check flight status for AA100 and book a taxi if delayed diye sorduğu çok turlu bir işlev çağrısı örneğini inceleyelim. Kullanıcı, birden fazla görev gerektiren karmaşık bir soru sorduğunda ne olduğunu görebilirsiniz.
Dönüş (Turn) |
Step |
Kullanıcı İsteği (User Request) |
Model Response (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 |
Aşağıdaki kod, verilen sırayı adım adım açıklar.
1. Tur, 1. Adım (Kullanıcı İsteği)
{
"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"
]
}
}
}
]
}
1. Dönüş, 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. Tur, 2. Adım (Kullanıcı Yanıtı - Araç Çıkışlarını Gönderme)
Bu kullanıcı dönüşü yalnızca functionResponse içerdiğinden (yeni metin yok) hâlâ 1. dönüşteyiz ve <Signature_A> korunmalıdır.
"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 veriyor.
{
"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ı - Araç Çıktısı Gönderme)
Taksi rezervasyonu onayını göndermek için bu döngüdeki TÜM işlev çağrıları (<Signature A> + <Signature B>) için imzalar 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 işlev çağrısı örneği
Kullanıcının "Check weather in Paris and London" diye sorduğu paralel işlev çağırma örneğini inceleyelim. Modelin nerede doğrulama yaptığını görebilirsiniz.
Dönüş (Turn) |
Step |
Kullanıcı İsteği (User Request) |
Model Response (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ı izlemek için gereken kod aşağıda verilmiştir.
1. Tur, 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. Dönüş, 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. Tur, 2. Adım (Kullanıcı Yanıtı - Araç Çıkışlarını Gönderme)
İlk bölümdeki <Signature_A> işaretini tam olarak alındığı şekilde korumalısınız.
"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 Gemini 3 Pro'ya farklı bir modelden geçmişi 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 önerilmez.Ancak bu durumun 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ğrulamanın atlanması 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 geçmiş paralel işlev çağrıları ve yanıtları geri gönderiyorum ve API 400 döndürüyor. Neden?
API, paralel işlev çağrıları "FC1 + imza, FC2" döndürdüğünde, beklenen kullanıcı yanıtı "FC1+ imza, FC2, FR1, FR2" olur. Bunları "FC1 + imza, FR1, FC2, FR2" şeklinde iç içe yerleştirirseniz 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ğiyle FC içermeyen bir model yanıtı sırasında model, düşünce imzasını boş metin içerikli bir bölümde döndürebilir. Model tarafından
finish_reasondöndürülene kadar isteğin tamamını ayrıştırmanız önerilir.
Model serisine göre düşünce imzası davranışı
Gemini 3 Pro 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 3 Pro, her zaman ilk işlev çağrısı bölümünde imzaya sahip olur. Bu parçanın iade edilmesi zorunludur.
- Gemini 2.5, ilk bölümde imzayı (türden bağımsız olarak) içerir. Bu parçayı iade etmek isteğe bağlıdır.
- Yanıt içinde işlev çağrısı yoksa,
- Model bir düşünce ürettiğinde Gemini 3 Pro, son kısımda imzayı gösterir.
- Gemini 2.5'in hiçbir bölümünde imza bulunmaz.
Gemini 2.5 modellerinde düşünme imzası davranışı için Düşünme sayfasına bakın.