推理层级（Inference Tiers）教程：从零开始理解并应用

本教程深入解析Gemini API的推理层级（Priority与Flex），帮助开发者根据工作负载特性优化成本与延迟。Priority层级提供毫秒级延迟和高可靠性，适合面向用户的关键应用；Flex层级以50%成本提供1-15分钟延迟，适合后台任务。教程涵盖层级对比、工作原理、代码实现、超时配置与重试策略，并强调生产环境中的最佳实践。通过本教程，开发者将掌握如何灵活选择服务层级，构建高效、经济的AI应用。

技术背景

在AI应用开发中，推理成本与延迟是核心权衡。标准API提供均衡性能，但面对交互式应用（如聊天机器人）需要极低延迟，而批量任务（如数据标注）则希望降低成本。Gemini API的推理层级应运而生：Priority层级为关键业务提供高优先级计算，确保低延迟和高可靠性；Flex层级利用空闲计算资源，以更低价格提供可接受的延迟。这解决了开发者手动管理异步任务（如Batch API）的复杂性，同时优化了成本与性能。适用场景包括：面向用户的实时应用（Priority）、后台数据处理与顺序链（Flex）。主要限制：Priority成本较高（+75-100%），Flex延迟可达15分钟且可能被丢弃（503错误），且两者均为付费功能。

核心原理

推理层级通过将请求路由到不同优先级的计算队列来实现差异化服务。Priority层级将流量导向高关键性队列，确保计算资源优先分配，从而获得低延迟和高可靠性；当流量超过动态限制时，服务器端会优雅降级到标准层级，避免请求失败。Flex层级则利用非高峰期的空闲计算能力，以“尽力而为”的方式处理请求，因此延迟可变且可能被丢弃。这种设计允许开发者通过简单的参数切换，在成本、延迟和可靠性之间做出灵活权衡，而无需管理复杂的异步任务。

架构分析

系统架构基于Gemini API的同步端点，通过请求中的service_tier字段选择层级。客户端使用google-genai SDK，通过client.interactions.create()发起请求。SDK支持每请求超时和全局超时配置，以及流式传输。重试逻辑通过捕获errors.APIError（如503、429）实现指数退避，并在多次失败后回退到标准层级。关键设计决策包括：使用同步接口简化开发，通过服务端降级保证Priority的稳定性，以及提供灵活的配置选项以适应不同场景。

完整实战教程

Copyright 2026 Google LLC.

#@title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

优先级与弹性推理层级

<a target="_blank" href="https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Inference_tiers.ipynb">

</a>

Gemini API 提供了不同的 service_tiers（服务层级），以帮助您管理成本和延迟。

Priority 和 Flex 层级允许您使用标准的同步端点，将后台任务路由到 Flex，将交互式任务路由到 Priority。这消除了异步任务管理的复杂性，同时让您获得专业层级的成本效益和性能优势：

在本笔记本中，您将学习：

  1. Priority 和 Flex 的比较
  2. 如何使用 Priority 层级
  3. 如何使用 Flex 层级
  4. 如何调整超时时间
  5. 如何实现重试
注意： 推理层级仅为付费功能。Flex 适用于付费层级的所有层级，Priority 适用于 Tier 2 和 Tier 3。本笔记本在免费层级下无法运行。（有关更多详细信息，请参阅 定价）。
注意： 本笔记本使用 Interactions API，这是与 Gemini 模型交互的最新方式。正在寻找 generateContent 版本？请查看 归档分支。

设置

安装 SDK

从 PyPI 安装 SDK。

%pip install -U -q "google-genai>=2.9.0"  # 2.0 for Interactions API

设置你的 API 密钥

要运行以下单元格，你的 API 密钥必须存储在名为 GEMINI_API_KEY 的 Colab 密钥中。如果你还没有 API 密钥，或者不确定如何创建 Colab 密钥，请参阅 [身份验证]

image](../quickstarts/Authentication.ipynb) 查看演练。

from google.colab import userdata

GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')

初始化 SDK 客户端

使用你的 API 密钥初始化客户端：

from google import genai
from google.genai import errors, types

client = genai.Client(api_key=GEMINI_API_KEY)

选择模型

大多数 Gemini 2.5 和 Gemini 3 模型都支持推理层级。有关更多详细信息，请参阅文档：

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

优先级与 Flex 对比

| 特性 | 标准 | Flex | 优先级 | 批量 | 缓存 |

| :--- | :--- | :--- | :--- | :--- | :--- |

| 定价 | 全价 | 5折 | 比标准高75%至100% | 5折 | 9折 + 按比例计算的令牌存储 |

| 延迟 | 秒级到分钟级 | 分钟级（目标1-15分钟） | 秒级 | 最长24小时 | 更快的首令牌时间 |

| 可靠性 | 高 / 中高 | 尽力而为（可丢弃） | 高（不可丢弃） | 高（针对吞吐量） | 不适用 |

| 接口 | 同步 | 同步 | 同步 | 异步 | 保存状态 |

| 最佳用例 | 通用应用工作流 | 非紧急的顺序链 | 生产环境、面向用户的应用 | 海量数据集、离线评估 | 对同一文件的重复查询 |

优先级的主要优势

* 低延迟：专为交互式、面向用户的AI工具的秒级响应时间而设计。

* 高可靠性：流量以最高关键性处理，严格不可丢弃。

* 优雅降级：超过动态限制的流量高峰会自动降级到标准层处理，而不是失败，从而防止服务中断。

Flex的主要优势

* 成本效益：为非生产评估、后台代理和数据丰富节省大量成本。

* 低摩擦：无需管理批量对象、作业ID或轮询；只需在现有请求中添加一个参数即可。

* 同步工作流：适用于顺序API链，其中下一个请求依赖于前一个请求的输出，使其比批量更适合代理工作流。

优先级推理

Gemini Priority API 是一个高级推理层级，专为需要更低延迟和最高可靠性的关键业务工作负载而设计，价格更高。优先级层级的流量优先于标准 API 和 Flex 层级的流量。

Priority 的工作原理

优先级推理将请求路由到高关键性计算队列，为面向用户的应用程序提供可预测、快速的性能。其主要机制是对超出动态限制的流量进行优雅的服务器端降级，以标准处理方式继续处理，从而确保应用程序的稳定性，而不是使请求失败。

Priority 速率限制

Priority 消耗有自己的速率限制，即使消耗会计入整体交互流量速率限制。默认速率限制为：每个模型和层级的标准速率限制的 0.3 倍。

如何使用 Priority

要使用 Priority 层级，请在请求正文中将 service_tier 字段设置为 "priority"。如果省略该字段，默认层级为标准。

try:
    interaction = client.interactions.create(
        model=MODEL_ID,
        input="Why is the sky blue?",
        service_tier='priority',
    )

    # Check the service tier from the interaction metadata
    print(f"Service tier: {interaction.service_tier}")
    print(interaction.steps[-1].content[0].text)

except errors.APIError as e:
    print(e.code, e.message)
except Exception as e:
    print(f"Error during API call: {e}")

你会在请求头中找到服务层级：

# The service tier is available directly on the interaction object
print(f"Service tier: {interaction.service_tier}")

Flex 推理

Gemini Flex API 是一个推理层级，与标准费率相比，可降低 50% 的成本，但代价是延迟可变且可用性为尽力而为。它专为延迟容忍型工作负载而设计，这些工作负载需要同步处理，但不需要标准 API 的实时性能。

Flex 的工作原理

Gemini Flex 推理弥合了标准 API 与 Batch API 的 24 小时周转时间之间的差距。它利用非高峰期的“可丢弃”计算能力，为后台任务和顺序工作流提供经济高效的解决方案。

如何使用 Flex

要使用 Flex 层级，请在请求正文中将 service_tier 指定为 "flex"。默认情况下，如果省略此字段，请求将使用标准层级。

try:
    interaction = client.interactions.create(
        model=MODEL_ID,
        input="Why is the sky blue?",
        service_tier='flex',
    )

    print(interaction.steps[-1].content[0].text)
except errors.APIError as e:
    print(e.code, e.message)

print(f"Service tier: {interaction.service_tier}")

调整超时窗口

你可以为 REST API 和客户端库配置每个请求的超时时间，并且仅在使用客户端库时配置全局超时。

始终确保你的客户端超时覆盖预期的服务器等待窗口（例如，Flex 等待队列为 600 秒以上）。SDK 期望超时值以毫秒为单位。

每个请求的超时

try:
    interaction = client.interactions.create(
        model=MODEL_ID,
        input="why is the sky blue?",
        service_tier="flex",
        timeout=900,
    )
    print(interaction.steps[-1].content[0].text)
except errors.APIError as e:
    print(e.code, e.message)

使用流式传输的示例（超时适用于每个数据块或整体，具体取决于实现方式）

try:
    response = client.interactions.create(
        model=MODEL_ID,
        input="List 5 ideas for a sci-fi movie.",
        service_tier="flex",
        stream=True,
    )
    for event in response:
        if hasattr(event, 'delta') and hasattr(event.delta, 'text') and event.delta.text:
            print(event.delta.text, end="")
except errors.APIError as e:
    print(e.code, e.message)
except Exception as e:
    print(f"An error occurred during streaming: {e}")

全局超时

如果你希望所有通过特定 genai.Client 实例（仅限客户端库）发出的 API 调用都有默认超时，可以在初始化客户端时使用 http_options 和 genai.types.HttpOptions 进行配置。

global_timeout_ms = 120000

client_with_global_timeout = genai.Client(
    api_key=GEMINI_API_KEY,
    http_options=types.HttpOptions(timeout=global_timeout_ms)
)

try:
    # Calling interactions.create using global timeout...
    interaction = client_with_global_timeout.interactions.create(
        model=MODEL_ID,
        input="Summarize the history of AI development since 2000.",
        service_tier="flex",
    )

    print(interaction.steps[-1].content[0].text)
except Exception as e:
    print(f"Error: {e}")

实现重试

由于 Flex 是可丢弃的，并且会以 503 错误失败，以下是一个可选实现重试逻辑以继续处理失败请求的示例：

import time


def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(
                model=MODEL_ID,
                input="Provide a very brief definition of machine learning.",
                service_tier="flex",
            )
        except errors.APIError as e:
            # Check for 503 Service Unavailable or 429 Rate Limits
            print(e.code)
            if attempt < max_retries - 1:
                delay = base_delay * (2**attempt)  # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                # Fallback to standard on last strike
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model=MODEL_ID,
                    input="Provide a very brief definition of machine learning.",
                )
        except Exception as e:
            print(f"An error occurred: {e}")

# Usage
interaction = call_with_retry()
print(interaction.steps[-1].content[0].text)

更多资源

如需了解更多信息，请参阅以下资源：

常见问题

常见错误：1) 免费层级调用导致403错误，需升级付费层级；2) Flex请求因资源不足返回503，应实现重试或回退；3) 超时设置过短导致请求中断，需确保超时覆盖Flex的等待队列（>600秒）；4) API密钥未正确配置，导致认证失败。排查方法：检查API密钥和层级支持；查看错误码（503、429、403）；调整超时参数；使用日志记录请求元数据。生产优化：为Flex任务设置合理的重试策略和回退机制；监控请求延迟和成功率；根据业务需求动态选择层级；利用缓存减少重复查询成本。

企业应用扩展

进一步学习：1) 结合Batch API处理大规模离线任务，与Flex形成互补；2) 探索Gemini API的优化文档，了解提示工程和模型选择对成本的影响；3) 实现更复杂的重试策略，如基于令牌桶的速率限制；4) 使用监控工具（如Cloud Monitoring）跟踪推理成本与性能；5) 考虑多区域部署以降低延迟。

总结

本教程深入解析Gemini API的推理层级（Priority与Flex），帮助开发者根据工作负载特性优化成本与延迟。Priority层级提供毫秒级延迟和高可靠性，适合面向用户的关键应用；Flex层级以50%成本提供1-15分钟延迟，适合后台任务。教程涵盖层级对比、工作原理、代码实现、超时配置与重试策略，并强调生产环境中的最佳实践。通过本教程，开发者将掌握如何灵活选择服务层级，构建高效、经济的AI应用。

内容来源与验证

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员
查看全部API 与工程实践教程