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

Перед настройкой Claude Code с Vertex AI убедитесь, что у вас есть:

  • Аккаунт Google Cloud Platform (GCP) с включенной оплатой
  • Проект GCP с включенным API Vertex AI
  • Доступ к желаемым моделям Claude (например, Claude Sonnet 4)
  • Установленный и настроенный Google Cloud SDK (gcloud)
  • Выделенная квота в желаемом регионе GCP

Vertex AI может не поддерживать модели по умолчанию Claude Code в регионах, отличных от us-east5. Убедитесь, что вы используете us-east5 и имеете выделенную квоту, или переключитесь на поддерживаемые модели.

​
Настройка

​
1. Включение API Vertex AI

Включите API Vertex AI в вашем проекте GCP:

# Установите ID вашего проекта
gcloud config set project YOUR-PROJECT-ID

# Включите API Vertex AI
gcloud services enable aiplatform.googleapis.com

​
2. Запрос доступа к модели

Запросите доступ к моделям Claude в Vertex AI:

  1. Перейдите в Vertex AI Model Garden
  2. Найдите модели “Claude”
  3. Запросите доступ к желаемым моделям Claude (например, Claude Sonnet 4)
  4. Дождитесь одобрения (может занять 24-48 часов)

​
3. Настройка учетных данных GCP

Claude Code использует стандартную аутентификацию Google Cloud.

Для получения дополнительной информации см. документацию по аутентификации Google Cloud.

При аутентификации Claude Code автоматически использует ID проекта из переменной окружения ANTHROPIC_VERTEX_PROJECT_ID. Чтобы переопределить это, установите одну из этих переменных окружения: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT или GOOGLE_APPLICATION_CREDENTIALS.

​
4. Настройка Claude Code

Установите следующие переменные окружения:

# Включите интеграцию с Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Опционально: Отключите кэширование промптов при необходимости
export DISABLE_PROMPT_CACHING=1

# Опционально: Переопределите регионы для конкретных моделей
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4

Кэширование промптов автоматически поддерживается, когда вы указываете эфемерный флаг cache_control. Чтобы отключить его, установите DISABLE_PROMPT_CACHING=1. Для повышенных лимитов скорости обратитесь в службу поддержки Google Cloud.

При использовании Vertex AI команды /login и /logout отключены, поскольку аутентификация обрабатывается через учетные данные Google Cloud.

​
5. Конфигурация модели

Claude Code использует эти модели по умолчанию для Vertex AI:

Тип моделиЗначение по умолчанию
Основная модельclaude-sonnet-4@20250514
Малая/быстрая модельclaude-3-5-haiku@20241022

Для настройки моделей:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

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

Назначьте необходимые разрешения IAM:

Роль roles/aiplatform.user включает необходимые разрешения:

  • aiplatform.endpoints.predict - Требуется для вызова модели
  • aiplatform.endpoints.computeTokens - Требуется для подсчета токенов

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

Подробности см. в документации Vertex IAM.

Мы рекомендуем создать выделенный проект GCP для Claude Code, чтобы упростить отслеживание затрат и контроль доступа.

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

Если вы столкнулись с проблемами квот:

  • Проверьте текущие квоты или запросите увеличение квоты через Cloud Console

Если вы столкнулись с ошибками 404 “модель не найдена”:

  • Убедитесь, что у вас есть доступ к указанному региону
  • Подтвердите, что модель включена в Model Garden

Если вы столкнулись с ошибками 429:

  • Убедитесь, что основная модель и малая/быстрая модель поддерживаются в выбранном вами регионе

​
Дополнительные ресурсы