Gemini через OpenAI API: миграция в три строки и десять проверок

Google пишет, что для Gemini достаточно изменить API Key, Base URL и Model. Это правда для первого ответа. Для production ещё нужно проверить thinking, Streaming, Tool Calls, ошибки, Usage и то, что ваш Fallback не меняет смысл задачи.

Минимальный Python example

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[
        {"role": "system", "content": "Отвечай кратко и по-русски."},
        {"role": "user", "content": "Объясни hybrid search."},
    ],
)
print(response.choices[0].message.content)

Thinking через reasoning_effort

OpenAI-compatible слой сопоставляет reasoning_effort с Gemini thinking settings. Для моделей Gemini 3 доступны уровни от low до high; thinking нельзя считать одинаковым между семействами.

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    reasoning_effort="low",
    messages=messages,
)

Не ставьте high по умолчанию. Измерьте влияние на качество, output Token и latency.

Десять Contract Tests

1. System Message действительно влияет на ответ.

2. Streaming завершается ожидаемым событием.

3. Usage содержит необходимые поля.

4. JSON Schema выдерживает 100 реальных примеров.

5. Tool Arguments проходят вашу валидацию.

6. Reasoning Effort не ломает бюджет.

7. Изображения передаются в поддерживаемом формате.

8. 429 и 5xx корректно классифицируются.

9. Timeout не запускает необратимый Tool повторно.

10. Model ID логируется в каждом Trace.

Почему Google рекомендует нативный API новым проектам

OpenAI compatibility удобна для миграции существующего клиента. Google прямо рекомендует Gemini API новым приложениям, если OpenAI library ещё не используется. Причина практическая: Interactions API, Grounding, Live и новые Gemini-функции появляются в нативном контракте раньше и полнее.

Совместимый endpoint — мост, а не гарантия доступа ко всем возможностям платформы.

Fallback между Gemini и другими моделями

try:
    return gemini(messages, profile="multimodal_fast")
except TransientError:
    return gateway(messages, profile="multimodal_fast")

Fallback запускается только для transient errors. Плохое качество нужно ловить Eval, а не повторять запрос случайной моделью. Резерв обязан поддерживать изображения, Schema и тот же Data Policy.

OdiRouter.ai можно использовать как единый OpenAI-compatible слой для Gemini и других моделей. Приложение обращается к профилю, а не к Model ID; нативные Gemini-функции остаются отдельным адаптером.

Dual adapter лучше lowest common denominator

Не пытайтесь спрятать весь Gemini за минимальным общим контрактом. Иначе совместимость превращается в добровольный отказ от преимуществ модели.

Перевести первый запрос на Gemini действительно можно тремя строками. Перевести production — значит зафиксировать Contract Tests, правила thinking, нативные возможности и безопасный Fallback.

OpenAI compatibility уменьшает стоимость миграции. Архитектурное мышление уменьшает стоимость следующей миграции.