Гибкий инференс

Описание: узнайте, как оптимизировать расходы с помощью уровня вывода Flex

Gemini Flex API – это уровень инференса, который позволяет снизить затраты на 50% по сравнению со стандартными тарифами в обмен на переменную задержку и доступность по мере возможности. Он предназначен для рабочих нагрузок, допускающих задержку и требующих синхронной обработки, но не нуждающихся в производительности стандартного API в реальном времени.

Как использовать Flex

Чтобы использовать уровень 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 Inference позволяет сократить разрыв между стандартным API и 24-часовым временем обработки Batch API. Он использует вычислительные мощности, которые можно отключить в периоды низкой нагрузки, чтобы обеспечить экономичное решение для фоновых задач и последовательных рабочих процессов.

Функция Согнуть Приоритет Стандартный Пакетное задание
Цены Скидка 50 % на 75–100% больше, чем в подписке Standard; Полная цена Скидка 50 %
Задержка Минуты (цель – 1–15 мин.) Низкая (секунды) Секунды в минуты До 24 часов
Надежность Негарантированное обслуживание (с возможностью отбрасывания) Высокий (неосыпающийся) Высокий / выше среднего Высокая (для пропускной способности)
Интерфейс Синхронная Синхронная Синхронная Асинхронный код

Основные преимущества

  • Экономичность. Значительная экономия при оценке непроизводственных сред, работе фоновых агентов и обогащении данных.
  • Простота использования. Вам не нужно управлять пакетными объектами, идентификаторами заданий или опросами. Достаточно добавить один параметр в существующие запросы.
  • Синхронные рабочие процессы. Идеально подходят для последовательных цепочек API, в которых следующий запрос зависит от результата предыдущего. Это делает их более гибкими, чем пакетные запросы, для рабочих процессов с агентами.

Примеры использования

  • Офлайн-оценка. Проведение регрессионных тестов или составление рейтингов с использованием LLM в качестве судьи.
  • Фоновые агенты. Последовательные задачи, такие как обновление CRM, создание профиля или модерация контента, где допустима задержка в несколько минут.
  • Исследования с ограниченным бюджетом. Академические эксперименты, для которых требуется большое количество токенов при ограниченном бюджете.

Ограничение частоты запросов

Трафик гибкого инференса учитывается в общих ограничениях частоты запросов. Для него не действуют расширенные ограничения, как для Batch API.

Отключаемая мощность

Трафик Flex имеет более низкий приоритет. Если объем стандартного трафика резко увеличится, запросы Flex могут быть вытеснены, чтобы обеспечить пропускную способность для пользователей с высоким приоритетом. Если вам нужен приоритетный инференс, выберите Приоритетный инференс.

Коды ошибок

Если гибкая емкость недоступна или система перегружена, API возвращает стандартные коды ошибок:

  • 503 Service Unavailable – система перегружена.
  • 429 Too Many Requests – превышено ограничение частоты запросов или исчерпаны ресурсы.

Ответственность клиента

  • Нет резервного варианта на стороне сервера. Чтобы избежать неожиданных расходов, система не будет автоматически переводить запрос Flex на уровень Standard, если емкость Flex будет заполнена.
  • Повторные попытки. Вам необходимо реализовать собственную логику повторных попыток на стороне клиента с экспоненциальной выдержкой.
  • Тайм-ауты. Поскольку запросы Flex могут находиться в очереди, мы рекомендуем увеличить клиентские тайм-ауты до 10 минут или более, чтобы избежать преждевременного закрытия подключения.

Как настроить окна ожидания

Вы можете настроить тайм-ауты на уровне запроса для REST API и клиентских библиотек, а также глобальные тайм-ауты только при использовании клиентских библиотек.

Всегда следите за тем, чтобы клиентское время ожидания покрывало предполагаемое время ожидания на стороне сервера (например, 600 секунд и более для очередей ожидания Flex). В SDK значения времени ожидания указываются в миллисекундах.

Время ожидания для каждого запроса

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 API предпочтительную продолжительность тайм-аута (по умолчанию 600 с). Сервер попытается выполнить это требование, но не гарантирует его соблюдение. Значение должно быть указано в секундах.

  • --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"
 }'

Глобальные тайм-ауты

Если вы хотите, чтобы у всех вызовов API, выполненных через определенный экземпляр 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 можно отменить и он выдает ошибки с кодом 503, ниже приведен пример того, как можно реализовать логику повторных попыток, чтобы продолжить работу с неудачными запросами:

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

Цены

Стоимость гибкого вывода составляет 50% от стандартной цены API и рассчитывается за токен.

Поддерживаемые модели

Flex-вывод поддерживается на следующих моделях:

Модель Гибкий инференс
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 Image ✔️
Gemini 2.5 Flash-Lite ✔️

Дальнейшие действия

Узнайте больше о других вариантах вывода и оптимизации Gemini: