Урок 1: Анализ отличий Gemini 3: Нативные возможности и новые лимиты

Добро пожаловать в первый модуль. Если вы работали с предыдущими версиями моделей Google или OpenAI, вы привыкли к определённым паттернам проектирования. Gemini 3 заставляет нас пересмотреть некоторые из них. Это не просто «более быстрая версия 1.5», это сдвиг парадигмы в сторону нативной мультимодальности.

В этом уроке мы не будем тратить время на маркетинг. Мы разберем архитектурные отличия, которые напрямую влияют на то, как вы пишете код, проектируете агентов и управляете стоимостью токенов.

Ключевая концепция: Что значит «Нативная мультимодальность»?

В старых архитектурах (и во многих текущих моделях конкурентов) работа с файлами — это «костыль». Когда вы отправляли аудиофайл, под капотом часто запускался процесс Whisper (или аналог) для транскрипции в текст, и только этот текст попадал в LLM. Вы теряли интонацию, паузы, эмоции и фоновые шумы.

Gemini 3 — нативная модель. Она обучалась на аудио, видео и изображениях одновременно с текстом. Для неё аудио — это не транскрипция, это поток токенов, несущих семантический смысл звука. Это позволяет модели:

• Понимать сарказм по интонации голоса.
• Синхронизировать события на видео с точностью до кадра без внешних инструментов OCR.
• Реагировать быстрее, так как убраны промежуточные этапы препроцессинга.

Работа с видео и аудио: Новый подход

Раньше для анализа видео нам приходилось разбивать его на кадры, выбирать каждый n-й кадр, переживать за лимиты токенов и склеивать контекст. В Gemini 3 API процесс упрощен, но требует понимания того, как управляется сессия загрузки.

Давайте посмотрим, как теперь выглядит работа с «тяжелым» контентом через File API. Обратите внимание: мы больше не отправляем байты напрямую в `generate_content` для больших файлов, мы используем загрузку через File API для создания ссылки URI.

import os
import time
import google.generativeai as genai

# Настройка API ключа
genai.configure(api_key=os.environ["GEMINI_API_KEY"])

def process_heavy_video(file_path):
    print(f"Загрузка файла: {file_path}...")
    
    # 1. Загрузка файла через File API
    # Это критично для Gemini 3 при работе с длинными видео/аудио
    video_file = genai.upload_file(path=file_path)
    
    print(f"Файл загружен: {video_file.uri}")
    
    # 2. Ожидание обработки (Active State)
    # Gemini 3 требует времени на токенизацию мультимедиа на сервере
    while video_file.state.name == "PROCESSING":
        print("Обработка файла на стороне Google...")
        time.sleep(2)
        video_file = genai.get_file(video_file.name)
        
    if video_file.state.name == "FAILED":
        raise ValueError("Ошибка обработки видео")
        
    print("Файл готов к использованию.")

    # 3. Инициализация модели Gemini 3
    # Обратите внимание на системные инструкции - они стали строже и эффективнее
    model = genai.GenerativeModel(
        model_name="gemini-1.5-pro-latest", # Используем актуальный алиас для v3 фич
        system_instruction="Ты эксперт по анализу видеопотока. Твоя задача - найти аномалии."
    )

    # 4. Запрос
    response = model.generate_content(
        ["Опиши таймкоды, где человек на видео выглядит взволнованным, основываясь на мимике и голосе.", video_file],
        request_options={"timeout": 600} # Увеличиваем таймаут для глубокого анализа
    )
    
    return response.text

# Пример вызова (псевдокод)
# print(process_heavy_video("security_camera_footage.mp4"))

Контекстное окно и Context Caching

Gemini 3 продолжает тренд на гигантские контекстные окна (до 2 миллионов токенов и выше). Однако, главная проблема большого контекста — это не «влезет ли», а «сколько это стоит» и «сколько ждать ответа».

Если вы каждый раз отправляете книгу на 500 страниц в промпте, вы платите за обработку этих 500 страниц при каждом запросе. Это убивает экономику приложения.

Context Caching (Кэширование контекста) — это киллер-фича экосистемы Gemini 3. Она позволяет «заморозить» токены на серверах Google. Вы платите один раз за загрузку (дорого) и затем копейки за хранение (дешево). Последующие запросы к этому кэшу обрабатываются мгновенно, так как матрица внимания (attention matrix) уже посчитана.

Когда использовать кэширование?

• Чат-боты по документации: Загрузили мануал на 1000 страниц в кэш, пользователи задают вопросы дешево и быстро.
• Анализ длинных видео: Видео закэшировано, агент делает по нему 50 разных запросов.
• Few-Shot Prompting: Если у вас есть 100 идеальных примеров (few-shot), закэшируйте их, чтобы не тратить инпут-токены каждый раз.

from google.generativeai import caching
import datetime

# Создание кэша для большого документа
def create_documentation_cache(document_files):
    # Создаем кэш с "временем жизни" (TTL)
    cache = caching.CachedContent.create(
        model="models/gemini-1.5-pro-001",
        display_name="technical_docs_v3", 
        system_instruction="Ты — технический ассистент поддержки.",
        contents=document_files, # Список объектов, загруженных через upload_file
        ttl=datetime.timedelta(minutes=60) # Кэш живет 1 час
    )
    
    return cache

# Использование кэша
def query_cached_model(cache_name, user_query):
    # Подключаемся к существующему кэшу по имени
    model = genai.GenerativeModel.from_cached_content(cached_content=cache_name)
    
    response = model.generate_content(user_query)
    return response.text

Давайте посчитаем.

Вариант А (Без кэша):
1 запрос = 1.5М токенов.
500 запросов * 1.5М = 750М токенов.
Стоимость: 750 * $3.50 = $2625.
Это колоссально дорого и медленно.

Вариант Б (С кэшем):
1. Первичная загрузка (Write): 1.5М * $3.50 = $5.25 (один раз).
2. Хранение (Storage): 1.5М * $4.00/час * 8 часов = $48.00.
3. Запросы (Read from cache): Теперь мы платим только за промпт пользователя (пусть 100 токенов) и ответ. Но даже если считать повторное чтение контекста (в Gemini платится сниженная цена за input cached), допустим $0.80 * 1.5М * 500 (если архитектура биллинга считает каждый хит полного контекста, что обычно дешевле, но для простоты возьмем только хранение и малый инпут). 

В реальности Gemini Context Caching работает так: вы платите за создание + хранение. Входящие запросы к кэшу стоят ЗНАЧИТЕЛЬНО дешевле, чем обработка сырых токенов.

Итог: $5.25 (загрузка) + $48 (хранение) + стоимость генерации ответов. Это порядка $60-70 против $2625.

Вывод: Использование кэширования в сценариях с большим неизменным контекстом и частыми запросами обязательно.

JSON Mode и Структурированный вывод

В Gemini 3 была проведена огромная работа над `response_mime_type`. Если раньше мы умоляли модель в промпте: «Пожалуйста, верни только валидный JSON, без markdown, без лишних слов», то теперь это управляется на уровне конфигурации.

Режим JSON Schema гарантирует, что модель вернет данные, строго соответствующие вашей схеме. Это критично для построения агентов, которые передают данные другим API. Модель больше не «галлюцинирует» полями, которых нет в описании.

Важное изменение: В Gemini 3 при использовании `response_mime_type="application/json"` вы обязаны также упомянуть JSON в самом промпте или предоставить схему. Иначе API может вернуть ошибку или непредсказуемый результат. Это защита от дурака.

import typing_extensions as typing

# Определение строгой схемы через Typing
class Recipe(typing.TypedDict):
    name: str
    ingredients: list[str]
    calories: int
    is_vegan: bool

model = genai.GenerativeModel("gemini-1.5-pro-latest")

# Запрос с принудительной схемой
result = model.generate_content(
    "Предложи рецепт лазаньи.",
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema=Recipe # Передаем класс схемы напрямую
    )
)

print(result.text)
# Результат гарантированно будет соответствовать полям Recipe

Лимиты и Квоты (RPM, TPM, RPD)

Переход на Gemini 3 меняет подход к лимитам. Google вводит более агрессивное разделение между уровнями доступа.

• RPM (Requests Per Minute): В бесплатном тире (Free tier) лимиты могут быть жесткими (например, 2-15 RPM). Это делает его непригодным для продакшна, кроме тестов.
• TPM (Tokens Per Minute): Это зачастую более важный лимит. Один запрос с книгой внутри может съесть весь ваш минутный лимит TPM, и следующие запросы будут падать с ошибкой 429, даже если RPM низкий.
• Batch Requests: В Gemini 3 улучшена поддержка асинхронных пакетных запросов. Если вам не нужен ответ прямо сейчас (например, ночной анализ логов), используйте Batch API — это дешевле и имеет отдельные, более высокие квоты.

Совет эксперта: Всегда оборачивайте вызовы API в логику с экспоненциальной задержкой (exponential backoff) при ошибках 429. В Python для этого отлично подходит библиотека `tenacity`.

Заключение урока

Мы рассмотрели фундамент Gemini 3. Главный вывод: перестаньте относиться к модели как к текстовому генератору. Это мультимодальный процессор с памятью (через кэширование).

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