Zarządzanie sesjami w interfejsie Live API

Gemini Live API przetwarza ciągłe strumienie dźwięku lub tekstu nazywane sesjami. Możesz zarządzać cyklem życia sesji – od początkowego uzgadniania połączenia do jego prawidłowego zakończenia.

Limity sesji

W przypadku interfejsu Live API _sesja_ to trwałe połączenie, w którym dane wejściowe i wyjściowe są przesyłane strumieniowo w sposób ciągły.

Jeśli sesja przekroczy którykolwiek z tych limitów, połączenie zostanie przerwane. Pamiętaj jednak, że Live API udostępnia kilka opcji (patrz poniżej), które pozwalają radzić sobie z tymi limitami związanymi z sesją.

  • Okno kontekstu sesji jest ograniczone do 128 tys. tokenów.

    Ze względu na ten limit okna kontekstu przybliżone maksymalne długości sesji w zależności od modalności danych wejściowych są następujące:

    • Sesje z danymi wejściowymi tylko w postaci dźwięku są ograniczone do 15 minut.
    • Sesje z danymi wejściowymi w postaci wideo i dźwięku są ograniczone do 2 minut.
  • Długość połączenia jest ograniczona do około 10 minut.

    Około 60 sekund przed zakończeniem połączenia otrzymasz powiadomienie going away.

Oto kilka opcji radzenia sobie z limitami związanymi z sesją:

  • Skompresuj okno kontekstu sesji aby serwer automatycznie utrzymywał rozmiar kontekstu w ramach limitu.

  • Wznów sesję aby zapobiec utracie kontekstu rozmowy podczas krótkich przerw w połączeniu sieciowym lub po otrzymaniu powiadomienia going away.

Rozpoczęcie sesji

Aby zobaczyć pełny fragment kodu pokazujący, jak rozpocząć sesję, zapoznaj się z przewodnikiem dla początkujących dotyczącym Live API.

Aktualizowanie w trakcie sesji

Modele Live API obsługują te zaawansowane funkcje aktualizacji w trakcie sesji:

Dodawanie przyrostowych aktualizacji treści

Podczas aktywnej sesji możesz dodawać przyrostowe aktualizacje. Używaj tej funkcji do wysyłania danych wejściowych w postaci tekstu, ustalania kontekstu sesji lub przywracania kontekstu sesji.

  • W przypadku dłuższych kontekstów zalecamy podanie podsumowania pojedynczej wiadomości, aby zwolnić okno kontekstu na potrzeby kolejnych interakcji.

  • W przypadku krótkich kontekstów możesz wysyłać interakcje krok po kroku, aby przedstawić dokładną sekwencję zdarzeń, tak jak w poniższym fragmencie kodu.

Swift

// Define initial turns (history/context).
let turns: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of France?")]),
  ModelContent(role: "model", parts: [TextPart("Paris")]),
]

// Send history, keeping the conversational turn OPEN (false).
await session.sendContent(turns, turnComplete: false)

// Define the new user query.
let newTurn: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of Germany?")]),
]

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.sendContent(newTurn, turnComplete: true)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

const turns = [{ text: "Hello from the user!" }];

await session.send(
  turns,
  false // turnComplete: false
);

console.log("Sent history. Waiting for next input...");

// Define the new user query.
const newTurn [{ text: "And what is the capital of Germany?" }];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
    newTurn,
    true // turnComplete: true
);
console.log("Sent final query. Model response expected now.");

Dart

// Define initial turns (history/context).
final List turns = [
  Content(
    "user",
    [Part.text("What is the capital of France?")],
  ),
  Content(
    "model",
    [Part.text("Paris")],
  ),
];

// Send history, keeping the conversational turn OPEN (false).
await session.send(
  input: turns,
  turnComplete: false,
);

// Define the new user query.
final List newTurn = [
  Content(
    "user",
    [Part.text("What is the capital of Germany?")],
  ),
];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
  input: newTurn,
  turnComplete: true,
);

Unity

// Define initial turns (history/context).
List turns = new List {
    new ModelContent("user", new ModelContent.TextPart("What is the capital of France?") ),
    new ModelContent("model", new ModelContent.TextPart("Paris") ),
};

// Send history, keeping the conversational turn OPEN (false).
foreach (ModelContent turn in turns)
{
    await session.SendAsync(
        content: turn,
        turnComplete: false
    );
}

// Define the new user query.
ModelContent newTurn = ModelContent.Text("What is the capital of Germany?");

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.SendAsync(
    content: newTurn,
    turnComplete: true
);

Aktualizowanie instrukcji systemowych w trakcie sesji

Dostępne tylko wtedy, gdy jako dostawcę interfejsu API używasz Vertex AI Gemini API.

Podczas aktywnej sesji możesz aktualizować instrukcje systemowe. Używaj tej funkcji, aby dostosowywać odpowiedzi modelu, np. zmieniać język odpowiedzi lub modyfikować ton.

Aby zaktualizować instrukcje systemowe w trakcie sesji, możesz wysłać treść tekstową z rolą system. Zaktualizowane instrukcje systemowe będą obowiązywać do końca sesji.

Swift

await session.sendContent(
  [ModelContent(
    role: "system",
    parts: [TextPart("new system instruction")]
  )],
  turnComplete: false
)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

Not yet supported for Web apps - check back soon!

Dart

try {
  await _session.send(
    input: Content(
      'system',
      [Part.text('new system instruction')],
    ),
    turnComplete: false,
  );
} catch (e) {
  print('Failed to update system instructions: $e');
}

Unity

try
{
    await session.SendAsync(
        content: new ModelContent(
            "system",
            new ModelContent.TextPart("new system instruction")
        ),
        turnComplete: false
    );
}
catch (Exception e)
{
    Debug.LogError($"Failed to update system instructions: {e.Message}");
}

Kompresowanie okna kontekstu

Kliknij swojego dostawcę Gemini API, aby wyświetlić na tej stronie treści i kod specyficzne dla dostawcy.

Live API Okno kontekstu sesji interfejsu Live API przechowuje dane przesyłane strumieniowo w czasie rzeczywistym (25 tokenów na sekundę w przypadku dźwięku i 258 tokenów na sekundę w przypadku wideo) oraz inne treści, w tym dane wejściowe w postaci tekstu i dane wyjściowe modelu. Wszystkie Live API modele mają limit okna kontekstu sesji wynoszący 128 tys. tokenów.

Ze względu na ten limit okna kontekstu przybliżone maksymalne długości sesji w zależności od modalności danych wejściowych są domyślnie następujące:

  • Sesje z danymi wejściowymi tylko w postaci dźwięku są ograniczone do 15 minut.
  • Sesje z danymi wejściowymi w postaci wideo i dźwięku są ograniczone do 2 minut.

W przypadku długotrwałych sesji w miarę postępu rozmowy gromadzi się historia tokenów audio lub wideo. Jeśli ta historia przekroczy limit modelu, model może halucynować, działać wolniej lub sesja może zostać wymuszona.

Aby umożliwić dłuższe sesje, możesz włączyć kompresję okna kontekstu, ustawiając pole contextWindowCompression w ramach LiveGenerationConfig. Gdy ta opcja jest włączona, serwer używa mechanizmu okna przesuwnego, aby automatycznie odrzucać najstarsze tury lub podsumowywać je w celu utrzymania rozmiaru kontekstu w ramach domyślnych lub określonych limitów. Instrukcje systemowe nie są odrzucane i zawsze pozostają na początku okna kontekstu.

Z punktu widzenia użytkownika pozwala to na teoretycznie nieskończony czas trwania sesji, ponieważ „pamięć” jest stale zarządzana.

Możesz skonfigurować mechanizm okna przesuwnego oraz opcjonalnie liczbę tokenów, która wywołuje kompresję (patrz dostępne ustawienia i wartości poniżej). Oto kilka ogólnych kwestii, które należy wziąć pod uwagę podczas korzystania z tych ustawień:

  • Ustawienie bardzo niskiej wartości targetTokens spowoduje zwolnienie większej ilości miejsca w kontekście na potrzeby ciągłych strumieni, ale model szybko „zapomni” starsze tury rozmowy.

  • Ustawienie wartości targetTokens bliższej wartości triggerTokens zachowuje więcej pamięci, ale będzie znacznie częściej wywoływać procedury kompresji.

Ustawienie Domyślna wartość okna przesuwnego, jeśli nie jest ustawiona w konfiguracji Wartość minimalna Wartość maksymalna
triggerTokens
długość kontekstu przed wywołaniem kompresji
80% limitu okna kontekstu modelu 5000 128 000
targetTokens
docelowa liczba tokenów do zachowania
50% wartości triggerTokens
  • Jeśli triggerTokens nie jest wyraźnie ustawiona, to targetTokens domyślnie przyjmuje wartość 50% domyślnej wartości triggerTokens.
  • Wartość targetTokens musi być mniejsza niż wartość triggerTokens
0 128 000

Swift


// Initialize the Gemini Developer API backend service
let liveModel = FirebaseAI.firebaseAI(backend: .googleAI()).liveModel(
  modelName: "gemini-2.5-flash-native-audio-preview-12-2025",
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  generationConfig: LiveGenerationConfig(
    responseModalities: [.audio],
    contextWindowCompression: ContextWindowCompressionConfig(
      triggerTokens: 10000,
      slidingWindow: SlidingWindow(
        targetTokens: 2000,
      )
    )
  )
)

Kotlin


// Initialize the Gemini Developer API backend service
val liveModel = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel(
    modelName = "gemini-2.5-flash-native-audio-preview-12-2025",
    // Enable context window compression.
    // (Optional) Configure the number of tokens in the context window that triggers the compression.
    generationConfig = liveGenerationConfig {
        responseModality = ResponseModality.AUDIO,
        contextWindowCompression = ContextWindowCompressionConfig(
            triggerTokens = 10000,
            slidingWindow = SlidingWindow(targetTokens = 2000)
        )
    }
)

Java


// Initialize the Gemini Developer API backend service
LiveGenerativeModel lm = FirebaseAI.getInstance(GenerativeBackend.googleAI()).liveModel(
        "gemini-2.5-flash-native-audio-preview-12-2025",
        // Enable context window compression.
        // (Optional) Configure the number of tokens in the context window that triggers the compression.
        new LiveGenerationConfig.Builder()
                .setResponseModality(ResponseModality.AUDIO)
                .setContextWindowCompression(
                        new ContextWindowCompressionConfig(10000, new SlidingWindow(2000))
                )
                .build()
);

Web


const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

const liveModel = getLiveGenerativeModel(ai, {
  model: "gemini-2.5-flash-native-audio-preview-12-2025",
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  generationConfig: {
    responseModalities: [ResponseModality.AUDIO],
    contextWindowCompression: {
      triggerTokens: 10000,
      slidingWindow: {
        targetTokens: 2000,
      },
    },
  },
});

Dart


final _liveModel = FirebaseAI.googleAI().liveGenerativeModel(
  model: 'gemini-2.5-flash-native-audio-preview-12-2025',
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  liveGenerationConfig: LiveGenerationConfig(
    responseModalities: [ResponseModalities.audio],
    contextWindowCompression: ContextWindowCompressionConfig(
      triggerTokens: 10000,
      slidingWindow: SlidingWindow(targetTokens: 2000),
    ),
  ),
);

Unity


var liveModel = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI()).GetLiveModel(
    modelName: "gemini-2.5-flash-native-audio-preview-12-2025",
    // Enable context window compression.
    // (Optional) Configure the number of tokens in the context window that triggers the compression.
    liveGenerationConfig: new LiveGenerationConfig(
        responseModalities: new[] { ResponseModality.Audio },
        contextWindowCompression: new ContextWindowCompressionConfig(
            triggerTokens: 10000,
            slidingWindow: new SlidingWindow(targetTokens: 2000)
        )
    )
);

Wykrywanie, kiedy sesja się zakończy

Maksymalny czas trwania pojedynczego, ciągłego połączenia WebSocket wynosi około 10 minut. Do klienta wysyłane jest powiadomienie going away 60 sekund przed zakończeniem połączenia, które może pomóc w podjęciu dalszych działań (np. przez wznowienie sesji).

Poniższy przykład pokazuje, jak wykryć zbliżające się zakończenie połączenia, nasłuchując powiadomienia going away:

Swift

for try await response in session.responses {
  switch response.payload {

  case .goingAwayNotice(let goingAwayNotice):
    // Prepare for the session to close soon
    if let timeLeft = goingAwayNotice.timeLeft {
        print("Server going away in \(timeLeft) seconds")
    }
  }
}

Kotlin

for (response in session.responses) {
    when (val message = response.payload) {
        is LiveServerGoAway -> {
            // Prepare for the session to close soon
            val remaining = message.timeLeft
            logger.info("Server going away in $remaining")
        }
    }
}

Java

session.getResponses().forEach(response -> {
    if (response.getPayload() instanceof LiveServerResponse.GoingAwayNotice) {
        LiveServerResponse.GoingAwayNotice notice = (LiveServerResponse.GoingAwayNotice) response.getPayload();
        // Prepare for the session to close soon
        Duration timeLeft = notice.getTimeLeft();
    }
});

Web

for await (const message of session.receive()) {
  switch (message.type) {

  ...
  case "goingAwayNotice":
    console.log("Server going away. Time left:", message.timeLeft);
    break;
  }
}

Dart

Future _handleLiveServerMessage(LiveServerResponse response) async {
  final message = response.message;
  if (message is GoingAwayNotice) {
     // Prepare for the session to close soon
     developer.log('Server going away. Time left: ${message.timeLeft}');
  }
}

Unity

foreach (var response in session.Responses) {
    if (response.Payload is LiveSessionGoingAway notice) {
        // Prepare for the session to close soon
        TimeSpan timeLeft = notice.TimeLeft;
        Debug.Log($"Server going away notice received. Remaining: {timeLeft}");
    }
}

Wznawianie sesji

Live API obsługuje wznawianie sesji, aby zapobiec utracie kontekstu rozmowy. Każda sesja ma uchwyt, którego można używać w tych przypadkach:

  • Utrzymywanie sesji przed osiągnięciem limitu czasu połączenia

    Maksymalny czas trwania pojedynczego, ciągłego połączenia WebSocket wynosi około 10 minut. Możesz wykryć, kiedy połączenie się zakończy, nasłuchując powiadomienia going away, a następnie przedłużyć sesję, nawiązując nowe połączenie za pomocą uchwytu sesji.

  • Wznawianie sesji tuż po zerwaniu połączenia

    Jeśli połączenie zostanie zakończone lub przerwane przed osiągnięciem maksymalnego limitu czasu połączenia (np. podczas przełączania się z Wi-Fi na 5G), serwer zachowa stan sesji przez około 10 minut. W tym czasie możesz wznowić sesję, nawiązując nowe połączenie za pomocą uchwytu sesji.

  • Wznawianie sesji po dłuższym czasie

    Po zakończeniu połączenia serwer zachowuje stan sesji przez kilka godzin. W tym czasie możesz wznowić sesję, nawiązując nowe połączenie za pomocą uchwytu sesji. Pamiętaj, że ten czas jest inny w przypadku 2 dostawców: Gemini Developer API2 godziny, | Vertex AI Gemini API24 godziny.Gemini API

Domyślnie wznawianie sesji jest wyłączone. Aby włączyć wznawianie sesji, podczas nawiązywania nowego połączenia przekaż pustą konfigurację wznawiania. Gdy ta opcja jest włączona, serwer okresowo wysyła aktualizacje zawierające uchwyt wznawiania sesji. Jeśli sesja zostanie rozłączona, możesz ponownie się połączyć i przekazać ten uchwyt, aby wznowić sesję z zachowaniem jej kontekstu.

Poniższe przykłady pokazują 2 sposoby wznawiania sesji:

Swift

// Local variable to save the active session handle
var activeSessionHandle: String?

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = try await liveModel.connect(
  sessionResumption: SessionResumptionConfig()
)

// Start receiving responses
for try await message in session.responses {
  // Check for new session handles inside your message handling loop
  switch message.payload {
  case let .sessionResumptionUpdate(updateMessage):
    guard let newHandle = updateMessage.newHandle, updateMessage.resumable else {
      continue
    }
    activeSessionHandle = newHandle
    print("SessionResumptionUpdate: handle \(newHandle)")
  // ... handle other LiveServerMessage types ...
  default:
    break
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if let handle = activeSessionHandle {
  session = try await liveModel.connect(
    sessionResumption: SessionResumptionConfig(handle: handle)
  )
}

// Option 2: Resume the session directly on an existing session object
if let handle = activeSessionHandle {
  try await session.resumeSession(
    sessionResumption: SessionResumptionConfig(handle: handle)
  )
}

Kotlin

// Local variable to save the active session handle
var activeSessionHandle: String? = null

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = liveModel.connect(
    sessionResumption = SessionResumptionConfig()
)

// Start receiving responses
session.receive().collect { message ->
    // Process other received response types...

    // Check for new session handles inside your message handling loop
    if (message is LiveSessionResumptionUpdate) {
        if (message.resumable == true && message.newHandle != null) {
            activeSessionHandle = message.newHandle
            Log.d("TAG", "SessionResumptionUpdate: handle ${message.newHandle}")
        }
    }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
activeSessionHandle?.let { handle ->
    session = liveModel.connect(
        sessionResumption = SessionResumptionConfig(handle = handle)
    )
}

// Option 2: Resume the session directly on an existing session object
activeSessionHandle?.let { handle ->
    session.resumeSession(
        sessionResumption = SessionResumptionConfig(handle = handle)
    )
}

Java

For Java, session resumption is not yet supported. Check back soon!

Web

// Local variable to save the active session handle
let activeSessionHandle = null;

// Initialize the session. Passing an empty object requests the server to send SessionResumptionUpdate
let session = await liveModel.connect({});

// Start receiving responses
for await (const message of session.receive()) {
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (message.type === 'sessionResumptionUpdate') {
    if (message.resumable && message.newHandle) {
      activeSessionHandle = message.newHandle;
      console.log(`SessionResumptionUpdate: handle ${activeSessionHandle}`);
    }
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (activeSessionHandle) {
  session = await liveModel.connect({
    handle: activeSessionHandle
  });
}

// Option 2: Resume the session directly on an existing session object
if (activeSessionHandle) {
  await session.resumeSession({
    handle: activeSessionHandle
  });
}

Dart

// Local variable to save the active session handle
String? _activeSessionHandle;

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var _session = await _liveModel.connect(
  sessionResumption: SessionResumptionConfig(),
);

// Start receiving responses
await for (final message in _session.receive()) {
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (message is SessionResumptionUpdate &&
      message.resumable != null &&
      message.resumable!) {
    _activeSessionHandle = message.newHandle;
    log('SessionResumptionUpdate: handle ${message.newHandle}');
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (_activeSessionHandle != null) {
  _session = await _liveModel.connect(
    sessionResumption: SessionResumptionConfig.resume(_activeSessionHandle!),
  );
}

// Option 2: Alternatively, resume the session directly on an existing session object
if (_activeSessionHandle != null) {
  await _session.resumeSession(
    sessionResumption: SessionResumptionConfig.resume(_activeSessionHandle!),
  );
}

Unity

// Local variable to save the active session handle
string activeSessionHandle = null;

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = await liveModel.ConnectAsync(
    sessionResumption: new SessionResumptionConfig()
);

// Start receiving responses
await foreach (var response in session.ReceiveAsync())
{
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (response.Message is LiveSessionResumptionUpdate updateMessage)
  {
    if (updateMessage.Resumable == true && !string.IsNullOrEmpty(updateMessage.NewHandle))
    {
      activeSessionHandle = updateMessage.NewHandle;
      Debug.Log($"SessionResumptionUpdate: handle {activeSessionHandle}");
    }
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (!string.IsNullOrEmpty(activeSessionHandle)) {
  session = await liveModel.ConnectAsync(
      sessionResumption: new SessionResumptionConfig(activeSessionHandle)
  );
}

// Option 2: Resume the session directly on an existing session object
if (!string.IsNullOrEmpty(activeSessionHandle)) {
  await session.ResumeSessionAsync(
      sessionResumption: new SessionResumptionConfig(activeSessionHandle)
  );
}