# 优先推理

{% callout type="note" %}
该功能位于 [预览](/docs/models#preview).
{% /callout %}

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

优先级推断可跨 Interactions API 端点使用。

## 如何使用优先权  {% #how-to-use %}

要使用优先级，请设置 `service_tier` 您请求中的字段 `priority`。如果省略该字段，则默认层为标准层。

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Triage this critical customer support ticket immediately.",
    service_tier='priority'
)
print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
    const interaction = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        input: "Triage this critical customer support ticket immediately.",
        service_tier: "priority"
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ServiceTier;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.of("Perform a priority inference task."))
        .serviceTier(ServiceTier.PRIORITY)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:       interactions.Model("gemini-4-hydrogen"),
            Input:       interactions.NewInteractionsInput("Perform a priority inference task."),
            ServiceTier: interactions.ServiceTierPriority.ToPointer(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Triage this critical customer support ticket immediately.",
    "service_tier": "priority"
  }'
```
{% /tab %}
{% /tabs %}

## 优先级推断的工作原理  {% #how-it-works %}

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

| 特点      | 优先级           | 标准型  | 柔性            | 批次       |
| ------- | ------------- | ---- | ------------- | -------- |
| **价格**  | 75-100 比标准多 % | 全价   | 50%折扣         | 50%折扣    |
| **延迟**  | 秒数            | 秒到分钟 | 分钟（1-15 分钟目标） | 长达 24 小时 |
| **可靠性** | 高（不可脱落）       | 高/中高 | 尽力而为（可脱落）     | 高（针对吞吐量） |
| **接口**  | 同步            | 同步   | 同步            | 异步       |

### 主要优点  {% #benefits %}

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

* **高可靠性**：流量受到最高级别的处理，并且严格不可丢弃。

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

* **低摩擦**：使用相同的同步 `create` 方法作为标准层和 Flex 层。

### 使用案例  {% #use-cases %}

优先级处理非常适合性能和可靠性至关重要的业务关键型工作流程。

* **交互式人工智能应用**：客户服务聊天机器人和副驾驶，用户支付额外费用并期望快速、一致的响应。

* **实时决策引擎**：需要高度可靠、低延迟结果的系统，例如实时票证分类或欺诈检测。

* **高级客户功能**：需要为付费客户保证更高服务水平目标 (SLO) 的开发人员。

### 速率限制  {% #rate-limits %}

优先消费有其自己的速率限制，即使消费被计入 [总体交互流量限制](https://aistudio.google.com/rate-limit)。优先级推理的默认速率限制是 **0.3x 型号/层级的标准速率限制**

### 优雅的降级逻辑  {% #downgrade %}

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

### 客户责任  {% #client %}

* **反应监测**：开发者应该监控 `x-gemini-service-tier`
  API 响应中的标头，用于检测请求是否经常降级为 `standard`.

* **重试**：客户端必须针对标准错误实现重试逻辑/指数退避，例如 `DEADLINE_EXCEEDED`.

## 价格  {% #pricing %}

优先级推理的定价比 75-100 高 [标准 API](/docs/pricing) 并按 token 计费。

## 支持的模型  {% #supported-models %}

以下模型支持优先级推断：

| 模型                                                            | 优先推理 |
| ------------------------------------------------------------- | ---- |
| [Gemini 4 Carbon](/docs/models/gemini-4-carbon)               | ✔️   |
| [Gemini 4 Argon](/docs/models/gemini-4-argon)                 | ✔️   |
| [Gemini 4 Hydrogen](/docs/models/gemini-4-hydrogen)           | ✔️   |
| [Gemini 3.8 Flash](/docs/models/gemini-3.8-flash)             | ✔️   |
| [Gemini 3.6 Flash](/docs/models/gemini-3.6-flash)             | ✔️   |
| [Gemini 3.5 Flash-Lite](/docs/models/gemini-3.5-flash-lite)   | ✔️   |
| [Gemini 3.1 Flash-Lite](/docs/models/gemini-3.1-flash-lite)   | ✔️   |
| [Gemini 3.1 Pro Preview](/docs/models/gemini-3.1-pro-preview) | ✔️   |
| [Gemini 3 Flash Preview](/docs/models/gemini-3-flash-preview) | ✔️   |
| [Gemini 2.5 Pro](/docs/models/gemini-2.5-pro)                 | ✔️   |
| [Gemini 2.5 Flash](/docs/models/gemini-2.5-flash)             | ✔️   |
| [Gemini 2.5 Flash-Lite](/docs/models/gemini-2.5-flash-lite)   | ✔️   |

## 后续步骤  {% #whats-next %}

* [弹性推理](/docs/flex-inference) 以降低成本。
* [token](/docs/tokens)：了解token。
