Google Gemini

Hermes Agent поддерживает Google Gemini как нативный провайдер — через Google AI Studio / Gemini API, а не через OpenAI-совместимый эндпоинт. Это позволяет Hermes транслировать свой внутренний цикл агента с OpenAI-образными сообщениями и инструментами в нативный API Gemini generateContent, сохраняя вызов инструментов, стриминг, мультимодальные входы и специфические метаданные ответов Gemini.

Требования

• API-ключ Google AI Studio — создайте на aistudio.google.com/apikey
• Google Cloud проект с включённой оплатой — рекомендуется для использования с агентом. Бесплатный тир Gemini слишком мал для долгих агентских сессий: Hermes может делать несколько вызовов модели на один ход пользователя.
• Установленный Hermes — дополнительные Python-пакеты для нативного провайдера Gemini не нужны.

Быстрый старт

# Добавьте API-ключ Gemini
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# Выберите Gemini в качестве провайдера
hermes model
# → Choose "More providers..." → "Google AI Studio"
# → Hermes проверяет тир ключа и показывает модели Gemini
# → Выберите модель

# Начните общение
hermes chat

Если предпочитаете редактировать конфиг напрямую, используйте нативный базовый URL Gemini API:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Конфигурация

После запуска hermes model файл ~/.hermes/config.yaml будет содержать:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

А в ~/.hermes/.env:

GOOGLE_API_KEY=...

Нативный Gemini API

Рекомендуемый эндпоинт:

https://generativelanguage.googleapis.com/v1beta

Hermes распознаёт этот эндпоинт и создаёт нативный адаптер Gemini. Внутри агентский цикл Hermes по-прежнему работает с OpenAI-образными сообщениями, а потом транслирует каждый запрос в нативную схему Gemini:

• messages[] → Gemini contents[]
• системные промпты → Gemini systemInstruction
• схемы инструментов → Gemini functionDeclarations
• результаты инструментов → Gemini functionResponse parts
• потоковые ответы → OpenAI-образные чанки стрима для цикла Hermes

Массивы типов в параметрах инструментов — вида "type": ["number", "null"] — переводятся в принятую у Gemini форму «скалярный тип плюс nullable». Объединения из нескольких типов сохраняют все варианты через anyOf, включая вложенные свойства и элементы массивов. Всё это происходит само: ни MCP-сервер, ни конфигурацию провайдера менять не нужно.

Предпочитайте нативный эндпоинт

Google также предоставляет OpenAI-совместимый эндпоинт:

https://generativelanguage.googleapis.com/v1beta/openai/

Для агентских сессий Hermes предпочтительнее нативный эндпоинт Gemini. Hermes включает нативный адаптер Gemini — он напрямую отображает многоходовое использование инструментов, результаты вызовов инструментов, стриминг, мультимодальные входы и метаданные ответов Gemini на generateContent API. OpenAI-совместимый эндпоинт полезен, когда специально нужна совместимость с OpenAI API.

Если раньше вы задавали GEMINI_BASE_URL в URL /openai — удалите это или измените:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Базовые URL, указывающие на корень хоста Google, нормализуются сами: если адрес не заканчивается сегментом версии API (v1beta, v1alpha, v1, …), Hermes добавит /v1beta за вас, так что GEMINI_BASE_URL=https://generativelanguage.googleapis.com работает так же, как адрес с явным суффиксом /v1beta. Та же нормализация действует для базового URL Gemini TTS (tts.gemini.base_url). Запросы чата идут по нативному пути Gemini только тогда, когда базовый URL указывает на generativelanguage.googleapis.com или на хост экспресс-режима Vertex AI (см. ниже); прокси на другом хосте считается OpenAI-совместимым эндпоинтом — настраивайте его через URL в стиле /openai.

Ключи экспресс-режима Vertex AI

Теперь Google выдаёт ключи с префиксом AQ.… и для Google AI Studio, и для экспресс-режима Vertex AI (старый формат ключей Studio AIza… постепенно выводится), так что по префиксу ключа больше нельзя понять, к какой поверхности он относится. Hermes никогда не перенаправляет запросы по виду ключа: поверхность определяет настроенный базовый URL. Для хоста AI Studio по умолчанию задайте GEMINI_API_KEY и оставьте GEMINI_BASE_URL пустым; для ключа экспресс-режима Vertex AI задайте GEMINI_BASE_URL равным https://aiplatform.googleapis.com (с /v1beta1 или без), и Hermes дополнит его до формы publishers/google. Каждая поверхность принимает только свои ключи: 403 PERMISSION_DENIED обычно значит, что ключ и хост перепутаны, и Hermes добавляет к ошибке подсказку с названием другой поверхности. Базовый URL на любом другом хосте (прокси) никогда не переписывается. Экспресс-ключи не имеют отношения к провайдеру Vertex AI на основе OAuth, которому API-ключ не нужен.

Доступные модели

Список моделей Gemini в hermes model поддерживается в реестре провайдеров Hermes. Распространённые варианты:

Доступность моделей меняется. Если модель исчезла или недоступна для вашего ключа — запустите hermes model снова и выберите из актуального списка.

Плавающие алиасы

Google публикует плавающие алиасы для семейств Pro и Flash Gemini. gemini-pro-latest и gemini-flash-latest удобны, если хотите, чтобы Google автоматически продвигал модель вперёд без изменений конфига Hermes. Учтите: если новые модели вводят другие тарифы, ваши расходы на использование могут измениться.

model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Если нужна строгая воспроизводимость — используйте явные ID моделей, например gemini-3.1-pro-preview или gemini-3.7-flash.

Gemma через Gemini API

Google также предоставляет модели Gemma через Gemini API. Hermes распознаёт их как Google-модели, но скрывает записи Gemma с очень низкой пропускной способностью из списка по умолчанию, чтобы новые пользователи случайно не выбрали оценочную модель для долгих агентских сессий.

Полезные ID для оценки:

Эти модели лучше воспринимать как оценочные опции для ключей Gemini API. Ценообразование Google Gemma API только бесплатное, а лимиты использования низкие по сравнению с продакшеновыми моделями Gemini, поэтому при устойчивом использовании Hermes-агента обычно стоит переходить на платную модель Gemini, самостоятельно развёрнутый (self-hosted) вариант или на другого провайдера с подходящей квотой.

Чтобы использовать модель Gemma, скрытую из списка, задайте её напрямую:

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Смена модели в ходе сессии

Используйте команду /model прямо в разговоре:

/model gemini-3.7-flash
/model gemini-flash-latest
/model gemini-3.1-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

Если Gemini ещё не настроен — выйдите из сессии и сначала запустите hermes model. Команда /model переключает между уже настроенными провайдерами и моделями; новые API-ключи она не запрашивает.

Диагностика

hermes doctor

Команда doctor проверяет:

• Наличие GOOGLE_API_KEY или GEMINI_API_KEY
• Возможность разрешить учётные данные настроенного провайдера

Шлюз (платформы мессенджеров)

Gemini работает со всеми платформами шлюза Hermes (Telegram, Discord, Slack, WhatsApp, LINE, Feishu и другими). Настройте Gemini как провайдер, затем запустите шлюз как обычно:

hermes gateway setup
hermes gateway start

Шлюз считывает config.yaml и использует ту же конфигурацию провайдера Gemini.

Решение проблем

«Gemini native client requires an API key»

Hermes не нашёл подходящего API-ключа. Добавьте один из вариантов в ~/.hermes/.env:

GOOGLE_API_KEY=...
# или
GEMINI_API_KEY=...

Затем снова запустите hermes model.

«This Google API key is on the free tier»

Hermes проверяет API-ключи Gemini при настройке. Квоты бесплатного тира могут исчерпаться после нескольких ходов агента: вызов инструментов, повторные попытки, сжатие и вспомогательные задачи требуют нескольких вызовов модели.

Включите оплату на Google Cloud проекте, привязанном к ключу, при необходимости перегенерируйте ключ, затем запустите:

hermes model

«404 model not found»

Выбранная модель недоступна для вашего аккаунта, региона или ключа. Снова запустите hermes model и выберите другую модель Gemini из актуального списка.

Модель Gemma не отображается в hermes model

Hermes может скрывать из списка модели Gemma с низкой пропускной способностью. Если вы намеренно хотите её оценить — задайте ID модели напрямую в ~/.hermes/config.yaml.

«429 quota exceeded» для Gemma

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

Настроен OpenAI-совместимый эндпоинт

Проверьте ~/.hermes/.env на наличие:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

Измените на нативный эндпоинт или удалите переопределение:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Вызов инструментов завершается с ошибками схемы

Обновите Hermes и снова запустите hermes model. Нативный адаптер Gemini очищает схемы инструментов под строгий формат объявлений функций Gemini; старые сборки или кастомные эндпоинты могут не делать этого.

Связанная документация

• AI-провайдеры
• Конфигурация
• Резервные провайдеры
• AWS Bedrock — нативная интеграция с облачным провайдером через учётные данные AWS