使用佈建輸送量

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

已佈建輸送量的運作方式

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

檢查佈建輸送量配額

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

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

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

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

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

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

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

• 小型 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。

範例

pip install --upgrade google-genai

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

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

npm install @google/genai

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

# 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();
    }
  }
}

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 金鑰做為參數。

如要瞭解如何建立 Cloud de Confiance by S3NS 繫結至服務帳戶的 API 金鑰，請參閱「取得 Cloud de Confiance by S3NS API 金鑰」。如要瞭解如何使用 API 金鑰傳送要求至 Gemini API，請參閱「連線至 Knowledge MCP 伺服器」。

舉例來說，以下範例說明如何在使用佈建輸送量時，透過 API 金鑰提交要求：

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，接收有關佈建輸送量訂單的電子郵件通知。啟用後，按一下「Provisioned Throughput Orders」(佈建輸送量訂單) 頁面頂端的「Notifications」(通知)。然後在開啟的對話方塊中，按一下「重要聯絡人」，並按照畫面上的指示操作。

1. 如果尚未啟用，請啟用 Essential Contacts API。

   啟用 API 時所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

2. 前往「佈建輸送量」頁面。

   前往「佈建輸送量」

3. 按一下 [通知]。

4. 在「通知」對話方塊中，按一下「重要聯絡人」。

   「重要聯絡人」頁面隨即開啟。

5. 按一下「新增聯絡人」。

6. 在「新增聯絡人」對話方塊的「電子郵件地址」和「確認電子郵件地址」欄位中，輸入聯絡人的電子郵件地址。

7. 選取「產品更新」。

8. 按一下 [儲存]。

系統會針對下列佈建輸送量事件通知聯絡電子郵件地址：

監控佈建輸送量

您可以透過一組在 aiplatform.googleapis.com/PublisherModel 資源類型上測量的指標，自行監控佈建輸送量用量。

佈建輸送量流量監控功能為公開預先發布版。

維度

您可以根據下列維度篩選指標：

路徑前置字串

指標的路徑前置字串為 aiplatform.googleapis.com/publisher/online_serving。

舉例來說，/consumed_throughput 指標的完整路徑是 aiplatform.googleapis.com/publisher/online_serving/consumed_throughput。

指標

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

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

資訊主頁

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

1. 前往 Cloud de Confiance 控制台的「佈建輸送量」頁面。

   前往「佈建輸送量」

2. 如要查看訂單中個別模型的佈建輸送量使用情形，請選取「使用情形摘要」分頁標籤。

   在「各模型的佈建輸送量使用情形」表格中，您可以查看所選時間範圍的下列資訊：

   • 您擁有的 GSU 總數。

   • 以 GSU 計算的尖峰處理量用量。

   • 平均 GSU 使用率。

   • 達到佈建輸送量上限的次數。

3. 從「依模型提供的佈建輸送量使用率」表格中選取模型，即可查看所選模型的更多專屬指標。

如何解讀監控資訊主頁

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

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

• 系統會即時強制執行配額，但監控圖表會將資料匯總為 1 分鐘或更高的平均資訊主頁對齊週期，視監控資訊主頁中指定的時間範圍而定。

• Agent Platform 和監控資訊主頁會在不同的系統時鐘上執行。

• 如果流量爆量，在 1 秒內超過強制執行時間範圍的處理量配額，系統就會將整個要求視為溢出流量。不過，如果該秒的監控資料是在 1 分鐘的校正週期內取平均值，整體佈建輸送量使用率可能會偏低，因為整個校正週期的平均使用率可能不會超過 100%。如果看到溢出流量，表示在配額強制執行期間，當這些特定要求提出時，您已完全使用佈建輸送量配額。無論監控資訊主頁顯示的平均使用率為何，都會發生這種情況。

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

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

• 藍色長條代表以佈建輸送量形式接受的流量。

• 橘色長條代表流量超出 GSU 限制，並以溢出流量處理。

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

• 藍線代表佈建輸送量流量。

• 橘色線條代表溢出流量。

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

排解監控資訊主頁問題

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

1. 放大：將資訊主頁時間範圍設為 12 小時以內，即可提供最精細的 1 分鐘校正間隔。較大的時間範圍可平緩導致節流的尖峰，並提高對齊期間平均值。

2. 檢查總流量：模型專屬的資訊主頁會以兩條不同的線條，分別顯示專屬和溢出流量，這可能會導致您誤以為佈建輸送量配額未充分運用，且溢出過早。如果流量超過可用配額，系統會將整個要求視為溢出流量來處理。如要查看其他實用視覺化資料，請使用 Metrics Explorer 將查詢新增至資訊主頁，並加入特定模型和區域的權杖輸送量。如要查看所有流量類型 (專用、溢出和共用) 的總流量，請勿加入任何其他匯總或篩選條件。

監控 Genmedia 模型

Veo 3 模型不支援監控佈建輸送量。

警告

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

啟用警告

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

1. 前往 Cloud de Confiance 控制台的「佈建輸送量」頁面。

   前往「佈建輸送量」

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 details」(Google Agent Platform 詳細資料) 窗格隨即顯示。

4. 選取「快訊」分頁標籤，然後選取「快訊政策」範本。

後續步驟

• 排解錯誤代碼 429。