Samouczek API Gemini 3.8 Flash: poziomy rozumowania, ekstrakcja PDF i wywoływanie funkcji w Pythonie

Czym jest Gemini 3.8 Flash?

Gemini 3.8 Flash to model roboczy Google, ogólnodostępny od 2 września 2026 r., pod identyfikatorem gemini-3.8-flash. Pojawił się 3 tygodnie po 3.7 Flash, a Google pozycjonuje go do długohoryzontalnego kodowania, agentowych workflowów i wieloetapowego rozumowania w wyspecjalizowanych domenach, jak finanse i prawo.

Specyfikacje istotne dla wywołań API nie zmieniły się względem 3.7: 

• okno kontekstu 1M tokenów
• maks. 64k tokenów wyjściowych
• wejście multimodalne (tekst, obrazy, wideo, audio, PDF) z wyjściem tekstowym
• Ta sama cena wprowadzająca $0,75 za 1M tokenów wejścia i $3,75 za 1M tokenów wyjścia do 31 grudnia 2026 r. (od 1 stycznia 2027 r. wzrost do $1,50 i $7,50)

Zmieniło się zachowanie, nie interfejs: Google mówi, że 3.8 mocniej pracuje nad złożonymi zadaniami, wykonując dodatkowe kroki rozumowania i iteracyjnie wywołując narzędzia, co może podnieść użycie tokenów na wyższych poziomach wysiłku. 3.7 Flash pozostaje w pełni wspierany dla obciążeń, gdzie efektywność liczy się bardziej niż głębokość.

Po benchmarki i szczegółowe ceny zajrzyj do naszego przewodnika po Gemini 3.8 Flash, albo przeczytaj przewodnik Czym jest Google Gemini? dla przeglądu platformy.

Gemini 3.8 Flash vs. 3.8 Flash Cyber

Premiera obejmuje 2 warianty i tylko 1 z nich ma identyfikator modelu, który możesz wpisać. 

• Gemini 3.8 Flash to model ogólny, dostępny dziś w Google AI Studio i Gemini API. 
• Gemini 3.8 Flash Cyber to wariant cyberbezpieczeństwa dostrojony do wykrywania podatności i automatycznego patchowania.

Wariant Cyber nie jest dostępny w publicznym API: dostęp odbywa się przez Fairwind Program Google, który jest ograniczony do zatwierdzonych organów rządowych, operatorów infrastruktury krytycznej i maintainerów oprogramowania.

Jeśli śledzisz ten tutorial, twój identyfikator modelu to gemini-3.8-flash. Nic poniżej nie wymaga ani nie używa wariantu Cyber.

Interactions API vs. generateContent

Aby wywołać Gemini 3.8 Flash, użyj client.interactions.create() w SDK google-genai. Google udostępniło Interactions API w GA w czerwcu 2026 i rekomenduje je do wszelkich nowych prac. Choć generateContent wciąż działa, jest już przestarzałe. Nowe funkcje, jak historia po stronie serwera, wykonywanie w tle i obserwowalne kroki wykonania trafiają najpierw do Interactions.

Największa praktyczna zmiana to zarządzanie stanem. Wywołania wieloturowe używają teraz serwerowego previous_interaction_id: przekazujesz ID ostatniej interakcji, a serwer odtwarza stan. Nie musisz już ręcznie dopinać ani ponownie wysyłać całej historii czatu z klienta. Unikaj też wstępnego wypełniania tur modelu; to stary wzorzec generateContent i zepsuje się na Gemini 3.x.

Jest jedna rzecz, która łapie prawie każdego i wróci przy PDF: previous_interaction_id odtwarza historię rozmowy i nic więcej. tools, system_instruction, generation_config i response_format są ograniczone do interakcji, więc każda tura, która ich potrzebuje, musi je podać ponownie.

thinking_level zastępuje pokrętła próbkowania

W starszych modelach Gemini deweloperzy używali temperature, top_p i top_k, aby kontrolować losowość wyjścia. Gemini 3.x porzuca te pokrętła próbkowania i zastępuje je thinking_level, które jest teraz jedynym regulatorem.

Akceptuje 3 wartości:

• low: najmniej tokenów rozumowania, najszybciej i najtaniej. Pasuje do ekstrakcji, klasyfikacji i wszystkiego, co sam sprawdzisz.

• medium: domyślne i rekomendowane przez Google do kodu i pracy agentów.

• high: największy budżet rozumowania, do twardej logiki wieloetapowej i zadań mocno narzędziowych.

Nie wysyłaj minimal. Jest nieprawidłowe od Gemini Flash 3.7 i zwraca błąd walidacji 400. 

Jeszcze jedna reguła przeniesiona z 3.7: frequency_penalty, presence_penalty i candidate_count teraz rzucają aktywny błąd API, więc usuń je także ze starych konfiguracji.

Jak skonfigurować API Gemini 3.8 Flash?

Konfiguracja środowiska zajmuje około 2 minuty. Potrzebujesz klucza API z Google AI Studio i zaktualizowanej biblioteki Pythona google-genai.

Zdobądź klucz API z Google AI Studio

Wejdź do Google AI Studio w przeglądarce i zaloguj się kontem Google. Kliknij Create API Key, wybierz lub utwórz projekt Google Cloud i skopiuj tajny klucz. 

Otwórz terminal i zapisz klucz jako zmienną środowiskową poleceniem export GEMINI_API_KEY=<your-key>.

Nigdy nie przekazuj klucza jako parametru zapytania ?key= w URL; query stringi trafiają do logów serwerów, historii przeglądarki i cache’y proxy. Jeśli chcesz eksplorować model w playgroundzie przed pisaniem kodu, Tutorial Google AI Studio obejmuje tryby Chat, Build i Stream; ten artykuł pozostaje przy API.

Dla systemów produkcyjnych historia uwierzytelniania się zmienia: Vertex AI (teraz część Gemini Enterprise Agent Platform) daje OAuth, role IAM i regionalne endpointy zamiast surowego klucza API. W tym tutorialu używamy kluczy AI Studio, bo to najszybsza ścieżka nauki, ale zaplanuj migrację do Vertex, zanim dotkniesz prawdziwych danych użytkowników.

Zainstaluj google-genai i utwórz klienta

Wielu tutoriali nadal każe instalować google-generativeai. To stare SDK i nie ma Interactions API. Zainstaluj google-genai (wersja 2.3.0 lub nowsza):

pip install -U google-genai

Po instalacji sprawdź, czy Python ładuje bibliotekę i inicjalizuje klienta bez błędów:

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

Wykonaj pierwsze wywołanie Interactions API

Każde żądanie do Interactions API tworzy zasób Interaction, który zapisuje całą turę: twoje wejście, myśli modelu, wywołania narzędzi i końcowe wyjście. SDK udostępnia finalny tekst przez wygodną właściwość output_text, więc rzadko musisz ręcznie przechodzić przez kroki.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

U mnie model odpowiedział złożonym one-linerem w pandas i taką linią użycia:

Te liczby ukrywają pierwszą realną różnicę względem 3.7. Uruchomiłem to samo zadanie raz jeszcze z dłuższym promptem i bez ograniczenia wyjścia i 3.8 zużył 1 436 tokenów myślenia wobec 870 tokenów wyjścia. Z ograniczeniem zużył 1 515 wobec 42. Budżet rozumowania prawie się nie ruszył, co jest odwrotnością 3.7, gdzie te same 2 prompty zmieniały myślenie z 838 do 1 530.

Innymi słowy, 3.8 decyduje, jak mocno myśleć na podstawie zadania, a nie tego, jak sformułujesz zadanie, co pasuje do twierdzenia Google, że model celowo bardziej rozumuje i weryfikuje. Myślenie jest rozliczane po stawce wyjścia, więc przy ograniczonym wywołaniu około 97% rozliczonych tokenów to było rozumowanie, którego nie widziałem. Dlatego istnieje kolejna sekcja. 

Strumieniuj odpowiedź

Dla interfejsów czatu lub czegokolwiek, co ktoś ogląda, czekanie kilka sekund na całą odpowiedź jest odczuwalnie wolne. Przekaż stream=True do client.interactions.create() i wypisuj fragmenty, gdy nadchodzą:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Gdy to uruchomiłem, model zwrócił długą, dobrze zorganizowaną odpowiedź przy thinking_level: "low": porównanie koncepcyjne, tabelę podsumowującą i 2 przykłady SQL znajdujące ostatnie zamówienie każdego klienta — 1 z joinem na tabeli pochodnej i 1 z korelowanym podzapytaniem na liście SELECT. Pierwsze słowa pojawiły się niemal natychmiast — o to chodzi.

To końcowe print() jest tam z powodu. Bez niego ostatni fragment kończy się w połowie linii i zsh pokazuje zbłąkany %, bo strumień zatrzymuje się dokładnie tam, gdzie przestaje tekst modelu. Też ważne: delty niosą tekst tylko jeśli logujesz liczniki tokenów per żądanie — odczytuj je z końcowego zdarzenia ukończenia, a nie sumuj fragmentów.

Jak thinking_level zmienia koszt i jakość?

thinking_level ustala, ile rozumowania Gemini 3.8 Flash wykona, zanim napisze odpowiedź. Tokeny rozumowania są rozliczane jak zwykłe tokeny wyjściowe po $3,75 za 1M, więc poziom bezpośrednio kontroluje koszt i latencję, a Google mówi, że 3.8 celowo to wykorzystuje: wykonuje dodatkowe kroki przy złożonych zadaniach i może zużywać więcej tokenów na wyższych poziomach wysiłku niż 3.7.

Uruchom jeden prompt na low, medium i high

Test to warunek wyścigu w funkcji ponownego pobierania płatności, wysyłany z tym samym promptem na wszystkich 3 poziomach. Błędy współbieżności karzą pobieżne czytanie, więc jeśli poziomy się różnią, to tu powinno to wyjść. Jeśli masz uruchomić tylko 1 blok kodu z tego artykułu, niech to będzie ten — liczby przemawiają lepiej niż jakikolwiek opis.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Dla kontekstu, podatność to nieatomowe sprawdź-potem-działaj na payment_attempts[order_id]. Przy współbieżności 2 wątki mogą oba przejść warunek while i oba wywołać charge_fn(), zanim którykolwiek zwiększy licznik. Naprawa oznacza owinięcie przepływu odczyt-sprawdź-obciąż-zwiększ w blokadę per zamówienie albo użycie klucza idempotencji w bramce.

Porównanie wyników

Wyniki z moich uruchomień:

Wszystkie 3 poziomy znalazły podwójne obciążenie i wszystkie 3 dostarczyły blokowanie per zamówienie, więc niepowiązane zamówienia biegną równolegle. Druga część to nagłówek, jeśli porównasz to na 3.7: tam low owinęło wszystko jedną globalną blokadą trzymaną podczas wywołania sieciowego, a blokady per zamówienie pojawiły się dopiero na medium. W 3.8 low pisze lepszy projekt przy 0 tokenach myślenia, w 7,8 sekundy, za mniej niż 3 setne centa.

Co więc dają poziomy teraz? Głębokość audytu. Ten kod ma 4 odrębne tryby awarii (podwójne obciążenie, KeyError przy współbieżnym usunięciu, ponowne obciążenie po tym, jak ścieżka sukcesu usuwa stan oraz nieatomowe inkrementacje licznika), i tylko high nazwał wszystkie 4; low pominął przypadek ponownego obciążenia, a medium — licznik. 

high był też jedynym, który rozpisał semantykę ścieżki błędu swojej poprawki: po wyczerpaniu prób późniejsi wywołujący dostają False zamiast kolejnego obciążenia.

Kolumna „myślenie” to twierdzenie Google „3.8 pracuje mocniej” widoczne w terminalu. Na tym samym promptcie w 3.7 medium wzrosło z 2 343 tokenów myślenia do 3 158, a high z 2 217 do 4 512 — mniej więcej podwójnie — i dodatkowe tokeny kupiły pełniejszą analizę, a nie inny werdykt. Latencja wzrosła równolegle w tym przebiegu (7,8 s, 16,6 s, 25,5 s), ale pojedyncze pomiary na tych modelach się wahają, więc porównuj liczby tokenów, a nie sekundy.

Wybierz domyślny poziom i kiedy eskalować

To moja reguła kciuka dla poziomów rozumowania:

• W 3.8 low zasłużył na większą rolę niż sugeruje domyślne medium Google: dostarczył poprawną, dobrze zaprojektowaną naprawę przy 0 tokenach myślenia, więc zacznij od niego dla czegokolwiek, co człowiek przeczyta, zanim to się liczy (triage, szkice, podsumowania, kod, który zrecenzujesz). 

• Zachowaj medium tam, gdzie wyjście idzie bez czytania, bo dodatkowe myślenie przyniosło pełniejszą analizę trybów awarii, a w nieczytanym pipeline’ie dokładnie ten niewymieniony tryb zadziała.

• Zarezerwuj high dla wyjść, gdzie sama ścieżka błędu jest produktem, jak przepływy płatności, migracje czy wszystko, co recenzent audytuje linia po linii. U mnie tylko ten poziom wychwycił wszystkie 4 błędy i udokumentował zachowanie po wyczerpaniu prób.

Przy 6.6x koszcie low względem high ten trade-off czyta się inaczej przy $3,75 za 1M tokenów wyjściowych teraz versus $7,50 po 31 grudnia 2026 — eskaluj per żądanie, nie globalnie.

Warto znać furtkę: Google podaje, że 3.7 Flash pozostaje w pełni wspierany dla obciążeń „efficiency-first”. Jeśli dodatkowa skrupulatność 3.8 kosztuje więcej niż wymaga twoje zadanie, pozostanie na gemini-3.7-flash dla tego obciążenia jest wspieraną decyzją, nie hackiem.

Jak wyodrębnić dane strukturalne z PDF?

Gemini 3.8 Flash czyta PDF-y bezpośrednio jako wejście, więc możesz wysłać fakturę lub raport i zadawać o nie pytania. Użyłem jednokartkowej faktury dostawcy z numerem, datami, 4 pozycjami i sumą.

Dołącz PDF do promptu

Prześlij lokalny PDF faktury używając Files API. Files API zajmuje się przechowywaniem i cache’owaniem pliku w infrastrukturze Google:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

Wyjście z mojej faktury:

Wszystkie 3 wartości są poprawne. Przesyłanie odbywa się raz, a plik pozostaje dostępny dla kolejnych żądań, co ma znaczenie, gdy zadasz więcej niż 1 pytanie o ten sam dokument. Odpowiedź wraca jako wypunktowanie markdown — dobre do czytania, złe do wpięcia w pipeline.

Wymuś JSON schematem odpowiedzi

Aby dostać JSON zamiast prozy, przekaż schemat w response_format. W Interactions API to parametr najwyższego poziomu; ustawienie responseMimeType w generationConfig, które zobaczysz w starszych tutorialach, należy do przestarzałego endpointu generateContent.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Oto wyjście, które dostałem: 

Twoja klasa Pydantic definiuje wymagane pola i typy danych, a model_json_schema() generuje schemat JSON wymagany przez Gemini API. Po przetworzeniu json.loads() konwertuje wyjście modelu do standardowego słownika Pythona. Od tego momentu dane strukturalne możesz zamienić na wiersz DataFrame, zapisać do bazy lub dodać do Arkusza Google.

Zadaj dopytanie z previous_interaction_id

Dla 2. pytania o ten sam dokument przekaż id 1. interakcji jako previous_interaction_id. Serwer ma już PDF i 1. wymianę, więc nie wysyłasz ich ponownie:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Zwrócił wszystkie 4 pozycje w kolejności, łącznie z powtórzoną linią compute, bez komentarza o powtórzeniu. To właściwe zachowanie dla zadanego pytania; jeśli chcesz wskazywania anomalii, poproś o to. 

Dla porządku: 3.7 zachował się identycznie, więc dodatkowa skrupulatność 3.8 dotyczy własnego rozumowania, a nie zgłaszania audytów, o które nie prosiłeś.

2 rzeczy o tym wywołaniu: 

• response_format się nie przeniósł, bo jest ograniczony do interakcji, więc ta tura zwróciła prozę. 

• Interakcje są domyślnie przechowywane (store=True) przez 55 dni na płatnym planie i 1 dzień na darmowym; store=False czyni wywołanie bezstanowym, ale wtedy nie możesz z niego łańcuchować previous_interaction_id.

Jak dodać wywoływanie funkcji w Gemini 3.8 Flash?

Wywoływanie funkcji w Gemini 3.8 Flash to jedna pętla: model prosi o narzędzie, twój kod je uruchamia, odsyłasz wynik, a model pisze finalną odpowiedź. W tej sekcji zbudujemy pętlę ręcznie.

Jeśli chcesz, by Google obsłużyło pętlę za ciebie hostowanymi agentami wielonarzędziowymi, przeczytaj nasz tutorial o „Managed Agents” w Gemini API. A jeśli docelowo idziesz w agentów, kurs Building AI Agents with Google ADK buduje pełnego asystenta wsparcia klientów na tych samych prymitywach.

Zdefiniuj narzędzie i wykonaj pętlę interakcji

Narzędzie to lookup_exchange_rate(currency, date), oparte na małym słowniku w pamięci, więc przykład działa bez zewnętrznego API. Deklaracja to schemat JSON. Model nigdy nie uruchamia funkcji; zwraca krok function_call proszący twój kod o:

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

Wyjście: 

Zdarzyły się 3 rzeczy:  

1. Tura 1 zwróciła krok function_call z nazwą, ustrukturyzowanymi argumentami i id.

2. Twój Python wykonał lookup.

3. Tura 2 wysłała blok function_result referujący to wywołanie. 

Parametr tools jest przekazywany ponownie w turze 2 z tego samego powodu, dla którego trzeba było ponownie przekazać response_format w sekcji PDF: previous_interaction_id przenosi historię, nie konfigurację.

Błędy przy wywoływaniu funkcji w Gemini 3.x

Jeśli pętla narzędzia się psuje, to prawie zawsze jedna z 2 rzeczy. 

Po pierwsze, każdy wynik musi mapować się do swojego wywołania. W Interactions API to call_id i name w bloku function_result; w przestarzałym generateContent FunctionResponse musi pasować do id i name poprzedzającego FunctionCall. Żadne nie jest opcjonalne w Gemini 3.x.

Po drugie, błąd Malformed_Function_Call zwykle pojawia się, gdy model emituje komentarz przed wywołaniem narzędzia. Przewodnik deweloperski 3.8 Google mówi, by sprzątać wstępny tekst przed narzędziem, formatować instrukcje inline przez \n\n i owijać notatki robocze w dedykowane wywołanie funkcji zamiast surowego tekstu. Zaostrzyj system instruction; nie retry’uj na ślepo.

Co się psuje przy przejściu na Gemini 3.8 Flash?

To zależy, skąd startujesz. 

• Z Gemini 3.7 Flash: nic. Zmień string modelu na gemini-3.8-flash i każdy snippet z tego artykułu zadziała bez zmian, bo powierzchnia API jest identyczna. 

• Z Gemini 3.6 Flash lub starszych konfiguracja modelu wymaga tego samego 15‑minutowego audytu co wcześniej.

Lista kontrolna migracji (z 3.6 Flash lub starszych)

Przerób to w kolejności. Pozycje 1–3 powodują natychmiastowe 400; pozycje 4 i 5 powodują ciche problemy z jakością.

1. Zmień ID modelu na gemini-3.8-flash.

2. Usuń martwe parametry próbkowania: temperature, top_p i top_k są ignorowane lub odrzucane w Gemini 3.x, a frequency_penalty, presence_penalty i candidate_count rzucają aktywny błąd API. Wyczyść wszystkie 6 ze starych konfiguracji.

3. Zastąp thinking_budget przez thinking_level: używaj tylko low, medium lub high. Stara wartość minimal zwraca błąd walidacji. Wysłanie jednocześnie thinking_budget i thinking_level w jednym żądaniu daje 400.

4. Usuń wstępnie wypełnione tury modelu: wyrzuć je z każdej konwersacji, którą konstruujesz, i upewnij się, że końcowa tura użytkownika ma niepusty tekst. Payload historii nie może kończyć się turą modelu.

5. Ustandaryzuj przepływy wieloturowe: polegaj na previous_interaction_id zamiast odtwarzania historii po stronie klienta. Musisz ponownie podawać narzędzia, system_instruction i generation_config w każdej turze, gdzie mają znaczenie.

Google publikuje wersję autorytatywną w dokumentacji modeli Gemini API, włącznie z automatyczną ścieżką, jeśli twój agent kodujący wspiera umiejętności. Przeczytaj sam choć raz; automatyczna migracja nie powie ci, czemu twoje temperature=0.2 tam w ogóle było.

Błędy, na które trafisz w produkcji

Oto 4 kody statusu warte obsłużenia i co każdy znaczy w tym API:

Jeszcze 2 rzeczy:

• Ustaw jawne timeouty klienta, gdy łączysz thinking_level: "high" z długimi pętlami narzędzi, bo zawieszone żądanie jest gorsze niż nieudane, a dodatkowa skrupulatność 3.8 sprawia, że długie przebiegi rozumowania są bardziej prawdopodobne, nie mniej. 

• Loguj interaction.id przy każdym żądaniu; to uchwyt do pobierania, debugowania lub usuwania przechowywanych interakcji później.

Na koniec

Wszystko w tym artykule sprowadza się do 3 zmian. Interactions API zmieniło konwencję wywołań, thinking_level zastąpiło każde pokrętło próbkowania, którym kiedyś stroiłeś, a stan po stronie serwera przez previous_interaction_id sprawił, że follow‑up do PDF i pętla narzędzia stały się turami‑jednolinijkowcami zamiast odtwarzania historii. Gemini 3.8 Flash nie zmienił tej powierzchni; zmienił to, jak mocno model pracuje w środku, dlatego pomiary w tym artykule zostały zrobione świeżo na 3.8, a nie przeniesione z 3.7.

Zanim przyjmiesz moje rekomendacje poziomów na wiarę, puść skrypt porównawczy na zadaniu z własnego backlogu; poziom, który wygrywa na wyścigu ponownego pobierania płatności, może przegrać na twoim generowaniu SQL. 

Gdy pojedyncze wywołania API przestają wystarczać, a chcesz produkcyjnych systemów AI, nasza ścieżka Associate AI Engineer for Developers obejmuje całą drogę, a ścieżka Associate AI Engineer for Data Scientists to samo z perspektywy danych.