Claude Code 공식문서 리뷰-Deployment[3] : Google Vertex AI의 Claude Code(Claude Code on Google Vertex AI)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [Google Vertex AI의 Claude Code]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/google-vertex-ai

Claude Code on Google Vertex AI - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

GCP를 이미 쓰고 있는가?

회사에서 GCP 인프라를 쓰고 있다면, Claude Code를 Vertex AI로 연동하는 것이 가장 자연스러운 선택이다. 기존 GCP 계정, IAM 정책, 서비스 계정 인증을 그대로 활용할 수 있고, GCP 콘솔에서 비용과 사용량을 통합 관리할 수 있다.

Google Vertex AI란?
GCP에서 제공하는 완전 관리형 AI 플랫폼이다. Claude를 포함한 여러 AI 모델을 GCP 인프라 내에서 사용할 수 있어서, 회사의 보안 정책을 그대로 적용할 수 있다.

Vertex AI를 선택하면 좋은 경우

• 회사에서 이미 GCP를 주력 클라우드로 사용 중
• Google Cloud IAM으로 팀 권한을 관리하고 있음
• GCP Billing으로 비용을 통합 관리하고 싶음
• VPC, 프라이빗 서브넷 등 GCP 보안 정책 준수 필요
• 1M 토큰 컨텍스트 윈도우가 필요함 (Vertex AI 베타 기능)

 

시작하기 전에 준비할 것들

걱정할 필요 없다. 대부분 GCP 사용자라면 이미 갖춰져 있을 항목들이다. 체크리스트처럼 하나씩 확인해 보자.

필수 항목

• GCP 계정 - 결제가 활성화된 계정
  -> GCP 콘솔에서 Vertex AI 메뉴가 보이면 OK
• Claude 모델 접근 권한 - Model Garden에서 Claude Sonnet 4.5 또는 Haiku 4.5 사용 승인
  -> 처음이라면 2단계에서 접근 요청 필요 (24-48시간 소요 가능)
• Google Cloud SDK (gcloud) - 터미널에서 인증 설정에 필요
  -> 터미널에서 gcloud --version 실행하면 확인 가능
• IAM 권한 - Vertex AI API를 호출할 수 있는 권한
  -> 자세한 설정은 아래 "IAM 구성" 섹션 참고

선택 항목 (있으면 편리)

• Cloud Shell - gcloud 로컬 설치 없이 브라우저에서 바로 사용 가능
• Workload Identity Federation - CI/CD 환경에서 키 없이 인증

 

리전 구성 - 어떤 리전을 선택해야 할까?

왜 리전 설정이 중요한가?

모든 리전에서 Claude 모델을 쓸 수 있는 것이 아니다. 특히 글로벌 엔드포인트와 리전 엔드포인트의 차이를 알아두어야 한다.

글로벌 vs 리전 엔드포인트

글로벌 엔드포인트 CLOUD_ML_REGION=global	장점: 여러 리전에서 자동 라우팅, 안정성 높음 단점: 일부 모델(예: Haiku 3.5) 미지원 권장: 대부분의 경우 이 설정으로 시작
리전 엔드포인트 CLOUD_ML_REGION=us-east5	장점: 특정 모델 사용 가능, 데이터 지역 요구사항 충족 단점: 해당 리전 할당량에 영향 받음 권장: 글로벌 엔드포인트에서 미지원 모델 사용 시

특정 모델만 다른 리전에서 사용하기

글로벌 엔드포인트를 기본으로 쓰면서, 특정 모델만 리전 엔드포인트를 사용할 수 있다:

export CLOUD_ML_REGION=global
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

 

설정 프로세스

1단계: Vertex AI API 활성화

처음 GCP에서 Vertex AI를 쓰는가?
GCP 프로젝트에서 Vertex AI API를 활성화해야 한다. 한 번만 하면 된다.

진행 순서

1. 프로젝트 ID 설정

   gcloud config set project YOUR-PROJECT-ID

2. Vertex AI API 활성화

   gcloud services enable aiplatform.googleapis.com

이미 활성화되어 있는지 확인하는 방법

gcloud services list --enabled | grep aiplatform

-> 결과가 나오면 이미 활성화된 것이다.

 

2단계: Model Garden에서 모델 접근 요청

Claude 모델은 Model Garden에서 접근 요청을 해야 한다. 승인까지 24-48시간이 걸릴 수 있으니 미리 신청해두자.

진행 순서

1. GCP 콘솔에서 Vertex AI Model Garden 이동
   -> 검색창에 "Model Garden" 입력
2. "Claude" 검색
   -> Anthropic의 Claude 모델들이 표시된다
3. 원하는 모델 선택 후 "Enable" 클릭
   -> Claude Sonnet 4.5 권장 (기본 모델로 사용됨)
4. 사용 사례 양식 작성
   -> "개발 도구로 사용", "코드 작성 지원" 등 실제 사용 목적을 적으면 된다

승인 속도 높이는 팁

상세한 사용 목적을 작성하면 승인이 빨라질 수 있다. "Claude Code CLI 도구를 통한 개발 생산성 향상" 같이 구체적으로 적어보자.

 

3단계: GCP 자격 증명 구성 - 나에게 맞는 방법 선택하기

어떤 방법을 선택해야 할까?

Claude Code는 Google Cloud 표준 인증 체인을 사용한다. 각자의 상황에 맞는 방법을 아래에서 선택하자.

상황 1: "gcloud CLI가 이미 설정되어 있어요"

개인 개발자이거나 이미 로컬에서 gcloud를 쓰고 있다면 가장 간단한 방법이다.

설정 방법

# 애플리케이션 기본 자격 증명 설정
gcloud auth application-default login

-> 브라우저가 열리고 Google 계정으로 로그인하면 자격 증명이 저장된다.

상황 2: "서비스 계정을 사용해요"

CI/CD 환경이나 자동화된 워크플로우에서 사용할 때 적합하다.

설정 방법

# 서비스 계정 키 파일 경로 설정
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

보안 팁: 서비스 계정 키는 Git에 커밋하지 말자. Secret Manager 사용을 권장한다.

상황 3: "GitHub Actions 등 CI/CD에서 키 없이 사용하고 싶어요"

Workload Identity Federation을 사용하면 서비스 계정 키 없이 인증할 수 있다.

GitHub Actions 예시

- uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: 'projects/123456/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
    service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

상황 4: "일단 빠르게 테스트해보고 싶어요"

Cloud Shell을 사용하면 인증 설정 없이 바로 테스트할 수 있다.

설정 방법

1. GCP 콘솔에서 Cloud Shell 아이콘 클릭
2. Claude Code 설치: npm install -g @anthropic-ai/claude-code
3. 환경 변수 설정 후 바로 사용

-> Cloud Shell은 이미 gcloud 인증이 되어 있어서 추가 설정이 필요 없다.

 

4단계: Claude Code가 Vertex AI를 쓰도록 설정

이 단계에서 하는 일

Claude Code는 기본적으로 Anthropic API를 직접 호출한다. Vertex AI를 사용하려면 "Vertex AI를 통해 호출하라"고 명시적으로 알려줘야 한다.

셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 다음을 추가하자:

# Vertex AI 통합 활성화 (필수)
export CLAUDE_CODE_USE_VERTEX=1

# 리전 설정 (필수)
export CLOUD_ML_REGION=global

# GCP 프로젝트 ID (필수)
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 선택: 글로벌 엔드포인트에서 미지원 모델용 리전 재정의
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

각 설정의 의미

CLAUDE_CODE_USE_VERTEX=1	Claude Code에게 "Vertex AI API를 써라"고 알려준다
CLOUD_ML_REGION=global	어느 리전의 Vertex AI를 쓸지 지정. global 권장
ANTHROPIC_VERTEX_PROJECT_ID	Vertex AI가 활성화된 GCP 프로젝트 ID
VERTEX_REGION_*	특정 모델만 다른 리전에서 사용할 때 (선택 사항)

알아두자

• Vertex AI 사용 시 Claude Code의 /login, /logout 명령은 비활성화된다
  -> Google Cloud 인증 방식으로만 로그인하기 때문
• 프로젝트 ID는 GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT로도 재정의 가능하다

 

5단계: 모델 구성 - 작업에 맞는 모델 선택하기

Sonnet vs Haiku, 어떤 걸 써야 할까?

Claude Code는 상황에 따라 두 가지 모델을 자동으로 전환한다. 직접 선택할 필요는 없지만, 어떻게 동작하는지 알아두면 유용하다.

기본 모델 설정 (자동 선택)

Sonnet 4.5 기본 모델 (복잡한 작업)	언제 사용? 코드 작성, 리팩토링, 복잡한 분석 기본값: claude-sonnet-4-5@20250929
Haiku 4.5 소형/빠른 모델 (빠른 작업)	언제 사용? 파일 탐색, 간단한 검색, 빠른 응답 필요 시 기본값: claude-haiku-4-5@20251001

실제 사용 예시

• Sonnet 사용: "이 함수를 리팩토링해줘", "새로운 API 엔드포인트를 만들어줘"
• Haiku 사용: "이 에러 메시지를 찾아줘", "프로젝트 구조를 보여줘"

커스터마이징: 필요시 모델 변경하기

대부분의 경우 기본 설정으로 충분하다.

하지만 다음과 같은 경우 모델을 직접 지정할 수 있다:

• 특정 버전의 모델을 고정하고 싶을 때
• 비용 절감을 위해 항상 Haiku를 쓰고 싶을 때
• 최신 모델(예: Opus 4.1)을 사용하고 싶을 때

# 커스텀 모델 구성
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

# 선택: 프롬프트 캐싱 비활성화 (캐싱 비용을 피하고 싶을 때)
export DISABLE_PROMPT_CACHING=1

Haiku 3.5에서 4.5 업그레이드 주의

Claude Code는 Haiku 3.5에서 4.5로 자동 업그레이드하지 않는다. 수동으로 업그레이드하려면 다음을 설정하자:

export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

 

1M 토큰 컨텍스트 윈도우 - Vertex AI의 특별 기능

왜 이 기능이 중요한가?

Claude Sonnet 4 및 Sonnet 4.5는 Vertex AI에서 1M (100만) 토큰 컨텍스트 윈도우를 지원한다. 이는 대규모 코드베이스 전체를 한 번에 분석할 수 있다는 의미다.

1M 토큰으로 할 수 있는 것

• 대규모 코드베이스 분석: 수천 개 파일로 구성된 프로젝트 전체를 컨텍스트에 넣고 분석
• 긴 대화 유지: 복잡한 리팩토링 작업을 여러 단계에 걸쳐 진행하면서 맥락 유지
• 문서 전체 참조: 긴 기술 문서나 스펙을 전부 참조하면서 작업

사용 방법

확장된 컨텍스트를 사용하려면 Vertex AI 요청에 베타 헤더를 포함해야 한다:

context-1m-2025-08-07

주의사항

• 현재 베타 상태이며, 정식 출시 전 변경될 수 있다
• 긴 컨텍스트는 비용이 증가할 수 있다 (토큰당 과금)
• 모든 리전에서 지원되지 않을 수 있다 - 글로벌 엔드포인트 권장

 

IAM 권한 설정 - Claude Code가 Vertex AI에 접근하려면?

왜 IAM 설정이 필요한가?

Claude Code가 Vertex AI API를 호출하려면 "이 계정/서비스 계정이 Vertex AI를 쓸 권한이 있다"는 것을 GCP에 증명해야 한다. IAM 역할이 바로 이 권한을 정의하는 것이다.

필요한 IAM 역할

역할	설명
roles/aiplatform.user	Vertex AI 모델 호출 및 예측에 필요한 기본 역할

포함된 권한:

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

역할 부여 방법

# 사용자에게 역할 부여
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
    --member="user:your-email@example.com" \
    --role="roles/aiplatform.user"

# 서비스 계정에 역할 부여
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
    --member="serviceAccount:your-sa@YOUR-PROJECT-ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

보안 팁: 권한을 더 제한하고 싶다면?

더 제한적인 접근을 위해 필요한 권한만 포함된 커스텀 역할을 생성할 수 있다. aiplatform.endpoints.predict 권한만 있으면 Claude Code는 동작한다.

회사에서 사용하는가? 전용 GCP 프로젝트 추천

Claude Code용 GCP 프로젝트를 별도로 만들면 이런 장점이 있다:

• 비용 추적: Claude Code 비용만 따로 확인 가능
• 보안 격리: 다른 GCP 리소스와 분리되어 더 안전
• 권한 관리: Vertex AI만 접근 가능하도록 최소 권한 적용

 

문제 해결 - 자주 겪는 문제와 해결 방법

문제 해결 팁

대부분의 Vertex AI 연동 문제는 리전 설정, 모델 접근 권한, 또는 인증 문제다. 아래 체크리스트를 순서대로 확인해 보자.

문제 1: "Model not found" 404 에러

증상

- "Could not find model..." 에러 발생
- "Model not available in this region" 메시지
- Claude Code가 시작은 되는데 응답이 안 옴

원인

1. Model Garden에서 모델이 활성화되지 않음
2. 해당 리전에서 모델을 지원하지 않음
3. 글로벌 엔드포인트에서 미지원 모델 사용 시도

해결 방법

1. Model Garden에서 모델 활성화 확인
   -> GCP 콘솔 -> Vertex AI -> Model Garden -> Claude 검색 -> Enable 확인
2. 리전 지원 여부 확인
   -> Model Garden의 "Supported features"에서 글로벌 엔드포인트 지원 여부 확인
3. 글로벌 엔드포인트 미지원 시 리전 재정의

   export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

 

문제 2: 429 요청 한도 에러

증상

- "Too many requests" 에러
- "Resource exhausted" 메시지

원인

해당 리전의 할당량(Quota)을 초과했다.

해결 방법

1. 현재 할당량 확인
   -> GCP 콘솔 -> IAM & Admin -> Quotas -> "aiplatform" 검색
2. 할당량 증가 요청
   -> Google Cloud 지원팀에 문의하여 할당량 증가 요청
3. 글로벌 엔드포인트로 전환 고려

   export CLOUD_ML_REGION=global

   -> 글로벌 엔드포인트는 여러 리전에서 자동 라우팅되어 가용성이 높다

 

문제 3: 인증 에러 / Permission Denied

증상

- "Permission denied" 에러
- "Request had insufficient authentication scopes"
- "Unauthenticated" 메시지

해결 방법

1. gcloud 인증 재설정

   gcloud auth application-default login

2. IAM 역할 확인
   -> roles/aiplatform.user 역할이 부여되어 있는지 확인
3. 프로젝트 ID 확인
   -> ANTHROPIC_VERTEX_PROJECT_ID가 올바른지 확인

 

프롬프트 캐싱 관련

프롬프트 캐싱이란?

반복되는 프롬프트를 캐싱하여 비용을 절감하는 기능이다. cache_control 임시 플래그 지정 시 자동 지원된다.

캐싱 비활성화가 필요한 경우:

• 일부 리전에서 캐싱이 지원되지 않는 경우
• 캐싱 관련 에러가 발생하는 경우

export DISABLE_PROMPT_CACHING=1

 

더 알아보기 - 유용한 자료 모음

각 상황에 맞는 자료를 찾아보자

설정 중 막히거나, 더 깊이 알고 싶을 때 참고할 수 있는 공식 문서들이다.

리소스	언제 유용한가?
Vertex AI 문서 Google Cloud 공식 가이드	이럴 때 보자: - Vertex AI가 처음이라 전반적으로 이해하고 싶을 때 - 모델 목록과 각 모델의 성능 비교가 필요할 때 - 보안 설정, VPC 연동 등 심화 내용을 알고 싶을 때
Vertex AI 가격 요금 계산기	이럴 때 보자: - Claude Code 도입 전 예상 비용을 계산하고 싶을 때 - Sonnet vs Haiku 비용 차이를 비교하고 싶을 때 - 프롬프트 캐싱 사용 시 비용 절감 효과를 확인하고 싶을 때
Vertex AI 할당량 할당량 관리 가이드	이럴 때 보자: - 429 에러가 자주 발생할 때 - 팀에서 동시에 많이 사용할 때 할당량 증가 필요 - 각 리전별 할당량 제한을 확인하고 싶을 때

도움이 더 필요한가?

• Google Cloud Support: Vertex AI 관련 기술 문제는 Google Cloud Support 티켓으로 문의
  -> 리전 이슈, IAM 권한 문제, 할당량 증가 요청 등
• Claude Code GitHub: Claude Code 자체의 버그나 기능 요청
  -> https://github.com/anthropics/claude-code

 

핵심 요약 - 설정 체크리스트

빠르게 확인하자

아래 항목들이 제대로 설정되어 있다면 Claude Code를 Vertex AI에서 사용할 준비가 완료된 것이다.

항목	설정 내용
Vertex AI 활성화	export CLAUDE_CODE_USE_VERTEX=1 -> ~/.zshrc 또는 ~/.bashrc에 추가
리전 설정	export CLOUD_ML_REGION=global -> 글로벌 엔드포인트 권장
프로젝트 ID	export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
GCP 인증	다음 중 하나 선택: - gcloud auth application-default login - 서비스 계정 키 (GOOGLE_APPLICATION_CREDENTIALS) - Workload Identity Federation
기본 모델	- Sonnet 4.5: 복잡한 코딩 작업 - Haiku 4.5: 빠른 검색/탐색 -> 자동 선택되므로 별도 설정 불필요
IAM 권한	roles/aiplatform.user -> aiplatform.endpoints.predict 권한 포함
특별 기능	1M 토큰 컨텍스트 윈도우 (베타) -> Vertex AI의 차별화 포인트

다음 단계

모든 설정이 완료되었다면 터미널을 재시작하고 Claude Code를 실행해 보자.

# 터미널 재시작 후
source ~/.zshrc  # 또는 source ~/.bashrc

# Claude Code 실행
claude

# 또는
claude "간단한 Python 함수를 작성해줘"

-> 정상적으로 응답이 오면 성공
-> 에러가 발생하면 위 "문제 해결" 섹션을 참고하자.

Google Vertex AI로 Claude Code를 더 안전하고 효율적으로 사용하자

기존 GCP 인프라와의 통합, IAM 권한 관리, 비용 통합 추적, 그리고 1M 토큰 컨텍스트 윈도우까지.
GCP 사용자라면 Vertex AI가 최적의 선택일 것 이다.