在 Google Cloud 上设置 Claude（Anthropic 托管）

Google Cloud 上的 Claude Models（Anthropic 托管）让您可以通过自己的 Google Cloud 项目调用 Claude。 Anthropic 负责运营 Claude API。Google Cloud 负责处理访问权限，因此您需要使用 Google 凭据登录。项目设置完成且您的账户获得访问权限后，只需几行 Python 代码即可获得第一条回复。

检查您拥有的服务

Google Cloud 以两种服务的形式提供 Claude，每种服务都有各自的设置方式。这里的步骤适用于 Anthropic 托管。另一种服务是 Google 托管，Google 在其中作为 Google Cloud's Agent Platform 的一部分运营 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 步中进行。

您不需要 Anthropic API 密钥，因为此服务不使用 API 密钥。

用量会计费，并且该服务的 SDK 客户端目前处于测试版阶段。 计费通过 Google Cloud Marketplace 进行，因此费用会出现在您的 Google Cloud 账单中，Anthropic 不会单独发送发票。您在此处发送的那一条请求同样会计费。

下面的命令使用了占位符值。请将 my-project-id 替换为您的项目 ID，将 you@example.com 替换为您的 Google 账户，并将 wrkspc_01AbCdEf23GhIj 替换为您的工作区 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 角色。 发起调用的身份需要在该项目上拥有此角色。

   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，而 Anthropic 支持则负责处理 Claude 本身的问题，包括模型和 API 错误。

运行任意 Claude API 示例

要在此服务上运行 Claude API 示例，只需替换其导入和客户端构造函数。 模型 ID 保持不变，因为此服务使用与 Claude API 相同的模型 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)

替换之后，只有导入和客户端发生了变化：

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 以及模型是什么。然后再学习 Tool use with the Messages API。

无论是在这些课程中，还是在文档中，只要有示例创建了 anthropic.Anthropic() 客户端，在运行之前都请替换其导入和客户端。 请跳过任何获取或存储 API 密钥、或检查余额的步骤，因为此服务不使用 API 密钥，而是通过 Google Cloud 计费。部分课程使用 TypeScript，文档中列出了每种语言对应的软件包和客户端。

当您需要时，文档中还包含以下主题：

• 从 Google 托管迁移
• 客户管理的加密密钥（CMEK）
• 监控与日志记录
• 速率限制