Перейти к основному содержанию

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

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

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

Claude Code можно использовать как с глобальными, так и с региональными конечными точками Vertex AI.
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.6)
  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 ephemeral. Чтобы отключить его, установите DISABLE_PROMPT_CACHING=1. Для повышенных лимитов скорости обратитесь в поддержку Google Cloud. При использовании Vertex AI команды /login и /logout отключены, так как аутентификация обрабатывается через учетные данные Google Cloud.

​
5. Закрепите версии моделей

Закрепите конкретные версии моделей для каждого развертывания. Если вы используете псевдонимы моделей (sonnet, opus, haiku) без закрепления, Claude Code может попытаться использовать более новую версию модели, которая не включена в вашем проекте Vertex AI, что приведет к сбою существующих пользователей при выпуске обновлений Anthropic.
Установите эти переменные окружения на конкретные ID моделей Vertex AI: 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
Для текущих и устаревших ID моделей см. Обзор моделей. Полный список переменных окружения см. в разделе Конфигурация моделей. Claude Code использует эти модели по умолчанию, когда переменные закрепления не установлены:
Тип моделиЗначение по умолчанию
Основная модельclaude-sonnet-4-6
Малая/быстрая модельclaude-haiku-4-5@20251001
Для дальнейшей настройки моделей: 
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

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

Назначьте требуемые разрешения IAM: Роль roles/aiplatform.user включает требуемые разрешения:
  • aiplatform.endpoints.predict - требуется для вызова модели и подсчета токенов
Для более строгих разрешений создайте пользовательскую роль только с указанными выше разрешениями. Для получения дополнительной информации см. документацию Vertex IAM.
Создайте выделенный проект GCP для Claude Code, чтобы упростить отслеживание затрат и контроль доступа.

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

Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5 и Sonnet 4 поддерживают контекстное окно с 1M токенов на Vertex AI. Claude Code автоматически включает расширенное контекстное окно при выборе варианта модели с 1M. Чтобы включить контекстное окно с 1M для вашей закрепленной модели, добавьте [1m] к ID модели. Подробности см. в разделе Закрепите модели для развертываний третьих сторон.

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

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

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