الاستدلال المرن

واجهة برمجة التطبيقات Gemini Flex API هي طبقة استدلال تقدّم خصمًا بنسبة% 50 مقارنةً بالأسعار العادية، مقابل وقت استجابة متغيّر وتوفّر بأفضل جهد. تم تصميمها لأحمال العمل التي تتحمّل وقت الاستجابة والتي تتطلّب معالجة متزامنة ولكنّها لا تحتاج إلى الأداء في الوقت الفعلي الذي توفّره واجهة برمجة التطبيقات العادية.

كيفية استخدام الطبقة المرنة

لاستخدام الطبقة المرنة، حدِّد service_tier على أنّه flex في طلبك. تستخدم الطلبات الطبقة العادية تلقائيًا إذا تم حذف هذا الحقل.

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="Analyze this dataset for trends...",
        service_tier='flex'
    )
    print(interaction.steps[-1].content[0].text)
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: 'gemini-3-flash-preview',
            input: 'Analyze this dataset for trends...',
            serviceTier: 'flex'
        });
        console.log(interaction.steps.at(-1).content[0].text);
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}
await main();

راحة

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3-flash-preview",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'

آلية عمل الاستدلال المرن

يسدّ الاستدلال المرن في Gemini الفجوة بين واجهة برمجة التطبيقات العادية ومدة المعالجة التي تبلغ 24 ساعة في واجهة برمجة التطبيقات Batch API. ويستخدِم قدرة الحوسبة "القابلة للتخفيض" في أوقات انخفاض الطلب لتوفير حلّ فعّال من حيث التكلفة للمهام في الخلفية وسير العمل المتسلسل.

الميزة Flex الأولوية خطة "الرزمة العادية" مجمّعة
الأسعار خصم بنسبة% 50 أكثر بنسبة %75 إلى %100 من الخطة العادية السعر الكامل خصم بنسبة% 50
وقت الاستجابة دقائق (الهدف من دقيقة واحدة إلى 15 دقيقة) منخفض (ثوانٍ) من ثوانٍ إلى دقائق ما يصل إلى 24 ساعة
الموثوقية بأفضل جهد (قابلة للتخفيض) عالية (غير قابلة للتخفيض) عالية / متوسطة عالية عالية (لمعدّل نقل البيانات)
الواجهة متزامن متزامن متزامن غير متزامن

المزايا الرئيسية

  • فعالية التكلفة: وفورات كبيرة لعمليات التقييم غير الإنتاجية والوكلاء في الخلفية وإثراء البيانات
  • سهولة الاستخدام: ما عليك سوى إضافة مَعلمة واحدة إلى طلباتك الحالية.
  • سير العمل المتزامن: مثالي لسلاسل واجهات برمجة التطبيقات المتسلسلة حيث يعتمد الطلب التالي على ناتج الطلب السابق، ما يجعله أكثر مرونة من واجهة برمجة التطبيقات Batch API لسير العمل المستند إلى الوكلاء.

حالات الاستخدام

  • التقييمات بلا إنترنت: إجراء اختبارات الانحدار أو لوحات الصدارة "للنموذج اللغوي الكبير كحكم"
  • الوكلاء في الخلفية: مهام متسلسلة مثل تعديلات نظام إدارة علاقات العملاء أو إنشاء الملفات الشخصية أو الإشراف على المحتوى حيث تكون دقائق التأخير مقبولة
  • الأبحاث المقيّدة بالميزانية: التجارب الأكاديمية التي تتطلّب حجمًا كبيرًا من الرموز المميّزة بميزانية محدودة

حدود معدّل الاستخدام

يتم احتساب عدد الزيارات للاستدلال المرن ضمن حدود معدّل الاستخدام العامة rate limits، ولا يقدّم حدود معدّل استخدام ممتدة مثل Batch API.

القدرة القابلة للتخفيض

يتم التعامل مع عدد الزيارات المرنة بأولوية أقل. في حال حدوث ارتفاع في عدد الزيارات العادية، قد يتم إيقاف طلبات الطبقة المرنة أو إزالتها لضمان توفير القدرة للمستخدمين ذوي الأولوية العالية. إذا كنت تبحث عن استدلال ذي أولوية عالية، اطّلِع على الاستدلال ذي الأولوية

رموز الخطأ

عندما تكون القدرة المرنة غير متاحة أو يكون النظام مزدحمًا، ستعرض واجهة برمجة التطبيقات رموز الخطأ العادية:

  • خطأ 503: الخدمة غير متاحة: وصل النظام حاليًا إلى أقصى قدرته.
  • 429 Too Many Requests: حدود معدّل الاستخدام أو استنفاد الموارد

مسؤولية العميل

  • لا يوجد حلّ احتياطي من جهة الخادم: لمنع حدوث رسوم غير متوقّعة، لن يرقّي النظام تلقائيًا طلبًا مرنًا إلى الطبقة العادية إذا كانت القدرة المرنة ممتلئة.
  • إعادة المحاولة: عليك تنفيذ منطق إعادة المحاولة من جهة العميل باستخدام خوارزمية الرقود الأسي الثنائي.
  • مهلات الانتظار: بما أنّ الطلبات المرنة قد تبقى في صفّ الانتظار، ننصحك بزيادة مهلات الانتظار من جهة العميل إلى 10 دقائق أو أكثر لتجنُّب إغلاق الاتصال قبل الأوان.

تعديل فترات مهلة الانتظار

يمكنك ضبط مهلات الانتظار لكل طلب لواجهة برمجة التطبيقات REST API ومكتبات العميل. احرص دائمًا على أن تغطّي مهلة الانتظار من جهة العميل فترة الانتظار المقصودة من جهة الخادم (على سبيل المثال، 600 ثانية أو أكثر لقوائم انتظار الطبقة المرنة). تتوقّع حِزم تطوير البرامج (SDK) قيم مهلة الانتظار بالملّي ثانية.

مهلات الانتظار لكل طلب

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="why is the sky blue?",
        service_tier="flex",
        http_options={"timeout": 900000}
    )
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: "gemini-3-flash-preview",
            input: "why is the sky blue?",
            serviceTier: "flex",
            httpOptions: {timeout: 900000}
        });
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}

await main();

تنفيذ عمليات إعادة المحاولة

بما أنّ الطبقة المرنة قابلة للتخفيض وتؤدي إلى حدوث أخطاء 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.interactions.create(
                model="gemini-3-flash-preview",
                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:
                # Fallback to standard on last strike (Optional)
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-3-flash-preview",
                    input="Analyze this batch statement."
                )

# Usage
interaction = call_with_retry()
print(interaction.steps[-1].content[0].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 interaction = await ai.interactions.create({
        model: "gemini-3-flash-preview",
        input: "Analyze this batch statement.",
        serviceTier: '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-3-flash-preview",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
}

async function main() {
    const interaction = await callWithRetry();
    console.log(interaction.steps.at(-1).content[0].text);
}

await main();

الأسعار

يتم تسعير الاستدلال المرن بنسبة% 50 من واجهة برمجة التطبيقات العادية ، ويتم تحصيل الرسوم لكل رمز مميّز.

النماذج المتوافقة

تتوافق النماذج التالية مع الاستدلال المرن:

الطراز الاستدلال المرن
Gemini 3.1 Flash-Lite ‫✔️
Gemini 3.1 Flash-Lite (إصدار تجريبي) ‫✔️
Gemini 3.1 Pro (إصدار تجريبي) ‫✔️
Gemini 3 Flash (إصدار تجريبي) ‫✔️
Gemini 2.5 Pro ‫✔️
Gemini 2.5 Flash ‫✔️
Gemini 2.5 Flash-Lite ‫✔️

الخطوات التالية