Claude on Vertex AI

Anthropic 的 Claude 模型可通过 Vertex AI 使用。

用于访问 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。

pip install -U google-cloud-aiplatform "anthropic[vertex]"

npm install @anthropic-ai/vertex-sdk

dotnet add package Anthropic.Vertex

go get github.com/anthropics/anthropic-sdk-go

implementation("com.anthropic:anthropic-java-vertex:2.33.0")

<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java-vertex</artifactId>
    <version>2.33.0</version>
</dependency>

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.vertex.backends.VertexBackend;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;

public class BasicMessage {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.builder()
            .backend(VertexBackend.fromEnv())
            .build();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_4_7)
            .maxTokens(1024L)
            .addUserMessage("What is the capital of France?")
            .build();

        Message response = client.messages().create(params);
        response.content().stream()
            .flatMap(block -> block.text().stream())
            .forEach(textBlock -> System.out.println(textBlock.text()));
    }
}

composer require anthropic-ai/sdk google/auth

# Gemfile
gem "anthropic"
gem "googleauth"

访问 Vertex AI

模型可用性

请注意，Anthropic 模型的可用性因区域而异。在 Vertex AI Model Garden 中搜索"Claude"或前往 Anthropic Claude 模型获取最新信息。

API 模型 ID

生命周期术语（已弃用、已退役）在模型弃用中定义；"即将退役"标注给出了平台公布的退役日期。下表中的日期是 Vertex AI 的时间表，由 Google Cloud 独立设置。模型在此处的生命周期状态和日期可能与模型弃用页面上 Anthropic 运营的时间表不同。

模型	Vertex AI API 模型 ID
Claude Opus 4.7	claude-opus-4-7
Claude Opus 4.6	claude-opus-4-6
Claude Sonnet 4.6	claude-sonnet-4-6
Claude Sonnet 4.5	claude-sonnet-4-5@20250929
Claude Sonnet 4 已弃用。将于 2026 年 9 月 14 日退役。	claude-sonnet-4@20250514
Claude Sonnet 3.7 已于 2026 年 5 月 11 日退役。	claude-3-7-sonnet@20250219
Claude Opus 4.5	claude-opus-4-5@20251101
Claude Opus 4.1	claude-opus-4-1@20250805
Claude Opus 4 已弃用。将于 2026 年 9 月 14 日退役。	claude-opus-4@20250514
Claude Haiku 4.5	claude-haiku-4-5@20251001
Claude Haiku 3.5 已弃用。将于 2026 年 7 月 5 日退役。	claude-3-5-haiku@20241022

Tip

正在升级到更新的 Claude 模型？在 Claude Code 中，运行 /claude-api migrate 以在代码库中应用模型 ID 交换和重大参数更改。该技能检测您的代码目标云平台，并为该平台调整模型 ID 格式和功能更改。请参阅迁移到更新的 Claude 模型。

发起请求

在运行请求之前，您可能需要运行 gcloud auth application-default login 以向 GCP 进行认证。

以下示例展示如何从 Vertex AI 上的 Claude 生成文本：

MODEL_ID=claude-opus-4-7
LOCATION=global
PROJECT_ID=MY_PROJECT_ID

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://$LOCATION-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/anthropic/models/${MODEL_ID}:streamRawPredict -d \
'{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [{
    "role": "user",
    "content": "Hey Claude!"
  }],
  "max_tokens": 100
}'

# ant CLI 不支持 Vertex AI。

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

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const projectId = "MY_PROJECT_ID";
const region = "global";

// 通过标准 `google-auth-library` 流程。
const client = new AnthropicVertex({
  projectId,
  region
});

async function main() {
  const result = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 100,
    messages: [
      {
        role: "user",
        content: "Hey Claude!"
      }
    ]
  });
  console.log(JSON.stringify(result, null, 2));
}

main();

using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Vertex;

var projectId = "MY_PROJECT_ID";
var region = "global";

var client = new AnthropicClient
{
    Backend = new VertexBackend(projectId, region)
};

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 100,
    Messages = [new() { Role = Role.User, Content = "Hey Claude!" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/vertex"
)

func main() {
	// 使用默认 Google Cloud 凭证
	client := anthropic.NewClient(
		vertex.WithGoogleAuth(context.Background(), "global", "MY_PROJECT_ID"),
	)

	message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
		Model:     "claude-opus-4-7",
		MaxTokens: 100,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hey Claude!")),
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", message)
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.vertex.backends.VertexBackend;

public class VertexExample {

  public static void main(String[] args) {
    // 使用默认 Google Cloud 凭证
    AnthropicClient client = AnthropicOkHttpClient.builder()
      .backend(VertexBackend.fromEnv())
      .build();

    Message message = client
      .messages()
      .create(
        MessageCreateParams.builder()
          .model("claude-opus-4-7")
          .maxTokens(100)
          .addUserMessage("Hey Claude!")
          .build()
      );

    System.out.println(message);
  }
}

<?php

use Anthropic\Vertex;

$client = Vertex\Client::fromEnvironment(
    location: 'global',
    projectId: 'MY_PROJECT_ID',
);

$message = $client->messages->create(
    maxTokens: 100,
    messages: [
        ['role' => 'user', 'content' => 'Hey Claude!']
    ],
    model: 'claude-opus-4-7',
);
echo $message->content[0]->text;

require "anthropic"

client = Anthropic::VertexClient.new(
  region: "global",
  project_id: "MY_PROJECT_ID"
)

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

puts message.content.first.text

有关更多详细信息，请参阅客户端 SDK 和官方 Vertex AI 文档。

Claude 也可通过 Amazon Bedrock、Claude Platform on AWS 和 Microsoft Foundry 使用。

数据保留

此产品的数据处理受 Google Cloud Vertex AI 管辖。有关详细信息，请参阅 Vertex AI 和零数据保留。

活动日志

Vertex 提供请求-响应日志服务，允许客户记录与使用相关的提示和补全。

Anthropic 建议您至少保留 30 天的滚动活动日志，以了解您的活动并调查任何潜在的滥用。

Note

启用此服务不会让 Google 或 Anthropic 访问您的内容。

功能支持

有关 Vertex AI 可用性的完整功能列表，请参阅功能概览。

支持的功能亮点

Messages API
Prompt caching
Extended thinking
Tool use，包括 Bash tool、Computer use tool、Memory tool 和 Text editor tool
Web search tool
Citations
Structured outputs

不支持的功能

输入源（图像和文档的 URL 源、Files API）
服务器端工具（代码执行、网络获取、顾问）
基础设施代理（Agent Skills、MCP 连接器、程序化工具调用）
API 端点（Message Batches、Models、Admin、Compliance、Usage and Cost）
Claude 托管代理

上下文窗口

Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 在 Vertex AI 上具有 1M token 上下文窗口。其他 Claude 模型，包括 Sonnet 4.5 和 Sonnet 4（已弃用），具有 200k token 上下文窗口。

Vertex AI 将请求有效负载限制为 30 MB。发送大型文档或多张图像时，您可能会在达到 token 限制之前达到此限制。

全球、多区域和区域端点

Vertex AI 提供三种端点类型：

全球端点： 动态路由以实现最大可用性
多区域端点： 在地理区域内动态路由（例如美国或欧盟），以实现高可用性的数据驻留
区域端点： 保证通过特定地理区域的数据路由

区域和多区域端点比全球端点有 10% 的价格溢价。

Note

这仅适用于 Claude Sonnet 4.5 和未来模型。旧模型（Claude Sonnet 4（已弃用）、Opus 4（已弃用）及更早版本）保持其现有定价结构。

何时使用每个选项

全球端点（推荐）：

提供最大可用性和正常运行时间
动态将请求路由到有可用容量的区域
无价格溢价
最适合数据驻留灵活的应用程序
仅支持按需付费流量（预配置吞吐量需要区域端点）

多区域端点：

在地理区域内动态路由请求（目前为 us 和 eu）
当您需要在广泛地理范围内进行数据驻留但又希望比单区域更高可用性时很有用
比全球端点有 10% 的价格溢价
仅支持按需付费流量（预配置吞吐量需要区域端点）

区域端点：

通过特定地理区域路由流量
单区域数据驻留、严格合规要求或预配置吞吐量所需
支持按需付费和预配置吞吐量
10% 的价格溢价反映了专用区域容量的基础设施成本

实现

使用全球端点（推荐）：

初始化客户端时将 region 参数设置为 "global"：

# ant CLI 不支持 Vertex AI。

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

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const projectId = "MY_PROJECT_ID";
const region = "global";

const client = new AnthropicVertex({
  projectId,
  region
});

const result = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 100,
  messages: [
    {
      role: "user",
      content: "Hey Claude!"
    }
  ]
});

using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Vertex;

var projectId = "MY_PROJECT_ID";
var region = "global";

var client = new AnthropicClient
{
    Backend = new VertexBackend(projectId, region)
};

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 100,
    Messages = [new() { Role = Role.User, Content = "Hey Claude!" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

package main

import (
	"context"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/vertex"
)

func main() {
	// 使用默认 Google Cloud 凭证
	client := anthropic.NewClient(
		vertex.WithGoogleAuth(context.Background(), "global", "MY_PROJECT_ID"),
	)

	message, _ := client.Messages.New(context.Background(), anthropic.MessageNewParams{
		Model:     "claude-opus-4-7",
		MaxTokens: 100,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hey Claude!")),
		},
	})
	_ = message
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.vertex.backends.VertexBackend;

void main() {
    // 使用默认 Google Cloud 凭证
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .backend(
            VertexBackend.builder()
                .region("global")
                .project("MY_PROJECT_ID")
                .build()
        )
        .build();

    var message = client
        .messages()
        .create(
            MessageCreateParams.builder()
                .model("claude-opus-4-7")
                .maxTokens(100)
                .addUserMessage("Hey Claude!")
                .build()
        );

    IO.println(message);
}

<?php

use Anthropic\Vertex;

$client = Vertex\Client::fromEnvironment(
    location: 'global',
    projectId: 'MY_PROJECT_ID',
);

$message = $client->messages->create(
    maxTokens: 100,
    messages: [
        ['role' => 'user', 'content' => 'Hey Claude!']
    ],
    model: 'claude-opus-4-7',
);

echo $message->content[0]->text;

require "anthropic"

client = Anthropic::VertexClient.new(
  region: "global",
  project_id: "MY_PROJECT_ID"
)

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

puts message.content.first.text

使用多区域端点：

将 region 参数设置为多区域标识符："us" 代表美国，"eu" 代表欧盟。SDK 将请求路由到相应的多区域端点（https://aiplatform.us.rep.googleapis.com 或 https://aiplatform.eu.rep.googleapis.com），该端点在该地理范围内的区域之间动态平衡流量。

# ant CLI 不支持 Vertex AI。

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us"  # 多区域标识符："us" 或 "eu"

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

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

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const projectId = "MY_PROJECT_ID";
const region = "us"; // 多区域标识符："us" 或 "eu"

const client = new AnthropicVertex({
  projectId,
  region
});

const result = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 100,
  messages: [
    {
      role: "user",
      content: "Hey Claude!"
    }
  ]
});

using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Vertex;

var projectId = "MY_PROJECT_ID";
var region = "us"; // 多区域标识符："us" 或 "eu"

var client = new AnthropicClient
{
    Backend = new VertexBackend(projectId, region)
};

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 100,
    Messages = [new() { Role = Role.User, Content = "Hey Claude!" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

package main

import (
	"context"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/vertex"
)

func main() {
	// 多区域标识符："us" 或 "eu"
	client := anthropic.NewClient(
		vertex.WithGoogleAuth(context.Background(), "us", "MY_PROJECT_ID"),
	)

	message, _ := client.Messages.New(context.Background(), anthropic.MessageNewParams{
		Model:     "claude-opus-4-7",
		MaxTokens: 100,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hey Claude!")),
		},
	})
	_ = message
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.vertex.backends.VertexBackend;

void main() {
    // 多区域标识符："us" 或 "eu"
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .backend(
            VertexBackend.builder()
                .region("us")
                .project("MY_PROJECT_ID")
                .build()
        )
        .build();

    var message = client
        .messages()
        .create(
            MessageCreateParams.builder()
                .model("claude-opus-4-7")
                .maxTokens(100)
                .addUserMessage("Hey Claude!")
                .build()
        );

    IO.println(message);
}

<?php

use Anthropic\Vertex;

$client = Vertex\Client::fromEnvironment(
    location: 'us', // 多区域标识符："us" 或 "eu"
    projectId: 'MY_PROJECT_ID',
);

$message = $client->messages->create(
    maxTokens: 100,
    messages: [
        ['role' => 'user', 'content' => 'Hey Claude!']
    ],
    model: 'claude-opus-4-7',
);
echo $message->content[0]->text;

require "anthropic"

client = Anthropic::VertexClient.new(
  region: "us", # 多区域标识符："us" 或 "eu"
  project_id: "MY_PROJECT_ID"
)

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

puts message.content.first.text

使用区域端点：

指定特定区域，如 "us-east1" 或 "europe-west1"：

# ant CLI 不支持 Vertex AI。

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us-east1"  # 指定特定区域

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

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

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const projectId = "MY_PROJECT_ID";
const region = "us-east1"; // 指定特定区域

const client = new AnthropicVertex({
  projectId,
  region
});

const result = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 100,
  messages: [
    {
      role: "user",
      content: "Hey Claude!"
    }
  ]
});

using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Vertex;

var projectId = "MY_PROJECT_ID";
var region = "us-east1";

AnthropicClient client = new()
{
    Backend = new VertexBackend(projectId, region)
};

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 100,
    Messages = [new() { Role = Role.User, Content = "Hey Claude!" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

package main

import (
	"context"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/vertex"
)

func main() {
	// 指定特定区域
	client := anthropic.NewClient(
		vertex.WithGoogleAuth(context.Background(), "us-east1", "MY_PROJECT_ID"),
	)

	message, _ := client.Messages.New(context.Background(), anthropic.MessageNewParams{
		Model:     "claude-opus-4-7",
		MaxTokens: 100,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hey Claude!")),
		},
	})
	_ = message
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.vertex.backends.VertexBackend;

void main() {
    // 使用默认 Google Cloud 凭证和特定区域
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .backend(
            VertexBackend.builder()
                .region("us-east1") // 指定特定区域
                .project("MY_PROJECT_ID")
                .build()
        )
        .build();

    var message = client
        .messages()
        .create(
            MessageCreateParams.builder()
                .model("claude-opus-4-7")
                .maxTokens(100)
                .addUserMessage("Hey Claude!")
                .build()
        );

    IO.println(message);
}

<?php

use Anthropic\Vertex;

$client = Vertex\Client::fromEnvironment(
    location: 'us-east1',
    projectId: 'MY_PROJECT_ID',
);

$message = $client->messages->create(
    maxTokens: 100,
    messages: [
        ['role' => 'user', 'content' => 'Hey Claude!']
    ],
    model: 'claude-opus-4-7',
);
echo $message->content[0]->text;

require "anthropic"

client = Anthropic::VertexClient.new(
  region: "us-east1", # 指定特定区域
  project_id: "MY_PROJECT_ID"
)

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

puts message.content.first.text

Note

Claude Mythos Preview 是一个研究预览，面向 Vertex AI 上受邀客户开放。有关更多信息，请参阅 Project Glasswing。

其他资源

Vertex AI 定价： cloud.google.com/vertex-ai/generative-ai/pricing
Claude 模型文档： Vertex AI 上的 Claude
Google 博客文章： Claude 模型的全球端点
Anthropic 定价详情： 云平台定价