«میانای برنامهسازی کاربردی Gemini Flex» یک سطح استنباطی است که درمقایسه با نرخهای استاندارد، ۵۰٪ کاهش هزینه ارائه میدهد، درعوض تأخیر متغیر و دردسترس بودن با تمام تلاش را ارائه میدهد. این API برای حجمهای کاری با تأخیرپذیری طراحی شده است که به پردازش همزمان نیاز دارند اما به عملکرد همزمان API استاندارد نیاز ندارند.
نحوه استفاده از Flex
برای استفاده از سطح «انعطافپذیر»، service_tier را در
بدنه درخواست بهعنوان flex مشخص کنید. اگر این فیلد حذف شود، درخواستها بهطور پیشفرض از سطح استاندارد استفاده میکنند.
Python
from google import genai
client = genai.Client()
try:
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Analyze this dataset for trends...",
config={"service_tier": "flex"},
)
print(response.text)
except Exception as e:
print(f"Flex request failed: {e}")
JavaScript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
try {
const response = await ai.models.generateContent({
model: "gemini-3.8-flash",
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-3.8-flash",
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())
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts":[{"text": "Summarize the latest research on quantum computing."}]
}],
"service_tier": "flex"
}'
نحوه عملکرد استنتاج انعطافپذیر
استنباط Gemini Flex شکاف بین «میانای برنامهسازی کاربردی» استاندارد و زمان پاسخ ۲۴ ساعته میانای برنامهسازی کاربردی دستهای را پر میکند. این سرویس از ظرفیت محاسباتی خارج از اوج مصرف و «قابلکاهش» استفاده میکند تا راهحلی مقرونبهصرفه برای وظایف پسزمینهای و گردشهای کار ترتیبی ارائه دهد.
| ویژگی | بهرخ کشیدن | اولویت | استاندارد | دسته |
|---|---|---|---|---|
| قیمتگذاری | ٪۵۰ تخفیف | ۷۵ تا ۱۰۰٪ بیشتر از «استاندارد» | قیمت کامل | ٪۵۰ تخفیف |
| تأخیر | دقیقه (هدف ۱ تا ۱۵ دقیقه) | کم (ثانیه) | ثانیه به دقیقه | حداکثر ۲۴ ساعت |
| قابلیت اطمینان | نهایت تلاش (قابلحذف) | زیاد (غیرقابل ریزش) | زیاد / متوسط روبهبالا | بالا (برای توان گذرداد) |
| میانای | همزمان | همزمان | همزمان | غیرهمگام |
مزایای کلیدی
- کارایی هزینه: صرفهجویی قابلتوجه برای ارزیابیهای غیرتولیدی، کارگزاران پسزمینه، و غنیسازی دادهها.
- اصطکاک کم: نیازی به مدیریت کردن اشیای دستهای، شناسههای کار، یا نظرسنجی نیست؛ کافی است یک پارامتر به درخواستهای موجودتان اضافه کنید.
- گردش کارهای همزمان: برای زنجیرههای متوالی میانای برنامهسازی کاربردی که در آن درخواست بعدی به برونداد درخواست قبلی بستگی دارد ایدهآل است و آن را انعطافپذیرتر از «دستهای» برای گردش کارهای عاملگرا میکند.
موارد استفاده
- ارزیابیهای آفلاین: اجرای آزمونهای پسرفت «مدل زبانی بزرگ بهعنوان داور» یا تابلوهای امتیازات.
- عاملهای پسزمینه: تکالیف ترتیبی مثل بهروزرسانیهای CRM، ساختن نمایههای شخصی، یا مدیریت محتوا که در آنها چند دقیقه تأخیر قابلقبول است.
- پژوهش با بودجه محدود: آزمایشهای آکادمیک که به حجم بالای کد با بودجه محدود نیاز دارند.
محدودیتهای نرخ
ترافیک استنباط انعطافپذیر در حدود نرخ کلی شما محاسبه میشود؛ این ترافیک حدود نرخ گستردهای مانند Batch API ارائه نمیدهد.
ظرفیت قابلکاهش
با ترافیک انعطافپذیر با اولویت پایینتر رفتار میشود. اگر افزایش ناگهانی در ترافیک استاندارد وجود داشته باشد، درخواستهای Flex ممکن است برای اطمینان از ظرفیت برای کاربران با اولویت بالا، پیشگیری یا حذف شوند. اگر بهدنبال استنباط اولویت بالا هستید، استنباط اولویتدار را بررسی کنید
کدهای خطا
وقتی ظرفیت «انعطافپذیر» دردسترس نباشد یا سیستم دچار ازدحام باشد، «میانای برنامهسازی کاربردی» کدهای خطای استاندارد را برمیگرداند:
- ۵۰۳ سرویس دردسترس نیست: درحالحاضر، سیستم به حداکثر ظرفیت رسیده است.
- 429 درخواستهای بیشازحد: محدودیتهای نرخ یا اتمام منابع.
مسئولیت کارخواه
- بدون بازگشت به سمت سرور: برای جلوگیری از هزینههای غیرمنتظره، اگر ظرفیت Flex تکمیل شده باشد، سیستم بهطور خودکار درخواست Flex را به سطح «استاندارد» ارتقا نخواهد داد.
- تلاشهای مجدد: باید منطق تلاش مجدد سمت کارخواه خودتان را با پسگیری نمایی پیادهسازی کنید.
- زمانهای اتمام: ازآنجاییکه درخواستهای Flex ممکن است در صف قرار بگیرند، توصیه میکنیم زمانهای اتمام سمت مشتری را به ۱۰ دقیقه یا بیشتر افزایش دهید تا از بسته شدن زودرس اتصال جلوگیری شود.
تنظیم کردن پنجرههای مهلت زمانی
میتوانید زمانهای اتمام درخواست را برای REST API و کتابخانههای کارخواه پیکربندی کنید، و زمانهای اتمام سراسری را فقط هنگام استفاده از کتابخانههای کارخواه پیکربندی کنید.
همیشه مطمئن شوید که مهلت زمانی سمت مشتری شما پنجره صبر سرور موردنظر را پوشش میدهد (برای نمونه، ۶۰۰ ثانیه و بیشتر برای صفهای انتظار Flex). کیتهای توسعه نرمافزار مقادیر درنگ را برحسب میلیثانیه انتظار دارند.
زمانهای اتمام درخواست
Python
from google import genai
client = genai.Client()
try:
response = client.models.generate_content(
model="gemini-3.8-flash",
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-3.8-flash",
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}")
JavaScript
import {GoogleGenAI} from '@google/genai';
const client = new GoogleGenAI({});
async function main() {
try {
const response = await client.models.generateContent({
model: "gemini-3.8-flash",
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-3.8-flash",
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-3.8-flash",
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-3.8-flash",
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
هنگام برقراری تماسهای REST، میتوانید بااستفاده از ترکیبی از سرایندهای HTTP و گزینههای curl، زمانهای اتمام را کنترل کنید:
سرصفحه
X-Server-Timeout(مهلت زمانی سرور): این سرصفحه مدت زمان مهلت زمانی ترجیحی (پیشفرض ۶۰۰ ثانیه) را به سرور «میانای برنامهسازی کاربردی Gemini» پیشنهاد میدهد. کارساز تلاش خواهد کرد این مورد را رعایت کند، اما تضمینی وجود ندارد. مقدار باید برحسب ثانیه باشد.--max-timeدرcurl(مهلت زمانی سمت کارخواه): گزینهcurl --max-time <seconds>محدودیت سختی برای کل زمان (به ثانیه) تعیین میکند که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-3.8-flash: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"
}'
درنگهای سراسری
اگر میخواهید همه تماسهای «میانای برنامهسازی کاربردی» که ازطریق نمونه genai.Client خاصی (فقط کتابخانههای کارخواه) برقرار میشوند زمان اتمام پیشفرض داشته باشند، میتوانید این را هنگام مقداردهی اولیه کارخواه بااستفاده از http_options و genai.types.HttpOptions پیکربندی کنید.
Python
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-3.8-flash",
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-3.8-flash",
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}")
JavaScript
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-3.8-flash",
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-3.8-flash",
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();
رفتن
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-3.8-flash")
// Go uses context for timeouts, not client options.
// Set a default timeout for requests.
globalTimeout := 120 * time.Second
fmt.Printf("Using default timeout of %v seconds.\n", globalTimeout.Seconds())
fmt.Println("Calling generate_content (using default timeout)...")
ctx1, cancel1 := context.WithTimeout(ctx, globalTimeout)
defer cancel1()
resp1, err := model.GenerateContent(ctx1, genai.Text("Summarize the history of AI development since 2000."), &genai.GenerateContentConfig{ServiceTier: "flex"})
if err != nil {
log.Printf("Request 1 failed: %v", err)
} else {
fmt.Println("GenerateContent 1 successful.")
fmt.Println(resp1.Text())
}
// A different timeout can be used for other requests.
shorterTimeout := 30 * time.Second
fmt.Printf("\nCalling generate_content with a shorter timeout of %v seconds...\n", shorterTimeout.Seconds())
ctx2, cancel2 := context.WithTimeout(ctx, shorterTimeout)
defer cancel2()
resp2, err := model.GenerateContent(ctx2, genai.Text("Provide a very brief definition of machine learning."), &genai.GenerateContentConfig{
ServiceTier: "flex",
})
if err != nil {
log.Printf("Request 2 failed: %v", err)
} else {
fmt.Println("GenerateContent 2 successful.")
fmt.Println(resp2.Text())
}
}
پیادهسازی تلاشهای مجدد
ازآنجاییکه Flex قابلحذف است و با خطاهای ۵۰۳ ازکار میافتد، در اینجا نمونهای از پیادهسازی اختیاری منطق تلاش مجدد برای ادامه دادن با درخواستهای ناموفق آورده شده است:
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.models.generate_content(
model="gemini-3.8-flash",
contents="Analyze this batch statement.",
config={"service_tier": "flex"},
)
except Exception as e:
# Check for 503 Service Unavailable or 429 Rate Limits
print(e.code)
if attempt < max_retries - 1:
delay = base_delay * (2 ** attempt) # Exponential Backoff
print(f"Flex busy, retrying in {delay}s...")
time.sleep(delay)
else:
# Fallback to standard on last strike (Optional)
print("Flex exhausted, falling back to Standard...")
return client.models.generate_content(
model="gemini-3.8-flash",
contents="Analyze this batch statement."
)
# Usage
response = call_with_retry()
print(response.text)
JavaScript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({});
async function sleep(ms) {
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 response = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "Analyze this batch statement.",
config: { serviceTier: 'flex' },
});
return response;
} 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.models.generateContent({
model: "gemini-3.8-flash",
contents: "Analyze this batch statement.",
});
}
}
}
}
async function main() {
const response = await callWithRetry();
console.log(response.text);
}
await main();
رفتن
package main
import (
"context"
"fmt"
"log"
"math"
"time"
"google.golang.org/genai"
)
func callWithRetry(ctx context.Context, client *genai.Client, maxRetries int, baseDelay time.Duration) (*genai.GenerateContentResponse, error) {
modelName := "gemini-3.8-flash"
content := genai.Text("Analyze this batch statement.")
flexConfig := &genai.GenerateContentConfig{
ServiceTier: "flex",
}
for attempt := 0; attempt < maxRetries; attempt++ {
log.Printf("Attempt %d: Calling Flex tier...", attempt+1)
resp, err := client.Models.GenerateContent(ctx, modelName, content, flexConfig)
if err == nil {
return resp, nil
}
log.Printf("Attempt %d failed: %v", attempt+1, err)
if attempt < maxRetries-1 {
delay := time.Duration(float64(baseDelay) * math.Pow(2, float64(attempt)))
log.Printf("Flex busy, retrying in %v...", delay)
time.Sleep(delay)
} else {
log.Println("Flex exhausted, falling back to Standard...")
return client.Models.GenerateContent(ctx, modelName, content)
}
}
return nil, fmt.Errorf("retries exhausted") // Should not be reached
}
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
defer client.Close()
resp, err := callWithRetry(ctx, client, 3, 5*time.Second)
if err != nil {
log.Fatalf("Failed after retries: %v", err)
}
fmt.Println(resp.Text())
}
قیمتگذاری
قیمت استنباط انعطافپذیر ۵۰٪ از میانای برنامهسازی کاربردی استاندارد است و براساس تعداد نشان صورتحساب میشود.
مدلهای پشتیبانیشده
مدلهای زیر از استنتاج انعطافپذیر پشتیبانی میکنند:
| مدل | استنتاج انعطافپذیر |
|---|---|
| Gemini 3.8 Flash | ✔️ |
| Gemini 3.6 Flash | ✔️ |
| Gemini 3.5 Flash-Lite | ✔️ |
| Gemini 3.1 Flash-Lite | ✔️ |
| پیشنمایش Gemini 3.1 Pro | ✔️ |
| پیشنمایش Gemini 3 Flash | ✔️ |
| پیشنمایش تصویر Gemini 3 Pro | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| تصویر Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
قدم بعدی چیست
درباره سایر گزینههای استنباط و بهینهسازی Gemini بخوانید:
- استنباط اولویت برای تأخیر بسیار کم.
- Batch API برای پردازش ناهمزمان در عرض ۲۴ ساعت.
- ذخیره کردن بافت در حافظه نهان برای کاهش هزینههای کد ورودی.