Google Cloud에서 Claude 설정하기(Anthropic 관리형)

Claude Models on Google Cloud(Anthropic 관리형)를 사용하면 자체 Google Cloud 프로젝트를 통해 Claude를 호출할 수 있습니다. Anthropic이 Claude API를 운영합니다. Google Cloud는 액세스를 처리하므로 Google 자격 증명으로 로그인합니다. 프로젝트가 설정되고 계정에 액세스 권한이 부여되면 몇 줄의 Python 코드로 첫 응답을 받을 수 있습니다.

사용 중인 서비스 확인하기

Google Cloud는 Claude를 두 가지 서비스로 제공하며, 각각 설정 방법이 다릅니다. 여기서 설명하는 단계는 Anthropic 관리형을 위한 것입니다. 다른 서비스는 Google 관리형으로, Google Cloud's Agent Platform의 일부로 Google이 Claude 모델을 운영합니다. 어떤 서비스를 사용하고 있는지 확인하려면 아래 표에서 이미 가지고 있는 항목을 찾으세요.

가지고 있는 것이 Google 관리형을 가리키는 경우 대신 Google Cloud에서 Claude 설정하기(Google 관리형)를 따르세요.

필요한 것과 비용

시작하기 전에 다음이 필요합니다:

• Google Cloud 프로젝트
• 설치된 gcloud CLI
• Python 3.10 이상

gcloud CLI를 막 설치했다면 gcloud auth login 또는 gcloud init으로 로그인하세요. 이는 gcloud CLI 자체의 로그인이며, "본인에게 액세스 권한 부여하기"의 2단계에서 필요합니다. SDK 클라이언트가 사용하는 Application Default Credentials는 3단계에서 다루는 별도의 로그인입니다.

이 서비스는 API 키를 사용하지 않으므로 Anthropic API 키가 필요하지 않습니다.

사용량은 요금이 청구되며, 이 서비스의 SDK 클라이언트는 베타 버전입니다. 청구는 Google Cloud Marketplace를 통해 이루어지므로 요금은 Google Cloud 청구서에 표시되며 Anthropic은 별도의 청구서를 보내지 않습니다. 여기서 보내는 한 번의 요청에도 요금이 부과됩니다.

아래 명령어는 자리표시자 값을 사용합니다. my-project-id는 프로젝트 ID로, you@example.com은 Google 계정으로, wrkspc_01AbCdEf23GhIj는 워크스페이스 ID로 바꾸세요. 워크스페이스 ID는 다음 섹션에서 설명합니다.

프로젝트를 한 번 준비하기

설정을 진행하면 Google Cloud 프로젝트에 대한 새 Anthropic 조직이 생성됩니다. 이는 회사에서 이미 보유하고 있는 Anthropic 조직과는 별개입니다. 새 조직은 기본 워크스페이스인 Default Workspace 하나로 시작하며, 이 서비스를 호출하는 모든 사람에게 해당 워크스페이스의 ID가 필요합니다.

일반적으로 관리자가 이 부분을 수행합니다. 관리자가 이미 완료했다면 워크스페이스 ID를 요청하고 "본인에게 액세스 권한 부여하기"로 넘어가세요.

기존 할인이 적용되고 있다면 시작하기 전에 Anthropic 또는 Google Cloud 계정 담당자에게 문의하세요. 할인은 과거 사용량에는 적용할 수 없습니다.

그런 다음 문서의 계정 설정하기 단계를 따르세요. 이 섹션에는 필요한 권한이 나열되어 있습니다. 이 단계는 Google Cloud Marketplace에서 구독하는 것부터 wrkspc_로 시작하는 워크스페이스 ID를 복사하는 것까지 안내합니다. ID를 개발자에게 전달하세요.

Marketplace 구독은 한 번만 진행하면 되므로, 다른 프로젝트를 추가하려면 해당 프로젝트에서 2단계부터 단계를 반복하세요. 단계가 실패하면 계정 설정 문제 해결을 참조하세요.

본인에게 액세스 권한 부여하기

Claude를 호출하는 각 개발자는 자신의 터미널에서 다음 단계를 순서대로 수행합니다.

1. gcloud에서 프로젝트를 설정합니다.

   bash

   gcloud config set project my-project-id

   gcloud가 사용 중인 프로젝트를 확인하려면 gcloud config get-value project를 실행하세요.

2. 계정에 roles/claude.user 역할을 부여합니다. 호출을 수행하는 ID에는 프로젝트에 대한 이 역할이 필요합니다.

   bash

   gcloud projects add-iam-policy-binding \
     my-project-id \
     --member="user:you@example.com" \
     --role="roles/claude.user"

   이 명령어를 실행하려면 프로젝트의 IAM 정책을 변경할 수 있는 권한이 필요합니다. 권한이 없다면 관리자에게 본인 계정에 대해 이 명령어를 실행해 달라고 요청하세요.

3. Application Default Credentials(ADC)로 로그인합니다. SDK 클라이언트는 ADC에서 Google 액세스 토큰을 가져옵니다. 로컬 개발의 경우 다음 명령어를 실행하세요:

   bash

   gcloud auth application-default login

   ADC가 작동하는지 확인하려면 gcloud auth application-default print-access-token을 실행하세요.

4. 두 개의 환경 변수를 설정합니다. SDK 클라이언트에는 프로젝트 ID와 워크스페이스 ID가 필요합니다.

   bash

   export ANTHROPIC_GOOGLE_CLOUD_PROJECT="my-project-id"
   export ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID="wrkspc_01AbCdEf23GhIj"

첫 응답 받아보기

Python에서 보낸 한 번의 요청으로 전체 설정이 제대로 작동하는지 확인할 수 있습니다. 두 변수를 설정한 터미널에 그대로 머물러 있으세요.

1. Google Cloud 추가 기능과 함께 SDK를 설치합니다.

   bash

   pip install -U "anthropic[google_cloud]"

2. 이 파일을 first_reply.py로 저장합니다. 이 코드는 클라이언트를 생성하며, 클라이언트가 Google 자격 증명을 자체적으로 확인합니다. 그런 다음 요청을 하나 보내고 돌아온 결과를 출력합니다.

   python

   from anthropic import AnthropicGoogleCloud
   
   client = AnthropicGoogleCloud()
   
   message = client.messages.create(
       model="claude-opus-5-5",
       max_tokens=1024,
       messages=[{
           "role": "user",
           "content": "Hello, Claude",
       }],
   )
   print(message)

3. 파일을 실행합니다.

   bash

   python first_reply.py

   전체 메시지가 터미널에 출력되며, Claude의 응답은 content에 들어 있습니다. 대신 오류가 발생하면 다음 섹션으로 이동하세요.

응답이 의도한 프로젝트를 통해 도착했는지 확인하세요. 클라이언트는 ANTHROPIC_GOOGLE_CLOUD_PROJECT에서 프로젝트 ID를 읽습니다. 같은 터미널에서 echo "$ANTHROPIC_GOOGLE_CLOUD_PROJECT"를 실행하세요. 이 값은 본인 또는 관리자가 준비한 프로젝트의 ID여야 합니다. gcloud에 설정된 프로젝트는 다른 프로젝트일 수 있으므로 변수를 확인하세요.

SDK 없이 동일한 요청을 확인하려면 cURL 샘플을 참조하세요.

첫 요청이 실패하는 경우

흔히 발생하는 두 가지 오류는 권한 오류와 사용할 수 없는 모델 오류입니다.

클라이언트가 워크스페이스 ID가 누락되었다고 표시하면, "본인에게 액세스 권한 부여하기"의 4단계와 같이 이 터미널에서 두 변수를 다시 설정하세요. 속도 제한의 경우 Anthropic 지원팀에 문의하세요.

권한 오류

Google Cloud는 호출자에게 권한이 없을 때 HTTP 403 오류를 반환합니다. 호출 중인 프로젝트에서 다음 두 가지를 확인하세요:

• claude.googleapis.com이 활성화되어 있는지 확인합니다. gcloud services list --enabled --project=my-project-id를 실행하여 해당 이름을 찾으세요.
• 계정에 roles/claude.user 또는 roles/claude.admin이 있는지 확인합니다.

새로 부여된 권한이나 새로 활성화된 서비스는 적용되기까지 약간의 시간이 걸릴 수 있습니다. 두 확인 사항이 모두 통과되면 잠시 기다린 후 first_reply.py를 다시 실행하세요.

사용할 수 없는 모델

오류 메시지는 Model {model} is not available for this organization's inference configuration.로 표시됩니다. 이는 Anthropic 조직에서 사용할 수 없는 모델을 요청할 때 발생합니다. 모델 및 모델 ID를 조회할 수 있으며, 모델 및 API 오류를 포함하여 Claude 자체는 Anthropic 지원팀이 처리합니다.

모든 Claude API 샘플 실행하기

이 서비스에서 Claude API 샘플을 실행하려면 import와 클라이언트 생성자를 교체하세요. 이 서비스는 Claude API와 동일한 모델 ID를 사용하므로 모델 ID는 그대로 유지됩니다. 이 서비스가 지원하지 않는 기능을 사용하는 샘플은 실행되지 않으므로, 먼저 짧은 지원되지 않는 기능 목록을 확인하세요.

Claude API용으로 작성된 샘플이 다음과 같다고 가정해 보겠습니다:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": "Hello, Claude",
    }],
)
print(message)

교체 후에는 import와 클라이언트만 변경됩니다:

from anthropic import AnthropicGoogleCloud

client = AnthropicGoogleCloud()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": "Hello, Claude",
    }],
)
print(message)

새 클라이언트가 차이점을 알아서 처리하므로 교체만으로 충분합니다. 이 서비스에 대한 요청은 Claude API 요청과 세 가지 측면에서 다릅니다.

클라이언트는 프로젝트, 위치, 워크스페이스 ID로부터 다음과 같은 형태로 기본 URL을 생성합니다:

https://claude.googleapis.com/v1/projects/{project}/locations/global/workspaces/{workspace}/invoke

다음 단계

다음으로 Claude Platform 101을 수강하세요. 이 과정에서는 messages, max_tokens, 모델이 무엇인지 배웁니다. 그런 다음 Messages API를 사용한 도구 사용을 수강하세요.

이 과정이나 문서에서 샘플이 anthropic.Anthropic() 클라이언트를 생성할 때마다 실행하기 전에 import와 클라이언트를 교체하세요. API 키를 가져오거나 저장하거나 크레딧을 확인하는 단계는 건너뛰세요. 이 서비스는 API 키를 사용하지 않고 Google Cloud를 통해 청구되기 때문입니다. 일부 레슨은 TypeScript를 사용하며, 문서에는 각 언어별 패키지와 클라이언트가 나열되어 있습니다.

필요할 때 다음 주제를 문서에서 확인할 수 있습니다:

• Google 관리형에서 마이그레이션하기
• 고객 관리형 암호화 키(CMEK)
• 모니터링 및 로깅
• 속도 제한