Обзор

Vertex AI — унифицированная ML-платформа Google, предоставляющая доступ к моделям Gemini, Anthropic Claude и другим сторонним LLM через единый API. Meridian выполняет следующие преобразования:

• Мультимодельная поддержка — единый интерфейс для Gemini, Anthropic и сторонних моделей;
• OAuth2-аутентификация — credentials сервисного аккаунта с автоматическим обновлением токенов;
• Управление project и region — автоматическое формирование endpoint'а из GCP project/region;
• Маршрутизация моделей — автоматическое определение провайдера (Gemini vs Anthropic) по имени модели;
• Конвертация запросов — преобразование в формат базового провайдера (Gemini или Anthropic);
• Поддержка embeddings — генерация векторов с опциями task type и truncation;
• Discovery моделей — пагинированный листинг моделей с информацией о развёртываниях.

Поддерживаемые операции

Beta-заголовки

Для моделей Anthropic на Vertex AI Meridian валидирует заголовки anthropic-beta и удаляет неподдерживаемые из запроса.

Поддерживаются: computer-use-*, compact-*, context-management-*, interleaved-thinking-*, context-1m-*.

Не поддерживаются: structured-outputs-*, advanced-tool-use-*, mcp-client-*, prompt-caching-scope-*, files-api-*, skills-*, fast-mode-*, redact-thinking-*.

Дефолты можно переопределить на уровне провайдера через вкладку Beta Headers в настройках провайдера или через beta_header_overrides в настройке провайдера. Полная матрица поддержки — на странице Anthropic.

1. Chat Completions

Параметры запроса

Маппинг основных параметров

Key configuration

Key configuration для Vertex требует Google Cloud credentials:

{
  "vertex_key_config": {
    "project_id": "my-gcp-project",
    "region": "us-central1",
    "auth_credentials": "{service-account-json}"
  }
}

Параметры конфигурации:

• project_id — GCP project ID (обязателен);
• region — GCP-регион для API endpoint'ов (обязателен). Примеры: us-central1, us-west1, eu-west1, global;
• auth_credentials — JSON credentials сервисного аккаунта (опционально при использовании default credentials).

Методы аутентификации

1. Service Account JSON (рекомендуется для production):

   {"auth_credentials": "{full-service-account-json}"}

2. Application Default Credentials (для локальной разработки):

   • Требуется переменная окружения GOOGLE_APPLICATION_CREDENTIALS;
   • Поле auth_credentials оставляется пустым.

Модели Gemini

При использовании моделей Gemini Meridian конвертирует запросы в формат Gemini API.

Маппинг параметров для Gemini

Все Gemini-совместимые параметры поддерживаются. Особая обработка:

• System prompts — конвертируются в формат system message для Gemini;
• Использование tools — маппится в формат function calling Gemini;
• Streaming — используется протокол стриминга Gemini.

Подробности конвертации — на странице Gemini.

Модели Anthropic (Claude)

При использовании моделей Anthropic через Vertex AI Meridian конвертирует запросы в message-формат Anthropic.

Маппинг параметров для Anthropic

Поддерживаются все стандартные параметры Anthropic:

• Reasoning/Thinking — параметры reasoning конвертируются в структуру thinking;
• System messages — извлекаются и помещаются в отдельное поле system;
• Группировка tool-сообщений — подряд идущие tool-сообщения объединяются;
• API version — автоматически устанавливается vertex-2023-10-16 для моделей Anthropic.

Подробности конвертации — на странице Anthropic.

Особенности Vertex + Anthropic

• Responses API использует специальный endpoint /v1/messages;
• anthropic_version автоматически выставляется в vertex-2023-10-16;
• Минимальный бюджет reasoning — 1024 токена;
• Поле model удаляется из запроса (Vertex использует другую идентификацию).

Выбор региона

Регион определяет API endpoint:

Доступность зависит от региона. Проверяйте доступность моделей в документации GCP.

Streaming

Формат streaming зависит от типа модели:

• Модели Gemini — стандартный streaming Gemini через server-sent events;
• Модели Anthropic — формат message streaming Anthropic.

2. Responses API

Responses API доступен и для моделей Anthropic (Claude), и для Gemini на Vertex AI.

Параметры запроса

Маппинг основных параметров

Модели Gemini

Для моделей Gemini конвертация следует формату Responses API Gemini.

Модели Anthropic (Claude)

Для моделей Anthropic конвертация следует message-формату Anthropic:

• instructions становится system-сообщением;
• reasoning маппится в структуру thinking.

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

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vertex/claude-3-5-sonnet",
    "input": "What is AI?",
    "instructions": "You are a helpful assistant",
    "project_id": "my-gcp-project",
    "region": "us-central1"
  }' \
  -H "X-Goog-Authorization: Bearer {token}"

Особенности обработки

• Endpoint: /v1/messages (формат Anthropic);
• anthropic_version автоматически выставляется в vertex-2023-10-16;
• Поля model и region удаляются из запроса;
• Поддерживается passthrough сырого тела запроса.

Подробности параметров — в Anthropic Responses API.

3. Embeddings

Embeddings поддерживаются для Gemini и других моделей, поддерживающих генерацию embedding'ов.

Параметры запроса

Основные параметры

Расширенные параметры

Для embedding-специфичных опций используйте extra_params:

curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "input": ["text to embed"],
    "dimensions": 256,
    "task_type": "RETRIEVAL_DOCUMENT",
    "title": "Document title",
    "project_id": "my-gcp-project",
    "region": "us-central1",
    "autoTruncate": true
  }'

Embedding-параметры

Эффект task type

Разные task types оптимизируют embedding под конкретные кейсы:

• RETRIEVAL_DOCUMENT — для документов в retrieval-системах;
• RETRIEVAL_QUERY — для запросов, ищущих документы;
• SEMANTIC_SIMILARITY — для задач семантического сходства;
• CLASSIFICATION — для классификации;
• CLUSTERING — для кластеризации.

Конвертация ответа

Ответ embeddings включает векторы и информацию о truncation:

{
  "embeddings": [
    {
      "values": [0.1234, -0.5678, ...],
      "statistics": {
        "token_count": 15,
        "truncated": false
      }
    }
  ]
}

Поля ответа:

• values — embedding-вектор в виде float'ов;
• statistics.token_count — число входных токенов;
• statistics.truncated — был ли вход усечён из-за длины.

4. Image Generation

Image Generation поддерживается для Gemini и Imagen на Vertex AI. Провайдер автоматически выбирает формат по типу модели.

Параметры запроса

Маппинг основных параметров

Определение типа модели

Vertex автоматически определяет тип модели и применяет соответствующую конвертацию:

1. Модели Gemini — формат Gemini (как Gemini Image Generation);
2. Модели Imagen — формат Imagen (определяется через IsImagenModel()).

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

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vertex/imagen-4.0-generate-001",
    "prompt": "A sunset over the mountains",
    "size": "1024x1024",
    "n": 2,
    "project_id": "my-gcp-project",
    "region": "us-central1"
  }' \
  -H "X-Goog-Authorization: Bearer {token}"

Конвертация запроса

Vertex конвертирует запрос по типу модели:

• Модели Gemini — используется gemini.ToGeminiImageGenerationRequest() (та же конвертация, что и для стандартного Gemini);
• Модели Imagen — используется gemini.ToImagenImageGenerationRequest() (Imagen-специфичный формат с конвертацией size/aspect ratio).

Все тела запроса конвертируются в map[string]interface{}, поле region удаляется перед отправкой в Vertex API.

Конвертация ответа

• Модели Gemini — ответы конвертируются через GenerateContentResponse.ToBifrostImageGenerationResponse() (как стандартный Gemini);
• Модели Imagen — ответы конвертируются через GeminiImagenResponse.ToBifrostImageGenerationResponse() (Imagen-специфичный формат).

Выбор endpoint

Провайдер автоматически выбирает endpoint по типу модели:

• Fine-tuned модели: /v1beta1/projects/{projectNumber}/locations/{region}/endpoints/{deployment}:generateContent;
• Модели Imagen: /v1/projects/{projectID}/locations/{region}/publishers/google/models/{model}:predict;
• Модели Gemini: /v1/projects/{projectID}/locations/{region}/publishers/google/models/{model}:generateContent.

Streaming

Streaming генерации изображений не поддерживается Vertex AI.

5. Image Edit

Image Edit поддерживается для моделей Gemini и Imagen на Vertex AI. Провайдер автоматически выбирает формат по типу модели.

Параметры запроса

Конвертация запроса

Vertex использует те же функции конвертации, что и Gemini:

1. Модели Gemini — gemini.ToGeminiImageEditRequest() (та же конвертация, что и для стандартного Gemini);
2. Модели Imagen — gemini.ToImagenImageEditRequest() (Imagen-специфичный формат с маппингом режима редактирования и конфигурацией маски).

Валидация моделей: поддерживаются только Gemini и Imagen. Остальные возвращают ConfigurationError.

Обработка тела запроса:

• Все тела запроса конвертируются в map[string]interface{} для совместимости с Vertex API;
• Поле region удаляется перед отправкой в Vertex API;
• Для моделей Gemini неподдерживаемые поля удаляются через stripVertexGeminiUnsupportedFields() (удаляет id из function_call и function_response).

Конвертация ответа

• Модели Gemini — ответы конвертируются через GenerateContentResponse.ToBifrostImageGenerationResponse() (как стандартный Gemini);
• Модели Imagen — ответы конвертируются через GeminiImagenResponse.ToBifrostImageGenerationResponse() (Imagen-специфичный формат).

Выбор endpoint

Провайдер автоматически выбирает endpoint по типу модели:

• Модели Gemini: /v1/projects/{projectID}/locations/{region}/publishers/google/models/{model}:generateContent;
• Модели Imagen: /v1/projects/{projectID}/locations/{region}/publishers/google/models/{model}:predict.

Streaming

Streaming редактирования изображений не поддерживается Vertex AI.

Image Variation

Image variation не поддерживается Vertex AI.

6. List Models

Параметры запроса

Не требуются. Автоматически используются project_id и region из key config.

Конвертация ответа

Возвращает модели, доступные в указанных project/region, с метаданными и информацией о развёртывании:

{
  "models": [
    {
      "name": "projects/{project}/locations/{region}/models/gemini-2.0-flash",
      "display_name": "Gemini 2.0 Flash",
      "description": "Fast multimodal model",
      "version_id": "1",
      "version_aliases": ["latest", "stable"],
      "capabilities": [...],
      "deployed_models": [...]
    }
  ],
  "next_page_token": "..."
}

Custom vs Non-Custom модели

Чтобы обеспечить полный листинг моделей, Meridian выполняет многопроходный discovery:

Трёхпроходный discovery моделей

1. Первый проход — кастомные модели из ответа API

   • Запрос к List Models API Vertex AI;
   • Возвращаются только кастомные fine-tuned модели, развёрнутые в проекте;
   • Кастомные модели определяются по deployment-значению, состоящему только из цифр;
   • Пример: "deployment": "1234567890".

2. Второй проход — non-custom модели из deployments

   • Добавляются стандартные foundation-модели из конфигурации deployments;
   • Non-custom модели имеют алфавитно-цифровые значения deployment (например, gemini-pro, claude-3-5-sonnet);
   • Фильтруются по allowedModels, если задано;
   • Пример: "deployment": "gemini-2.0-flash".

3. Третий проход — allowed-модели, отсутствующие в deployments

   • Добавляются модели из allowedModels, отсутствующие в deployments;
   • Гарантируется, что все явно разрешённые модели попадают в список;
   • В качестве значения deployment используется само имя модели;
   • Идентификаторы моделей только из цифр пропускаются (зарезервированы для кастомных).

Логика фильтрации моделей

• allowedModels пуст: включаются все модели со всех трёх проходов;
• allowedModels непуст: включаются только модели/deployments с ключами из allowedModels;
• Защита от дублирования: каждый model ID отслеживается, чтобы избежать дублей между проходами.

Форматирование имён моделей

Non-custom модели из deployments и allowed-моделей автоматически форматируются для отображения:

• gemini-pro → "Gemini Pro";
• claude-3-5-sonnet → "Claude 3 5 Sonnet";
• gemini_2_flash → "Gemini 2 Flash".

Используется title case, дефисы и подчёркивания заменяются на пробелы.

Пример конфигурации

{
  "vertex_key_config": {
    "project_id": "my-project",
    "region": "us-central1",
    "deployments": {
      "my-gemini-ft": "1234567890",
      "my-claude-ft": "9876543210"
    }
  }
}

{
  "vertex_key_config": {
    "project_id": "my-project",
    "region": "us-central1",
    "deployments": {
      "gemini-2.0-flash": "gemini-2.0-flash",
      "claude-3-5-sonnet": "claude-3-5-sonnet-v2@20241022"
    }
  }
}

{
  "vertex_key_config": {
    "project_id": "my-project",
    "region": "us-central1",
    "deployments": {
      "gemini-2.0-flash": "gemini-2.0-flash",
      "claude-3-5-sonnet": "claude-3-5-sonnet-v2@20241022",
      "gemini-1.5-pro": "gemini-1.5-pro"
    },
    "allowedModels": ["gemini-2.0-flash", "claude-3-5-sonnet"]
  }
}

Пагинация

Листинг моделей пагинируется автоматически. Если моделей больше 100, появится next_page_token. Meridian обрабатывает пагинацию внутренне.

Нюансы

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

HTTP-настройки: OAuth2-аутентификация с автоматическим обновлением токенов | регион-специфичные endpoint'ы | Max Connections 5000 | Max Idle 60 секунд.

Scope: https://www.googleapis.com/auth/cloud-platform.

Формат endpoint: https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/{resource}.

Примечание: для региона global endpoint имеет вид https://aiplatform.googleapis.com/v1/projects/{project}/locations/global/{resource}.

Setup и конфигурация

Vertex AI требует настройки project, выбора региона и Google Cloud-аутентификации. Подробная инструкция по настройке Vertex AI (Web UI, API, config.json) — на странице Настройка провайдеров.

Video Generation

Vertex AI маршрутизирует video generation через модели Veo (Gemini) на endpoint predictLongRunning. Все параметры идентичны Gemini Video Generation.

Поддерживаемые операции