Priority PayGo

优先随用随付 (Priority PayGo) 是一种消费选项，可提供比标准随用随付更稳定的性能，而无需预配吞吐量的前期承诺。

使用优先 PayGo 时，您需要按令牌用量付费，费率高于标准 PayGo。如需了解价格，请访问 Gemini Enterprise Agent Platform 价格页面。

何时使用优先 PayGo

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

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

支持的型号和地区

global 端点以及 us 和 eu 多区域端点支持优先 PayGo。优先 PayGo 不支持区域级端点。

以下型号支持优先 PayGo：

使用优先 PayGo

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

  • 使用预配吞吐量配额（如有），并溢出到优先 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

初始化您的生成式 AI 客户端，以使用优先 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

如需仅使用 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

初始化您的生成式 AI 客户端，以使用优先 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 用量

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

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 模型：每分钟 1,000 万个 token
  • Gemini Flash 和 Flash-Lite 模型：每分钟 5,000 万个 token

贵组织可以立即享受这些限额。没有过渡期，也无需先建立持续的用量，才能达到这些限额。与标准按需付费类似，模型系列显示的吞吐量限制独立适用于该系列中的每个模型。

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

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

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

后续步骤