Podpisy myśli to zaszyfrowane reprezentacje wewnętrznego procesu myślowego modelu. Służą one do zachowania kontekstu rozumowania w interakcjach wieloetapowych.
W przypadku korzystania z modeli myślenia (takich jak Gemini 3 i 2.5) interfejs API może zwracać pole thoughtSignature w częściach treści odpowiedzi (np. text lub functionCall).
Ogólnie rzecz biorąc, jeśli w odpowiedzi modelu otrzymasz sygnaturę myśli, w następnej turze rozmowy prześlij ją z powrotem w niezmienionej postaci wraz z historią rozmowy. Podczas korzystania z Gemini 3 Pro musisz przekazywać sygnatury myśli podczas wywoływania funkcji, w przeciwnym razie otrzymasz błąd weryfikacji (kod stanu 4xx).
Jak to działa
Ilustracja poniżej przedstawia znaczenie terminów „tura” i „krok” w kontekście wywoływania funkcji w interfejsie Gemini API. „Tura” to pojedyncza, pełna wymiana informacji w rozmowie między użytkownikiem a modelem. „Krok” to bardziej szczegółowe działanie lub operacja wykonywana przez model, często w ramach większego procesu, który ma na celu ukończenie tury.

Ten dokument dotyczy obsługi wywoływania funkcji w przypadku Gemini 3 Pro. Więcej informacji o różnicach w stosunku do wersji 2.5 znajdziesz w sekcji zachowanie modelu.
Gemini 3 Pro zwraca sygnatury myśli dla wszystkich odpowiedzi modelu (odpowiedzi z interfejsu API) z wywołaniem funkcji. Podpisy myśli pojawiają się w tych przypadkach:
- W przypadku równoległych wywołań funkcji pierwsza część wywołania funkcji zwrócona przez odpowiedź modelu będzie zawierać sygnaturę myśli.
- W przypadku sekwencyjnych wywołań funkcji (wielokrokowych) każde wywołanie funkcji będzie miało sygnaturę i musisz przekazać wszystkie sygnatury z powrotem.
- Odpowiedzi modelu bez wywołania funkcji będą zawierać sygnaturę myśli w ostatniej części zwróconej przez model.
Tabela poniżej przedstawia wizualizację wieloetapowych wywołań funkcji, łącząc definicje tur i etapów z wprowadzonym powyżej pojęciem sygnatur:
Obrót |
Step |
Prośba użytkownika |
Odpowiedź modelu |
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
|
Brak |
Podpisy w częściach wywoływania funkcji
Gdy Gemini generuje functionCall, korzysta z thought_signature, aby w kolejnym kroku prawidłowo przetworzyć dane wyjściowe narzędzia.
- Zachowanie:
- Wywołanie pojedynczej funkcji: część
functionCallbędzie zawieraćthought_signature. - Równoległe wywołania funkcji: jeśli model generuje w odpowiedzi równoległe wywołania funkcji, symbol
thought_signaturejest dołączany tylko do pierwszej części.functionCallKolejne części w tej samej odpowiedzifunctionCallnie będą zawierać podpisu.
- Wywołanie pojedynczej funkcji: część
- Wymaganie: podczas odsyłania historii rozmowy musisz zwrócić ten podpis w dokładnie tym samym miejscu, w którym został otrzymany.
- Weryfikacja: w przypadku wszystkich wywołań funkcji w bieżącej turze obowiązuje ścisła weryfikacja . (Wymagana jest tylko bieżąca tura. Nie sprawdzamy poprzednich tur).
- API cofa się w historii (od najnowszej do najstarszej), aby znaleźć najnowszą wiadomość użytkownika zawierającą standardowe treści (np.
text) ( czyli początek bieżącej tury). Nie będzie to befunctionResponse. - Wszystkie odpowiedzi modelu
functionCall, które pojawią się po tym konkretnym komunikacie o użyciu, są traktowane jako część odpowiedzi. - Pierwsza część
functionCallw każdym kroku bieżącej tury musi zawieraćthought_signature. - Jeśli w pierwszej części
functionCallw dowolnym kroku bieżącej tury pominieszthought_signature, żądanie zakończy się niepowodzeniem i zostanie zwrócony błąd 400.
- API cofa się w historii (od najnowszej do najstarszej), aby znaleźć najnowszą wiadomość użytkownika zawierającą standardowe treści (np.
- Jeśli prawidłowe podpisy nie zostaną zwrócone, wystąpi błąd w ten sposób:
gemini-3-pro-preview: Brak podpisów spowoduje błąd 400. Tekst będzie miał postać:- W wywołaniu funkcji
<Function Call>w bloku treści<index of contents array>brakuje elementuthought_signature. Na przykład w bloku treści1.brakujethought_signaturew wywołaniu funkcjiFC1.
- W wywołaniu funkcji
Przykład sekwencyjnego wywoływania funkcji
W tej sekcji znajdziesz przykład kilku wywołań funkcji, w których użytkownik zadaje złożone pytanie wymagające wykonania kilku zadań.
Przyjrzyjmy się przykładowi wywoływania funkcji w wielu turach, w którym użytkownik zadaje złożone pytanie wymagające wykonania kilku zadań: "Check flight status for AA100 and
book a taxi if delayed".
Obrót |
Step |
Prośba użytkownika |
Odpowiedź modelu |
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 |
Poniższy kod ilustruje sekwencję z tabeli powyżej.
Tura 1, krok 1 (prośba użytkownika)
{
"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"
]
}
}
]
}
]
}
Tura 1, krok 1 (odpowiedź modelu)
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>"
}
]
}
}
Tura 1, krok 2 (odpowiedź użytkownika – wysyłanie wyników narzędzia): ponieważ ta tura użytkownika zawiera tylko functionResponse (bez nowego tekstu), nadal jesteśmy w turze 1. Musimy zachować <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>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "check_flight",
"response": {
"status": "delayed",
"departure_time": "12 PM"
}
}
}
]
}
Tura 1, krok 2 (model): model decyduje teraz o zamówieniu taksówki na podstawie poprzedniego wyniku narzędzia.
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "book_taxi",
"args": {
"time": "10 AM"
}
},
"thoughtSignature": "<Signature B>"
}
]
}
}
Tura 1, krok 3 (Użytkownik – wysyłanie danych wyjściowych narzędzia) Aby wysłać potwierdzenie rezerwacji taksówki, musimy uwzględnić podpisy WSZYSTKICH wywołań funkcji w tej pętli (<Signature A> + <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>" //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"
}
}
}
]
}
}
Przykład wywoływania funkcji równoległych
Przyjrzyjmy się przykładowi równoległego wywoływania funkcji, w którym użytkownik prosi"Check weather in Paris and London" o wyświetlenie miejsca, w którym model przeprowadza weryfikację.
Obrót |
Step |
Prośba użytkownika |
Odpowiedź modelu |
FunctionResponse |
|---|---|---|---|---|
1 |
1 |
request1="Sprawdź pogodę w Paryżu i Londynie" |
FC1 („Paryż”) + podpis FC2 („Londyn”) |
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paryż") + podpis + FC2 ("Londyn") |
text_output (brak FC) |
Brak |
Poniższy kod ilustruje sekwencję z tabeli powyżej.
Tura 1, krok 1 (prośba użytkownika)
{
"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"
]
}
}
]
}
]
}
Tura 1, krok 1 (odpowiedź modelu)
{
"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
}
}
]
}
}
Tura 1, krok 2 (odpowiedź użytkownika – wysyłanie wyników narzędzia) Musimy zachować
<Signature_A> pierwszą część dokładnie tak, jak została otrzymana.
[
{
"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"
}
}
}
]
}
]
Podpisy w częściach innych niż functionCall
Gemini może też zwracać thought_signatures w ostatniej części odpowiedzi w przypadku części niebędących wywołaniami funkcji.
- Zachowanie: ostatnia część treści (
text, inlineData…) zwrócona przez model może zawieraćthought_signature. - Rekomendacja: zwracanie tych sygnatur jest zalecane, aby zapewnić wysoką jakość rozumowania modelu, zwłaszcza w przypadku złożonych instrukcji lub symulowanych przepływów pracy agenta.
- Weryfikacja: interfejs API nie wymusza weryfikacji. Jeśli je pominiesz, nie otrzymasz błędu blokującego, ale wydajność może się pogorszyć.
Tekst/wnioskowanie w kontekście (bez weryfikacji)
Tura 1, krok 1 (odpowiedź modelu)
{
"role": "model",
"parts": [
{
"text": "I need to calculate the risk. Let me think step-by-step...",
"thought_signature": "<Signature_C>" // OPTIONAL (Recommended)
}
]
}
Tura 2, krok 1 (użytkownik)
[
{ "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." }] }
]
Sygnatury zgodne z OpenAI
Poniższy przykład pokazuje, jak obsługiwać sygnatury myśli w interfejsie API do uzupełniania czatu za pomocą zgodności z OpenAI.
Przykład sekwencyjnego wywoływania funkcji
To przykład wywoływania wielu funkcji, w którym użytkownik zadaje złożone pytanie wymagające wykonania kilku zadań.
Przyjrzyjmy się przykładowi wywoływania funkcji w wielu turach, w którym użytkownik zadaje pytanieCheck flight status for AA100 and book a taxi if delayed. Zobaczysz, co się stanie, gdy użytkownik zada złożone pytanie wymagające wykonania wielu zadań.
Obrót |
Step |
Prośba użytkownika |
Odpowiedź modelu |
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 |
Poniższy kod przedstawia podaną sekwencję.
Tura 1, krok 1 (prośba użytkownika)
{
"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"
]
}
}
}
]
}
Tura 1, krok 1 (odpowiedź modelu)
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>"
}
},
"function": {
"arguments": "{\"flight\":\"AA100\"}",
"name": "check_flight"
},
"id": "function-call-1",
"type": "function"
}
]
}
Tura 1, krok 2 (odpowiedź użytkownika – wysyłanie wyników narzędzi)
Ponieważ ta tura użytkownika zawiera tylko functionResponse (bez nowego tekstu), nadal jesteśmy w turze 1 i musimy zachować <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>" //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\"}"
}
]
Tura 1, krok 2 (model)
Model decyduje teraz o zamówieniu taksówki na podstawie poprzedniego wyniku narzędzia.
{
"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"
}
]
}
Tura 1, krok 3 (użytkownik – wysyłanie wyniku narzędzia)
Aby wysłać potwierdzenie rezerwacji taksówki, musimy uwzględnić podpisy wszystkich wywołań funkcji w tej pętli (<Signature A> + <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>" //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\"}"
}
]
Przykład wywoływania funkcji równoległych
Przyjrzyjmy się przykładowi równoległego wywoływania funkcji, w którym użytkownik zadaje pytanie "Check weather in Paris and London", a Ty możesz zobaczyć, gdzie model przeprowadza weryfikację.
Obrót |
Step |
Prośba użytkownika |
Odpowiedź modelu |
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 |
Oto kod, który umożliwia przejście podanej sekwencji.
Tura 1, krok 1 (prośba użytkownika)
{
"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"
]
}
}
]
}
]
}
Tura 1, krok 1 (odpowiedź modelu)
{
"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
}
]
}
Tura 1, krok 2 (odpowiedź użytkownika – wysyłanie wyników narzędzi)
W pierwszej części musisz zachować <Signature_A> w dokładnie takiej formie, w jakiej została otrzymana.
"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\"}"
}
]
Najczęstsze pytania
Jak przenieść historię z innego modelu do Gemini 3 Pro, gdy w bieżącej turze i kroku występuje wywołanie funkcji? Muszę podać części wywołania funkcji, które nie zostały wygenerowane przez interfejs API, a więc nie mają powiązanego podpisu myśli?
Wstrzykiwanie niestandardowych bloków wywołań funkcji do żądania jest zdecydowanie odradzane.Jeśli jednak nie można tego uniknąć, np. w przypadku przekazywania do modelu informacji o wywołaniach funkcji i odpowiedziach, które zostały wykonane deterministycznie przez klienta, lub przenoszenia śladu z innego modelu, który nie zawiera sygnatur myśli, możesz ustawić w polu sygnatury myśli te sygnatury zastępcze:
"context_engineering_is_the_way_to_go"lub"skip_thought_signature_validator", aby pominąć weryfikację.Wysyłam przeplatane równoległe wywołania funkcji i odpowiedzi, a interfejs API zwraca kod 400. Dlaczego?
Gdy interfejs API zwraca równoległe wywołania funkcji „FC1 + podpis, FC2”, oczekiwana odpowiedź użytkownika to „FC1 + podpis, FC2, FR1, FR2”. Jeśli są one przeplatane w formacie „FC1 + podpis, FR1, FC2, FR2”, interfejs API zwróci błąd 400.
Podczas przesyłania strumieniowego i gdy model nie zwraca wywołania funkcji, nie mogę znaleźć podpisu myśli
Podczas odpowiedzi modelu niezawierającej funkcji FC z żądaniem przesyłania strumieniowego model może zwrócić sygnaturę myśli w części z pustą treścią tekstową. Zalecamy przeanalizowanie całego żądania, dopóki model nie zwróci znaku
finish_reason.
Zachowanie sygnatury myśli według serii modeli
Modele Gemini 3 Pro i Gemini 2.5 różnią się w przypadku sygnatur myśli w wywołaniach funkcji:
- Jeśli w odpowiedzi znajdują się wywołania funkcji:
- Gemini 3 Pro zawsze będzie zawierać sygnaturę w pierwszej części wywołania funkcji. Zwrot tej części jest obowiązkowy.
- Gemini 2.5 będzie umieszczać sygnaturę w pierwszej części (niezależnie od typu). Zwrot tej części jest opcjonalny.
- Jeśli w odpowiedzi nie ma wywołań funkcji,
- Gemini 3 Pro będzie zawierać podpis w ostatniej części, jeśli model wygeneruje myśl.
- Gemini 2.5 nie będzie zawierać podpisu w żadnej części.
Informacje o zachowaniu sygnatury myśli w przypadku modeli Gemini 2.5 znajdziesz na stronie Myślenie.