弹性推理
Gemini Flex API 是一个推理层,与标准费率相比,可降低 50% 的成本,以换取可变延迟和尽力而为的可用性。它专为需要同步处理但不需要标准 API 的实时性能的耐延迟工作负载而设计。
如何使用Flex #
要使用 Flex 层,请指定 service_tier 作为 flex 在请求正文中。默认情况下,如果省略此字段,请求将使用标准层。
from google import genai
client = genai.Client()
try:
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Analyze this dataset for trends...",
config={"service_tier": "flex"},
)
print(response.text)
except Exception as e:
print(f"Flex request failed: {e}")
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Analyze this dataset for trends...",
config: { serviceTier: "flex" },
});
console.log(response.text);
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
}
await main();
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)
}
result, err := client.Models.GenerateContent(
ctx,
"gemini-4-hydrogen",
genai.Text("Analyze this dataset for trends..."),
&genai.GenerateContentConfig{
ServiceTier: "flex",
},
)
if err != nil {
log.Printf("Flex request failed: %v", err)
return
}
fmt.Println(result.Text())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts":[{"text": "Summarize the latest research on quantum computing."}]
}],
"service_tier": "flex"
}'
Flex 推理的工作原理 #
Gemini Flex 推理弥补了标准 API 和 24 小时周转时间之间的差距 Batch API。它利用非高峰、“可缩减”的计算能力,为后台任务和顺序工作流程提供经济高效的解决方案。
| 特点 | 柔性 | 优先级 | 标准型 | 批次 |
|---|---|---|---|---|
| 价格 | 50%折扣 | 75-100 比标准多 % | 全价 | 50%折扣 |
| 延迟 | 分钟(1-15 分钟目标) | 低(秒) | 秒到分钟 | 长达 24 小时 |
| 可靠性 | 尽力而为(可脱落) | 高(不可脱落) | 高/中高 | 高(针对吞吐量) |
| 接口 | 同步 | 同步 | 同步 | 异步 |
主要优点 #
- 成本效率:为非生产评估、背景智能体和数据丰富节省大量资金。
- 低摩擦:无需管理批次对象、作业 ID 或轮询;只需向现有请求添加一个参数即可。
- 同步工作流程:非常适合顺序 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()
try:
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="why is the sky blue?",
config={
"service_tier": "flex",
"http_options": {"timeout": 900000}
},
)
except Exception as e:
print(f"Flex request failed: {e}")
# Example with streaming
try:
response = client.models.generate_content_stream(
model="gemini-4-hydrogen",
contents=["List 5 ideas for a sci-fi movie."],
config={
"service_tier": "flex",
"http_options": {"timeout": 60000}
}
# Per-request timeout for the streaming operation
)
for chunk in response:
print(chunk.text, end="")
except Exception as e:
print(f"An error occurred during streaming: {e}")
import {GoogleGenAI} from '@google/genai';
const client = new GoogleGenAI({});
async function main() {
try {
const response = await client.models.generateContent({
model: "gemini-4-hydrogen",
contents: "why is the sky blue?",
config: {
serviceTier: "flex",
httpOptions: {timeout: 900000}
},
});
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
// Example with streaming
try {
const response = await client.models.generateContentStream({
model: "gemini-4-hydrogen",
contents: ["List 5 ideas for a sci-fi movie."],
config: {
serviceTier: "flex",
httpOptions: {timeout: 60000}
},
});
for await (const chunk of response.stream) {
process.stdout.write(chunk.text());
}
} catch (e) {
console.log(`An error occurred during streaming: ${e}`);
}
}
await main();
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/api/iterator"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
defer client.Close()
timeoutCtx, cancel := context.WithTimeout(ctx, 900*time.Second)
defer cancel()
_, err = client.Models.GenerateContent(
timeoutCtx,
"gemini-4-hydrogen",
genai.Text("why is the sky blue?"),
&genai.GenerateContentConfig{
ServiceTier: "flex",
},
)
if err != nil {
fmt.Printf("Flex request failed: %v\n", err)
}
// Example with streaming
streamTimeoutCtx, streamCancel := context.WithTimeout(ctx, 60*time.Second)
defer streamCancel()
iter := client.Models.GenerateContentStream(
streamTimeoutCtx,
"gemini-4-hydrogen",
genai.Text("List 5 ideas for a sci-fi movie."),
&genai.GenerateContentConfig{
ServiceTier: "flex",
},
)
for {
response, err := iter.Next()
if err == iterator.Done {
break
}
if err != nil {
fmt.Printf("An error occurred during streaming: %v\n", err)
break
}
fmt.Print(response.Candidates[0].Content.Parts[0])
}
}
进行 REST 调用时,您可以使用 HTTP 标头和 curl 选项:
X-Server-Timeout标头(服务器端超时):此标头向 Gemini API 服务器建议首选超时持续时间(默认 600 秒)。服务器将尝试尊重这一点,但不能保证。该值应以秒为单位。--max-time在curl(客户端超时): 的curl --max-time选项对总时间(以秒为单位)设置硬性限制curl将等待整个操作完成。这是客户端的保护措施。
# Set a server timeout hint of 120 seconds and a client-side curl timeout of 125 seconds.
curl --max-time 125 \
-X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Server-Timeout: 120" \
-d '{
"contents": [{
"parts":[{"text": "Summarize the latest research on quantum computing."}]
}],
"service_tier": "flex"
}'
全局超时 #
如果您希望通过特定的 API 调用 genai.Client 实例(仅限客户端库)具有默认超时,您可以在初始化客户端时使用以下命令进行配置: http_options 和 genai.types.HttpOptions.
from google import genai
from google.genai import types
global_timeout_ms = 120000
client_with_global_timeout = genai.Client(
http_options=types.HttpOptions(timeout=global_timeout_ms)
)
try:
# Calling generate_content using global timeout...
response = client_with_global_timeout.models.generate_content(
model="gemini-4-hydrogen",
contents="Summarize the history of AI development since 2000.",
config={"service_tier": "flex"},
)
print(response.text)
# A per-request timeout will *override* the global timeout for that specific call.
shorter_timeout = 30000
response = client_with_global_timeout.models.generate_content(
model="gemini-4-hydrogen",
contents="Provide a very brief definition of machine learning.",
config={
"service_tier": "flex",
"http_options":{"timeout": shorter_timeout}
} # Overrides the global timeout
)
print(response.text)
except TimeoutError:
print(
f"A GenerateContent call timed out. Check if the global or per-request timeout was exceeded."
)
except Exception as e:
print(f"An error occurred: {e}")
import {GoogleGenAI} from '@google/genai';
const globalTimeoutMs = 120000;
const clientWithGlobalTimeout = new GoogleGenAI({httpOptions: {timeout: globalTimeoutMs}});
async function main() {
try {
// Calling generate_content using global timeout...
const response1 = await clientWithGlobalTimeout.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Summarize the history of AI development since 2000.",
config: { serviceTier: "flex" },
});
console.log(response1.text());
// A per-request timeout will *override* the global timeout for that specific call.
const shorterTimeout = 30000;
const response2 = await clientWithGlobalTimeout.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Provide a very brief definition of machine learning.",
config: {
serviceTier: "flex",
httpOptions: {timeout: shorterTimeout}
} // Overrides the global timeout
});
console.log(response2.text());
} catch (e) {
if (e.name === 'TimeoutError' || e.message?.includes('timeout')) {
console.log(
"A GenerateContent call timed out. Check if the global or per-request timeout was exceeded."
);
} else {
console.log(`An error occurred: ${e}`);
}
}
}
await main();
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Analyze this dataset for trends...",
config: { serviceTier: "flex" },
});
console.log(response.text);
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
}
await main();
实施重试 #
由于 Flex 是可脱落的并且会因 503 错误而失败,因此这里是一个可选地实现重试逻辑以继续处理失败请求的示例:
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Analyze this dataset for trends...",
config: { serviceTier: "flex" },
});
console.log(response.text);
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
}
await main();
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Analyze this dataset for trends...",
config: { serviceTier: "flex" },
});
console.log(response.text);
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
}
await main();
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: "Analyze this dataset for trends...",
config: { serviceTier: "flex" },
});
console.log(response.text);
} catch (e) {
console.log(`Flex request failed: ${e}`);
}
}
await main();
价格 #
Flex 推理的定价为 50% 标准 API 并按 token 计费。
支持的模型 #
以下模型支持 Flex 推理:
后续步骤 #
了解 Gemini 的其他内容 推理和优化 选项: