Руководство разработчика Gemini 3

Gemini 3 — наше самое интеллектуальное семейство моделей на сегодняшний день, созданное на основе передовых методов анализа. Оно разработано для воплощения любых идей в жизнь, позволяя освоить агентные рабочие процессы, автономное кодирование и сложные мультимодальные задачи. В этом руководстве рассматриваются ключевые функции семейства моделей Gemini 3 и способы максимально эффективного использования его возможностей.

Высокое/динамичное мышление Низкое мышление

Gemini 3 Pro по умолчанию использует динамическое мышление для анализа подсказок. Для более быстрых ответов с меньшей задержкой, когда не требуется сложных рассуждений, можно ограничить уровень мышления модели до 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]"}]
    }]
  }'

Исследовать

Познакомьтесь с нашей коллекцией приложений Gemini 3, чтобы увидеть, как модель справляется с передовыми рассуждениями, автономным кодированием и сложными многомодальными задачами.

Встречайте Gemini 3

Gemini 3 Pro — первая модель в новой серии. gemini-3-pro-preview лучше всего подходит для сложных задач, требующих обширных знаний о мире и развитого мышления в различных модальностях.

* Цена указана за 1 миллион токенов. Указанные цены действительны для стандартного текста; стоимость мультимодального ввода может отличаться.

Подробные ограничения по тарифам, цены на партии и дополнительную информацию смотрите на странице моделей .

Новые функции API в Gemini 3

Gemini 3 представляет новые параметры, призванные предоставить разработчикам больше контроля над задержкой, стоимостью и точностью мультимодального воспроизведения.

Уровень мышления

Параметр thinking_level управляет максимальной глубиной внутреннего процесса рассуждений модели, прежде чем она выдаст ответ. Gemini 3 рассматривает эти уровни как относительные допуски для рассуждений, а не как строгие гарантии. Если thinking_level не указан, Gemini 3 Pro по умолчанию использует значение high .

• low : минимизирует задержку и затраты. Оптимально для простых инструкций, чата или высокопроизводительных приложений.
• medium : (скоро), не поддерживается на момент запуска
• high (по умолчанию): обеспечивает максимальную глубину рассуждений. Модели может потребоваться значительно больше времени для достижения первого токена, но результат будет более тщательно обоснован.

Разрешение СМИ

Gemini 3 представляет детальный контроль над обработкой мультимодального изображения с помощью параметра media_resolution . Более высокое разрешение улучшает способность модели читать мелкий текст и распознавать мелкие детали, но увеличивает использование токенов и задержку. Параметр media_resolution определяет максимальное количество токенов, выделяемых на входное изображение или видеокадр.

Теперь вы можете задать разрешение media_resolution_low , media_resolution_medium или media_resolution_high для отдельного компонента носителя или глобально (через generation_config ). Если разрешение не указано, модель использует оптимальные значения по умолчанию в зависимости от типа носителя.

Рекомендуемые настройки

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"
          }
        }
      ]
    }]
  }'

Температура

Для Gemini 3 мы настоятельно рекомендуем сохранить параметр температуры на значении по умолчанию 1.0 .

В то время как предыдущие модели часто выигрывали от настройки температуры для управления креативностью, а не детерминизмом, возможности рассуждений Gemini 3 оптимизированы для настроек по умолчанию. Изменение температуры (ниже 1,0) может привести к неожиданному поведению, такому как зацикливание или снижение производительности, особенно при выполнении сложных математических задач или задач на рассуждения.

Мысленные подписи

Gemini 3 использует сигнатуры мыслей для сохранения контекста рассуждений между вызовами API. Эти сигнатуры представляют собой зашифрованные представления внутреннего мыслительного процесса модели. Чтобы модель сохраняла свои возможности рассуждений, необходимо возвращать эти сигнатуры модели в запросе точно в том виде, в котором они были получены:

• Вызов функций (строгий): API обеспечивает строгую проверку текущего хода. Отсутствие подписей приведёт к ошибке 400.
• Текст/чат: Проверка не является строго обязательной, но отсутствие подписей ухудшит обоснованность модели и качество ответа.

Вызов функции (строгая проверка)

Когда Gemini генерирует вызов functionCall , он полагается на thoughtSignature для корректной обработки выходных данных инструмента в следующем шаге. «Текущий шаг» включает все шаги модели ( functionCall ) и пользователя ( functionResponse ), выполненные с момента последнего стандартного text сообщения пользователя .

• Вызов одиночной функции: часть functionCall содержит сигнатуру. Вы должны её вернуть.
• Параллельные вызовы функций: сигнатуру будет содержать только первый элемент functionCall в списке. Необходимо вернуть элементы в том же порядке, в котором они были получены.
• Многошаговый (последовательный): если модель вызывает инструмент, получает результат и вызывает другой инструмент (в пределах одного хода), оба вызова функций имеют сигнатуры. Необходимо вернуть все накопленные сигнатуры в истории.

Текст и потоковая передача

Для стандартного чата или генерации текста наличие подписи не гарантируется.

• Непоточная передача : заключительная часть контента ответа может содержать thoughtSignature , хотя она присутствует не всегда. Если она возвращается, следует отправить её обратно для обеспечения максимальной производительности.
• Потоковая передача : если сигнатура сгенерирована, она может попасть в последний фрагмент, содержащий пустую текстовую часть. Убедитесь, что ваш потоковый анализатор проверяет наличие подписей, даже если текстовое поле пусто.

Примеры кода

// 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." }] 
  }
]

Миграция с других моделей

Если вы переносите трассировку разговора из другой модели (например, Gemini 2.5) или внедряете вызов пользовательской функции, которая не была сгенерирована Gemini 3, у вас не будет действительной подписи.

Чтобы обойти строгую проверку в этих конкретных сценариях, заполните поле этой фиктивной строкой: "thoughtSignature": "context_engineering_is_the_way_to_go"

Структурированные результаты с инструментами

Gemini 3 позволяет вам объединять структурированные выводы со встроенными инструментами, включая заземление с помощью поиска Google , контекста URL и выполнения кода .

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"]
        }
    }
  }'

Переход с Gemini 2.5

Gemini 3 — наша самая мощная модель на сегодняшний день, предлагающая значительные улучшения по сравнению с Gemini 2.5 Pro. При переходе на новую версию обратите внимание на следующее:

• Мышление: Если ранее вы использовали сложную разработку подсказок (вроде цепочки мыслей), чтобы заставить Gemini 2.5 рассуждать, попробуйте Gemini 3 с thinking_level: "high" и упрощенными подсказками.
• Настройки температуры: если ваш существующий код явно устанавливает температуру (особенно низкие значения для детерминированных выходных данных), мы рекомендуем удалить этот параметр и использовать значение Gemini 3 по умолчанию, равное 1,0, чтобы избежать потенциальных проблем с зацикливанием или снижения производительности при выполнении сложных задач.
• PDF и распознавание документов: разрешение распознавания текста по умолчанию для PDF-файлов изменилось. Если вы полагались на определённое поведение при анализе плотных документов, протестируйте новый параметр media_resolution_high , чтобы обеспечить постоянную точность.
• Потребление токенов: Переход на настройки по умолчанию Gemini 3 Pro может увеличить использование токенов для PDF-файлов, но уменьшить для видео. Если запросы теперь превышают контекстное окно из-за более высоких разрешений по умолчанию, мы рекомендуем явно уменьшить разрешение медиафайла.
• Сегментация изображений: Возможности сегментации изображений (возвращение масок на уровне пикселей для объектов) не поддерживаются в Gemini 3 Pro. Для рабочих нагрузок, требующих собственной сегментации изображений, мы рекомендуем продолжать использовать Gemini 2.5 Flash с отключенным режимом Thinking или Gemini Robotics-ER 1.5 .

Совместимость с OpenAI

Для пользователей, использующих уровень совместимости OpenAI, стандартные параметры автоматически сопоставляются с эквивалентами Gemini:

• reasoning_effort (OAI) соответствует thinking_level (Близнецы). Обратите внимание, что reasoning_effort средний соответствует thinking_level высокий.

Рекомендации по лучшим практикам

Gemini 3 — это модель рассуждения, которая меняет то, как следует подсказывать.

• Точные инструкции: будьте лаконичны в своих подсказках. Gemini 3 лучше всего реагирует на прямые и чёткие инструкции. Он может чрезмерно анализировать подробные или слишком сложные инженерные методы, используемые в старых моделях.
• Уровень детализации вывода: По умолчанию Gemini 3 менее многословен и предпочитает давать прямые, содержательные ответы. Если ваш вариант использования требует более разговорного или «болтливого» подхода, необходимо явно указать модель в подсказке (например, «Объясните это как дружелюбный и разговорчивый помощник»).
• Управление контекстом: при работе с большими наборами данных (например, целыми книгами, кодовыми базами или длинными видео) размещайте конкретные инструкции или вопросы в конце запроса, после контекста данных. Свяжите рассуждения модели с предоставленными данными, начав вопрос с фразы типа: «На основании приведённой выше информации...».

Дополнительную информацию о стратегиях проектирования подсказок можно найти в руководстве по проектированию подсказок .

Часто задаваемые вопросы

1. Какой срок действия лицензии Gemini 3 Pro? Срок действия лицензии Gemini 3 — январь 2025 года. Для получения более актуальной информации воспользуйтесь инструментом Search Grounding .

2. Каковы ограничения окна контекста? Gemini 3 Pro поддерживает окно контекста ввода размером 1 миллион токенов и до 64 тысяч токенов вывода.

3. Есть ли бесплатный тариф для Gemini 3 Pro? Вы можете бесплатно попробовать модель в Google AI Studio, но в настоящее время бесплатный тариф для gemini-3-pro-preview в API Gemini отсутствует.

4. Будет ли мой старый код thinking_budget работать? Да, thinking_budget по-прежнему поддерживается для обратной совместимости, но мы рекомендуем перейти на thinking_level для более предсказуемой производительности. Не используйте оба варианта в одном запросе.

5. Поддерживает ли Gemini 3 пакетный API? Да, Gemini 3 поддерживает пакетный API.

6. Поддерживается ли кэширование контекста? Да, кэширование контекста поддерживается в Gemini 3. Минимальное количество токенов, необходимое для запуска кэширования, составляет 2048 токенов.

7. Какие инструменты поддерживаются в Gemini 3? Gemini 3 поддерживает поиск Google , поиск файлов , выполнение кода и контекст URL . Также поддерживается стандартный вызов функций для ваших собственных инструментов. Обратите внимание, что Google Maps и Computer Use в настоящее время не поддерживаются.

Следующие шаги

• Начните работу с кулинарной книгой Gemini 3
• Ознакомьтесь со специальным руководством «Кулинарной книги» об уровнях мышления и о том, как перейти от бюджета мышления к уровням мышления.