# 弹性推理

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

Gemini Flex API 是一个推理层，与标准费率相比，可降低 50% 的成本，以换取可变延迟和尽力而为的可用性。它专为需要同步处理但不需要标准 API 的实时性能的耐延迟工作负载而设计。

## 如何使用Flex  {% #how-to-use-flex %}

要使用 Flex 层，请指定 `service_tier` 作为 `flex` 在你的要求中。默认情况下，如果省略此字段，请求将使用标准层。

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Analyze this dataset for trends...",
    service_tier='flex'
)
print(interaction.output_text)
```
{% /tab %}

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

const client = new GoogleGenAI({});

async function main() {
    const interaction = await client.interactions.create({
        model: 'gemini-4-hydrogen',
        input: 'Analyze this dataset for trends...',
        service_tier: 'flex'
    });
    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("Analyze this dataset for trends..."))
        .serviceTier(ServiceTier.FLEX)
        .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("Analyze this dataset for trends..."),
            ServiceTier: interactions.ServiceTierFlex.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": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'
```
{% /tab %}
{% /tabs %}

## Flex 推理的工作原理  {% #how-it-works %}

Gemini Flex 推理弥补了标准 API 和 24 小时周转时间之间的差距 [Batch API](/docs/batch-api)。它利用非高峰、“可缩减”的计算能力，为后台任务和顺序工作流程提供经济高效的解决方案。

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

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

* **成本效率**：为非生产评估、背景智能体和数据丰富节省大量资金。
* **低摩擦**：只需向现有请求添加一个参数即可。
* **同步工作流程**：非常适合顺序 API 链，其中下一个请求取决于前一个请求的输出，使其比智能体工作流程的 Batch 更加灵活。

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

* **线下评价**：运行“LLM-as-a-judge”回归测试或排行榜。
* **背景智能体**：连续任务，例如 CRM 更新、配置文件构建或内容审核，几分钟的延迟是可以接受的。
* **预算有限的研究**：在有限的预算下需要大量 token 的学术实验。

### 速率限制  {% #quota %}

Flex 推理流量计入您的总体流量 [速率限制](https://aistudio.google.com/rate-limit);它不提供像 [Batch API](/docs/batch-api).

### 可脱落容量  {% #capacity %}

Flex 流量的优先级较低。如果标准流量出现峰值，Flex 请求可能会被抢占或驱逐，以确保高优先级用户的容量。如果您正在寻找高优先级推理，请检查 [优先推理](/docs/priority-inference)

### 错误代码  {% #error-codes %}

当Flex容量不可用或系统拥塞时，API将返回标准错误代码：

* **503服务不可用**：系统当前已满负荷。
* **429 请求过多**：速率限制或资源耗尽。

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

* **没有服务器端回退**：为了防止意外收费，如果 Flex 容量已满，系统不会自动将 Flex 请求升级到标准层。

* **重试**：您必须使用指数退避来实现自己的客户端重试逻辑。

* **超时**：由于 Flex 请求可能位于队列中，因此我们建议将客户端超时增加到 10 分钟或更长，以避免连接过早关闭。

## 调整超时窗口  {% #timeout %}

您可以为 REST API 和客户端库配置每个请求超时。始终确保客户端超时覆盖预期的服务器耐心窗口（例如，Flex 等待队列为 600 秒以上）。 SDK 期望超时值以毫秒为单位。

### 每个请求超时  {% #per-request-timeout %}

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

client = genai.Client(http_options={"timeout": 900000})

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="why is the sky blue?",
    service_tier="flex",
)
```
{% /tab %}

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

const client = new GoogleGenAI({});

async function main() {
    const interaction = await client.interactions.create({
        model: "gemini-4-hydrogen",
        input: "why is the sky blue?",
        service_tier: "flex",
    }, {timeout: 900000});
}

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;
import com.google.genai.types.HttpOptions;

Client client =
    Client.builder()
        .httpOptions(HttpOptions.builder().timeout(900000).build())
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.of("why is the sky blue?"))
        .serviceTier(ServiceTier.FLEX)
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
```
{% /tab %}

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

import (
    "context"
    "log"
    "time"

    "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, &genai.ClientConfig{
        HTTPOptions: genai.HTTPOptions{
            Timeout: genai.Ptr(15 * time.Minute),
        },
    })
    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("why is the sky blue?"),
            ServiceTier: interactions.ServiceTierFlex.ToPointer(),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = res
}
```
{% /tab %}
{% /tabs %}

## 实施重试  {% #retries %}

由于 Flex 是可脱落的并且会因 503 错误而失败，因此这里是一个可选地实现重试逻辑以继续处理失败请求的示例：

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

client = genai.Client()

def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(
                model="gemini-4-hydrogen",
                input="Analyze this batch statement.",
                service_tier="flex",
            )
        except Exception as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-4-hydrogen",
                    input="Analyze this batch statement."
                )

interaction = call_with_retry()
print(interaction.output_text)
```
{% /tab %}

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

const ai = new GoogleGenAI({});

async function sleep(ms = 1000) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function callWithRetry(maxRetries = 3, baseDelay = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      console.log(`Attempt ${attempt + 1}: Calling Flex tier...`);
      const interaction = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        input: "Analyze this batch statement.",
        service_tier: 'flex',
      });
      return interaction;
    } catch (e) {
      if (attempt < maxRetries - 1) {
        const delay = baseDelay * (2 ** attempt);
        console.log(`Flex busy, retrying in ${delay}s...`);
        await sleep(delay * 1000);
      } else {
        console.log("Flex exhausted, falling back to Standard...");
        return await ai.interactions.create({
          model: "gemini-4-hydrogen",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
  throw new Error("Failed to complete request with retry.");
}

async function main() {
    const interaction = await callWithRetry();
    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();

int maxRetries = 3;
int baseDelay = 5;
Interaction interaction = null;

for (int attempt = 0; attempt < maxRetries; attempt++) {
  try {
    CreateModelInteraction flexParams =
        CreateModelInteraction.builder()
            .model(Model.of("gemini-4-hydrogen"))
            .input(InteractionsInput.of("Analyze this batch statement."))
            .serviceTier(ServiceTier.FLEX)
            .build();
    interaction =
        client.interactions.create(CreateInteractionRequestBody.of(flexParams)).interaction().get();
    break;
  } catch (Exception e) {
    if (attempt < maxRetries - 1) {
      int delay = baseDelay * (1 << attempt); // Exponential Backoff
      System.out.println("Flex busy, retrying in " + delay + "s...");
      Thread.sleep(delay * 1000L);
    } else {
      System.out.println("Flex exhausted, falling back to Standard...");
      CreateModelInteraction standardParams =
          CreateModelInteraction.builder()
              .model(Model.of("gemini-4-hydrogen"))
              .input(InteractionsInput.of("Analyze this batch statement."))
              .build();
      interaction =
          client
              .interactions
              .create(CreateInteractionRequestBody.of(standardParams))
              .interaction()
              .get();
    }
  }
}

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

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

import (
    "context"
    "fmt"
    "log"
    "time"

    "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)
    }

    maxRetries := 3
    baseDelay := 5
    var interaction *interactions.Interaction

    for attempt := 0; attempt < maxRetries; attempt++ {
        res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
            Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                Model:       interactions.Model("gemini-4-hydrogen"),
                Input:       interactions.NewInteractionsInput("Analyze this batch statement."),
                ServiceTier: interactions.ServiceTierFlex.ToPointer(),
            }),
        })
        if err == nil {
            interaction = res.Interaction
            break
        }

        if attempt < maxRetries-1 {
            delay := baseDelay * (1 << attempt) // Exponential Backoff
            fmt.Printf("Flex busy, retrying in %ds...\n", delay)
            time.Sleep(time.Duration(delay) * time.Second)
        } else {
            fmt.Println("Flex exhausted, falling back to Standard...")
            stdRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
                Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
                    Model: interactions.Model("gemini-4-hydrogen"),
                    Input: interactions.NewInteractionsInput("Analyze this batch statement."),
                }),
            })
            if err != nil {
                log.Fatal(err)
            }
            interaction = stdRes.Interaction
        }
    }

    if interaction != nil && interaction.OutputText != nil {
        fmt.Println(*interaction.OutputText)
    }
}
```
{% /tab %}
{% /tabs %}

## 价格  {% #pricing %}

Flex 推理的定价为 50% [标准 API](/docs/pricing)
并按 token 计费。

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

以下模型支持 Flex 推理：

| 模型                                                            | 弹性推理 |
| ------------------------------------------------------------- | ---- |
| [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/priority-inference) 实现超低延迟。
* [token](/docs/tokens)：了解token。
