Google Vertex AI에서 Claude Code 사용하기

Google Vertex AI를 통해 Claude Code를 구성하는 방법을 설정, IAM 구성 및 문제 해결을 포함하여 알아봅니다.

사전 요구 사항

Claude Code를 Vertex AI와 함께 구성하기 전에 다음을 준비하세요:

결제가 활성화된 Google Cloud Platform (GCP) 계정
Vertex AI API가 활성화된 GCP 프로젝트
원하는 Claude 모델에 대한 액세스 권한 (예: Claude Sonnet 4.6)
Google Cloud SDK (gcloud) 설치 및 구성 완료
원하는 GCP 리전에 할당된 할당량

참고: Claude Code를 여러 사용자에게 배포하는 경우, Anthropic이 새 모델을 출시할 때 서비스 중단을 방지하기 위해 모델 버전을 고정하세요.

리전 구성

Claude Code는 Vertex AI 글로벌 및 리전 엔드포인트 모두에서 사용할 수 있습니다.

참고: Vertex AI는 모든 리전이나 글로벌 엔드포인트에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 지원되는 리전으로 전환하거나, 리전 엔드포인트를 사용하거나, 지원되는 모델을 지정해야 할 수 있습니다.

설정

1. Vertex AI API 활성화

GCP 프로젝트에서 Vertex AI API를 활성화합니다:

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

2. 모델 액세스 요청

Vertex AI에서 Claude 모델에 대한 액세스를 요청합니다:

Vertex AI Model Garden으로 이동합니다
"Claude" 모델을 검색합니다
원하는 Claude 모델에 대한 액세스를 요청합니다 (예: Claude Sonnet 4.6)
승인을 기다립니다 (24~48시간 소요될 수 있음)

3. GCP 자격 증명 구성

Claude Code는 표준 Google Cloud 인증을 사용합니다.

자세한 내용은 Google Cloud 인증 문서를 참조하세요.

참고: 인증 시 Claude Code는 ANTHROPIC_VERTEX_PROJECT_ID 환경 변수의 프로젝트 ID를 자동으로 사용합니다. 이를 재정의하려면 GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT 또는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수 중 하나를 설정하세요.

4. Claude Code 구성

다음 환경 변수를 설정합니다:

# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1

# When CLOUD_ML_REGION=global, override region for unsupported models
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Optional: Override regions for other specific models
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를 사용할 때는 인증이 Google Cloud 자격 증명을 통해 처리되므로 /login 및 /logout 명령이 비활성화됩니다.

5. 모델 버전 고정

주의: 모든 배포에 대해 특정 모델 버전을 고정하세요. 모델 별칭(sonnet, opus, haiku)을 고정 없이 사용하면, Anthropic이 업데이트를 출시할 때 Claude Code가 Vertex AI 프로젝트에서 활성화되지 않은 최신 모델 버전을 사용하려고 시도하여 기존 사용자에게 문제가 발생할 수 있습니다.

다음 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다:

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 문서를 참조하세요.

참고: 비용 추적 및 액세스 제어를 간소화하기 위해 Claude Code 전용 GCP 프로젝트를 생성하세요.

1M 토큰 컨텍스트 윈도우

Claude Sonnet 4 및 Sonnet 4.6은 Vertex AI에서 1M 토큰 컨텍스트 윈도우를 지원합니다.

참고: 1M 토큰 컨텍스트 윈도우는 현재 베타 단계입니다. 확장된 컨텍스트 윈도우를 사용하려면 Vertex AI 요청에 context-1m-2025-08-07 베타 헤더를 포함하세요.

문제 해결

할당량 문제가 발생하는 경우:

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로 전환하는 것을 고려하세요

추가 리소스

Google Vertex AI에서 Claude Code 사용하기

Google Vertex AI를 통해 Claude Code를 구성하는 방법을 설정, IAM 구성 및 문제 해결을 포함하여 알아봅니다.

사전 요구 사항

Claude Code를 Vertex AI와 함께 구성하기 전에 다음을 준비하세요:

결제가 활성화된 Google Cloud Platform (GCP) 계정
Vertex AI API가 활성화된 GCP 프로젝트
원하는 Claude 모델에 대한 액세스 권한 (예: Claude Sonnet 4.6)
Google Cloud SDK (gcloud) 설치 및 구성 완료
원하는 GCP 리전에 할당된 할당량

참고: Claude Code를 여러 사용자에게 배포하는 경우, Anthropic이 새 모델을 출시할 때 서비스 중단을 방지하기 위해 모델 버전을 고정하세요.

리전 구성

Claude Code는 Vertex AI 글로벌 및 리전 엔드포인트 모두에서 사용할 수 있습니다.

참고: Vertex AI는 모든 리전이나 글로벌 엔드포인트에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. 지원되는 리전으로 전환하거나, 리전 엔드포인트를 사용하거나, 지원되는 모델을 지정해야 할 수 있습니다.

설정

1. Vertex AI API 활성화

GCP 프로젝트에서 Vertex AI API를 활성화합니다:

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

2. 모델 액세스 요청

Vertex AI에서 Claude 모델에 대한 액세스를 요청합니다:

Vertex AI Model Garden으로 이동합니다
"Claude" 모델을 검색합니다
원하는 Claude 모델에 대한 액세스를 요청합니다 (예: Claude Sonnet 4.6)
승인을 기다립니다 (24~48시간 소요될 수 있음)

3. GCP 자격 증명 구성

Claude Code는 표준 Google Cloud 인증을 사용합니다.

자세한 내용은 Google Cloud 인증 문서를 참조하세요.

참고: 인증 시 Claude Code는 ANTHROPIC_VERTEX_PROJECT_ID 환경 변수의 프로젝트 ID를 자동으로 사용합니다. 이를 재정의하려면 GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT 또는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수 중 하나를 설정하세요.

4. Claude Code 구성

다음 환경 변수를 설정합니다:

# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1

# When CLOUD_ML_REGION=global, override region for unsupported models
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Optional: Override regions for other specific models
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

5. 모델 버전 고정

주의: 모든 배포에 대해 특정 모델 버전을 고정하세요. 모델 별칭(sonnet, opus, haiku)을 고정 없이 사용하면, Anthropic이 업데이트를 출시할 때 Claude Code가 Vertex AI 프로젝트에서 활성화되지 않은 최신 모델 버전을 사용하려고 시도하여 기존 사용자에게 문제가 발생할 수 있습니다.

다음 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다:

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 문서를 참조하세요.

참고: 비용 추적 및 액세스 제어를 간소화하기 위해 Claude Code 전용 GCP 프로젝트를 생성하세요.

1M 토큰 컨텍스트 윈도우

Claude Sonnet 4 및 Sonnet 4.6은 Vertex AI에서 1M 토큰 컨텍스트 윈도우를 지원합니다.

참고: 1M 토큰 컨텍스트 윈도우는 현재 베타 단계입니다. 확장된 컨텍스트 윈도우를 사용하려면 Vertex AI 요청에 context-1m-2025-08-07 베타 헤더를 포함하세요.

문제 해결

할당량 문제가 발생하는 경우:

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로 전환하는 것을 고려하세요

33. Google Vertex AI에서 Claude Code 사용하기

Google Vertex AI에서 Claude Code 사용하기

사전 요구 사항

리전 구성

설정

1. Vertex AI API 활성화

2. 모델 액세스 요청

3. GCP 자격 증명 구성

4. Claude Code 구성

5. 모델 버전 고정

IAM 구성

1M 토큰 컨텍스트 윈도우

문제 해결

추가 리소스

33. Google Vertex AI에서 Claude Code 사용하기

Google Vertex AI에서 Claude Code 사용하기

사전 요구 사항

리전 구성

설정

1. Vertex AI API 활성화

2. 모델 액세스 요청

3. GCP 자격 증명 구성

4. Claude Code 구성

5. 모델 버전 고정

IAM 구성

1M 토큰 컨텍스트 윈도우

문제 해결

추가 리소스