Przewodnik dla deweloperów Gemini 3

Gemini 3 to nasza najbardziej inteligentna rodzina modeli, która opiera się na najnowocześniejszym wnioskowaniu. Został zaprojektowany tak, aby realizować dowolne pomysły dzięki opanowaniu przepływów pracy opartych na agentach, autonomicznego kodowania i złożonych zadań multimodalnych. Ten przewodnik zawiera informacje o najważniejszych funkcjach rodziny modeli Gemini 3 i o tym, jak w pełni wykorzystać ich potencjał.

Wysokie/dynamiczne myślenie Niskie myślenie

Gemini 3 Pro domyślnie używa dynamicznego myślenia, aby analizować prompty. Aby uzyskać szybsze odpowiedzi o mniejszych opóźnieniach, gdy nie jest wymagane złożone rozumowanie, możesz ograniczyć poziom myślenia modelu do poziomu low.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Odkrywaj

Zapoznaj się z naszą kolekcją 3 aplikacji Gemini, aby zobaczyć, jak model radzi sobie z zaawansowanym wnioskowaniem, autonomicznym kodowaniem i złożonymi zadaniami multimodalnymi.

Poznaj Gemini 3

Gemini 3 Pro to pierwszy model z nowej serii. gemini-3-pro-preview najlepiej sprawdza się w przypadku złożonych zadań, które wymagają szerokiej wiedzy o świecie i zaawansowanego wnioskowania w różnych trybach.

* Ceny dotyczą 1 miliona tokenów. Podane ceny dotyczą standardowego tekstu. Stawki za dane wejściowe multimodalne mogą się różnić.

Szczegółowe limity żądań, ceny pakietów i dodatkowe informacje znajdziesz na stronie modeli.

Nowe funkcje interfejsu API w Gemini 3

Gemini 3 wprowadza nowe parametry, które zapewniają deweloperom większą kontrolę nad opóźnieniami, kosztami i wiernością multimodalną.

Poziom myślenia

Parametr thinking_level kontroluje maksymalną głębokość wewnętrznego procesu rozumowania modelu przed wygenerowaniem odpowiedzi. Gemini 3 traktuje te poziomy jako względne limity na myślenie, a nie ścisłe gwarancje tokenów. Jeśli nie określisz wartości thinking_level, Gemini 3 Pro domyślnie użyje wartości high.

• low: minimalizuje opóźnienie i koszty. Najlepszy do prostych instrukcji, czatu i aplikacji o wysokiej przepustowości
• medium: (już wkrótce), nieobsługiwane w momencie wprowadzenia
• high (Domyślnie): maksymalizuje głębię rozumowania. Model może potrzebować znacznie więcej czasu na wygenerowanie pierwszego tokena, ale wynik będzie bardziej przemyślany.

Rozdzielczość multimediów

Gemini 3 wprowadza szczegółową kontrolę nad przetwarzaniem obrazu multimodalnego za pomocą parametru media_resolution. Wyższe rozdzielczości zwiększają zdolność modelu do odczytywania drobnego tekstu lub rozpoznawania małych szczegółów, ale zwiększają zużycie tokenów i opóźnienia. Parametr media_resolution określa maksymalną liczbę tokenów przypisanych do obrazu wejściowego lub klatki filmu.

Możesz teraz ustawić rozdzielczość na media_resolution_low, media_resolution_medium lub media_resolution_high dla poszczególnych części multimedialnych lub globalnie (za pomocą parametru generation_config). Jeśli nie określisz rozdzielczości, model użyje optymalnych ustawień domyślnych na podstawie typu multimediów.

Zalecane ustawienia

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Temperatura

W przypadku Gemini 3 zdecydowanie zalecamy pozostawienie parametru temperatury na domyślnej wartości 1.0.

W przypadku poprzednich modeli często warto było dostosować temperaturę, aby kontrolować kreatywność i determinizm, ale w przypadku Gemini 3 możliwości rozumowania są zoptymalizowane pod kątem ustawienia domyślnego. Zmiana temperatury (ustawienie jej poniżej 1,0) może prowadzić do nieoczekiwanych zachowań, takich jak zapętlanie lub pogorszenie wydajności, zwłaszcza w przypadku złożonych zadań matematycznych lub związanych z rozumowaniem.

Podpisy myślowe

Gemini 3 używa sygnatur myśli, aby zachować kontekst rozumowania w różnych wywołaniach interfejsu API. Są to zaszyfrowane reprezentacje wewnętrznego procesu myślowego modelu. Aby model zachował swoje możliwości rozumowania, musisz zwrócić te sygnatury do modelu w swoim żądaniu dokładnie w takiej postaci, w jakiej zostały otrzymane:

• Wywoływanie funkcji (ścisłe): interfejs API wymusza ścisłą weryfikację „bieżącej kolejki”. Brakujące podpisy spowodują błąd 400.
• Tekst/czat: weryfikacja nie jest ściśle egzekwowana, ale pominięcie sygnatur obniży jakość rozumowania i odpowiedzi modelu.

Wywoływanie funkcji (ścisła weryfikacja)

Gdy Gemini generuje functionCall, korzysta z thoughtSignature, aby w kolejnym kroku prawidłowo przetworzyć dane wyjściowe narzędzia. „Obecna tura” obejmuje wszystkie kroki Model (functionCall) i Użytkownik (functionResponse), które wystąpiły od ostatniej standardowej wiadomości Użytkownik text.

• Pojedyncze wywołanie funkcji: część functionCall zawiera sygnaturę. Musisz go zwrócić.
• Równoległe wywołania funkcji: tylko pierwsza część listy (functionCall) będzie zawierać sygnaturę. Części należy zwrócić w dokładnie takiej kolejności, w jakiej zostały dostarczone.
• Wielokrokowe (sekwencyjne): jeśli model wywołuje narzędzie, otrzymuje wynik i wywołuje inne narzędzie (w ramach tej samej tury), oba wywołania funkcji mają sygnatury. Musisz zwrócić wszystkie zgromadzone podpisy w historii.

Tekst i streaming

W przypadku standardowego czatu lub generowania tekstu obecność podpisu nie jest gwarantowana.

• Bez przesyłania strumieniowego: ostatnia część odpowiedzi może zawierać znak thoughtSignature, ale nie zawsze jest on obecny. Jeśli zostanie zwrócony, odeślij go, aby utrzymać jak najlepszą skuteczność.
• Streaming: jeśli sygnatura zostanie wygenerowana, może dotrzeć w ostatnim bloku, który zawiera pustą część tekstową. Upewnij się, że parser strumienia sprawdza podpisy nawet wtedy, gdy pole tekstowe jest puste.

Przykłady kodu

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Migracja z innych modeli

Jeśli przenosisz ślad rozmowy z innego modelu (np. Gemini 2.5) lub wstrzykniesz niestandardowe wywołanie funkcji, które nie zostało wygenerowane przez Gemini 3, nie będziesz mieć prawidłowego podpisu.

Aby pominąć ścisłą weryfikację w tych konkretnych scenariuszach, wypełnij pole tym konkretnym ciągiem znaków: "thoughtSignature": "context_engineering_is_the_way_to_go"

Uporządkowane dane wyjściowe z narzędziami

Gemini 3 umożliwia łączenie danych strukturalnych z wbudowanymi narzędziami, takimi jak wyszukiwanie w Google, kontekst adresu URL i wykonywanie kodu.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Przenoszenie danych z Gemini 2.5

Gemini 3 to nasza najbardziej zaawansowana rodzina modeli. Jest ulepszoną wersją Gemini 2.5 Pro. Podczas migracji weź pod uwagę te kwestie:

• Myślenie: jeśli wcześniej używasz złożonych technik promptowania (np. Chain-of-thought), aby zmusić Gemini 2.5 do rozumowania, wypróbuj Gemini 3 z thinking_level: "high" i uproszczonymi promptami.
• Ustawienia temperatury: jeśli dotychczasowy kod wyraźnie ustawia temperaturę (zwłaszcza na niskie wartości w przypadku deterministycznych wyników), zalecamy usunięcie tego parametru i użycie domyślnej wartości 1,0 dla Gemini 3, aby uniknąć potencjalnych problemów z zapętlaniem lub pogorszenia wydajności w przypadku złożonych zadań.
• Rozumienie dokumentów i plików PDF: domyślna rozdzielczość OCR w przypadku plików PDF została zmieniona. Jeśli w przypadku analizowania dokumentów o dużej gęstości informacji polegasz na określonym działaniu, przetestuj nowe ustawienie media_resolution_high, aby mieć pewność, że nadal będzie ono działać prawidłowo.
• Zużycie tokenów: przejście na domyślne ustawienia Gemini 3 Pro może zwiększyć zużycie tokenów w przypadku plików PDF, ale zmniejszyć je w przypadku filmów. Jeśli żądania przekraczają teraz okno kontekstu ze względu na wyższe domyślne rozdzielczości, zalecamy wyraźne zmniejszenie rozdzielczości multimediów.
• Segmentacja obrazu: funkcje segmentacji obrazu (zwracanie masek obiektów na poziomie pikseli) nie są obsługiwane w Gemini 3 Pro. W przypadku zadań wymagających natywnej segmentacji obrazów zalecamy dalsze korzystanie z Gemini 2.5 Flash z wyłączonym myśleniem lub z Gemini Robotics-ER 1.5.

Zgodność z OpenAI

W przypadku użytkowników korzystających z warstwy zgodności OpenAI standardowe parametry są automatycznie mapowane na odpowiedniki w Gemini:

• reasoning_effort (OAI) odpowiada thinking_level (Gemini). Pamiętaj, że reasoning_effort średni odpowiada thinking_level wysokiemu.

Sprawdzone metody dotyczące promptów

Gemini 3 to model rozumowania, który zmienia sposób, w jaki należy formułować prompty.

• Precyzyjne instrukcje: podawaj zwięzłe prompty. Gemini 3 najlepiej reaguje na bezpośrednie i jasne instrukcje. Może nadmiernie analizować rozbudowane lub zbyt złożone techniki inżynierii promptów używane w przypadku starszych modeli.
• Poziom szczegółowości odpowiedzi: domyślnie Gemini 3 jest mniej rozwlekły i woli udzielać bezpośrednich, zwięzłych odpowiedzi. Jeśli Twój przypadek użycia wymaga bardziej konwersacyjnej lub „gadatliwej” osobowości, musisz wyraźnie nakierować model w prompcie (np. „Wyjaśnij to jako przyjazny, rozmowny asystent”).
• Zarządzanie kontekstem: podczas pracy z dużymi zbiorami danych (np. całymi książkami, bazami kodu lub długimi filmami) umieszczaj konkretne instrukcje lub pytania na końcu promptu, po kontekście danych. Zakotwicz rozumowanie modelu w dostarczonych danych, zaczynając pytanie od frazy „Na podstawie powyższych informacji…”.

Więcej informacji o strategiach projektowania promptów znajdziesz w przewodniku po inżynierii promptów.

Najczęstsze pytania

1. Jaka jest data odcięcia wiedzy w przypadku Gemini 3 Pro? Model Gemini 3 ma datę odcięcia wiedzy w styczniu 2025 r. Aby uzyskać bardziej aktualne informacje, skorzystaj z narzędzia Search Grounding.

2. Jakie są limity okna kontekstu? Gemini 3 Pro obsługuje okno kontekstu z milionem tokenów na wejściu i do 64 tys. tokenów na wyjściu.

3. Czy Gemini 3 Pro ma bezpłatną wersję? Możesz wypróbować ten model bezpłatnie w Google AI Studio, ale obecnie nie ma bezpłatnego poziomu gemini-3-pro-preview w Gemini API.

4. Czy mój stary kod thinking_budget będzie nadal działać? Tak, znacznik thinking_budget jest nadal obsługiwany ze względu na zgodność z wcześniejszymi rozwiązaniami, ale zalecamy przejście na znacznik thinking_level, aby uzyskać bardziej przewidywalną skuteczność. Nie używaj obu tych parametrów w tym samym żądaniu.

5. Czy Gemini 3 obsługuje interfejs Batch API? Tak, Gemini 3 obsługuje interfejs Batch API.

6. Czy buforowanie kontekstowe jest obsługiwane? Tak, pamięć podręczna kontekstu jest obsługiwana w przypadku Gemini 3. Minimalna liczba tokenów wymagana do rozpoczęcia buforowania to 2048.

7. Które narzędzia są obsługiwane w Gemini 3? Gemini 3 obsługuje wyszukiwarkę Google, wyszukiwanie plików, wykonywanie kodu i kontekst adresu URL. Obsługuje też standardowe wywoływanie funkcji w przypadku własnych narzędzi niestandardowych. Pamiętaj, że Mapy Google i korzystanie z komputera nie są obecnie obsługiwane.

Dalsze kroki

• Pierwsze kroki z Gemini 3 Cookbook
• Zapoznaj się z przewodnikiem po poziomach myślenia i dowiedz się, jak przejść z budżetu na myślenie na poziomy myślenia.