Google Vertex AI

Hermes Agent поддерживает модели Gemini на Google Cloud Vertex AI через OpenAI-совместимый эндпоинт Vertex. В отличие от провайдера Google AI Studio (который использует статический API-ключ для generativelanguage.googleapis.com), Vertex даёт корпоративные лимиты запросов и биллинг/кредиты GCP — это правильный выбор, если вы хотите, чтобы расходы на Gemini списывались с вашего аккаунта Google Cloud, а не с ключа AI Studio.

инфо

Vertex использует OAuth2, а не API-ключ

У Vertex нет статического API-ключа для стандартного эндпоинта. Каждому запросу нужен короткоживущий OAuth2-токен доступа (со сроком жизни около часа), выпущенный либо из JSON сервисного аккаунта, либо из Application Default Credentials (ADC). Hermes сам выпускает такие токены и автоматически обновляет их — вставлять токен вручную не нужно ни разу. Именно поэтому вставка временного токена в поле api_key кастомного провайдера не работает: он истекает прямо посреди сессии.

Предварительные требования

Проект Google Cloud с включённым Vertex AI API и активным биллингом.
Учётные данные, один из вариантов:
- файл-ключ JSON сервисного аккаунта с ролью roles/aiplatform.user, либо
- Application Default Credentials через gcloud auth application-default login (или через сервер метаданных при запуске на GCP VM).
google-auth — устанавливается автоматически при первом выборе Vertex (ленивая установка). Если управляемая установка требует починки, запустите hermes setup.

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

# Вариант A — JSON сервисного аккаунта (рекомендуется для серверов / шлюзов)
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env

# Вариант B — Application Default Credentials (хорош для локальной разработки)
gcloud auth application-default login

# Выбираем Vertex в качестве провайдера
hermes model
# → Выбрать «More providers...» → «Google Vertex AI»
# → Ввести ID проекта GCP (или оставить пустым, чтобы использовать тот, что указан в учётных данных)
# → Выбрать регион (по умолчанию: global)
# → Выбрать модель Gemini

# Начинаем чат
hermes chat

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

Vertex разделяет настройки по степени чувствительности:

Путь к учётным данным — это указатель на секрет, он хранится в ~/.hermes/.env.
ID проекта и регион — не секретные настройки маршрутизации, они хранятся в ~/.hermes/config.yaml.

~/.hermes/.env:

# Один из вариантов (проверяются в этом порядке); если оставить оба пустыми — используется ADC:
VERTEX_CREDENTIALS_PATH=/path/to/service-account.json
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

~/.hermes/config.yaml:

model:
  default: google/gemini-3-flash-preview
  provider: vertex

vertex:
  project_id: my-gcp-project   # пусто → использовать проект, встроенный в учётные данные
  region: global               # для превью Gemini 3.x требуется именно "global"

совет

Переменные окружения имеют приоритет над config.yaml

VERTEX_PROJECT_ID и VERTEX_REGION переопределяют значения vertex.project_id / vertex.region из config.yaml. Используйте их для точечных переопределений в рамках отдельной сессии оболочки; постоянные настройки держите в config.yaml.

Как работает аутентификация

Hermes ищет учётные данные в следующем порядке: VERTEX_CREDENTIALS_PATH → GOOGLE_APPLICATION_CREDENTIALS → ADC.
Он выпускает OAuth2-токен доступа (scope cloud-platform) и кэширует его, обновляя, когда до истечения срока действия остаётся менее 5 минут.
Токен передаётся стандартному OpenAI-клиенту, направленному на эндпоинт Vertex:
```
https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi
```
Для региональных локаций вместо этого используется хост {region}-aiplatform.googleapis.com.
Если сессия длится дольше срока жизни токена и запрос возвращает 401, Hermes автоматически перевыпускает токен и повторяет запрос. На долго работающем шлюзе, если у ADC истёк собственный refresh-токен, Hermes переключается на JSON сервисного аккаунта, если он настроен.

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

Vertex требует префикс вендора google/ в ID моделей. Селектор hermes model предлагает:

Модель	ID
Gemini 3.8 Flash	`google/gemini-3.8-flash`
Gemini 3.7 Flash	`google/gemini-3.7-flash`
Gemini 3.1 Pro Preview	`google/gemini-3.1-pro-preview`
Gemini 3 Pro Preview	`google/gemini-3-pro-preview`
Gemini 3 Flash Preview	`google/gemini-3-flash-preview`
Gemini 3.1 Flash Lite Preview	`google/gemini-3.1-flash-lite-preview`
Gemini 2.5 Pro	`google/gemini-2.5-pro`
Gemini 2.5 Flash	`google/gemini-2.5-flash`

заметка

Регион

global для Gemini 3.x Превью-модели Gemini 3.x обслуживаются через эндпоинт global. Региональные эндпоинты (us-central1 и т. п.) могут отдавать для них 404. Оставляйте region: global, если только у вас нет конкретной причины закрепиться за определённым регионом.

Переключение моделей посреди сессии

/model google/gemini-3-pro-preview
/model google/gemini-3-flash-preview

/model переключается между уже настроенными провайдерами и моделями; новые учётные данные он не собирает. Сначала настройте Vertex командой hermes model.

Reasoning / размышления

Vertex открывает доступ к thinking budget Gemini через OpenAI-совместимый интерфейс. Hermes автоматически транслирует свою настройку reasoning-effort в extra_body.google.thinking_config, так что reasoning_effort работает точно так же, как и на других поверхностях Gemini.

Диагностика

hermes doctor

Doctor сообщает, удаётся ли разрешить учётные данные Vertex (путь к сервисному аккаунту или ADC) и настроен ли провайдер.

Устранение неполадок

«Vertex AI credentials could not be resolved»

Hermes не нашёл ни JSON сервисного аккаунта, ни рабочего ADC. Либо задайте VERTEX_CREDENTIALS_PATH в ~/.hermes/.env, либо выполните gcloud auth application-default login. Если ваш проект не встроен в учётные данные, укажите vertex.project_id в config.yaml.

`google-auth` не установлен

Hermes ставит его лениво при первом выборе провайдера Vertex. Если не получилось, запустите hermes setup, чтобы починить управляемую установку.

404 на моделях Gemini 3.x

Скорее всего, вы находитесь на региональном эндпоинте. Установите region: global в секции vertex: файла config.yaml (или снимите VERTEX_REGION).

403 / отказано в доступе

Сервисному аккаунту (или вашей ADC-идентичности) нужна роль roles/aiplatform.user на проекте, а Vertex AI API должен быть включён для этого проекта.

Смотрите также

Google Gemini (AI Studio) — Gemini со статическим API-ключом без GCP
AWS Bedrock — ещё одна нативная интеграция облачного провайдера
Провайдеры ИИ
Конфигурация