Priority PayGo

优先级随用随付 (Priority PayGo) 使用方案可提供比标准随用随付 (Standard PayGo) 更稳定的性能，且无需像预配吞吐量那样预先做出承诺。

使用 Priority PayGo 时，您需要按 token 用量付费，费率高于 Standard PayGo。如需了解价格信息，请参阅 Gemini Enterprise Agent Platform 价格页面。

何时使用 Priority PayGo

Priority PayGo 非常适合具有波动或不可预测流量模式的业务关键型工作负载。以下是示例用例：

  • 面向客户的虚拟助理
  • Agentic Workflows 和跨智能体互动
  • 研究模拟

支持的模型和位置

通常，global、us 和 eu 端点支持 Priority PayGo。不过，某些模型（例如 Gemini 2.5 模型）可能不支持所有这三个端点。请查看 Google 模型中链接的各个模型页面，了解使用 Priority PayGo 时支持哪些端点。

以下模型支持 Priority PayGo：

使用优先随用随付

如需使用 Priority PayGo 向 Gemini API 发送请求，您必须在请求中添加 X-Vertex-AI-LLM-Shared-Request-Type 标头。您可以通过以下两种方式使用 Priority PayGo：

  • 使用预配吞吐量配额（如有），超出部分使用优先级随用随付。

  • 仅使用 Priority PayGo。

以下示例使用 global 端点。如需改为将请求发送到多区域端点，请将 global 替换为 us 或 eu。对于 REST 请求，您还必须将 aiplatform.googleapis.com 主机名替换为 aiplatform.us.rep.googleapis.com 或 aiplatform.eu.rep.googleapis.com。如需了解详情，请参阅多区域端点。

使用优先级随用随付，同时将预配吞吐量用作默认方案

如需在用完优先 PayGo 之前先用完所有可用的预配吞吐量配额，请在请求中添加标头 X-Vertex-AI-LLM-Shared-Request-Type: priority，如以下示例所示。

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

初始化 GenAI 客户端，以便使用 Priority PayGo。完成此步骤后，您无需进一步调整代码，即可在同一客户端上使用 Priority PayGo 与 Gemini API 进行交互。

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

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

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。 。
  • MODEL_ID：您要为其初始化 Priority PayGo 的模型的模型 ID。如需查看支持 Priority PayGo 的模型列表，请参阅模型版本。
  • PROMPT_TEXT：要包含在提示中的文本说明。 JSON。
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

您应该收到类似以下内容的 JSON 响应。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度，请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前（例如 gemini-3.5-flash）。此示例可能还支持其他模型。

仅使用优先随用随付

如需仅使用 Priority PayGo，请在请求中添加标头 X-Vertex-AI-LLM-Request-Type: shared 和 X-Vertex-AI-LLM-Shared-Request-Type: priority，如以下示例所示。

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

初始化 GenAI 客户端，以便使用 Priority PayGo。完成此步骤后，您无需进一步调整代码，即可在同一客户端上使用 Priority PayGo 与 Gemini API 进行交互。

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。 。
  • MODEL_ID：您要为其初始化 Priority PayGo 的模型的模型 ID。如需查看支持 Priority PayGo 的模型列表，请参阅模型版本。
  • PROMPT_TEXT：要包含在提示中的文本说明。 JSON。
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

您应该收到类似以下内容的 JSON 响应。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度，请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前（例如 gemini-3.5-flash）。此示例可能还支持其他模型。

验证 Priority PayGo 用量

您可以根据响应中的流量类型来验证请求是否使用了 Priority PayGo，如以下示例所示。

Python

您可以从响应中的 traffic_type 字段验证请求是否使用了 Priority PayGo。如果您的请求是使用 Priority PayGo 处理的，则 traffic_type 字段会设置为 ON_DEMAND_PRIORITY。

sdk_http_response=HttpResponse(
  headers=<dict len=9>
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=<FinishReason.STOP: 'STOP'>
)] create_time=datetime.datetime(2025, 12, 3, 20, 32, 55, 916498, tzinfo=TzInfo(0)) model_version='gemini-2.5-flash' prompt_feedback=None response_id='response_id' usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=1408,
  candidates_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=<TrafficType.ON_DEMAND_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

您可以通过响应中的 trafficType 字段验证请求是否使用了 Priority PayGo。如果您的请求是使用 Priority PayGo 处理的，则 trafficType 字段会设置为 ON_DEMAND_PRIORITY。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}

吞吐量限制

Priority PayGo 在组织级别为每个模型提供基准吞吐量限制：

  • Gemini Pro 模型：每分钟 10,000,000 个 token
  • Gemini Flash 和 Flash-Lite 模型：每分钟 50,000,000 个 token

这些限制会立即对您的组织生效。没有爬坡期，也无需在达到这些限制之前建立持续用量。与标准 PayGo 类似，为模型系列显示的吞吐量限制会单独应用于该系列中的每个模型。

超出限额的流量不会自动降级。当有可用容量时，Agent Platform 会继续优先处理该流量，并按 Priority PayGo 费率计费。只有在没有空闲容量来优先处理请求时，请求才会降级为标准随用随付，并且这些请求会按标准随用随付费率计费。

您可以根据响应验证请求是否已降级。对于降级为标准 PayGo 的请求，流量类型会设置为 ON_DEMAND。如需了解详情，请参阅验证 Priority PayGo 用量。

为降低降级几率，请在每分钟内平滑流量，而不是发送急剧的秒级峰值。如果您的工作负载需要更高的限制，请与您的销售团队联系。对于需要专用、有保障的容量的工作负载，请参阅预配吞吐量。

后续步骤