SpyBara
Go Premium

google-vertex-ai.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

2 added, 2 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Google Vertex AI에서 Claude Code 사용하기

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

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return <div className="cc-cs not-prose"> <div className="cc-cs-card"> <div className="cc-cs-text"> Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

<div className="cc-cs-actions"> <a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

필수 요구사항

Vertex AI를 사용하여 Claude Code를 구성하기 전에 다음을 확인하십시오:

자신의 Vertex AI 자격증명으로 로그인하려면 아래의 Vertex AI로 로그인을 따르십시오. 팀 전체에 Claude Code를 배포하려면 수동 설정 단계를 사용하고 롤아웃 전에 모델 버전을 고정하십시오.

Vertex AI로 로그인

Google Cloud 자격증명이 있고 Vertex AI를 통해 Claude Code 사용을 시작하려면 로그인 마법사가 이를 안내합니다. GCP 측 필수 요구사항을 프로젝트당 한 번 완료하면 마법사가 Claude Code 측을 처리합니다.

1

GCP 프로젝트에서 Claude 모델 활성화

프로젝트에 대해 Vertex AI API를 활성화한 다음 Vertex AI Model Garden에서 원하는 Claude 모델에 대한 액세스를 요청합니다. 계정에 필요한 권한은 IAM 구성을 참조하십시오.

2

Claude Code를 시작하고 Vertex AI 선택

claude를 실행합니다. 로그인 프롬프트에서 3rd-party platform을 선택한 다음 Google Vertex AI를 선택합니다.

3

마법사 프롬프트 따르기

Google Cloud에 인증하는 방법을 선택합니다: gcloud의 Application Default Credentials, 서비스 계정 키 파일 또는 환경에 이미 있는 자격증명. 마법사는 프로젝트와 지역을 감지하고, 프로젝트가 호출할 수 있는 Claude 모델을 확인하며, 이를 고정할 수 있게 합니다. 결과를 사용자 설정 파일의 env 블록에 저장하므로 환경 변수를 직접 내보낼 필요가 없습니다.

로그인한 후 언제든지 /setup-vertex를 실행하여 마법사를 다시 열고 자격증명, 프로젝트, 지역 또는 모델 고정을 변경할 수 있습니다.

지역 구성

Claude Code는 Vertex AI 전역, 다중 지역 및 지역 엔드포인트를 지원합니다. CLOUD_ML_REGION을 global, eu 또는 us와 같은 다중 지역 위치 또는 us-east5와 같은 특정 지역으로 설정합니다. Claude Code는 aiplatform.eu.rep.googleapis.com 및 aiplatform.us.rep.googleapis.com 호스트를 포함한 다중 지역 위치에 대해 각 형식에 맞는 올바른 Vertex AI 호스트명을 선택합니다.

수동 설정

마법사 대신 환경 변수를 통해 Vertex AI를 구성하려면(예: CI 또는 스크립트된 엔터프라이즈 롤아웃의 경우) 아래 단계를 따르십시오.

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 인증을 사용합니다.

자세한 내용은 Google Cloud 인증 설명서를 참조하십시오.

Claude Code v2.1.121 이상은 동일한 Application Default Credentials 체인을 통해 X.509 인증서 기반 Workload Identity Federation을 지원합니다. GOOGLE_APPLICATION_CREDENTIALS를 자격증명 구성 파일의 경로로 설정합니다.

고급 자격증명 구성

Claude Code는 gcpAuthRefresh 설정을 통해 GCP에 대한 자동 자격증명 새로 고침을 지원합니다. Claude Code가 GCP 자격증명이 만료되었거나 로드할 수 없음을 감지하면 요청을 다시 시도하기 전에 구성된 명령을 실행하여 새 자격증명을 얻습니다.

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

명령의 출력은 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL을 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 인증 흐름에 적합합니다. 인증이 완료되지 않으면 새로 고침 명령은 3분 후에 시간 초과됩니다. .claude/settings.json과 같은 프로젝트 설정에서 gcpAuthRefresh를 설정하면 워크스페이스 신뢰 프롬프트를 수락한 후에만 명령이 실행됩니다.

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

대부분의 모델 버전에는 해당하는 VERTEX_REGION_CLAUDE_* 변수가 있습니다. 전체 목록은 환경 변수 참조를 참조하십시오. Vertex Model Garden에서 어떤 모델이 전역 엔드포인트를 지원하는지 또는 지역 전용인지 확인하십시오.

Prompt caching은 자동으로 활성화됩니다. 이를 비활성화하려면 DISABLE_PROMPT_CACHING=1을 설정하십시오. 기본 5분 대신 1시간 캐시 TTL을 요청하려면 ENABLE_PROMPT_CACHING_1H=1을 설정하십시오. 1시간 TTL을 사용한 캐시 쓰기는 더 높은 요금으로 청구됩니다. 높은 속도 제한을 위해 Google Cloud 지원팀에 문의하십시오. Vertex AI를 사용할 때 /logout 명령은 Google Cloud 자격증명을 통해 인증이 처리되므로 사용할 수 없습니다.

Claude Code는 MCP tool search를 Vertex AI에서 기본적으로 비활성화합니다. 따라서 모든 MCP 도구 정의는 미리 로드됩니다. Vertex AI는 Claude Sonnet 4.5 이상 및 Claude Opus 4.5 이상에 대해 도구 검색을 지원합니다. 이러한 모델에서 도구 검색을 활성화하려면 ENABLE_TOOL_SEARCH=true를 설정하십시오. Vertex AI의 이전 모델은 필요한 베타 헤더를 허용하지 않으며, 이러한 모델에서 도구 검색을 활성화하면 요청이 실패합니다.

5. 모델 버전 고정

이러한 환경 변수를 특정 Vertex AI 모델 ID로 설정합니다.

ANTHROPIC_DEFAULT_OPUS_MODEL이 없으면 Vertex의 opus 별칭이 Opus 4.6으로 확인됩니다. 최신 모델을 사용하려면 Opus 4.8 ID로 설정합니다:

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

현재 및 레거시 모델 ID는 모델 개요를 참조하십시오. 환경 변수의 전체 목록은 모델 구성을 참조하십시오.

Claude Code는 고정 변수가 설정되지 않았을 때 이러한 기본 모델을 사용합니다:

모델 유형 기본값
주 모델 claude-sonnet-4-5@20250929
소형/빠른 모델 주 모델과 동일

백그라운드 작업(예: 세션 제목 생성)은 소형/빠른 모델(일반적으로 Haiku 클래스 모델)을 사용합니다. Vertex AI에서 Claude Code는 모든 프로젝트 또는 지역에서 Haiku가 활성화되지 않을 수 있으므로 이를 주 모델로 기본 설정합니다. 백그라운드 작업에 Haiku를 사용하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 프로젝트에서 사용 가능한 모델 ID로 설정합니다.

모델을 추가로 사용자 정의하려면:

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

시작 모델 확인

Claude Code가 Vertex AI로 구성되어 시작할 때 사용하려는 모델이 프로젝트에서 액세스 가능한지 확인합니다. 이 확인에는 Claude Code v2.1.98 이상이 필요합니다.

현재 Claude Code 기본값보다 오래된 모델 버전을 고정했고 프로젝트가 최신 버전을 호출할 수 있으면 Claude Code는 고정을 업데이트하라는 메시지를 표시합니다. 수락하면 새 모델 ID를 사용자 설정 파일에 쓰고 Claude Code를 다시 시작합니다. 거절하면 다음 기본 버전 변경까지 기억됩니다.

모델을 고정하지 않았고 현재 기본값을 프로젝트에서 사용할 수 없으면 Claude Code는 현재 세션에 대해 이전 버전으로 폴백하고 알림을 표시합니다. 폴백은 유지되지 않습니다. Model Garden에서 최신 모델을 활성화하거나 버전을 고정하여 선택을 영구적으로 만듭니다.

IAM 구성

필요한 IAM 권한을 할당합니다:

roles/aiplatform.user 역할에는 필요한 권한이 포함됩니다:

더 제한적인 권한의 경우 위의 권한만 포함하는 사용자 정의 역할을 만듭니다.

자세한 내용은 Vertex IAM 설명서를 참조하십시오.

1M 토큰 context window

Claude Sonnet 5, Opus 4.6 이상 및 Sonnet 4.6은 Vertex AI에서 1M 토큰 context window를 지원합니다. Sonnet 5는 항상 1M 윈도우로 실행되며, 선택할 [1m] 변형이 없습니다. 다른 모델의 경우, Claude Code는 1M 모델 변형을 선택할 때 확장된 context window를 자동으로 활성화합니다.

설정 마법사는 모델을 고정할 때 1M context 옵션을 제공합니다. 수동으로 고정된 모델에 대해 대신 활성화하려면 모델 ID에 [1m]을 추가합니다. 자세한 내용은 타사 배포를 위한 모델 고정을 참조하십시오.

문제 해결

"기본 자격증명을 로드할 수 없음" 오류가 발생하는 경우:

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

"모델을 찾을 수 없음" 404 오류가 발생하는 경우:

429 오류가 발생하는 경우:

추가 리소스