使用已佈建的處理量

本頁說明預先佈建輸送量的運作方式、如何控管溢出或略過預先佈建輸送量，以及如何監控用量。

佈建輸送量的運作方式

本節說明「佈建輸送量」的運作方式，包括在配額強制執行期間檢查配額。

檢查佈建輸送量配額

佈建處理量配額上限是您購買的生成式 AI 擴充單元 (GSU) 數量，以及每個 GSU 的處理量倍數。系統會在配額強制執行週期內，每次您提出要求時進行檢查。配額強制執行週期是指強制執行最高佈建輸送量配額的頻率。

收到要求時，系統並不知道實際的回應大小。由於我們優先考量即時應用程式的回覆速度，因此預先佈建的輸送量會估算輸出權杖大小。如果初始預估值超過可用的佈建傳輸量上限配額，系統會以即付即用方式處理要求。否則，系統會以佈建傳輸量方式處理要求。方法是比較初始預估值與佈建輸送量的配額上限。

系統產生回應並得知實際輸出權杖大小後，會將預估用量與實際用量之間的差額加到可用的已佈建處理量配額金額，藉此調整實際用量和配額。

佈建輸送量配額強制執行時間

Vertex AI 會在強制執行 Gemini 模型佈建輸送量配額時，套用動態視窗。這可為容易出現尖峰流量的流量提供最佳穩定性。Vertex AI 不會採用固定時間範圍，而是會根據模型類型和您佈建的 GSU 數量，自動調整彈性時間範圍，並強制執行配額。因此，在某些情況下，您可能會暫時遇到優先流量超過每秒配額的情況。不過，您不得在時間範圍內超過配額。這些時間範圍以 Vertex AI 內部時鐘時間為準，與提出要求的時間無關。

配額強制執行期限的運作方式

強制執行時間範圍會決定您在受到節流前，可超出每秒限制的「爆量」程度。系統會自動套用這個視窗。請注意，這些時間範圍可能會變更，以提升效能和穩定性。

小型 GSU 分配量 (3 個 GSU 以下)：視窗範圍為 40 至 120 秒，可處理較大的個別要求，不會中斷。

舉例來說，如果您購買 1 個 GSU 的 gemini-2.5-flash，平均每秒可獲得 2,690 個權杖的連續處理量。在任何 120 秒的時間範圍內，總用量不得超過 322,800 個權杖 (每秒 2,690 個權杖 * 120 秒)。因此，如果您傳送每秒使用 70,000 個權杖的要求，但 120 秒內的總用量仍低於 322,800 個權杖，則每秒 70,000 個權杖的爆量仍計為佈建輸送量，因為平均用量不會超過每秒 2,690 個權杖。
標準 (中型) GSU 分配 (超過 3 個 GSU)：如果是中型 GSU 部署 (例如少於 50 個 GSU)，時間範圍可能介於 5 秒到 30 秒。GSU 門檻和脈絡窗口會因模型而異。

舉例來說，如果您購買 25 個 gemini-2.5-flash GSU，平均每秒可獲得 67,250 個符記 (每秒 2,690 個符記 * 25) 的連續輸送量。在任何 30 秒的時間範圍內，總用量不得超過 2,017,500 個權杖 (每秒 67,250 個權杖 * 30 秒)。因此，如果您傳送的要求每秒使用 1,000,000 個權杖，但 30 秒內的總用量仍不超過 2,017,500 個權杖，則每秒 1,000,000 個權杖的爆量仍計為佈建輸送量，因為平均用量不會超過每秒 67,250 個權杖。
高精確度 (大規模) GSU 分配：對於大規模 GSU 部署 (例如 50 個以上的 GSU)，時間範圍可能介於 1 到 5 秒，確保基礎架構能以最高準確度處理高頻率要求。

舉例來說，如果您購買 250 個 gemini-2.5-flash GSU，平均每秒可獲得 672,500 個符記 (每秒 2,690 個符記 * 250)，持續輸送資料。在任何 5 秒時間範圍內，總用量不得超過 3,362,500 個權杖 (每秒 672,500 個權杖 * 5 秒)。因此，如果您傳送每秒使用 5,000,000 個權杖的要求，系統不會將其視為佈建處理量，因為在 5 秒的時間範圍內，5,000,000 個權杖的總用量超過 3,362,500 個權杖的限制。另一方面，如果 5 秒時間範圍內的平均用量未超過每秒 672,500 個權杖，則每秒使用 1,000,000 個權杖的要求可以透過佈建輸送量處理。

控管超額用量或略過佈建的處理量

當您超過購買的處理量時，可以使用 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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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
}

Node.js

安裝

npm install @google/genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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

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 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK：

# 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 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

設定環境後，您可以使用 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

尺寸	值
`type`	`input` `output`
`request_type`	`dedicated`：流量是使用佈建輸送量處理。 `spillover`：超過佈建輸送量配額後，系統會以即付即用配額處理流量。請注意，如果啟用明確快取，Gemini 2.0 模型就不支援 `spillover` 指標，因為這些模型不支援明確快取。在本例中，流量會顯示為 `shared`。 `shared`：如果已啟用佈建輸送量，系統會使用共用的 HTTP 標頭，以隨用隨付配額處理流量。如果「佈建輸送量」未啟用，系統預設會以隨用隨付方式處理流量。

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。

指標

您可以在 aiplatform.googleapis.com/PublisherModel 資源上查看 Gemini 模型適用的下列 Cloud Monitoring 指標。使用 dedicated 要求類型，篩選出佈建輸送量用量。

指標	顯示名稱	說明
`/dedicated_gsu_limit`	限制 (GSU)	專屬 GSU 限制。這項指標可協助您瞭解 GSU 中佈建輸送量的配額上限。
`/tokens`	權杖	輸入和輸出詞元數量分布情形。
`/token_count`	符記數量	累積的輸入和輸出詞元數量。
`/consumed_token_throughput`	詞元處理量	總處理量用量，其中包含權杖的消耗率，以及配額對帳。請參閱「佈建的處理量配額檢查」。使用這項指標瞭解佈建的處理量配額用量。
`/dedicated_token_limit`	上限 (每秒權杖數)	每秒詞元數的專屬限制。使用這項指標，瞭解以權杖為準的模型佈建處理量配額上限。
`/characters`	字元	輸入和輸出字元數分布情形。
`/character_count`	字元數	累計輸入和輸出字元數。
`/consumed_throughput`	字元處理量	總處理量用量，其中包含字元消耗率，並納入配額對帳佈建總處理量配額檢查。使用這項指標，瞭解已佈建的處理量配額使用情形。如果是以權杖為準的模型，這項指標等同於以權杖為單位計算的耗用量乘以 4。
`/dedicated_character_limit`	上限 (每秒字元數)	每秒字元數的專屬限制。這項指標可協助您瞭解字元型模型的佈建輸送量配額上限。
`/model_invocation_count`	模型叫用次數	模型調用次數 (預測要求)。
`/model_invocation_latencies`	模型叫用延遲	模型叫用延遲時間 (預測延遲時間)。
`/first_token_latencies`	第一個權杖的延遲時間	從收到要求到傳回第一個權杖的時間長度。

Anthropic 模型也有佈建處理量的篩選器，但僅適用於 tokens 和 token_count。

資訊主頁

佈建輸送量的預設監控資訊主頁提供指標，可協助您進一步瞭解用量和佈建輸送量使用率。如要存取資訊主頁，請按照下列步驟操作：

前往 Google Cloud 控制台的「佈建輸送量」頁面。
前往「佈建處理量」
如要查看訂單中個別模型的佈建輸送量使用情形，請選取「使用情形摘要」分頁標籤。

在「各模型的佈建輸送量使用情形」表格中，您可以查看所選時間範圍的下列資訊：
- 您擁有的 GSU 總數。
- 以 GSU 計算的尖峰處理量用量。
- 平均 GSU 使用率。
- 達到佈建輸送量上限的次數。
從「Provisioned Throughput utilization by model」(模型提供的處理量使用率) 表格中選取模型，即可查看所選模型的更多指標。

如何解讀監控資訊主頁

系統會在要求提出時，以毫秒級的頻率即時檢查可用配額，但會根據 Vertex AI 內部時鐘時間，將這項資料與配額強制執行期間的滾動資料進行比較。這項比較與提出要求的時間無關。配額對帳完成後，監控資訊主頁就會回報用量指標。不過，系統會根據所選時間範圍，匯總這些指標，提供資訊主頁對齊週期的平均值。監控資訊主頁支援的最低精細度為分鐘層級。此外，監控資訊主頁的時鐘時間與 Vertex AI 不同。

時間差有時會導致監控資訊主頁中的資料與即時成效不一致。可能原因如下：

系統會即時強制執行配額，但監控圖表會將資料匯總為 1 分鐘或更高的平均資訊主頁對齊週期，視監控資訊主頁中指定的時間範圍而定。
Vertex AI 和監控資訊主頁使用不同的系統時鐘。
如果 1 秒內的流量爆增，導致超過佈建處理量配額，系統會將整個要求視為溢出流量處理。不過，如果該秒的監控資料是在 1 分鐘的對齊期間內取平均值，整體佈建的處理量用量可能會偏低，因為整個對齊期間的平均用量可能不會超過 100%。如果看到溢出流量，表示在配額強制執行期間，當這些特定要求提出時，您已充分運用佈建輸送量配額。無論監控資訊主頁顯示的平均使用率為何，都會發生這種情況。

監控資料可能出現差異的範例

這個範例說明視窗未對齊所導致的部分差異。圖 1 顯示特定時間範圍內的輸送量用量。在這張圖中：

藍色長條代表以佈建輸送量形式接受的流量。
橘色長條代表流量超出 GSU 限制，並以溢出流量處理。

根據輸送量用量，圖 2 顯示可能因視窗未對齊而出現的視覺差異。在這張圖中：

藍線代表佈建處理量流量。
橘色線條代表溢出流量。

在這種情況下，監控資料可能會顯示在某個監控匯總時間範圍內，佈建輸送量用量沒有溢出，同時在另一個監控匯總時間範圍內，佈建輸送量用量低於 GSU 限制，但有溢出。

排解監控資訊主頁的問題

如要排解資訊主頁中非預期的溢位或 429 錯誤，請按照下列步驟操作：

放大：將資訊主頁的時間範圍設為 12 小時以內，即可提供最精細的 1 分鐘校正間隔。較大的時間範圍可平緩導致節流的尖峰，並提高對齊週期平均值。
檢查總流量：模型專屬資訊主頁會將專用和溢出流量顯示為兩條不同的線，這可能會導致您誤以為佈建輸送量配額未充分運用，且溢出過早。如果流量超過可用配額，系統會將整個要求視為溢出流量來處理。如要取得其他實用視覺化資料，請使用 Metrics Explorer 將查詢新增至資訊主頁，並加入特定模型和區域的權杖輸送量。如要查看所有流量類型 (專用、溢出和共用) 的總流量，請勿加入任何其他匯總或篩選器。

監控 Genmedia 模型

Veo 3 和 Imagen 模型不支援佈建輸送量監控功能。

快訊

啟用快訊功能後，請設定預設快訊，協助您管理流量用量。

啟用警告

如要在資訊主頁中啟用快訊，請按照下列步驟操作：

前往 Google Cloud 控制台的「佈建輸送量」頁面。
前往「佈建處理量」
如要查看訂單中個別模型的佈建輸送量使用情形，請選取「使用情形摘要」分頁標籤。
選取「建議的快訊」，系統會顯示下列快訊：
- Provisioned Throughput Usage Reached Limit
- Provisioned Throughput Utilization Exceeded 80%
- Provisioned Throughput Utilization Exceeded 90%
查看有助於管理流量的快訊。

查看更多快訊詳細資料

如要查看快訊的詳細資訊，請按照下列步驟操作：

前往「整合」頁面。
前往「整合」頁面
在「Filter」欄位中輸入「vertex」，然後按 Enter 鍵。系統會顯示「Google Vertex AI」。
如要查看更多資訊，請按一下「查看詳細資料」。系統會顯示「Google Vertex AI 詳細資料」窗格。
選取「快訊」分頁標籤，然後選取「快訊政策」範本。

後續步驟

排解錯誤代碼 429。

使用已佈建的處理量 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

佈建輸送量的運作方式

檢查佈建輸送量配額

佈建輸送量配額強制執行時間

配額強制執行期限的運作方式

控管超額用量或略過佈建的處理量

預設行為

僅使用佈建輸送量

僅使用即付即用方案

範例

Python

安裝

Go

Node.js

安裝

Java

REST

搭配 API 金鑰使用佈建輸送量

REST

監控佈建輸送量

尺寸

路徑前置字串

指標

資訊主頁

如何解讀監控資訊主頁

監控資料可能出現差異的範例

排解監控資訊主頁的問題

監控 Genmedia 模型

快訊

啟用警告

查看更多快訊詳細資料

後續步驟

使用已佈建的處理量