Priority PayGo

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

使用 Priority PayGo 时，您需要按令牌使用量付费，费率高于标准随用随付。如需了解价格信息，请参阅 Vertex AI 价格页面。

何时使用 Priority PayGo

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

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

支持的模型和位置

以下模型仅在 global 端点中支持 Priority PayGo。Priority PayGo 不支持区域级或多区域级端点。

使用 Priority PayGo

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

  • 使用预配吞吐量配额（如果有），并溢出到 Priority PayGo。

  • 仅使用 Priority PayGo。

在使用预配吞吐量作为默认设置时使用 Priority PayGo

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

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 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_VERTEXAI=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-2.0-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 参考文档。

设置环境变量以将 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_VERTEXAI=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-2.0-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 Flash 和 Flash-Lite 模型： 400 万个令牌/分钟。
  • Gemini Pro 模型： 100 万个令牌/分钟。

每持续使用 10 分钟，斜坡限制就会增加 50%。

如果请求超出斜坡限制，或者系统因流量过大而暂时超出容量，则请求可能会降级为标准随用随付，并按标准随用随付费率收费。

为了尽可能减少降级，请逐步扩缩使用量，以保持在限制范围内。如果您仍然需要更好的性能，不妨考虑 购买额外的预配吞吐量配额。

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

后续步骤