使用 Anthropic Claude 模型的快速模式

快速模式可加快 Gemini Enterprise Agent Platform 上受支持的 Anthropic Claude 模型的输出 token 生成速度。它使用高速服务配置，可保留基础模型的智能和安全功能。您可以通过在请求正文中设置 "speed": "fast"，对在线预测请求启用快速模式。

对于延迟敏感型交互式工作负载，如果等待生成词元会中断开发者或用户流程，请使用快速模式：

  • 交互式智能体编码：通过人机协同智能体迭代执行多步骤编码、重构和调试任务，无需切换上下文。
  • 实时规划：收集代码库或操作上下文，并以交互方式生成执行计划。
  • 突发事件响应：在推理周转时间至关重要时，对生产环境提醒进行分类并汇总修复步骤。

支持的模型和生命周期政策

快速模式适用于受支持 Claude 模型系列的最新版本，以及即将停用版本的 30 天过渡期。 Agent Platform 支持以下模型的快速模式：

当受支持的模型系列推出新版本时，该系列中旧版本的快速模式将在新版本推出 30 天后停用。30 天的停用期结束后，向包含 "speed": "fast" 的先前模型版本发出的请求会返回 HTTP 400 (INVALID_ARGUMENT) 错误。对该模型版本的标准速度请求会继续正常运行。如需继续使用快速模式，请更新请求以定位到最新模型版本，或从请求正文中移除 "speed": "fast"。

支持的位置

对于受支持的模型，快速模式可在以下 API 位置 ID 中使用：

  • 全球（Google Cloud 上的 Anthropic Claude Fable 5.2）： global
  • 美国多区域（Google Cloud 上的 Anthropic Claude Fable 5.2）： us
  • 欧洲多区域（Google Cloud 上的 Anthropic Claude Fable 5.2）： eu

快速模式不公开支持直接区域端点。向不支持快速模式的位置发送包含 "speed": "fast" 的请求会返回 HTTP 400 (FAILED_PRECONDITION) 错误。

准备工作

在发送快速模式请求之前，请完成以下设置步骤。快速模式使用与标准 Claude 请求相同的项目设置和 Model Garden 启用。如需了解其他合作伙伴模型设置详情，请参阅准备工作。

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. 前往以下 Model Garden 模型卡片之一，点击启用，然后完成所有特定于模型的条款或数据共享要求：

所需的角色

如需获得向 Claude 模型发送快速模式预测请求所需的权限，请让管理员为您授予 Google Cloud 项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

发送快速模式请求

如需使用快速模式，请向标准发布方模型端点（例如 claude-fable-5-2）发送请求，并在顶级请求正文中设置 "speed": "fast"。无需 anthropic-beta 标头，也无需在 Model Garden 中启用单独的模型卡片。

REST

以下示例会向 global 端点上的 claude-fable-5-2 发送预测请求，并启用 "speed": "fast"。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID（例如 my-agent-project）。
  • MODEL：支持快速模式的 Claude 模型，例如 claude-fable-5-2（默认：claude-fable-5-2）。请始终在端点网址中指定基础模型 ID。

此示例使用 global 端点。如需改用受支持的多区域端点，请参阅指定多区域端点。

HTTP 方法和网址：

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict

请求 JSON 正文： 

{
  "anthropic_version": "vertex-2023-10-16",
  "speed": "fast",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Analyze the root cause of an HTTP 502 spike on an upstream GKE ingress controller and list three immediate mitigation steps."
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

响应是一个 JSON 对象，如下所示。在快速模式下处理请求时，usage 对象包含 "speed": "fast"。

Python

使用 Anthropic Vertex SDK (anthropic[vertex]) 时，在调用 client.messages.create() 时传递 extra_body={"speed": "fast"}：

from anthropic import AnthropicVertex
from anthropic.types import Message


def generate_with_fast_mode(
    project_id: str = "PROJECT_ID",
) -> Message:
    client = AnthropicVertex(
        project_id=project_id,
        region="global",
    )

    message = client.messages.create(
        model="claude-fable-5-2",
        max_tokens=1024,
        extra_body={"speed": "fast"},
        messages=[
            {
                "role": "user",
                "content": (
                    "Analyze the root cause of an HTTP 502 spike on an upstream "
                    "GKE ingress controller and list three immediate mitigation "
                    "steps."
                ),
            }
        ],
    )
    print(message.model_dump_json(indent=2))
    return message

查看使用的是哪种速度

您可以通过检查响应中的 usage.speed 字段来验证请求是否在快速模式下处理：

  • 快速模式：usage.speed 存在且设置为 "fast"（在一元响应中，或在流式响应的 message_start 或 message_delta 事件中）。
  • 标准速度：当您发送标准请求（省略 "speed": "standard" 或 speed）时，usage.speed 为 "standard" 或省略。

配额、监控和访问权限控制

快速模式使用与标准速度流量隔离的专用容量和速率限制，同时继承项目对基础模型的访问配置。

配额

在全球和多区域端点上，快速模式请求会消耗专用的共享沿袭配额存储桶，该存储桶与标准速度模型配额分开。快速模式流量不会消耗您的标准 anthropic-claude-fable 配额，标准速度流量也不会消耗您的快速模式配额。

如需在Google Cloud 控制台的配额和系统限制页面上查看或申请增加快速模式配额，请按 base_model 过滤：

  • anthropic-claude-fable-fast（适用于全球和多区域端点）

使用方案和预配吞吐量

快速模式不支持预配吞吐量：

  • 仅限 PayGo：快速模式请求始终使用pay-as-you-go，即使您的项目有针对基础模型的有效预配吞吐量订单也是如此。快速模式流量绝不会消耗预配吞吐量订单中的资源，也不会溢出到这些订单中。
  • dedicated 请求标头受到限制：请勿在快速模式请求中包含 X-Vertex-AI-LLM-Request-Type: dedicated HTTP 标头（或 gRPC 元数据）。快速模式没有预配吞吐量配额，并且 dedicated 请求无法溢出到随用随付。因此，具有 X-Vertex-AI-LLM-Request-Type: dedicated 的快速模式请求会返回 HTTP 429 (RESOURCE_EXHAUSTED) 错误。请省略该标头，或改为设置 X-Vertex-AI-LLM-Request-Type: shared。

监控快速模式指标

在 Cloud Monitoring 中，快速模式流量会报告 model_user_id="claude-fable-5-2-fast"，而不是基本模型 ID (claude-fable-5-2)。在 Metrics Explorer 中按 model_user_id="claude-fable-5-2-fast" 过滤，以分别监控快速模式和标准速度流量的请求数、词元用量和延迟时间。

访问权限控制和组织政策

快速模式使用与基础模型相同的所需角色和 Model Garden 启用状态。如果请求返回 403 PERMISSION_DENIED，请验证您的主账号是否具有 Agent Platform User 角色 (roles/aiplatform.user)，以及是否已在 Model Garden 中启用基础模型。

如果您的组织强制执行 constraints/vertexai.allowedModels 组织政策限制，则快速模式由基础模型的 :predict 值（例如 publishers/anthropic/models/claude-fable-5-2:predict）控制：

  • 允许 publishers/anthropic/models/claude-fable-5-2:predict 即允许向 claude-fable-5-2 发出标准速度和快速模式请求。
  • 拒绝 publishers/anthropic/models/claude-fable-5-2:predict 会同时屏蔽标准速度和快速模式请求。

如需详细了解组织政策，请参阅控制对 Model Garden 模型的访问权限。

价格

快速模式始终采用pay-as-you-go结算方式，其价格与标准速度请求不同：

  • Token：所有 token 类型（输入、输出、5 分钟和 1 小时缓存写入以及缓存命中 token）的价格均为标准速度 token 费率的 2 倍。
  • 网页搜索：网页搜索工具调用按标准（1 倍）费率计费。

用量会根据基础模型的 Google Cloud SKU（带有快速模式标签）进行结算。 如需了解区域和全球 token 费率，请参阅 Agent Platform 价格页面。

限制和错误处理

使用快速模式时，请注意以下限制：

  • 无预配吞吐量：快速模式不支持预配吞吐量，并且始终使用随用随付。发送带有 X-Vertex-AI-LLM-Request-Type: dedicated 标头的快速模式请求会返回 HTTP 429 (RESOURCE_EXHAUSTED) 错误。
  • 无批量预测：快速模式专为交互式实时推理而设计，不支持批量预测。
  • 提示缓存隔离：提示缓存不会在标准速度请求和快速模式请求之间共享。以标准速度写入的缓存条目不会在快速模式下产生缓存命中。同样，快速模式缓存条目不会以标准速度产生缓存命中。
  • 不静默降级：如果无法在快速模式下处理带有 "speed": "fast" 的请求，智能体平台会返回错误，而不是回退到标准速度。

下表总结了针对无效或不受支持的快速模式请求返回的错误：

HTTP 状态和代码 出错提示 原因和修复
400 INVALID_ARGUMENT Fast mode (speed: fast) is not supported for this model. 目标模型不提供快速模式，或者其快速模式在较新模型版本发布 30 天后已停用。请定位到受支持的模型或移除 "speed": "fast"。
400 INVALID_ARGUMENT Invalid value for speed; expected "standard" or "fast". speed 字段包含不受支持的值或不是字符串。指定 "fast" 或 "standard"。
400 INVALID_ARGUMENT Invalid request body: duplicate keys or malformed JSON. JSON 请求正文包含重复的键（例如重复的 "speed" 键）或格式错误的 JSON 语法。请发送包含单个 "speed" 键的有效 JSON。
400 INVALID_ARGUMENT Fast mode is not supported for batch prediction. 请求已提交到具有 "speed": "fast" 的批量预测作业。移除 "speed": "fast" 以用于批处理工作负载。
400 FAILED_PRECONDITION Fast mode is not available in this location. 快速模式未在所请求的区域中部署。将请求路由到某个支持的位置。
404 NOT_FOUND Publisher Model ... was not found 请求网址定位到的是监控指标标签 (claude-fable-5-2-fast)，而不是可调用的模型 ID。定位到基础模型 ID (claude-fable-5-2)，并在请求正文中传递 "speed": "fast"。
429 RESOURCE_EXHAUSTED Too many requests. Exceeded the provisioned throughput 请求同时包含 "speed": "fast" 和 X-Vertex-AI-LLM-Request-Type: dedicated 标头。快速模式不支持预配吞吐量，始终使用随用随付；请移除 X-Vertex-AI-LLM-Request-Type: dedicated（或将其设置为 shared）。
429 RESOURCE_EXHAUSTED anthropic-claude-fable-fast 的配额已超出 您的项目在该位置超出了快速模式 QPM、输入 TPM 或输出 TPM 配额。请使用指数退避算法重试，或申请增加 anthropic-claude-fable-fast 的配额。

处理快速模式错误

由于 Agent Platform 不会静默降级快速模式请求，因此您的应用会决定在快速模式不可用时执行的操作。例如，快速模式会在下一个版本发布 30 天后停用，或者某个地点可能不提供快速模式。以下 Python 示例与特定的快速模式出错提示匹配，因此不相关的 HTTP 400 错误仍会显示。

回退到标准速度

对于可以容忍较高延迟的工作负载，请捕获快速模式可用性错误，并以标准速度重试请求：

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

# Errors that mean fast mode isn't available for this model or location.
_FAST_MODE_UNAVAILABLE = (
    "Fast mode (speed: fast) is not supported for this model.",
    "Fast mode is not available in this location.",
)


def generate_with_standard_fallback(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "claude-fable-5-2",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if not any(msg in str(e) for msg in _FAST_MODE_UNAVAILABLE):
            raise
        # Fast mode isn't available: retry at standard speed.
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
        )

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID，例如 my-agent-project。
  • LOCATION：受支持的位置，例如 global（默认：global）。
  • PROMPT：要发送给模型的提示文本。

移至下一个模型版本

如需在模型版本停用后继续使用快速模式，请在下一个版本中使用快速模式重试请求：

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

_FAST_MODE_NOT_SUPPORTED = (
    "Fast mode (speed: fast) is not supported for this model."
)


def generate_with_next_version(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "CURRENT_MODEL",
    next_model: str = "NEXT_MODEL",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if _FAST_MODE_NOT_SUPPORTED not in str(e):
            raise
        # Fast mode is retired on this version: use the next version.
        return client.messages.create(
            model=next_model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID，例如 my-agent-project。
  • LOCATION：受支持的位置，例如 global（默认：global）。
  • CURRENT_MODEL 和 NEXT_MODEL：您使用的模型版本（例如 claude-fable-5-2）以及同一模型系列中的下一个版本。
  • PROMPT：要发送给模型的提示文本。

下一版本模式仅处理模型停用错误。如果该位置不提供快速模式，则下一个版本不会解决该错误。请改为将请求路由到受支持的位置。

后续步骤