Vertex AI에서 Claude 호출하기 — Model Garden 활성화부터 첫 응답까지

7월 22, 2026

Claude를 쓰는 방법은 Anthropic에 직접 API 키를 발급받는 것만 있는 게 아니다. 이미 GCP를 쓰고 있다면 Vertex AI를 통해 같은 모델을 호출할 수 있다. 결제가 GCP로 통합되고 인증도 IAM으로 처리되기 때문에, 프로젝트가 GCP 위에 있다면 오히려 이쪽이 관리가 깔끔하다. 이 글에서는 Model Garden에서 Claude 모델을 활성화하고 Python으로 첫 응답을 받아보기까지의 과정을 실제 셋업 순서 그대로 정리한다.

왜 Vertex를 거쳐 Claude를 쓰나 — 직접 API와의 차이

기능적으로 모델 자체는 같다. 차이는 호출 경로와 운영 방식에 있다. 직접 API는 Anthropic 콘솔에서 키를 발급받아 별도 결제 수단으로 쓰는 구조이고, Vertex AI 경유는 GCP 프로젝트의 IAM 권한으로 인증하고 비용도 GCP 청구서에 합산되는 구조다. 공식 문서 기준 토큰 단가는 양쪽이 동일하다.

정리하면 이렇다. API 키를 코드나 서버에 심지 않고 서비스 계정 권한으로 처리하고 싶을 때, 비용을 GCP 결제 하나로 모아 보고 싶을 때, 감사 로그나 조직 정책 같은 GCP 거버넌스를 그대로 적용하고 싶을 때 Vertex 경유가 유리하다. 반대로 최신 기능이 가장 먼저 열리는 곳은 보통 직접 API 쪽이라는 점은 감안해야 한다.

Model Garden에서 Claude 모델 활성화

사전 준비부터 첫 활성화까지의 순서다.

결제 계정이 연결된 GCP 프로젝트를 준비한다.
Vertex AI API를 활성화한다. 콘솔에서 해도 되고 아래처럼 명령으로 해도 된다.
콘솔에서 Vertex AI → Model Garden으로 이동해 검색창에 "Claude"를 입력한다.
쓰려는 모델 카드(예: Claude Sonnet)를 열고 사용 설정(Enable) 버튼을 누른다.
Anthropic 이용약관 동의 화면이 나오면 확인 후 동의한다. 이 절차는 모델별로 한 번씩만 하면 된다.

gcloud services enable aiplatform.googleapis.com --project=your-project-id

사용 설정 버튼이 보이지 않거나 눌리지 않는다면 계정 권한 문제일 가능성이 크다. 프로젝트에 Vertex AI 관련 역할이 있는지부터 확인한다.

인증 — 서비스 계정과 ADC 설정

Vertex 경유의 장점이 여기서 나온다. 별도의 API 키 없이 GCP 인증 체계를 그대로 쓴다. 로컬 개발 환경에서는 애플리케이션 기본 사용자 인증 정보(ADC)를 만들어 두면 SDK가 알아서 집어 쓴다.

gcloud auth application-default login

서버나 CI 환경이라면 서비스 계정을 만들고 Vertex AI 사용자(roles/aiplatform.user) 역할을 부여한다.

gcloud iam service-accounts create llm-caller --project=your-project-id

gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:llm-caller@your-project-id.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

GCE·Cloud Run처럼 GCP 안에서 실행되는 워크로드라면 연결된 서비스 계정 권한만으로 동작하고, 외부 서버라면 키 파일을 만들어 GOOGLE_APPLICATION_CREDENTIALS 환경변수로 지정한다.

첫 호출 코드 (Python)

Anthropic 공식 SDK에 Vertex 전용 클라이언트가 들어 있다. 확장 패키지로 설치한다.

pip install -U "anthropic[vertex]"

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="your-project-id", region="us-east5")

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Vertex AI 경유 호출 테스트입니다. 짧게 인사해 주세요."}],
)

print(message.content[0].text)

응답이 긴 작업이라면 스트리밍도 그대로 지원된다. client.messages.stream()을 with 문으로 열어 텍스트 조각을 순서대로 받는 방식으로, 직접 API와 사용법이 동일하다. 프롬프트 캐싱이나 도구 호출 같은 부가 기능도 공식 문서 기준 대부분 Vertex 경유에서 똑같이 동작하므로, 기능 때문에 경로 선택을 고민할 일은 많지 않다.

직접 API의 Anthropic 클라이언트와 메서드 구조가 같아서, 기존 코드가 있다면 클라이언트 생성부만 바꾸면 거의 그대로 동작한다. 모델 ID는 Model Garden의 모델 카드에 표기된 값을 그대로 쓴다. 최신 모델은 claude-sonnet-5처럼 짧은 형식이고, 이전 세대 모델은 claude-sonnet-4-5@20250929처럼 날짜 접미사가 붙은 형식도 있으니 카드에서 확인하는 것이 정확하다.

리전 선택과 할당량(quota) 주의점

처음 호출할 때 가장 자주 걸리는 부분이 리전이다. Claude 모델은 모든 리전에서 제공되지 않는다. 공식 문서 기준 us-east5, europe-west1 등 일부 리전과, 트래픽을 알아서 분산하는 global 엔드포인트가 제공되며 모델마다 지원 리전이 다르다. 데이터 상주 요건이 없다면 region에 "global"을 지정하는 것이 가용성 면에서 무난하고, 특정 지역 처리가 필요하면 해당 리전을 명시한다.

404/모델 없음 오류: 해당 리전에서 그 모델이 제공되지 않는 경우가 대부분이다. 모델 카드의 지원 리전 목록을 확인한다.
429 오류(할당량 초과): 분당 요청·토큰 할당량은 모델·리전 조합별로 걸려 있다. 콘솔의 IAM 및 관리자 → 할당량 페이지에서 현재 한도를 보고 필요하면 상향을 신청한다.
약관 미동의 오류: Model Garden에서 사용 설정을 건너뛴 경우다. 활성화 절차를 먼저 마친다.

비용이 어디서 집계되는가

Vertex 경유 호출 비용은 Anthropic이 아니라 GCP 결제 계정으로 청구된다. 결제 콘솔의 보고서에서 서비스 필터를 "Vertex AI"로 걸면 확인할 수 있고, SKU 설명에 모델 이름이 포함되어 있어 모델별 지출도 구분된다. 토큰 사용량이 늘어나기 시작하면 결제 데이터를 BigQuery로 내보내 월별 리포트를 자동화하는 것까지 해 두면 관리가 편해진다. 이 부분은 별도 글에서 다룬다.

처음 며칠은 결제 보고서를 일 단위로 열어 보며 예상 금액과 실제 청구가 맞아떨어지는지 확인하는 습관을 들이는 것이 좋다. 호출량이 갑자기 튀는 시점을 빨리 잡을 수 있고, 예산 알림까지 걸어 두면 실수로 반복 호출 루프를 돌려도 피해를 줄일 수 있다. 셋업 자체는 한 시간이 걸리지 않으니, GCP 프로젝트가 이미 있다면 오늘 바로 첫 호출까지 끝내 볼 만하다.

함께 보면 좋은 글: Vertex AI 모델별 토큰 사용량과 비용 추적

※ 이 글의 활성화 절차·지원 리전·모델 ID는 2026년 기준이며 변경될 수 있습니다.

이 블로그 검색

에이븐스튜디오