使用预配吞吐量

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

预配吞吐量的工作原理

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

预配吞吐量配额检查

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

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

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

预配吞吐量配额强制执行窗口

在为 Gemini 模型强制执行预配吞吐量配额时，Agent Platform 会应用动态窗口。这可为容易出现高峰的流量提供最佳稳定性。Agent Platform 不会采用固定的时间窗口，而是会根据模型类型和您已预配的 GSU 数量，在可自动调整的灵活时间窗口内强制执行配额。因此，在某些情况下，您可能会暂时遇到优先流量超出每秒配额的情况。不过，您不得在窗口持续时间内超出配额。这些时间段基于 Agent Platform 内部时钟时间，与发出请求的时间无关。

配额强制执行时间范围的运作方式

强制执行窗口用于确定在受到限制之前，您可以超出每秒限制的程度或“突增”程度。系统会自动应用此窗口。请注意，这些时间窗口可能会发生变化，以优化性能和可靠性。

  • 较小的 GSU 分配（3 个或更少的 GSU）：窗口范围可以从 40 秒到 120 秒不等，以便处理较大的单个请求，而不会中断。

    例如，如果您购买了 1 GSU 的 gemini-2.5-flash，则平均可获得每秒 2,690 个 token 的持续吞吐量。在任意 120 秒的时间窗口内，您的总用量不得超过 322,800 个 token（每秒 2,690 个 token * 120 秒）。因此，如果您发送的请求每秒使用 70,000 个 token，但 120 秒内的总用量仍低于 322,800 个 token，那么每秒 70,000 个 token 的突发用量仍计为预配吞吐量，因为平均用量未超过每秒 2,690 个 token。

  • 标准（中型）GSU 分配（超过 3 个 GSU）：对于中型 GSU 部署（例如，少于 50 个 GSU），该时间范围可以从 5 秒到 30 秒不等。GSU 阈值和上下文窗口因模型而异。

    例如，如果您购买了 25 个 GSU 的 gemini-2.5-flash，则可获得平均每秒 67,250 个 token（每秒 2,690 个 token * 25）的持续吞吐量。在任何 30 秒的时间窗口内，您的总用量不得超过 2,017,500 个 token（每秒 67,250 个 token * 30 秒）。因此，如果您发送的请求每秒使用 1,000,000 个 token，但 30 秒内的总用量保持在 2,017,500 个 token 以内，那么每秒 1,000,000 个 token 的突发用量仍计为预配吞吐量，因为平均用量不会超过每秒 67,250 个 token。

  • 高精度（大规模）GSU 分配：对于大规模 GSU 部署（例如 50 个或更多 GSU），窗口范围可以为 1 到 5 秒，以确保高频请求在整个基础架构中以最高准确率进行处理。

    例如，如果您购买了 250 GSU 的 gemini-2.5-flash，则可获得平均每秒 672,500 个 token（每秒 2,690 个 token * 250）的持续吞吐量。在任意 5 秒时间段内，您的总用量不得超过 3,362,500 个 token（每秒 672,500 个 token * 5 秒）。因此，如果您发送的请求每秒使用 5,000,000 个 token，那么该请求将不会作为预配吞吐量请求进行处理，因为在 5 秒的时间窗口内，5,000,000 个 token 的总用量超过了 3,362,500 个 token 的限制。另一方面，如果每秒使用 1,000,000 个 token 的请求在 5 秒时间窗口内的平均使用量不超过每秒 672,500 个 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 参考文档。

设置环境变量以将 Google 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_ENTERPRISE=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-3.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 参考文档。

设置环境变量以将 Google 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_ENTERPRISE=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
}

Node.js

安装

npm install @google/genai

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

设置环境变量以将 Google 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_ENTERPRISE=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateWithProvisionedThroughput(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
    httpOptions: {
      apiVersion: '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',
      },
    },
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'How does AI work?',
  });

  console.log(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:
  //  ...

  return response.text;
}

Java

了解如何安装或更新 Java。

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

设置环境变量以将 Google 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_ENTERPRISE=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import java.util.Map;

public class ProvisionedThroughputWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Provisioned Throughput.
  public static String generateContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("us-central1")
            .vertexAI(true)
            .httpOptions(
                HttpOptions.builder()
                    .apiVersion("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
                        Map.of("X-Vertex-AI-LLM-Request-Type", "shared"))
                    .build())
            .build()) {

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "How does AI work?", GenerateContentConfig.builder().build());

      System.out.println(response.text());
      // Example response:
      // At its core, **AI (Artificial Intelligence) works by enabling machines to learn,
      // reason, and make decisions in ways that simulate human intelligence.** Instead of being
      // explicitly programmed for every single task...
      return response.text();
    }
  }
}

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 发送请求，请参阅 Agent Platform 中的 Gemini API 快速入门。

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

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"
        }
      ]
    }
  ]
}'

接收电子邮件通知

您可以使用重要联系人 API 接收有关您的预配吞吐量订单的邮件通知。启用后，点击“预配吞吐量订单”页面顶部的通知。然后，在打开的对话框中，点击重要联系人，并按照屏幕上的说明操作。

  1. 启用 Essential Contacts API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  2. 前往“预配吞吐量”页面。

    前往“预配吞吐量”

  3. 点击通知。

  4. 在通知对话框中，点击重要联系人。

    系统会打开“重要联系人”页面。

  5. 点击添加联系人。

  6. 在添加联系人对话框中，在电子邮件和确认电子邮件字段中输入联系人的电子邮件地址。

  7. 选择产品最新资讯。

  8. 点击保存。

系统会针对以下预配吞吐量事件通知联系电子邮件地址：

事件 联系人收到通知的时间
订单已提交 几分钟内
订单已激活 几分钟内
订单更新已提交 几分钟内
订单更新已启用 几分钟内
1 个月、3 个月或 1 年的订单过期时间 到期日期前 2 周
订单有效期为 1 周。 到期日期前 3 天
1 个月、3 个月或 1 年自动续订 自动续订日期前 2 周

监控预配吞吐量

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

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

尺寸

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

维度 值
type input
output
request_type

dedicated：流量使用预配吞吐量进行处理。

spillover：在超出预配吞吐量配额后，流量将按随用随付配额处理。请注意，如果启用了显式缓存，则 Gemini 2.0 模型的预配吞吐量不支持 spillover 指标，因为这些模型不支持显式缓存。在这种情况下，流量会显示为 shared。

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. 从按模型列出的预配吞吐量利用率表中选择一个模型，以查看所选模型特定的更多指标。

如何解读监控信息中心

预配吞吐量会在请求发出时，以毫秒级实时检查可用配额，但会根据代理平台内部时钟时间，将此数据与滚动配额强制执行周期进行比较。此比较与发出请求的时间无关。监控信息中心会在配额协调后报告使用情况指标。不过，这些指标会进行汇总，以根据所选时间范围提供信息中心对齐周期的平均值。监控信息中心支持的最低粒度为分钟级。此外，监控信息中心的时钟时间与 Agent Platform 的不同。

这些时间上的差异有时可能会导致监控信息中心内的数据与实时效果之间存在差异。这些错误可能是由以下任何原因造成的：

  • 系统会实时强制执行配额，但监控图表会将数据汇总为 1 分钟或更长的平均信息中心对齐时间段，具体取决于监控信息中心内指定的时间范围。

  • Agent Platform 和监控信息中心在不同的系统时钟上运行。

  • 在一秒的时间段内，如果突发流量根据强制执行窗口超出预配吞吐量配额，则整个请求将作为溢出流量处理。不过，如果将该秒的监控数据在 1 分钟的对齐周期内取平均值，则预配吞吐量的总体利用率可能会显得较低，因为整个对齐周期的平均利用率可能不会超过 100%。如果您看到溢出流量，则表明在发出这些特定请求的配额强制执行期间，您的预配吞吐量配额已完全用尽。无论监控信息中心显示的平均利用率如何，都是如此。

监控数据中可能存在的差异示例

此示例展示了因窗口未对齐而导致的一些差异。图 1 显示了特定时间段内的吞吐量使用情况。 在此图中：

  • 蓝条表示以预配吞吐量形式接受的流量。

  • 橙色条表示将用量推高到超出 GSU 限制的流量，并作为溢出流量进行处理。

不同时间段内的吞吐量用量
图 1. 不同时间段内的吞吐量用量

根据吞吐量使用情况，图 2 显示了可能因窗口错位而导致的视觉差异。在此图中：

  • 蓝线表示预配吞吐量流量。

  • 橙线表示溢出流量。

监控数据可能存在差异
图 2. 监控信息中心中可能存在的视觉差异

在这种情况下，监控数据可能会显示某个监控汇总时间段的预置吞吐量使用情况，但没有溢出；同时，在另一个监控汇总时间段内，预置吞吐量使用情况低于 GSU 限制，但发生了溢出。

排查监控信息中心问题

您可以按照以下步骤排查信息中心内出现的意外溢出或 429 错误：

  1. 放大：将信息中心的时间范围设置为 12 小时或更短，以提供最精细的 1 分钟校准时间段。较大的时间范围可平滑导致节流的峰值，并提高对齐时间段的平均值。

  2. 检查总流量：模型专属的信息中心会将专用流量和溢出流量显示为两条单独的线，这可能会导致您得出“预配吞吐量配额未得到充分利用，过早溢出”的错误结论。如果流量超出可用配额，整个请求将作为溢出流量处理。如需其他有用的可视化图表，请使用 Metrics Explorer 向信息中心添加查询，并纳入特定模型和区域的令牌吞吐量。请勿添加任何其他汇总或过滤条件，以查看所有流量类型（专用、溢出和共享）的总流量。

监控 Genmedia 模型

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

提醒

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

启用提醒

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

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

    前往“预配吞吐量”

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

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

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

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

查看更多提醒详细信息

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

  1. 前往集成页面。

    前往“集成”

  2. 在过滤条件字段中输入“Agent Platform”，然后按 Enter 键。系统随即会显示 Google Agent Platform。

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

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

后续步骤