弹性推理
Gemini Flex API 是一个推理层,与标准费率相比,可降低 50% 的成本,以换取可变延迟和尽力而为的可用性。它专为需要同步处理但不需要标准 API 的实时性能的耐延迟工作负载而设计。
如何使用Flex #
要使用 Flex 层,请指定 service_tier 作为 flex 在你的要求中。默认情况下,如果省略此字段,请求将使用标准层。
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)
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();
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(""));
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)
}
}
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"
}'
Flex 推理的工作原理 #
Gemini Flex 推理弥补了标准 API 和 24 小时周转时间之间的差距 Batch API。它利用非高峰、“可缩减”的计算能力,为后台任务和顺序工作流程提供经济高效的解决方案。
| 特点 | 柔性 | 优先级 | 标准型 | 批次 |
|---|---|---|---|---|
| 价格 | 50%折扣 | 75-100 比标准多 % | 全价 | 50%折扣 |
| 延迟 | 分钟(1-15 分钟目标) | 低(秒) | 秒到分钟 | 长达 24 小时 |
| 可靠性 | 尽力而为(可脱落) | 高(不可脱落) | 高/中高 | 高(针对吞吐量) |
| 接口 | 同步 | 同步 | 同步 | 异步 |
主要优点 #
- 成本效率:为非生产评估、背景智能体和数据丰富节省大量资金。
- 低摩擦:只需向现有请求添加一个参数即可。
- 同步工作流程:非常适合顺序 API 链,其中下一个请求取决于前一个请求的输出,使其比智能体工作流程的 Batch 更加灵活。
使用案例 #
- 线下评价:运行“LLM-as-a-judge”回归测试或排行榜。
- 背景智能体:连续任务,例如 CRM 更新、配置文件构建或内容审核,几分钟的延迟是可以接受的。
- 预算有限的研究:在有限的预算下需要大量 token 的学术实验。
速率限制 #
Flex 推理流量计入您的总体流量 速率限制;它不提供像 Batch API.
可脱落容量 #
Flex 流量的优先级较低。如果标准流量出现峰值,Flex 请求可能会被抢占或驱逐,以确保高优先级用户的容量。如果您正在寻找高优先级推理,请检查 优先推理
错误代码 #
当Flex容量不可用或系统拥塞时,API将返回标准错误代码:
- 503服务不可用:系统当前已满负荷。
- 429 请求过多:速率限制或资源耗尽。
客户责任 #
没有服务器端回退:为了防止意外收费,如果 Flex 容量已满,系统不会自动将 Flex 请求升级到标准层。
重试:您必须使用指数退避来实现自己的客户端重试逻辑。
超时:由于 Flex 请求可能位于队列中,因此我们建议将客户端超时增加到 10 分钟或更长,以避免连接过早关闭。
调整超时窗口 #
您可以为 REST API 和客户端库配置每个请求超时。始终确保客户端超时覆盖预期的服务器耐心窗口(例如,Flex 等待队列为 600 秒以上)。 SDK 期望超时值以毫秒为单位。
每个请求超时 #
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",
)
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();
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();
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
}
实施重试 #
由于 Flex 是可脱落的并且会因 503 错误而失败,因此这里是一个可选地实现重试逻辑以继续处理失败请求的示例:
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)
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();
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(""));
}
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)
}
}
价格 #
Flex 推理的定价为 50% 标准 API 并按 token 计费。
支持的模型 #
以下模型支持 Flex 推理: