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

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

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

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

​
Настройка

​
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=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

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

# Когда CLOUD_ML_REGION=global, переопределите регион для неподдерживаемых моделей
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Опционально: Переопределите регионы для других конкретных моделей
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-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
Кэширование промптов автоматически поддерживается, когда вы указываете эфемерный флаг 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, чтобы упростить отслеживание затрат и контроль доступа.

​
Контекстное окно 1M токенов

Claude Sonnet 4 поддерживает контекстное окно 1M токенов на Vertex AI.
Контекстное окно 1M токенов в настоящее время находится в бета-версии. Чтобы использовать расширенное контекстное окно, включите бета-заголовок context-1m-2025-08-07 в ваши запросы Vertex AI.

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

Если вы столкнулись с проблемами квот:
  • Проверьте текущие квоты или запросите увеличение квоты через Cloud Console
Если вы столкнулись с ошибками 404 “модель не найдена”:
  • Подтвердите, что модель включена в Model Garden
  • Убедитесь, что у вас есть доступ к указанному региону
  • Если используете CLOUD_ML_REGION=global, проверьте, что ваши модели поддерживают глобальные конечные точки в Model Garden в разделе “Поддерживаемые функции”. Для моделей, которые не поддерживают глобальные конечные точки, либо:
    • Укажите поддерживаемую модель через ANTHROPIC_MODEL или ANTHROPIC_SMALL_FAST_MODEL, или
    • Установите региональную конечную точку, используя переменные окружения VERTEX_REGION_<MODEL_NAME>
Если вы столкнулись с ошибками 429:
  • Для региональных конечных точек убедитесь, что основная модель и малая/быстрая модель поддерживаются в выбранном вами регионе
  • Рассмотрите переключение на CLOUD_ML_REGION=global для лучшей доступности

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