Podpisy myśli to zaszyfrowane reprezentacje wewnętrznego procesu myślowego modelu. Służą one do zachowania kontekstu rozumowania w interakcjach wieloetapowych.
Gdy używasz modeli myślących (takich jak Gemini 3 i 2.5), interfejs API może
zwracać pole thoughtSignature w częściach odpowiedzi dotyczących treści (np. text lub functionCall).
Ogólnie rzecz biorąc, jeśli otrzymasz podpis myśli w odpowiedzi modelu, w następnym etapie rozmowy musisz go przekazać dokładnie w takiej postaci, w jakiej został otrzymany, podczas wysyłania historii rozmowy.
Gdy używasz modeli Gemini 3, musisz przekazywać podpisy myśli podczas wywoływania funkcji. W przeciwnym razie otrzymasz błąd weryfikacji (kod stanu 4xx).
Dotyczy to również sytuacji, gdy używasz ustawienia minimal
poziomu myślenia w przypadku Gemini 3
Flash.
Jak to działa
Poniższy diagram ilustruje znaczenie słów „etap” i „krok” w kontekście wywoływania funkcji w interfejsie Gemini API. „Etap” 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 mającego na celu ukończenie etapu.

Ten dokument koncentruje się na obsłudze wywoływania funkcji w przypadku modeli Gemini 3. Więcej informacji o różnicach w przypadku modelu 2.5 znajdziesz w sekcji Zachowanie modelu.
Gemini 3 zwraca podpisy myśli we wszystkich odpowiedziach modelu (odpowiedziach z interfejsu API) z wywołaniem funkcji. Podpisy myśli pojawiają się w tych przypadkach:
- Gdy występują równoległe wywołania funkcji, pierwsza część wywołania funkcji zwrócona przez odpowiedź modelu będzie zawierać podpis myśli.
- Gdy występują sekwencyjne wywołania funkcji (wieloetapowe), każde wywołanie funkcji będzie miało podpis i musisz przekazać wszystkie podpisy.
- Odpowiedzi modelu bez wywołania funkcji będą zawierać podpis myśli w ostatniej części zwróconej przez model.
W tabeli poniżej przedstawiono wizualizację wieloetapowych wywołań funkcji, łącząc definicje etapów i kroków z koncepcją podpisów wprowadzoną powyżej:
Etap |
Krok |
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, w następnym etapie rozmowy korzysta z thought_signature, aby prawidłowo przetworzyć dane wyjściowe narzędzia.
- Zachowanie:
- Pojedyncze wywołanie funkcji: część
functionCallbędzie zawieraćthought_signature. - Równoległe wywołania funkcji: jeśli model wygeneruje w odpowiedzi równoległe wywołania funkcji,
thought_signaturezostanie dołączony tylko do pierwszejfunctionCallczęści. Kolejne częścifunctionCallw tej samej odpowiedzi nie będą zawierać podpisu.
- Pojedyncze wywołanie funkcji: część
- Wymaganie: podczas wysyłania historii rozmowy musisz zwrócić ten podpis w dokładnie tej części, w której został otrzymany.
- Weryfikacja: w przypadku wszystkich wywołań funkcji w bieżącym etapie rozmowy obowiązuje ścisła weryfikacja . (Wymagany jest tylko bieżący etap rozmowy. Nie weryfikujemy poprzednich etapów).
- Interfejs API cofa się w historii (od najnowszej do najstarszej), aby znaleźć najnowszą wiadomość użytkownika zawierającą standardową treść (np.
text) ( czyli początek bieżącego etapu rozmowy). Nie be tofunctionResponse. - Wszystkie etapy
functionCallmodelu występujące po tej konkretnej wiadomości użytkownika są uważane za część etapu. - Pierwsza część
functionCallw każdym kroku bieżącego etapu rozmowy musi zawierać swójthought_signature. - Jeśli pominiesz
thought_signaturew pierwszej częścifunctionCallw dowolnym kroku bieżącego etapu rozmowy, żądanie zakończy się niepowodzeniem z błędem 400.
- Interfejs API cofa się w historii (od najnowszej do najstarszej), aby znaleźć najnowszą wiadomość użytkownika zawierającą standardową treść (np.
- Jeśli nie zostaną zwrócone prawidłowe podpisy, wystąpi błąd:
- Modele Gemini 3: brak podpisów spowoduje błąd 400. Komunikat będzie miał postać:
- Wywołanie funkcji
<Function Call>w bloku treści<index of contents array>nie zawierathought_signature. Na przykład Wywołanie funkcjiFC1w bloku treści1.nie zawierathought_signature.
- Wywołanie funkcji
- Modele Gemini 3: brak podpisów spowoduje błąd 400. Komunikat będzie miał postać:
Przykład sekwencyjnego wywoływania funkcji
Ta sekcja zawiera przykład wielu 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 ramach wielu etapów rozmowy, 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".
Etap |
Krok |
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.
Etap 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"
]
}
}
]
}
]
}
Etap 1, krok 1 (odpowiedź modelu)
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>"
}
]
}
}
Etap 1, krok 2 (odpowiedź użytkownika – wysyłanie danych wyjściowych narzędzia) Ponieważ ten etap rozmowy użytkownika zawiera tylko functionResponse (bez nowego tekstu), nadal jesteśmy na etapie 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"
}
}
}
]
}
Etap 1, krok 2 (model) Model decyduje teraz o zamówieniu taksówki na podstawie poprzednich danych wyjściowych narzędzia.
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "book_taxi",
"args": {
"time": "10 AM"
}
},
"thoughtSignature": "<Signature B>"
}
]
}
}
Etap 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 równoległego wywoływania funkcji
Przyjrzyjmy się przykładowi równoległego wywoływania funkcji, w którym użytkownik pyta
"Check weather in Paris and London" aby zobaczyć, gdzie model przeprowadza weryfikację.
Etap |
Krok |
Prośba użytkownika |
Odpowiedź modelu |
FunctionResponse |
|---|---|---|---|---|
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 ("Paris") + signature FC2 ("London") |
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paris") + signature + FC2 ("London") |
text_output (no FCs) |
Brak |
Poniższy kod ilustruje sekwencję z tabeli powyżej.
Etap 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"
]
}
}
]
}
]
}
Etap 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
}
}
]
}
}
Etap 1, krok 2 (odpowiedź użytkownika – wysyłanie danych wyjściowych narzędzia) Musimy zachować
<Signature_A> w pierwszej części dokładnie w takiej postaci, w jakiej 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 częściach innych niż wywołanie funkcji.
- Zachowanie: ostatnia część treści (
text, inlineData…) zwrócona przez model może zawieraćthought_signature. - Zalecenie: zwracanie tych podpisów jest zalecane , aby zapewnić modelowi wysoką jakość rozumowania, zwłaszcza w przypadku złożonych instrukcji lub symulowanych przepływów pracy agenta.
- Weryfikacja: interfejs API nie wymusza ścisłej weryfikacji. Jeśli je pominiesz, nie otrzymasz błędu blokującego, ale wydajność może się pogorszyć.
Tekst/rozumowanie w kontekście (bez weryfikacji)
Etap 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)
}
]
}
Etap 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." }] }
]
Podpisy zapewniające zgodność z OpenAI
Poniższe przykłady pokazują, jak obsługiwać podpisy myśli w interfejsie Chat Completion API przy użyciu zgodności z OpenAI.
Przykład sekwencyjnego wywoływania funkcji
To jest przykład wielu 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 ramach wielu etapów rozmowy, w którym użytkownik pyta
Check flight status for AA100 and book a taxi if delayed Możesz zobaczyć, co
się stanie, gdy użytkownik zada złożone pytanie wymagające wykonania kilku zadań.
Etap |
Krok |
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 daną sekwencję.
Etap 1, krok 1 (prośba użytkownika)
{
"model": "google/gemini-3.1-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"
]
}
}
}
]
}
Etap 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"
}
]
}
Etap 1, krok 2 (odpowiedź użytkownika – wysyłanie danych wyjściowych narzędzia)
Ponieważ ten etap rozmowy użytkownika zawiera tylko functionResponse (bez nowego tekstu), nadal jesteśmy
na etapie 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\"}"
}
]
Etap 1, krok 2 (model)
Model decyduje teraz o zamówieniu taksówki na podstawie poprzednich danych wyjściowych 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"
}
]
}
Etap 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>).
"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 równoległego wywoływania funkcji
Przyjrzyjmy się przykładowi równoległego wywoływania funkcji, w którym użytkownik pyta
"Check weather in Paris and London" aby zobaczyć, gdzie model przeprowadza
weryfikację.
Etap |
Krok |
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 przedstawia daną sekwencję.
Etap 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"
]
}
}
]
}
]
}
Etap 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
}
]
}
Etap 1, krok 2 (odpowiedź użytkownika – wysyłanie danych wyjściowych narzędzia)
Musisz zachować <Signature_A> w pierwszej części dokładnie w takiej postaci, 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 z częścią wywołania funkcji w bieżącym etapie rozmowy i kroku? 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.W przypadkach, gdy nie można tego uniknąć, np. gdy trzeba przekazać informacje modelowi o wywołaniach funkcji i odpowiedziach, które zostały wykonane deterministycznie przez klienta, lub gdy trzeba przenieść ślad z innego modelu, który nie zawiera podpisów myśli, możesz ustawić w polu podpisu myśli te podpisy 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 błąd 400. Dlaczego?
Gdy interfejs API zwraca równoległe wywołania funkcji „FC1 + signature, FC2”, oczekiwana odpowiedź użytkownika to „FC1 + signature, FC2, FR1, FR2”. Jeśli przeplatasz je jako „FC1 + signature, FR1, FC2, FR2”, interfejs API zwróci błąd 400.
Podczas przesyłania strumieniowego, gdy model nie zwraca wywołania funkcji, nie mogę znaleźć podpisu myśli
Podczas odpowiedzi modelu, która nie zawiera wywołania funkcji z żądaniem przesyłania strumieniowego, model może zwrócić podpis myśli w części z pustą częścią treści tekstowej. Zalecamy analizowanie całego żądania, dopóki model nie zwróci
finish_reason.
Podpisy myśli w przypadku różnych modeli
Modele Gemini 3 i modele Gemini 2.5 różnią się zachowaniem w przypadku podpisów myśli w wywołaniach funkcji:
- Jeśli w odpowiedzi znajdują się wywołania funkcji:
- Gemini 3 zawsze będzie mieć podpis w pierwszej części wywołania funkcji. Obowiązkowe jest zwrócenie tej części.
- Gemini 2.5 będzie mieć podpis w pierwszej części (niezależnie od typu). Zwrócenie tej części jest opcjonalne.
- Jeśli w odpowiedzi nie ma wywołań funkcji:
- Gemini 3 będzie mieć podpis w ostatniej części, jeśli model wygeneruje myśl.
- Gemini 2.5 nie będzie mieć podpisu w żadnej części.
Więcej informacji o porównaniu znajdziesz na stronie Myślenie. W przypadku modeli Gemini 3 Image zapoznaj się z sekcją Proces myślowy w przewodniku po generowaniu obrazów.