使用预配吞吐量

本页面介绍了预配吞吐量的工作原理、如何控制超额用量或绕过预配吞吐量，以及如何监控用量。

预配吞吐量的工作原理

本部分介绍了预配吞吐量如何通过在配额强制执行期内检查配额来运作。

预配吞吐量配额检查

预配吞吐量的配额上限是所购买的生成式 AI 扩缩单元 (GSU) 数量与每个 GSU 的吞吐量的乘积。每当您在配额强制执行周期内发出请求时，系统都会检查您的预配吞吐量配额，该周期是指强制执行预配吞吐量配额上限的频率。

在收到请求时，实际响应大小是未知的。由于我们优先考虑实时应用的响应速度，因此预配吞吐量会估计输出 token 大小。如果初始估计值超过可用的预配吞吐量配额上限，则该请求将按随用随付方式处理。否则，将按预配吞吐量方式处理。为此，系统会将初始估算值与预配吞吐量配额上限进行比较。

生成响应并确定实际输出 token 大小后，系统会通过将估算用量与实际用量之间的差额添加到您的可用预配吞吐量配额中，来协调实际用量和配额。

预配吞吐量配额强制执行周期

对于 Gemini 模型，配额强制执行期最长可能需要 30 秒，且可能会发生变化。这意味着，在某些情况下，您可能会暂时遇到优先流量超出每秒配额的情况，但不应超出 30 秒的配额。这些时间段基于 Vertex AI 内部时钟时间，与发出请求的时间无关。

例如，如果您购买了 1 GSU 的 gemini-2.0-flash-001，则始终开启的吞吐量应该为每秒 3,360 个 token。按平均算，每 30 秒的 token 数不应超过 100,800 个，该结果的计算公式如下：

3,360 tokens per second * 30 seconds = 100,800 tokens

如果您在一天内只提交了一个请求，该请求在一秒钟内使用了 8,000 个 token，那么即使您在请求时超出了每秒 3,360 个 token 的限制，该请求仍可能会作为预配吞吐量请求进行处理。这是因为该请求未超过每 30 秒 100,800 个 token 的阈值。

控制超额或绕过预配吞吐量

在超出所购吞吐量时，使用 API 控制超额用量或按请求绕过预配吞吐量。

仔细阅读每种选项，确定您必须采取哪些措施才能满足您的使用场景。

默认行为

如果请求超出剩余的预配吞吐量配额，默认情况下，整个请求将按需处理，并按随用随付费率计费。发生这种情况时，流量会在监控信息中心中显示为溢出。如需详细了解如何监控预配吞吐量使用情况，请参阅监控预配吞吐量。

预配吞吐量订单生效后，系统会自动执行默认行为。只要您在预配的区域中使用订单，就无需更改代码即可开始使用订单。

仅使用预配吞吐量

如果您通过避免按需费用来管理成本，请仅使用预配吞吐量。超出预配吞吐量订单金额的请求会返回错误 429。

向 API 发送请求时，请将 X-Vertex-AI-LLM-Request-Type HTTP 标头设置为 dedicated。

仅使用随用随付

这也称为按需使用。请求会绕过预配吞吐量订单，并直接发送到随用随付订单。这可能适用于正在开发的实验或应用。

向 API 发送请求时，请将 X-Vertex-AI-LLM-Request-Type HTTP 标头设置为 shared。

示例

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(
    http_options=HttpOptions(
        api_version="v1",
        headers={
            # Options:
            # - "dedicated": Use Provisioned Throughput
            # - "shared": Use pay-as-you-go
            # https://cloud.google.com/vertex-ai/generative-ai/docs/use-provisioned-throughput
            "X-Vertex-AI-LLM-Request-Type": "shared"
        },
    )
)
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="How does AI work?",
)
print(response.text)
# Example response:
# Okay, let's break down how AI works. It's a broad field, so I'll focus on the ...
#
# Here's a simplified overview:
# ...

Go

了解如何安装或更新 Go。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"
	"net/http"

	"google.golang.org/genai"
)

// generateText shows how to generate text Provisioned Throughput.
func generateText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{
			APIVersion: "v1",
			Headers: http.Header{
				// Options:
				// - "dedicated": Use Provisioned Throughput
				// - "shared": Use pay-as-you-go
				// https://cloud.google.com/vertex-ai/generative-ai/docs/use-provisioned-throughput
				"X-Vertex-AI-LLM-Request-Type": []string{"shared"},
			},
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := genai.Text("How does AI work?")

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// Artificial Intelligence (AI) isn't magic, nor is it a single "thing." Instead, it's a broad field of computer science focused on creating machines that can perform tasks that typically require human intelligence.
	// .....
	// In Summary:
	// ...

	return nil
}

REST

设置您的环境后，您可以使用 REST 测试文本提示。以下示例会向发布方模型端点发送请求。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Vertex-AI-LLM-Request-Type: dedicated" \ # Options: dedicated, shared
  $URL \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello."}]}]}'

将预配吞吐量与 API 密钥搭配使用

如果您已为特定项目、Google 模型和区域购买了预配置吞吐量，并希望使用它通过 API 密钥发送请求，则必须在请求中包含项目 ID、模型、位置和 API 密钥作为参数。

如需了解如何创建 Google Cloud 绑定到服务账号的 API 密钥，请参阅获取 Google Cloud API 密钥。如需了解如何使用 API 密钥向 Gemini API 发送请求，请参阅 Vertex AI 中的 Gemini API 快速入门。

例如，以下示例展示了如何在通过预置吞吐量提交请求时使用 API 密钥：

REST

设置您的环境后，您可以使用 REST 测试文本提示。以下示例会向发布方模型端点发送请求。

curl \
-X POST \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent?key=YOUR_API_KEY" \
-d $'{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}'

监控预配吞吐量

预览版

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

您可以使用一组基于 aiplatform.googleapis.com/PublisherModel 资源类型测量的指标，来自行监控预配吞吐量用量。

预配吞吐量流量监控是一项公开试用功能。

尺寸

您可以使用以下维度过滤指标：

维度	值
type	input output
request_type	dedicated：流量使用预配吞吐量进行处理。 spillover：在超出预配吞吐量配额后，流量将按随用随付配额处理。 shared：如果预配吞吐量处于有效状态，则流量将按照随用随付配额使用共享的 HTTP 标头进行处理。 如果预配吞吐量未处于有效状态，则默认情况下，流量会按随用随付方式处理。

路径前缀

指标的路径前缀为 aiplatform.googleapis.com/publisher/online_serving。

例如，/consumed_throughput 指标的完整路径为 aiplatform.googleapis.com/publisher/online_serving/consumed_throughput。

指标

Gemini 模型的 aiplatform.googleapis.com/PublisherModel 资源上提供以下 Cloud Monitoring 指标。使用 dedicated 请求类型过滤预配吞吐量用量。

指标	显示名称	说明
/dedicated_gsu_limit	限制 (GSU)	以 GSU 为单位的专用限制。使用此指标可了解预配吞吐量的配额上限（以 GSU 为单位）。
/tokens	令牌	输入和输出词元计数分布。
/token_count	词元数	累计输入和输出词元数。
/consumed_token_throughput	token 吞吐量	吞吐量使用情况（考虑消耗速率），以 token 数表示，并纳入配额对账。请参阅预配吞吐量配额检查。 使用此指标可了解预配吞吐量配额的使用情况。
/dedicated_token_limit	限制（每秒 token 数）	每秒 token 数的专用限制。使用此指标可了解基于 token 的模型所对应的预配吞吐量配额上限。
/characters	角色	输入和输出字符数分布。
/character_count	字符数	累计输入和输出字符数。
/consumed_throughput	字符吞吐量	吞吐量使用情况（考虑消耗速率），以字符数表示，并纳入配额协调预配吞吐量配额检查。 使用此指标可了解您的预配吞吐量配额的使用情况。 对于基于 token 的模型，此指标等同于以 token 为单位的使用吞吐量乘以 4。
/dedicated_character_limit	限制（每秒字符数）	每秒字符数的专用限制。使用此指标可了解基于字符的模型所对应的预配吞吐量配额上限。
/model_invocation_count	模型调用次数	模型调用（预测请求）的数量。
/model_invocation_latencies	模型调用延迟时间	模型调用延迟时间（预测延迟时间）。
/first_token_latencies	第一个词元延迟时间	从收到请求到返回第一个词元所用的时间。

Anthropic 模型也具有针对预配吞吐量的过滤器，但仅适用于 tokens 和 token_count。

信息中心

预配吞吐量的默认监控信息中心提供指标，可让您更好地了解用量和预配吞吐量利用率。如需访问信息中心，请执行以下操作：

1. 在 Google Cloud 控制台中，前往预配吞吐量页面。

   前往“预配吞吐量”

2. 如需查看各订单中每个模型的预配吞吐量利用率，请选择利用率摘要标签页。

   在按模型列出的预配吞吐量利用率表中，您可以查看所选时间范围内的以下信息：

   • 您拥有的 GSU 总数。

   • 以 GSU 为单位的吞吐量使用量峰值。

   • 平均 GSU 利用率。

   • 达到预配吞吐量限制的次数。

3. 从按模型列出的预配吞吐量利用率表中选择一个模型，以查看所选模型特定的更多指标。

信息中心的限制

信息中心可能会显示意外结果，尤其是对于波动较大（例如，每秒查询次数少于 1 次）或不频繁的流量。以下原因可能会导致这些结果：

• 如果时间范围超过 12 小时，配额强制执行期的表示可能会不太准确。吞吐量指标及其派生指标（例如利用率）会显示基于所选时间范围的校准时间段内的平均值。当时间范围扩大时，每个校准时间段也会扩大。在计算平均使用量时，校准时间段会扩大。由于配额强制执行是在分钟级以下计算的，因此将时间范围设置为 12 小时或更短的时间段会生成分钟级数据，这些数据与实际的配额强制执行时间段更具可比性。如需详细了解校准时间段，请参阅校准：序列内正则化。如需详细了解时间范围，请参阅正则化时间间隔。
• 如果同时提交了多个请求，监控聚合可能会影响您过滤到特定请求的能力。
• 预配吞吐量会在发出请求时限制流量，但在配额协调后报告用量指标。
• 预配吞吐量配额强制执行期独立于监控汇总期或请求/响应期，可能与后者不一致。
• 如果没有发生任何错误，您可能会在错误率图表中看到一条错误消息。例如，“请求数据时出错。找不到一个或多个资源”。

监控 Genmedia 模型

预配吞吐量监控功能不适用于 Veo 3 和 Imagen 模型。

提醒

启用提醒后，设置默认提醒，以帮助您管理流量使用情况。

启用提醒

如需在信息中心内启用提醒，请执行以下操作：

1. 在 Google Cloud 控制台中，前往预配吞吐量页面。

   前往“预配吞吐量”

2. 如需查看各订单中每个模型的预配吞吐量利用率，请选择利用率摘要标签页。

3. 选择建议的提醒，系统会显示以下提醒：

   • Provisioned Throughput Usage Reached Limit
   • Provisioned Throughput Utilization Exceeded 80%
   • Provisioned Throughput Utilization Exceeded 90%

4. 查看有助于您管理流量的提醒。

查看更多提醒详细信息

如需查看有关提醒的更多信息，请执行以下操作：

1. 前往集成页面。

   前往“集成”

2. 在过滤条件字段中输入“vertex”，然后按 Enter 键。Google Vertex AI 随即显示。

3. 如需查看更多信息，请点击查看详细信息。系统随即会显示 Google Vertex AI 详细信息窗格。

4. 选择提醒标签页，然后选择提醒政策模板。

后续步骤

• 排查错误代码 429 问题。