Session management with Live API

در Live API، یک جلسه به یک اتصال پایدار اشاره دارد که در آن ورودی و خروجی به طور مداوم از طریق همان اتصال پخش می‌شوند (درباره نحوه عملکرد آن بیشتر بخوانید). این طراحی منحصر به فرد جلسه، تأخیر کم را ممکن می‌سازد و از ویژگی‌های منحصر به فردی پشتیبانی می‌کند، اما می‌تواند چالش‌هایی مانند محدودیت‌های زمانی جلسه و خاتمه زودهنگام را نیز ایجاد کند. این راهنما استراتژی‌هایی را برای غلبه بر چالش‌های مدیریت جلسه که ممکن است هنگام استفاده از Live API ایجاد شوند، پوشش می‌دهد.

طول عمر جلسه

بدون فشرده‌سازی، جلسات فقط صوتی به ۱۵ دقیقه و جلسات صوتی-تصویری به ۲ دقیقه محدود می‌شوند. تجاوز از این محدودیت‌ها باعث خاتمه جلسه (و در نتیجه، اتصال) می‌شود، اما می‌توانید از فشرده‌سازی پنجره زمینه برای افزایش مدت زمان جلسات به نامحدود استفاده کنید.

طول عمر یک اتصال نیز محدود به حدود ۱۰ دقیقه است. وقتی اتصال خاتمه می‌یابد، جلسه نیز خاتمه می‌یابد. در این حالت، می‌توانید با استفاده از قابلیت از سرگیری جلسه، یک جلسه را طوری پیکربندی کنید که روی چندین اتصال فعال بماند. همچنین قبل از پایان اتصال، یک پیام GoAway دریافت خواهید کرد که به شما امکان می‌دهد اقدامات بیشتری انجام دهید.

فشرده‌سازی پنجره زمینه

برای فعال کردن جلسات طولانی‌تر و جلوگیری از قطع ناگهانی اتصال، می‌توانید فشرده‌سازی پنجره زمینه را با تنظیم فیلد contextWindowCompression به عنوان بخشی از پیکربندی جلسه فعال کنید.

در ContextWindowCompressionConfig ، می‌توانید مکانیزم پنجره کشویی و تعداد توکن‌هایی که فشرده‌سازی را آغاز می‌کنند، پیکربندی کنید.

پایتون

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

جاوا اسکریپت

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

از سرگیری جلسه

برای جلوگیری از خاتمه جلسه هنگامی که سرور به صورت دوره‌ای اتصال WebSocket را مجدداً تنظیم می‌کند، فیلد sessionResumption را در پیکربندی setup پیکربندی کنید.

ارسال این پیکربندی باعث می‌شود سرور پیام‌های SessionResumptionUpdate را ارسال کند که می‌توان از آنها برای از سرگیری جلسه با ارسال آخرین توکن از سرگیری به عنوان SessionResumptionConfig.handle اتصال بعدی استفاده کرد.

توکن‌های از سرگیری به مدت ۲ ساعت پس از پایان آخرین جلسات معتبر هستند.

پایتون

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

client = genai.Client()
model = "gemini-3.1-flash-live-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())

جاوا اسکریپت

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

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-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.AUDIO],
    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 است که زمان باقی‌مانده را نشان می‌دهد و به شما امکان می‌دهد قبل از اینکه اتصال به عنوان ABORTED قطع شود، اقدامات بیشتری انجام دهید.

پایتون

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)

جاوا اسکریپت

const turns = await handleTurn();

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

دریافت پیام پس از تکمیل تولید

سرور یک پیام generationComplete ارسال می‌کند که نشان می‌دهد مدل تولید پاسخ را به پایان رسانده است.

پایتون

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

جاوا اسکریپت

const turns = await handleTurn();

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

قدم بعدی چیست؟

روش‌های بیشتر برای کار با Live API را در راهنمای کامل قابلیت‌ها ، صفحه استفاده از ابزار یا کتاب آشپزی Live API بررسی کنید.