Эта страница переведена с помощью Cloud Translation API.

Интеграция с партнерами и библиотеками

В этом руководстве изложены архитектурные стратегии для создания библиотек, платформ и шлюзов на основе API Gemini. В нем подробно описаны технические компромиссы между использованием официальных SDK GenAI, прямого API (REST/gRPC) и уровня совместимости OpenAI.

Это руководство пригодится, если вы разрабатываете инструменты для других разработчиков, например, для фреймворков с открытым исходным кодом, корпоративных шлюзов или агрегаторов SaaS, и вам необходимо оптимизировать их с точки зрения управления зависимостями, размера пакета или функционального соответствия.

Что такое интеграция с партнерами?

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

Структура экосистемы

Кто вы: Разработчик или сопровождающий фреймворка с открытым исходным кодом (например, LangChain, LlamaIndex, Spring AI) или языкового клиента.
Ваша цель: широкая совместимость. Вы хотите, чтобы ваша библиотека работала в любой среде, выбранной пользователем, без возникновения конфликтов.

Платформа среды выполнения и периферийных устройств

Кто вы: SaaS-платформы, шлюзы искусственного интеллекта или поставщики облачной инфраструктуры (например, Vercel, Cloudflare, Zapier), где выполнение кода происходит в ограниченных средах.
Ваша цель: производительность. Вам необходима низкая задержка, минимальный размер пакета и быстрый холодный запуск.

Агрегатор

Кто вы: Платформы, прокси-серверы или внутренние «моделевые сады», которые стандартизируют доступ ко многим различным поставщикам LLM (например, OpenAI, Anthropic, Google) в единый интерфейс.
Ваша цель: портативность и единообразие.

Корпоративный шлюз

Кто вы: Вы работаете во внутренних командах разработки платформ в крупных компаниях, создавая «золотые пути» для сотен внутренних разработчиков.
Ваша цель: стандартизация, управление и унифицированная аутентификация.

Сравнение с первого взгляда

Глобальная передовая практика: Все партнеры должны отправлять заголовок x-goog-api-client независимо от выбранного пути.

Если вы...	Рекомендуемый путь	Ключевое преимущество	Ключевой компромисс	Передовая практика
Корпоративный шлюз, структура экосистемы	Google GenAI SDK	Вершинная совместимость и скорость. Встроенная обработка типов, аутентификации и сложных функций (например, загрузка файлов). Беспроблемная миграция в Google Cloud.	Вес зависимостей. Транзитивные зависимости могут быть сложными и находиться вне вашего контроля. Ограничено поддерживаемыми языками (Python/Node/Go/Java).	Блокировка версий. Закрепите версии SDK во внутренних базовых образах, чтобы обеспечить стабильность работы между командами.
Структура экосистемы, периферийные платформы и агрегаторы	Прямой API (REST / gRPC)	Отсутствие зависимостей. Вы контролируете HTTP-клиент и точный размер пакета. Полный доступ ко всем функциям API и модели.	Высокие затраты на разработку. JSON-структуры могут быть глубоко вложенными и требуют строгой ручной проверки и проверки типов.	Используйте спецификации OpenAPI. Автоматизируйте генерацию типов, используя наши официальные спецификации, вместо того, чтобы писать их вручную.
Агрегатор, использующий SDK OpenAI, требующие только текстовых рабочих процессов. (Оптимизация для обеспечения переносимости устаревших систем)	совместимость с OpenAI	Мгновенная переносимость. Возможно повторное использование существующего кода или библиотек, совместимых с OpenAI.	Ограничение по функциональности. Функции, специфичные для конкретной модели (встроенное видео, кэширование), могут быть недоступны.	План миграции. Используйте это для быстрой проверки, но для получения полного функционала API планируйте перейти на Direct API.

Интеграция Google GenAI SDK

Что касается фреймворков, то внедрение Google GenAI SDK зачастую является самым простым вариантом, учитывая минимальное количество строк кода на поддерживаемых языках.

Для внутренних команд, занимающихся разработкой платформы, основной задачей часто является «золотой стандарт», позволяющий инженерам-разработчикам быстро продвигаться вперед, соблюдая при этом политики безопасности.

Преимущества:

Единый интерфейс для миграции в Vertex AI: внутренние разработчики часто создают прототипы с использованием ключей API (Gemini API) и развертывают их в Vertex AI (IAM) для соответствия требованиям производственной среды. SDK абстрагирует эти различия в аутентификации. Аналогично, для фреймворков вы можете реализовать один путь выполнения кода и поддерживать два набора пользователей.
Вспомогательные средства на стороне клиента: SDK включает в себя идиоматические утилиты, которые сокращают объем шаблонного кода для сложных задач.
- Примеры: непосредственная поддержка объектов изображений PIL в подсказках, автоматический вызов функций и исчерпывающие типы данных.
Доступ к функциям с первого дня: новые функции API становятся доступны на момент запуска через SDK.
Улучшена поддержка генерации кода: локальная установка SDK предоставляет доступ к определениям типов и строкам документации для помощников программирования (например, Cursor, Copilot). Этот контекст повышает точность генерации кода по сравнению с генерацией необработанных REST-запросов.

Компромисс:

Вес и сложность зависимостей: SDK имеют собственные зависимости, что может увеличить размер пакета и потенциально создать риски для цепочки поставок.
Версионирование: Новые функции API часто привязаны к минимальным версиям SDK. Вам может потребоваться отправлять обновления пользователям для доступа к новым функциям или моделям, что в некоторых случаях может потребовать изменений в транзитивных зависимостях, влияющих на ваших пользователей.
Ограничения протокола: SDK поддерживают только HTTPS для основного API и WebSockets (WSS) для Live API. gRPC не поддерживается с помощью высокоуровневых клиентов SDK.
Поддержка языков: SDK поддерживают текущие версии языков. Если вам необходимо поддерживать версии, поддержка которых прекращена (например, Python 3.9), вам потребуется создать форк.

Передовая практика:

Блокировка версий: зафиксируйте версию SDK во внутренних базовых образах, чтобы обеспечить стабильность работы между командами.

Прямая интеграция API

Если вы распространяете библиотеку среди тысяч разработчиков, работаете в условиях ограниченных ресурсов или создаете агрегатор, которому требуются самые современные функции Gemini, вам может потребоваться интегрироваться с API напрямую, используя REST или gRPC.

Преимущества:

Полный доступ ко всем функциям: в отличие от слоя совместимости OpenAI, прямое использование API позволяет активировать функции Gemini, такие как загрузка файлов через File API, создание кэша контента и использование двустороннего Live API.
Минимальное количество зависимостей: В среде, где зависимости являются важными из-за размера или затрат на аудит, использование API напрямую через стандартную библиотеку, такую как fetch или через обертку, например httpx гарантирует легковесность вашей библиотеки.
Языковая независимость: это единственный путь для языков, не охваченных SDK, таких как Rust, PHP и Ruby, поскольку языковых ограничений нет.
Производительность: Прямой API не требует инициализации, что минимизирует холодные запуски в бессерверных функциях.

Компромисс:

Реализация Vertex AI вручную: В отличие от SDK, прямое использование API не обеспечивает автоматической обработки различий в аутентификации между AI Studio (ключ API) и Vertex AI (IAM). Для поддержки обеих сред необходимо реализовать отдельные обработчики аутентификации.
Отсутствуют встроенные типы или вспомогательные функции: вы не получите автозавершение кода или проверки на этапе компиляции для объектов запросов, если не реализуете их самостоятельно. Клиентских «вспомогательных функций» (например, преобразователей функций в схемы) нет, поэтому вам придется вручную написать эту логику.

Передовая практика

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

Конечная точка: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

Интеграция с SDK OpenAI

Если ваша платформа отдает приоритет единой схеме (завершение чата OpenAI) перед функциями, специфичными для конкретной модели, то это самый быстрый путь.

Преимущества:

Простота использования: Часто поддержку Gemini можно добавить, изменив baseURL и apiKey . Это быстрый способ интегрировать реализации "используй свой собственный ключ", добавляя поддержку Gemini без написания нового кода.
Ограничения: Этот путь рекомендуется только в том случае, если вы ограничены использованием OpenAI SDK и вам не требуются расширенные функции Gemini, такие как File API, или ручное добавление поддержки таких инструментов, как Grounding с помощью Google Search.

Компромисс:

Ограничения функциональности: слой совместимости накладывает ограничения на основные возможности Gemini. Доступные серверные инструменты различаются в зависимости от платформы и могут потребовать ручной обработки для работы с инструментами API Gemini.
Накладные расходы на перевод: Поскольку схема OpenAI не соответствует архитектуре Gemini в соотношении 1:1, использование уровня совместимости вносит некоторые сложности, требующие дополнительной работы по реализации, например, сопоставление инструмента «поиска» пользователя с соответствующим инструментом платформы. Если вам требуется значительное количество специальных случаев, возможно, целесообразнее использовать отдельный SDK или API для каждой платформы.

Передовая практика

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

Передовая практика для всех партнеров: идентификация клиентов.

При обращении к API Gemini в качестве платформы или библиотеки необходимо идентифицировать клиента с помощью заголовка x-goog-api-client .

Это позволяет Google идентифицировать ваши конкретные сегменты трафика, и если ваша библиотека выдает определенный шаблон ошибки, мы можем связаться с вами, чтобы помочь в отладке.

Используйте формат company-product/version (например, acme-framework/1.2.0 ).

Примеры реализации

GenAI SDK

Предоставив API-клиент, SDK автоматически добавит ваш пользовательский заголовок к своим внутренним заголовкам.

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

Прямой API (REST)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

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

Посетите раздел обзора библиотеки , чтобы узнать о комплектах разработки GenAI SDK.
Ознакомьтесь со справочником API.
Ознакомьтесь с руководством по совместимости с OpenAI.