Anthropic Claude 模型的快速模式

在 Gemini Enterprise Agent Platform，快速模式可加快支援的 Anthropic Claude 模型生成輸出詞元。這項服務採用高速服務設定，可保留基礎模型的智慧和安全功能。如要啟用線上預測要求的快速模式，請在要求主體中設定 "speed": "fast"。

如果互動式工作負載對延遲時間較敏感，且等待生成詞元會中斷開發人員或使用者流程，請使用快速模式：

• 互動式代理程式碼撰寫：透過人工介入迴路代理，反覆執行多步驟程式碼撰寫、重構和偵錯工作，不需切換情境。
• 即時規劃：收集存放區或作業背景資訊，並以互動方式生成執行計畫。
• 事件應變：在推論週轉時間至關重要時，分類正式環境警告並整合修復步驟。

支援的模型和生命週期政策

快速模式適用於支援的 Claude 模型系列最新版本，以及即將淘汰版本的 30 天轉換期。Agent Platform 支援下列模型的快速模式：

• Google Cloud 上的 Anthropic Claude Fable 5.2 (claude-fable-5-2)

當支援的模型系列推出新版本時，舊版本的快速模式會在 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) 錯誤。

事前準備

傳送快速模式要求前，請先完成下列設定步驟。Fast 模式使用的專案設定和 Model Garden 啟用方式，與標準 Claude 要求相同。如要進一步瞭解合作夥伴模型設定，請參閱「事前準備」。

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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

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.

Verify that billing is enabled for your Google Cloud project.

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

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

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.

Verify that billing is enabled for your Google Cloud project.

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

1. 前往下列其中一個 Model Garden 模型資訊卡，按一下「Enable」(啟用)，然後完成任何模型專屬條款或資料共用規定：
   • 前往 Google Cloud 上的 Anthropic Claude Fable 5.2

必要的角色

如要取得向 Claude 模型傳送快速模式預測要求所需的權限，請要求管理員在 Google Cloud 專案中授予您下列 IAM 角色：

• 將預測要求傳送至合作夥伴模型：Agent Platform 使用者 (roles/aiplatform.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

傳送快速模式要求

如要使用快速模式，請向標準發布者模型端點 (例如 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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"。

回應

{
  "id": "msg_vrtx_01FastModeExample89ABcdEF",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5-2",
  "content": [
    {
      "type": "text",
      "text": "Here are the most common root causes for an HTTP 502 spike on a GKE Ingress controller and three immediate mitigation steps..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 34,
    "output_tokens": 218,
    "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" 或省略。

配額、監控和存取控管

快速模式會使用專屬容量和頻率限制，與標準速度流量區隔，同時沿用專案對基礎模型的存取權設定。

配額

在全球和多區域端點上，快速模式要求會耗用專屬的共用譜系配額 bucket，與標準速度模型配額分開計算。快速模式流量不會消耗標準 anthropic-claude-fable 配額，標準速度流量也不會消耗快速模式配額。

如要查看或要求提高快速模式配額，請在Google Cloud 控制台的「Quotas and system limits」(配額和系統限制) 頁面，依 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" 篩選，即可監控快捷模式的要求數量、詞元用量和延遲時間，與標準速度流量分開。

注意：claude-fable-5-2-fast 只是監控指標標籤，並非可呼叫的模型 ID。請一律將 API 要求傳送至基礎模型 ID (例如 claude-fable-5-2)，並在要求主體中加入 "speed": "fast"。在端點網址中呼叫 claude-fable-5-2-fast 會傳回 HTTP 404 (NOT_FOUND) 錯誤。

存取控管和組織政策

快速模式使用的必要角色和 Model Garden 啟用狀態，與基礎模型相同。如果要求傳回 403 PERMISSION_DENIED，請確認主體具備 Agent Platform 使用者角色 (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計費方式，且定價與標準速度要求不同：

• 詞元：所有詞元類型 (輸入、輸出、5 分鐘和 1 小時快取寫入，以及快取命中詞元) 的定價為標準速度詞元費率的 2 倍。
• 網頁搜尋：網頁搜尋工具呼叫會依標準 (1 倍) 費率計費。

用量會依據基本模型的 Google Cloud SKU 計費，並標示為快速模式。如要瞭解區域和全球權杖費率，請參閱 Agent Platform 定價頁面。

限制和錯誤處理

使用快速模式時，請注意下列限制：

• 不支援佈建輸送量：快速模式不支援佈建輸送量，一律採用即付即用模式。如果傳送快速模式要求時，包含 X-Vertex-AI-LLM-Request-Type: dedicated 標頭，系統會傳回 HTTP 429 (RESOURCE_EXHAUSTED) 錯誤。
• 不支援批次預測：快速模式專為互動式即時推論設計，不支援批次預測。
• 提示詞快取隔離：標準速度和快速模式要求不會共用提示詞快取。以標準速度寫入的快取項目，不會在快速模式中產生快取命中。同樣地，快速模式快取項目不會以標準速度產生快取命中。
• 不自動降級：如果無法以快速模式處理含有 "speed": "fast" 的要求，Agent Platform 會傳回錯誤，而非降回標準速度。

下表概略說明無效或不支援的快速模式要求傳回的錯誤：

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 語法。傳送有效的 JSON，並包含單一 "speed" 鍵。
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：要傳送至模型的提示文字。

新版模式只會處理模型淘汰錯誤。如果該位置不提供快速模式，下一個版本也無法解決錯誤。請改將要求轉送至支援的位置。

後續步驟

• 使用 Claude 模型要求預測
• Anthropic Claude 模型的配額
• 提示詞快取
• 控管 Model Garden 模型的存取權