Flex PayGo

灵活随用随付 (Flex PayGo) 是一种经济实惠的方案,适用于可以容忍更长响应时间和更高限制的非关键工作负载,让您能够访问 Gemini 模型。与标准 PayGo 相比,Flex PayGo 提供 50% 的折扣。

何时使用 Flex PayGo

Flex PayGo 非常适合同步、可容忍延迟且对时间不敏感的非关键任务。以下是示例用例:

  • 离线分析文本、文档、图片、音频和视频文件

  • 模型质量评估

  • 数据注解和标签

  • 文档翻译

  • 构建商品清单

批量推理可提高每天处理数千亿个 token 的大型 24 小时工作负载的吞吐量和成功率。

支持的模型和位置

以下 Gemini 模型仅在 global 端点中支持 Flex PayGo。Flex PayGo 不支持单区域或多区域端点。

请求载荷限制

对于载荷直接包含在请求正文中的请求,Flex PayGo 请求的总载荷大小上限为 20 MB。如需处理更大的文件,请在请求中提供 Cloud Storage URI。

使用 Flex PayGo

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

  • 使用预配吞吐量配额(如有),然后使用 Flex PayGo。

  • 仅使用 Flex PayGo。

请注意,使用 Flex PayGo 的请求的预期延迟时间比 Standard PayGo 长。

您可以将请求超时设置为最长 30 分钟。

使用 Flex PayGo,同时将预配吞吐量用作默认设置

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

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 客户端,以便使用 Flex PayGo。完成此步骤后,您无需进一步调整代码,即可在同一客户端上使用 Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

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

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

  • PROJECT_ID:您的项目 ID。 。
  • MODEL_ID:要为其初始化 Flex PayGo 的模型的模型 ID。如需查看支持 Flex 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-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "thoughtsTokenCount": 1054
  }
}
请注意此示例网址中的以下内容:
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度,请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前(例如 gemini-3.5-flash)。此示例可能还支持其他模型。
  • 使用区域级 API 端点(例如 us-central1)时,端点网址中的区域决定了请求的处理位置。资源路径中任何冲突的位置都会被忽略。

仅使用 Flex PayGo

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

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 客户端,以便使用 Flex PayGo。完成此步骤后,您无需进一步调整代码,即可在同一客户端上使用 Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

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

  • PROJECT_ID:您的项目 ID。 。
  • MODEL_ID:要为其初始化 Flex PayGo 的模型的模型 ID。如需查看支持 Flex 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-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "thoughtsTokenCount": 1054
  }
}
请注意此示例网址中的以下内容:
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度,请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前(例如 gemini-3.5-flash)。此示例可能还支持其他模型。
  • 使用区域级 API 端点(例如 us-central1)时,端点网址中的区域决定了请求的处理位置。资源路径中任何冲突的位置都会被忽略。

验证 Flex PayGo 使用情况

您可以通过响应中的流量类型来验证请求是否使用了 Flex PayGo,如以下示例所示。

Python

您可以通过响应中的 traffic_type 字段验证请求是否使用了 Flex PayGo。如果您的请求是使用 Flex PayGo 处理的,则 traffic_type 字段会设置为 ON_DEMAND_FLEX。

sdk_http_response=HttpResponse(
  headers=
) 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_FLEX: 'ON_DEMAND_FLEX'>
) automatic_function_calling_history=[] parsed=None

REST

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

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

Flex PayGo 的额外配额

除了内容生成请求的可用配额(包括溢出流量的预配吞吐量配额)之外,利用 Flex PayGo 的请求还受以下配额的约束:

说明 项目中每个基本模型的 QPM
项目中每个基础模型的配额请求(使用 Flex PayGo) 3000

后续步骤

资源

专门与 Agent Platform 相关的配额和限制。

资源

与 Agent Platform 相关的配额和限制,不包括特定于产品的限制。

概览

了解 Google Cloud 如何限制 Google Cloud 项目可使用的资源数量,以及配额如何应用于一系列资源类型,包括硬件、软件和网络组件。