优先级推理

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

GenerateContent API 和 Interactions API 端点中的 Tier 2 & Tier 3 用户可以使用 Priority 推理。

如何使用 Priority

如需使用 Priority 层级，请将请求正文中的 service_tier 字段设置为 SERVICE_TIER_PRIORITY。如果省略该字段，则默认层级为标准层级。

Python

from google import genai

client = genai.Client()

try:
    response = client.models.generate_content(
        model="gemini-3-flash-preview",
        contents="Triage this critical customer support ticket immediately.",
        config={'service_tier': 'SERVICE_TIER_PRIORITY'},
    )

    # Validate for graceful downgrade
    if response.sdk_http_response.headers.get("x-gemini-service-tier") == "standard":
        print("Warning: Priority limit exceeded, processed at Standard tier.")

    print(response.text)

except Exception as e:
    # Standard error handling (e.g., DEADLINE_EXCEEDED)
    print(f"Error during API call: {e}")

JavaScript

在 JavaScript 中，降级由客户端库自动处理。 如果超出容量，系统会抛出错误，或者以标准层级处理。 响应对象不会直接公开标头以检查降级。

import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  try {
      const result = await ai.models.generateContent({
          model: "gemini-3-flash-preview",
          contents: "Triage this critical customer support ticket immediately.",
          config: {serviceTier: "priority"},
      });

      // Validate for graceful downgrade
      if (result.sdkHttpResponse.headers.get("x-gemini-service-tier") === "standard") {
          console.log("Warning: Priority limit exceeded, processed at Standard tier.");
      }

      console.log(result.text);

  } catch (e) {
      console.log(`Error during API call: ${e}`);
  }
}

await main();

Go

在 Go 中，降级由客户端库自动处理。 如果超出容量，系统会抛出错误，或者以标准层级处理。响应对象不会直接公开标头以检查降级。

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    resp, err := client.Models.GenerateContent(
        ctx,
        "gemini-3-flash-preview",
        genai.Text("Triage this critical customer support ticket immediately."),
        &genai.GenerateContentConfig{
            ServiceTier: "priority",
        },
    )
    if err != nil {
        log.Fatalf("Error during API call: %v", err)
    }

    // Validate for graceful downgrade
    if resp.SDKHTTPResponse.Header.Get("x-gemini-service-tier") == "standard" {
        fmt.Println("Warning: Priority limit exceeded, processed at Standard tier.")
    }

    fmt.Println(resp.Text())
}

REST

curl \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-d '{
  "contents": [{
    "parts":[{"text": "Analyze user sentiment in real time"}]
  }],
  "serviceTier": "PRIORITY"
}'

Priority 推理的工作原理

Priority 推理会将请求路由到高关键性计算队列，为面向用户的应用提供可预测的快速性能。其主要机制是针对超出动态限制的流量优雅地降级到标准处理，确保应用稳定性，而不是让请求失败。

功能 优先级 标准版 Flex 批量
价格 比标准价格高 75-100% 全价 5 折 5 折
延迟时间 低（秒） 秒到分钟 分钟（目标 1-15 分钟） 最长 24 小时
可靠性 高（不可舍弃） 高 / 中高 尽力而为（可舍弃） 高（针对吞吐量）
接口 同步 同步 同步 异步

主要优势

  • 低延迟时间：专为交互式 面向用户的 AI 工具提供毫秒级响应时间。
  • 高可靠性：流量以最高关键性处理，且 严格不可舍弃。
  • 优雅降级：超出动态限制的流量峰值会自动降级到标准层级进行处理，而不是失败，从而防止服务中断。
  • 低摩擦：使用与 标准层级和 Flex 层级相同的同步 generateContent 方法。

使用场景

Priority 处理非常适合性能和可靠性至关重要的关键业务工作流。

  • 交互式 AI 应用：客户服务聊天机器人和副驾驶，其中用户支付额外费用，并期望获得快速、一致的响应。
  • 实时决策引擎：需要高度可靠、低延迟 结果的系统，例如实时工单分诊或欺诈检测。
  • 高级客户功能：需要为付费客户保证更高服务等级目标 (SLO) 的开发者。

速率限制

Priority 消耗有自己的速率限制，即使消耗计入整体交互式流量速率限制也是如此。Priority 推理的默认速率限制为模型 / 层级的标准速率限制的 0.3 倍

优雅降级逻辑

如果由于拥塞而超出 Priority 限制，溢出请求会自动且优雅地 降级到标准处理，而不是因 503 或 429 错误而失败。降级的请求按标准费率计费，而不是按 Priority 额外费率计费。

客户端责任

  • 响应监控：开发者应监控service_tier值在 API 响应正文中，以检测请求是否经常降级为 standard。
  • 重试：客户端必须为 标准错误（例如 DEADLINE_EXCEEDED）实现重试逻辑/指数退避算法。

价格

Priority 推理的价格比标准 API 高 75-100%，并按词元计费。

支持的模型

以下模型支持 Priority 推理：

模型 Priority 推理
Gemini 3.1 Flash-Lite 预览版 ✔️
Gemini 3.1 Pro 预览版 ✔️
Gemini 3 Flash 预览版 ✔️
Gemini 3 Pro Image 预览版 ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash Image ✔️
Gemini 2.5 Flash-Lite ✔️

后续步骤

了解 Gemini 的其他推理和优化选项：