Session management with Live API

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

مدّة الجلسة

بدون الضغط، تقتصر جلسات الصوت فقط على 15 دقيقة، وتقتصر جلسات الصوت والفيديو على دقيقتين. سيؤدي تجاوز هذه الحدود القصوى إلى إنهاء الجلسة (وبالتالي الاتصال)، ولكن يمكنك استخدام ضغط نافذة السياق لإطالة الجلسات إلى مدة غير محدودة.

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

ضغط قدرة الاستيعاب

لتفعيل جلسات أطول وتجنُّب إنهاء الاتصال بشكل مفاجئ، يمكنك تفعيل ضغط نافذة السياق من خلال ضبط الحقل contextWindowCompression كجزء من إعدادات الجلسة.

في ContextWindowCompressionConfig، يمكنك ضبط آلية النافذة المتحركة وعدد الرموز المميّزة التي تؤدي إلى بدء الضغط.

Python

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  contextWindowCompression: { slidingWindow: {} }
};

استئناف الجلسة

لمنع إنهاء الجلسة عندما يعيد الخادم ضبط اتصال WebSocket بشكل دوري، عليك ضبط الحقل sessionResumption ضمن إعدادات الإعداد.

يؤدي ضبط هذا الإعداد إلى إرسال الرسائل SessionResumptionUpdate من الخادم، والتي يمكن استخدامها لاستئناف الجلسة من خلال تمرير رمز التمكين لاستئناف الجلسة الأخير على أنّه SessionResumptionConfig.handle للاتصال اللاحق.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-live-2.5-flash-preview"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

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

const ai = new GoogleGenAI({});
const model = 'gemini-live-2.5-flash-preview';

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

console.debug('Connecting to the service with handle %s...', previousSessionHandle)
const session = await ai.live.connect({
  model: model,
  callbacks: {
    onopen: function () {
      console.debug('Opened');
    },
    onmessage: function (message) {
      responseQueue.push(message);
    },
    onerror: function (e) {
      console.debug('Error:', e.message);
    },
    onclose: function (e) {
      console.debug('Close:', e.reason);
    },
  },
  config: {
    responseModalities: [Modality.TEXT],
    sessionResumption: { handle: previousSessionHandle }
    // The handle of the session to resume is passed here, or else null to start a new session.
  }
});

const inputTurns = 'Hello how are you?';
session.sendClientContent({ turns: inputTurns });

const turns = await handleTurn();
for (const turn of turns) {
  if (turn.sessionResumptionUpdate) {
    if (turn.sessionResumptionUpdate.resumable && turn.sessionResumptionUpdate.newHandle) {
      let newHandle = turn.sessionResumptionUpdate.newHandle
      // ...Store newHandle and start new session with this handle here
    }
  }
}

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

تلقّي رسالة قبل انقطاع الاتصال بالجلسة

يُرسِل الخادم رسالة GoAway التي تشير إلى أنّه سيتم قريبًا إنهاء الربط الحالي. تتضمّن هذه الرسالة timeLeft، التي تشير إلى الوقت المتبقّي وتتيح لك اتّخاذ إجراء آخر قبل إنهاء الاتصال على أنّه تم إلغاؤه.

Python

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.goAway) {
    console.debug('Time left: %s\n', turn.goAway.timeLeft);
  }
}

تلقّي رسالة عند اكتمال عملية الإنشاء

يُرسِل الخادم رسالة generationComplete تشير إلى أنّ النموذج قد انتهى من إنشاء الاستجابة.

Python

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.generationComplete) {
    // The generation is complete
  }
}

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

يمكنك استكشاف المزيد من الطرق للعمل مع Live API في الدليل الكامل لالميزات، أو في صفحة استخدام الأداة، أو في دليل Live API.