Google Vertex AI에서 Claude Code 사용하기

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

필수 요구사항

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

​

Vertex AI로 로그인

​

지역 구성

​

수동 설정

​

1. Vertex AI API 활성화

# 프로젝트 ID 설정
gcloud config set project YOUR-PROJECT-ID

# Vertex AI API 활성화
gcloud services enable aiplatform.googleapis.com

​

2. 모델 액세스 요청

1. Vertex AI Model Garden으로 이동합니다
2. “Claude” 모델을 검색합니다
3. 원하는 Claude 모델에 대한 액세스를 요청합니다(예: Claude Sonnet 4.6)
4. 승인을 기다립니다(24-48시간이 소요될 수 있습니다)

​

3. GCP 자격증명 구성

​

고급 자격증명 구성

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

​

4. Claude Code 구성

# Vertex AI 통합 활성화
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 선택사항: 사용자 정의 엔드포인트 또는 게이트웨이를 위해 Vertex 엔드포인트 URL 재정의
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 선택사항: 필요한 경우 prompt caching 비활성화
export DISABLE_PROMPT_CACHING=1

# 선택사항: 기본 5분 대신 1시간 prompt cache TTL 요청
export ENABLE_PROMPT_CACHING_1H=1

# CLOUD_ML_REGION=global일 때, 전역 엔드포인트를 지원하지 않는 모델의 지역 재정의
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

​

5. 모델 버전 고정

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

​

시작 모델 확인

​

IAM 구성

• aiplatform.endpoints.predict - 모델 호출 및 토큰 계산에 필요

​

1M 토큰 context window

​

문제 해결

• gcloud auth application-default login을 실행하여 Application Default Credentials를 설정합니다
• GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 키 파일 경로로 설정합니다
• 모든 옵션은 GCP 자격증명 구성을 참조하세요

• Cloud Console을 통해 현재 할당량을 확인하거나 할당량 증가를 요청합니다

• Model Garden에서 모델이 활성화되어 있는지 확인합니다
• 지정된 위치에서 모델을 사용할 수 있는지 확인합니다. 일부 모델은 특정 지역이 아닌 global 또는 eu 및 us와 같은 다중 지역 위치에서만 제공됩니다
• CLOUD_ML_REGION=global을 사용하는 경우 Model Garden의 “지원되는 기능” 아래에서 모델이 전역 엔드포인트를 지원하는지 확인합니다. 전역 엔드포인트를 지원하지 않는 모델의 경우:
  • ANTHROPIC_MODEL 또는 ANTHROPIC_DEFAULT_HAIKU_MODEL을 통해 지원되는 모델을 지정하거나,
  • VERTEX_REGION_<MODEL_NAME> 환경 변수를 사용하여 지역 또는 다중 지역 위치를 설정합니다

• 지역 엔드포인트의 경우 주 모델과 소형/빠른 모델이 선택한 지역에서 지원되는지 확인합니다
• CLOUD_ML_REGION=global로 전환하여 더 나은 가용성을 고려합니다

​

추가 리소스

• Vertex AI 설명서
• Vertex AI 가격
• Vertex AI 할당량 및 제한