Google Vertex AI의 Claude Code
설정, IAM 구성 및 문제 해결을 포함하여 Google Vertex AI를 통한 Claude Code 구성에 대해 알아보세요.
전제 조건
Vertex AI로 Claude Code를 구성하기 전에 다음 사항이 있는지 확인하세요:
- 청구가 활성화된 Google Cloud Platform (GCP) 계정
- Vertex AI API가 활성화된 GCP 프로젝트
- 원하는 Claude 모델에 대한 액세스 권한 (예: Claude Sonnet 4)
- Google Cloud SDK (
gcloud
)가 설치되고 구성됨 - 원하는 GCP 지역에 할당된 할당량
Vertex AI는 us-east5
가 아닌 지역에서 Claude Code 기본 모델을 지원하지 않을 수 있습니다. us-east5
를 사용하고 할당량이 할당되어 있는지 확인하거나 지원되는 모델로 전환하세요.
설정
1. Vertex AI API 활성화
GCP 프로젝트에서 Vertex AI API를 활성화하세요:
2. 모델 액세스 요청
Vertex AI에서 Claude 모델에 대한 액세스를 요청하세요:
- Vertex AI Model Garden으로 이동
- “Claude” 모델 검색
- 원하는 Claude 모델에 대한 액세스 요청 (예: Claude Sonnet 4)
- 승인 대기 (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 구성
다음 환경 변수를 설정하세요:
프롬프트 캐싱은 cache_control
임시 플래그를 지정할 때 자동으로 지원됩니다. 이를 비활성화하려면 DISABLE_PROMPT_CACHING=1
을 설정하세요. 높은 속도 제한을 위해서는 Google Cloud 지원팀에 문의하세요.
Vertex AI를 사용할 때는 Google Cloud 자격 증명을 통해 인증이 처리되므로 /login
및 /logout
명령이 비활성화됩니다.
5. 모델 구성
Claude Code는 Vertex AI에 대해 다음 기본 모델을 사용합니다:
모델 유형 | 기본값 |
---|---|
기본 모델 | claude-sonnet-4@20250514 |
소형/고속 모델 | claude-3-5-haiku@20241022 |
모델을 사용자 정의하려면:
IAM 구성
필요한 IAM 권한을 할당하세요:
roles/aiplatform.user
역할에는 필요한 권한이 포함되어 있습니다:
aiplatform.endpoints.predict
- 모델 호출에 필요aiplatform.endpoints.computeTokens
- 토큰 계산에 필요
더 제한적인 권한의 경우 위의 권한만으로 사용자 정의 역할을 생성하세요.
자세한 내용은 Vertex IAM 문서를 참조하세요.
비용 추적 및 액세스 제어를 단순화하기 위해 Claude Code 전용 GCP 프로젝트를 생성하는 것을 권장합니다.
문제 해결
할당량 문제가 발생하는 경우:
- Cloud Console을 통해 현재 할당량을 확인하거나 할당량 증가를 요청하세요
“model not found” 404 오류가 발생하는 경우:
- 지정된 지역에 대한 액세스 권한이 있는지 확인하세요
- Model Garden에서 모델이 활성화되어 있는지 확인하세요
429 오류가 발생하는 경우:
- 기본 모델과 소형/고속 모델이 선택한 지역에서 지원되는지 확인하세요