Logo
본문으로 이동
고급12분 소요google-vertex-aigcpenterprise

Google Vertex AI를 통해 Claude Code를 배포하면 GCP 네이티브 인프라에서 IAM 역할, Cloud Audit Logs, GCP Billing을 활용한 비용 추적을 사용할 수 있습니다. 이 가이드는 Vertex AI 통합의 전체 설정 과정을 안내합니다.

사전 요구사항

Google Vertex AI로 Claude Code를 구성하기 전에 다음을 준비해야 합니다.

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

여러 사용자에게 Claude Code를 배포하는 경우, Anthropic이 새 모델을 출시할 때 장애를 방지하기 위해 반드시 모델 버전을 고정해야 합니다.

리전 구성 개요

Claude Code는 Vertex AI 글로벌 엔드포인트와 리전별 엔드포인트 모두를 지원합니다.

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

설정 단계

1단계: Vertex AI API 활성화

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

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

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

2단계: 모델 접근 권한 요청

Vertex AI에서 Claude 모델에 대한 접근 권한을 요청합니다.

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

3단계: GCP 자격증명 구성

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

로컬 개발 환경 (Application Default Credentials):

gcloud auth application-default login

서비스 계정 키 파일 사용:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Workload Identity Federation (권장 - 프로덕션):

Workload Identity Federation을 통해 서비스 계정 키 없이 인증할 수 있습니다. 자세한 내용은 Google Cloud 인증 문서를 참조합니다.

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

Vertex AI를 사용할 때 인증은 Google Cloud 자격증명을 통해 처리되므로 /login 및 /logout 명령은 비활성화됩니다.

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 플래그를 지정할 때 자동으로 지원됩니다. 더 높은 요금 한도가 필요한 경우 Google Cloud 지원팀에 문의하세요.

5단계: 모델 버전 고정

모든 배포에 특정 모델 버전을 고정해야 합니다. 버전을 고정하지 않고 모델 별칭(sonnet, opus, haiku)을 사용하면, Anthropic이 업데이트를 출시할 때 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'

버전 고정 미설정 시 기본 모델:

모델 유형 기본값
기본 모델 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 베타 헤더를 포함시켜야 합니다.

트러블슈팅

할당량(Quota) 문제

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

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

"model not found" 404 오류

이 오류가 발생하는 경우:

  1. Model Garden에서 모델이 활성화되어 있는지 확인합니다.
  2. 지정된 리전에 대한 접근 권한이 있는지 확인합니다.
  3. CLOUD_ML_REGION=global을 사용하는 경우, Model Garden의 "Supported features"에서 모델이 글로벌 엔드포인트를 지원하는지 확인합니다.

글로벌 엔드포인트를 지원하지 않는 모델의 경우:

  • ANTHROPIC_MODEL 또는 ANTHROPIC_SMALL_FAST_MODEL로 지원되는 모델을 지정하거나
  • VERTEX_REGION_<MODEL_NAME> 환경 변수를 사용하여 리전별 엔드포인트를 설정합니다.

429 오류 (요청 한도 초과)

429 오류가 발생하는 경우:

  • 리전별 엔드포인트를 사용하는 경우, 기본 모델과 소형/고속 모델이 선택한 리전에서 지원되는지 확인합니다.
  • 더 나은 가용성을 위해 CLOUD_ML_REGION=global로 전환하는 것을 고려합니다.

추가 리소스

다음 단계

Google Vertex AI 통합을 완료한 후:

  1. 팀 배포: 팀원들에게 GCP 자격증명 설정 및 환경 변수 구성 방법을 안내합니다.
  2. 모델 버전 관리: 정기적으로 새 모델 버전을 검토하고, Model Garden에서 접근 권한을 확인한 후 계획적으로 버전을 업데이트합니다.
  3. 비용 모니터링: GCP Billing을 사용하여 팀별 Vertex AI 사용량을 추적하고 예산 알림을 설정합니다.
  4. 보안 감사: Cloud Audit Logs를 활용하여 Claude Code 사용 패턴을 모니터링하고 보안 정책을 시행합니다.
  5. 엔터프라이즈 배포 전략: 서드파티 통합 및 엔터프라이즈 배포 가이드에서 조직 전체 배포 모범 사례를 참조합니다.

관련 가이드

서드파티 통합 및 엔터프라이즈 배포고급

Claude Code의 서드파티 서비스 통합 및 엔터프라이즈 배포 옵션을 비교하고 조직 요구사항에 맞는 최적의 구성 방법을 알아봅니다.

Amazon Bedrock 통합고급

Amazon Bedrock을 통해 Claude Code를 설정하는 방법을 알아봅니다. IAM 구성, AWS 자격증명 설정, 모델 버전 고정, 트러블슈팅까지 단계별로 안내합니다.

Microsoft Azure AI Foundry 통합고급

Microsoft Azure AI Foundry를 통해 Claude Code를 설정하는 방법을 알아봅니다. Azure 자격증명 구성, RBAC 권한 설정, 모델 버전 고정, 트러블슈팅까지 단계별로 안내합니다.

Google Vertex AI 통합 | Claude Code 가이드 | GodDaeHee | GodDaeHee