使用预配吞吐量

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

预配吞吐量的工作原理

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

预配吞吐量配额检查

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

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

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

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

Agent Platform 在为 Gemini 模型强制执行预配吞吐量配额时会应用动态窗口。这可为容易出现峰值的流量提供最佳稳定性。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 个 gemini-2.5-flash GSU,则平均每秒可获得 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,000,000 个 token 的总用量超出了 5 秒时间窗口内 3,362,500 个 token 的限制。另一方面,如果 5 秒时间范围内的平均用量不超过每秒 672,500 个 token,则每秒使用 1,000,000 个 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.8-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 发送请求,请参阅 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"
        }
      ]
    }
  ]
}'

接收邮件通知

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

详细指标

详细指标会根据每个请求的推理日志(而非一分钟汇总指标)计算预配吞吐量信息中心。它们以秒级分辨率显示流量,因此您可以看到一分钟平均值隐藏的突发流量以及流量溢出的个别秒数。

详细指标会在标准指标旁边添加以下图表:吞吐量、缓存命中率和缓存的词元使用情况。

如需开启详细指标,请参阅在控制台中启用。日志存储桶升级完成后,从利用率摘要标签页中打开订单或模型,即可查看详细图表。如需使用 SQL 查询相同的数据(例如按项目划分的燃尽、按分钟划分的溢出或缓存命中率),请参阅使用 Observability Analytics 进行查询。

“预配吞吐量详情”页面上的详细指标
在“预配吞吐量”详情页面上选择的过去一天的详细指标。“预配吞吐量利用率”图表显示每秒吞吐量,分为专用吞吐量和溢出吞吐量,并与限制(每秒 token 数)进行对比。“请求速率”显示每秒请求数,分为专用和溢出。
“缓存 token 命中率”图表,其中选择了详细指标
“缓存 token 命中率”图表,其中显示了过去 7 天内所选的详细指标。它显示了从缓存中传送的输入 token 所占百分比,标记为“缓存 token 使用情况”。

如何解读监控信息中心

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

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

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

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

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

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

此示例说明了因窗口不一致而导致的一些差异。图 1 表示特定时间段内的吞吐量用量。在此图中:

  • 蓝色条表示作为预配吞吐量接纳的流量。

  • 橙色条表示导致用量超出 GSU 限制并作为溢出流量处理的流量。

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

根据吞吐量用量,图 2 表示由于窗口化未对齐而可能出现的视觉差异。在此图中:

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

  • 橙色线条表示溢出流量。

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

在这种情况下,监控数据可能会显示预配吞吐量用量,但在监控汇总时间范围内没有溢出,同时观察到预配吞吐量用量低于 GSU 限制,这与另一个监控汇总时间范围内的溢出一致。

排查监控信息中心问题

您可以通过执行以下步骤来排查信息中心内意外溢出或 429 错误的问题:

  1. 放大:将信息中心时间范围设置为 12 小时或更短,以提供最精细的 1 分钟校准时间段。较大的时间范围会消除导致限制的峰值,并增加校准时间段平均值。

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

监控 Genmedia 模型

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

提醒

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

启用提醒

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

  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 Platform 详细信息窗格。

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

后续步骤