Claude Models on Google Cloud (Google managed)

Claude Models on Google Cloud에서는 두 가지 Google Cloud 제품을 비교합니다. 또한 어떤 제품을 사용하고 있는지 확인하는 방법도 보여줍니다.

API 호출 전 준비 사항

Claude Models on Google Cloud (Google managed)를 사용하려면 다음이 필요합니다:

1. Agent Platform을 사용할 수 있는 Google Cloud 프로젝트. 설정 단계는 Google Cloud의 Anthropic Claude models on Agent Platform 페이지를 참조하세요.
2. 로컬 개발을 위해 설치된 gcloud CLI.
3. 호출을 수행하는 ID에 대해 aiplatform.endpoints.predict 권한을 포함하는 IAM 역할(예: Agent Platform User(roles/aiplatform.user)). 자세한 내용은 Google Cloud의 Agent Platform partner models 페이지를 참조하세요.
4. 해당 ID의 Google Cloud 자격 증명. SDK 예제의 경우 Google Cloud에 인증하기 위해 gcloud auth application-default login을 실행해야 할 수 있습니다. Claude Models on Google Cloud (Google managed)의 cURL 예제는 gcloud auth print-access-token으로 토큰을 가져옵니다. 이 명령은 Application Default Credentials가 아닌 gcloud CLI 자체의 로그인을 사용합니다. 해당 예제를 사용하려면 먼저 gcloud auth login 또는 gcloud init을 실행하세요.

SDK 설치

Anthropic의 클라이언트 SDK는 AnthropicVertex를 통해 Claude Models on Google Cloud (Google managed)를 지원합니다. 이를 제공하는 패키지를 설치하세요:

pip install -U "anthropic[vertex]"

ant CLI는 Claude Models on Google Cloud (Google managed)를 지원하지 않습니다.

요청 보내기

Claude Models on Google Cloud (Google managed)에 대한 요청은 :rawPredict로 끝나는 Agent Platform 엔드포인트 URL로 전송됩니다. 스트리밍 요청은 대신 :streamRawPredict를 사용합니다.

요청은 Messages API 요청과 거의 동일합니다. 주요 차이점은 두 가지입니다:

• 모델: 엔드포인트 URL이 모델을 지정합니다. cURL 요청에서는 본문에서 model을 생략하세요.
• 버전: cURL 요청에서는 anthropic_version을 헤더가 아닌 본문에 전달하세요. 값은 vertex-2023-10-16 또는 API 버전 2026-10-21로 설정하세요.

다음 예제는 글로벌 엔드포인트를 사용합니다. 다른 엔드포인트 유형은 글로벌, 멀티 리전 및 리전 엔드포인트를 참조하세요.

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-5-5",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

API 모델 ID

Claude Models on Google Cloud (Google managed)는 리전마다 서로 다른 Claude 모델을 제공합니다. 리전에서 제공하는 모델을 확인하려면 Model Garden에서 "Claude"를 검색하거나 Google Cloud의 Anthropic Claude models on Agent Platform 페이지를 참조하세요.

Google은 Claude Models on Google Cloud (Google managed)가 제공하는 모델의 수명 주기 날짜를 설정합니다. 이 날짜는 Claude API 일정과 다를 수 있습니다. 모델의 현재 종료 날짜는 Google Cloud의 Anthropic Claude models on Agent Platform 페이지를 참조하세요. 지원 중단(Deprecated)과 종료(Retired)의 의미는 모델 지원 중단을 참조하세요.

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

Claude Models on Google Cloud (Google managed)는 세 가지 엔드포인트 유형을 제공합니다. 클라이언트를 생성할 때 전달하는 리전 값으로 유형을 선택합니다. cURL 요청에서는 엔드포인트 유형이 호스트와 URL의 locations 세그먼트를 결정합니다.

엔드포인트 유형은 요청을 보내는 위치가 다릅니다:

• 글로벌: 요청이 가용 용량이 있는 모든 리전으로 전송됩니다. 최대 가용성을 원하고 데이터 레지던시가 유연한 경우에 사용하세요.
• 멀티 리전: 요청이 미국("us") 또는 유럽 연합("eu") 내의 모든 리전으로 전송됩니다. 넓은 지역 내 데이터 레지던시와 단일 리전보다 높은 가용성이 필요한 경우에 사용하세요.
• 리전: 요청이 "us-east5" 또는 "europe-west1"과 같이 지정한 리전으로만 전송됩니다. 단일 리전 데이터 레지던시가 필요하거나 엄격한 규정 준수 요건을 충족해야 하는 경우에 사용하세요.

멀티 리전 및 리전 엔드포인트는 글로벌 엔드포인트보다 비용이 10% 더 높습니다. 세 가지 엔드포인트 유형 모두 종량제 트래픽을 처리하며, 프로비저닝된 처리량에는 리전 엔드포인트가 필요합니다.

리전 엔드포인트는 Claude Sonnet 4.6 및 이전 모델만 제공합니다. 최신 모델의 경우 글로벌 또는 멀티 리전 엔드포인트를 사용하세요.

다음 예제는 us 멀티 리전 엔드포인트를 사용합니다. 강조 표시된 줄이 리전을 설정합니다. 글로벌 엔드포인트에 대한 전체 요청은 요청 보내기를 참조하세요.

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)

기능 지원

Claude Models on Google Cloud (Google managed)에서 지원되는 기능은 다음과 같습니다:

• Messages API
• 프롬프트 캐싱
• Thinking
• 다음 도구를 포함한 도구 사용:
  • Bash 도구
  • 브라우저 사용 도구
  • 컴퓨터 사용 도구
  • 메모리 도구
  • 텍스트 편집기 도구
  • 웹 검색 도구
• 인용
• 구조화된 출력

기능 개요에는 모든 기능과 Claude Models on Google Cloud (Google managed)의 지원 여부가 나열되어 있습니다.

지원되지 않는 기능

Claude Models on Google Cloud (Google managed)는 다음을 지원하지 않습니다:

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

서버 측 폴백 대신 클라이언트 측 폴백 패턴을 사용하세요.

컨텍스트 윈도우

Claude Models on Google Cloud (Google managed)는 다음 모델에 대해 1M 토큰 컨텍스트 윈도우를 제공합니다:

• Claude Fable 5.1
• Claude Fable 5
• Claude Opus 5.5
• Claude Opus 5
• Claude Opus 4.8
• Claude Opus 4.7
• Claude Opus 4.6
• Claude Sonnet 5.5
• Claude Sonnet 5
• Claude Sonnet 4.6
• Claude Haiku 5.5

다른 Claude 모델은 200k 토큰 컨텍스트 윈도우를 가집니다. 여기에는 Claude Sonnet 4.5(지원 중단)와 Claude Sonnet 4(지원 중단)가 포함됩니다.

Agent Platform은 요청 페이로드를 30MB로 제한합니다. 대용량 문서나 많은 이미지를 보내는 경우 토큰 제한보다 먼저 이 제한에 도달할 수 있습니다.

청구, 속도 제한 및 로깅

속도 제한

Google Cloud는 Claude Models on Google Cloud (Google managed)의 속도 제한과 할당량을 관리합니다. 할당량 증가를 요청하는 방법을 포함한 자세한 내용은 Google Cloud의 Quotas for Anthropic Claude models 페이지를 참조하세요.

청구

Google Cloud가 Claude Models on Google Cloud (Google managed) 사용 요금을 청구합니다. 가격은 Google Cloud의 Generative AI pricing 페이지를 참조하세요. 가격은 엔드포인트 유형에 따라서도 달라집니다. 글로벌, 멀티 리전 및 리전 엔드포인트를 참조하세요.

데이터 보존

Google Cloud가 Claude Models on Google Cloud (Google managed)의 데이터 처리를 관리합니다. 자세한 내용은 Agent Platform and zero data retention을 참조하세요.

모니터링 및 로깅

Claude Models on Google Cloud (Google managed)의 프롬프트와 완성 결과를 기록하려면 Agent Platform의 요청-응답 로깅 서비스를 사용하세요.

Anthropic은 최소 최근 30일간의 로그를 보관할 것을 권장합니다. 로그는 활동을 파악하고 잠재적인 오용을 조사하는 데 도움이 됩니다.

Claude Models on Google Cloud (Anthropic managed)에서 마이그레이션

이전 시 변경되는 사항은 두 Google Cloud 제품의 차이점을 참조하세요. Claude Models on Google Cloud (Google managed)로 이전하려면 다음 단계를 따르세요:

1. 1

   액세스 설정

   프로젝트와 호출을 수행하는 ID가 API 호출 전 준비 사항의 요구 사항을 충족하는지 확인하세요.

2. 2

   SDK 패키지 설치

   Claude Models on Google Cloud (Google managed)용 클라이언트를 제공하는 패키지를 설치하세요. SDK 설치를 참조하세요.

3. 3

   import 및 클라이언트 교체

   클라이언트를 import하고 생성하는 코드를 변경하세요. AnthropicGoogleCloud 대신 AnthropicVertex를 사용하세요. cURL 요청에는 새 URL, 새 헤더, 새 본문이 필요합니다. 다음 코드는 현재 사용 중인 Claude Models on Google Cloud (Anthropic managed)용 클라이언트를 생성합니다:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   from anthropic import AnthropicGoogleCloud
   
   client = AnthropicGoogleCloud()

   다음 코드는 Claude Models on Google Cloud (Google managed)용 클라이언트를 생성합니다. 글로벌 엔드포인트를 사용합니다. 다른 엔드포인트 유형은 글로벌, 멀티 리전 및 리전 엔드포인트를 참조하세요.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   from anthropic import AnthropicVertex
   
   project_id = "MY_PROJECT_ID"
   region = "global"
   
   client = AnthropicVertex(project_id=project_id, region=region)

   이 코드는 클라이언트를 생성할 때 프로젝트 ID와 리전을 전달합니다. MY_PROJECT_ID를 프로젝트 ID로 바꾸세요. 클라이언트로 수행하는 Messages API 호출은 그대로 유지됩니다. 예외는 다음 단계의 모델 ID와 기능입니다.

4. 4

   모델 ID 및 기능 확인

   • 모델 ID: Claude 4.6 이전 모델을 사용하는 경우 ID에서 스냅샷 날짜 앞의 하이픈을 @로 바꾸세요. 예를 들어 claude-haiku-4-5-20251001은 claude-haiku-4-5@20251001이 됩니다. 모델과 해당 ID는 API 모델 ID를 참조하세요.
   • 기능: 코드에서 사용하는 기능이 지원되지 않는 기능에 나열되어 있지 않은지 확인하세요.
5. 5

   테스트 요청 실행

   요청 보내기의 요청을 실행하여 설정이 작동하는지 확인하세요. 그런 다음 자체 코드를 실행하세요. 프로덕션 트래픽을 이전하기 전에 Claude Models on Google Cloud (Google managed)의 속도 제한에 대해 읽어 보세요.

다음 단계