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

Перед настройкой 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.

​
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:

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

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