Vertex AI에서 Claude 사용하기

Claude에 액세스하기 위한 Vertex API는 Messages API와 거의 동일하지만, 요청 형식에서 두 가지 주요 차이점이 있습니다:

• Vertex에서는 model이 요청 본문에 전달되지 않습니다. 대신 Google Cloud 엔드포인트 URL에 지정됩니다.
• Vertex에서는 anthropic_version이 헤더가 아닌 요청 본문에 전달되며, 반드시 vertex-2023-10-16 값으로 설정되어야 합니다.

Vertex는 Anthropic의 공식 클라이언트 SDK에서도 지원됩니다. 이 가이드는 Anthropic의 클라이언트 SDK 중 하나를 사용하여 Vertex AI에서 Claude에 요청을 보내는 방법을 안내합니다.

이 가이드는 Vertex AI를 사용할 수 있는 GCP 프로젝트가 이미 있다고 가정합니다. 필요한 설정 및 전체 안내에 대한 자세한 내용은 Vertex AI의 Anthropic Claude 모델을 참조하세요.



Vertex AI 액세스를 위한 SDK 설치

먼저 원하는 언어에 맞는 Anthropic의 클라이언트 SDK를 설치하세요.



Vertex AI 액세스



모델 가용성

Anthropic 모델 가용성은 리전에 따라 다릅니다. 최신 정보는 Vertex AI Model Garden에서 "Claude"를 검색하거나 Anthropic Claude 모델을 참조하세요.



API 모델 ID

수명 주기 용어(Deprecated, Retired)는 모델 지원 중단에 정의되어 있습니다. 파트너가 운영하는 플랫폼의 수명 주기 날짜는 파트너가 설정하며 Claude API 일정과 다를 수 있습니다. Vertex AI에서 각 모델의 현재 종료 날짜는 Vertex AI의 Claude 모델에 대한 Google Cloud 문서를 참조하세요.



요청 보내기

요청을 실행하기 전에 GCP 인증을 위해 gcloud auth application-default login을 실행해야 할 수 있습니다.

다음 예제는 Vertex AI에서 Claude로부터 텍스트를 생성하는 방법을 보여줍니다:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "global"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

자세한 내용은 클라이언트 SDK 및 공식 Vertex AI 문서를 참조하세요.

Claude는 Amazon Bedrock, AWS의 Claude Platform, Microsoft Foundry를 통해서도 사용할 수 있습니다.



데이터 보존

이 서비스의 데이터 처리는 Google Cloud Vertex AI의 정책을 따릅니다. 자세한 내용은 Vertex AI 및 제로 데이터 보존을 참조하세요.



활동 로깅

Vertex는 고객이 사용과 관련된 프롬프트 및 완성 결과를 로깅할 수 있는 요청-응답 로깅 서비스를 제공합니다.

Anthropic은 활동을 파악하고 잠재적인 오용을 조사할 수 있도록 최소 30일 롤링 기준으로 활동을 로깅할 것을 권장합니다.



기능 지원

Vertex AI 가용성을 포함한 전체 기능 목록은 기능 개요를 참조하세요.



지원되는 주요 기능

• Messages API
• 프롬프트 캐싱
• 확장 사고
• 도구 사용 — Bash 도구, 컴퓨터 사용 도구, 메모리 도구, 텍스트 편집기 도구 포함
• 웹 검색 도구
• 인용
• 구조화된 출력



지원되지 않는 기능

• 입력 소스(이미지 및 문서용 URL 소스, Files API)
• 서버 측 도구(코드 실행, 웹 가져오기, advisor)
• 에이전트 인프라(Agent Skills, MCP 커넥터, 프로그래밍 방식 도구 호출)
• API 엔드포인트(Message Batches, Models, Admin, Compliance, Usage and Cost)
• Claude Managed Agents
• 서버 측 폴백(fallbacks 매개변수; 대신 클라이언트 측 폴백 패턴을 사용하세요)



컨텍스트 윈도우

Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6은 Vertex AI에서 100만 토큰 컨텍스트 윈도우를 제공합니다. Sonnet 4.5 및 Sonnet 4(지원 중단됨)를 포함한 다른 Claude 모델은 20만 토큰 컨텍스트 윈도우를 제공합니다.

Vertex AI는 요청 페이로드를 30MB로 제한합니다. 대용량 문서나 많은 이미지를 전송할 때 토큰 제한에 도달하기 전에 이 제한에 도달할 수 있습니다.



글로벌, 멀티 리전 및 리전별 엔드포인트

Vertex AI는 세 가지 엔드포인트 유형을 제공합니다:

• 글로벌 엔드포인트: 최대 가용성을 위한 동적 라우팅
• 멀티 리전 엔드포인트: 높은 가용성과 함께 데이터 상주를 위해 지리적 영역(예: 미국 또는 유럽 연합) 내에서 동적 라우팅
• 리전별 엔드포인트: 특정 지리적 리전을 통한 데이터 라우팅 보장

리전별 및 멀티 리전 엔드포인트는 글로벌 엔드포인트 대비 10%의 가격 프리미엄이 적용됩니다.



각 옵션을 사용해야 하는 경우

글로벌 엔드포인트(권장):

• 최대 가용성 및 가동 시간 제공
• 가용 용량이 있는 리전으로 요청을 동적으로 라우팅
• 가격 프리미엄 없음
• 데이터 상주가 유연한 애플리케이션에 가장 적합
• 종량제 트래픽만 지원(프로비저닝된 처리량은 리전별 엔드포인트 필요)

멀티 리전 엔드포인트:

• 지리적 영역(현재 us 및 eu) 내의 리전 간에 요청을 동적으로 라우팅
• 광범위한 지리적 영역 내에서 데이터 상주가 필요하지만 단일 리전보다 높은 가용성을 원할 때 유용
• 글로벌 엔드포인트 대비 10% 가격 프리미엄
• 종량제 트래픽만 지원(프로비저닝된 처리량은 리전별 엔드포인트 필요)

리전별 엔드포인트:

• 특정 지리적 리전을 통해 트래픽 라우팅
• 단일 리전 데이터 상주, 엄격한 규정 준수 요구 사항 또는 프로비저닝된 처리량에 필요
• 종량제 및 프로비저닝된 처리량 모두 지원
• 10% 가격 프리미엄은 전용 리전 용량에 대한 인프라 비용을 반영



구현

글로벌 엔드포인트 사용(권장):

클라이언트를 초기화할 때 region 매개변수를 "global"로 설정하세요:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "global"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

멀티 리전 엔드포인트 사용:

region 매개변수를 멀티 리전 식별자로 설정하세요: 미국의 경우 "us", 유럽 연합의 경우 "eu". SDK는 요청을 해당 멀티 리전 엔드포인트(https://aiplatform.us.rep.googleapis.com 또는 https://aiplatform.eu.rep.googleapis.com)로 라우팅하며, 이 엔드포인트는 해당 지리적 영역 내의 리전 간에 트래픽을 동적으로 분산합니다.

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us"  # Multi-region identifier: "us" or "eu"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

리전별 엔드포인트 사용:

"us-east1" 또는 "europe-west1"과 같은 특정 리전을 지정하세요:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us-east1"  # Specify a specific region

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)



추가 리소스

• Vertex AI 가격: cloud.google.com/vertex-ai/generative-ai/pricing
• Claude 모델 문서: Vertex AI의 Claude
• Google 블로그 게시물: Claude 모델용 글로벌 엔드포인트
• Anthropic 가격 세부 정보: 클라우드 플랫폼 가격