Livesitzungen starten und verwalten

Die Live API ermöglicht Sprach- und Textinteraktionen mit geringer Latenz, indem kontinuierliche Audio- oder Textstreams, sogenannte Sitzungen, verarbeitet werden, um sofortige, menschenähnliche gesprochene Antworten zu liefern. Die Verwaltung des Sitzungslebenszyklus, vom ersten Handshake bis zur ordnungsgemäßen Beendigung, wird vom Entwickler gesteuert.

Auf dieser Seite erfahren Sie, wie Sie eine Unterhaltungssitzung mit Gemini-Modellen über die Live API starten. Sie können eine Sitzung mit Vertex AI Studio, dem Gen AI SDK oder WebSockets starten.

Auf dieser Seite wird auch Folgendes beschrieben:

  • Sitzung über das Standardzeitlimit hinaus verlängern
  • Vorherige Sitzung fortsetzen
  • Systemanweisungen während einer Sitzung aktualisieren
  • Kontextfenster einer Sitzung konfigurieren
  • Transkription für eine Sitzung aktivieren

Sitzungsdauer

Ohne Komprimierung sind reine Audio-Sitzungen auf 15 Minuten und Audio-Video-Sitzungen auf 2 Minuten begrenzt. Wenn Sie diese Limits überschreiten, wird die Sitzung beendet. Sie können jedoch die Kontextfensterkomprimierung verwenden, um Sitzungen unbegrenzt zu verlängern.

Die Lebensdauer einer Verbindung ist auf etwa 10 Minuten begrenzt. Wenn die Verbindung beendet wird, wird auch die Sitzung beendet. In diesem Fall können Sie eine einzelne Sitzung so konfigurieren, dass sie über mehrere Verbindungen hinweg aktiv bleibt. Verwenden Sie dazu die Sitzungswiederaufnahme. Sie erhalten außerdem eine GoAway-Meldung, bevor die Verbindung beendet wird, damit Sie weitere Maßnahmen ergreifen können.

Maximale Anzahl gleichzeitiger Sitzungen

Sie können mit einem Pay-as-you-go-Tarif (PayGo) bis zu 1.000 gleichzeitige Sitzungen pro Projekt haben. Dieses Limit gilt nicht für Kunden, die bereitgestellten Durchsatz verwenden.

Sitzung starten

Auf den folgenden Tabs sehen Sie, wie Sie eine Live-Unterhaltungssitzung mit Vertex AI Studio, dem Gen AI SDK oder WebSockets starten:

Console

  1. Öffnen Sie Vertex AI Studio > Stream realtime.
  2. Klicken Sie auf Sitzung starten, um die Unterhaltung zu beginnen.

Klicken Sie auf Sitzung beenden, um die Sitzung zu beenden.

Python

Bevor Sie beginnen, müssen Sie sich mit einem API-Schlüssel oder Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bei Vertex AI authentifizieren: 

gcloud auth application-default login

Weitere Informationen zum Einrichten der Authentifizierung finden Sie in unserer Schnellstartanleitung. 

import asyncio
from google import genai

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"
config = {
   "response_modalities": ["audio"],
}

async def main():
   # Establish WebSocket session
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       print("Session established. Sending audio...")

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

Python

Bei der Verwendung von WebSockets wird die Verbindung mit einem Standard-WebSocket-Handshake hergestellt. Der Endpunkt ist regional und verwendet OAuth 2.0-Bearer-Tokens für die Authentifizierung. In diesem Fall wird das Authentifizierungstoken in der Regel in den WebSocket-Headern übergeben (z. B. Authorization: Bearer [TOKEN]). 

import asyncio
import websockets

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

# Authentication
token_list = !gcloud auth application-default print-access-token
ACCESS_TOKEN = token_list[0]

# Configuration
MODEL_ID = "gemini-live-2.5-flash-preview-native-audio-09-2025"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"
config = {
   "response_modalities": ["audio"],
}

# Construct the WSS URL
HOST = f"{LOCATION}-aiplatform.googleapis.com"
URI = f"wss://{HOST}/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"

async def main():
   headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
  
   async with websockets.connect(URI, additional_headers=headers) as ws:
       print("Session established.")

       # Send Setup (Handshake)
       await ws.send(json.dumps({
           "setup": {
               "model": MODEL,
               "generation_config": config
           }
       }))
    # Send audio/video ...

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

Sitzung verlängern

Die maximale Länge einer Unterhaltungssitzung beträgt standardmäßig 10 Minuten. 60 Sekunden vor dem Ende der Sitzung wird eine goAway-Benachrichtigung (BidiGenerateContentServerMessage.goAway) an den Client gesendet.

Sie können die Sitzungslänge mit dem Gen AI SDK in 10-Minuten-Schritten verlängern. Sie können eine Sitzung beliebig oft verlängern. Ein Beispiel finden Sie unter Vorherige Sitzung fortsetzen.

So verlängern Sie eine Sitzung:

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)

Vorherige Sitzung fortsetzen

Die Live API unterstützt die Wiederaufnahme von Sitzungen, damit der Nutzer bei einer kurzen Unterbrechung (z. B. beim Wechsel von WLAN zu 5G) den Kontext der Unterhaltung nicht verliert. Sie können eine vorherige Sitzung innerhalb von 24 Stunden fortsetzen. Die Wiederaufnahme von Sitzungen erfolgt durch das Speichern von Cache-Daten, einschließlich Text-, Video- und Audio-Prompts sowie Modellausgaben. Der Datenschutz auf Projektebene wird für diese im Cache gespeicherten Daten erzwungen.

Die Sitzungswiederaufnahme ist standardmäßig deaktiviert. Wenn Sie die Sitzungswiederaufnahme aktivieren möchten, legen Sie das Feld sessionResumption der Nachricht BidiGenerateContentSetup fest. Wenn diese Option aktiviert ist, sendet der Server regelmäßig SessionResumptionUpdate-Nachrichten mit einem session_id und einem Wiederaufnahmetoken. Wenn die WebSocket-Verbindung getrennt wird, kann der Client eine neue Verbindung herstellen und diese Anmeldedaten in die neue Einrichtungsnachricht einfügen. Der Server stellt dann den vorherigen Kontext wieder her, sodass die Unterhaltung nahtlos fortgesetzt werden kann.

Das Fenster für die Wiederaufnahme ist begrenzt (in der Regel etwa 10 Minuten). Wenn der Client innerhalb dieses Zeitraums keine Verbindung herstellt, wird der Sitzungsstatus verworfen, um Serverressourcen freizugeben.

Im Folgenden finden Sie ein Beispiel für das Aktivieren der Sitzungswiederaufnahme und das Abrufen der Handle-ID:

Python

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


# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"

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

Nahtlose Wiederaufnahme von Sitzungen mit dem transparenten Modus ermöglichen

Wenn Sie die Sitzungswiederaufnahme aktivieren, können Sie auch den transparenten Modus aktivieren, um den Wiederaufnahmeprozess für den Nutzer nahtloser zu gestalten. Wenn der transparente Modus aktiviert ist, wird der Index der Clientnachricht, die dem Kontext-Snapshot entspricht, explizit zurückgegeben. So können Sie leichter feststellen, welche Clientnachricht Sie noch einmal senden müssen, wenn Sie die Sitzung über das Wiederaufnahme-Handle fortsetzen.

So aktivieren Sie den transparenten Modus:

Python

config = {
   "response_modalities": ["audio"],
   "session_resumption": {
     "session_resumption_config": {
        "transparent": True,
     }
   }
}

Systemanweisungen während einer Sitzung aktualisieren

Mit der Live API können Sie die Systemanweisungen während einer aktiven Sitzung aktualisieren. Damit können Sie die Antworten des Modells anpassen, z. B. die Sprache der Antwort ändern oder den Tonfall anpassen.

Wenn Sie die Systemanweisungen während der Sitzung aktualisieren möchten, können Sie Textinhalte mit der Rolle system senden. Die aktualisierte Systemanweisung bleibt für die verbleibende Sitzung in Kraft.

Python

session.send_client_content(
      turns=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )

Kontextfenster der Sitzung konfigurieren

Das Kontextfenster der Live API wird verwendet, um in Echtzeit gestreamte Daten (25 Tokens pro Sekunde (TPS) für Audio und 258 TPS für Video) und andere Inhalte zu speichern, einschließlich Texteingaben und Modellausgaben. Eine Sitzung hat ein Kontextfensterlimit von:

  • 128.000 Tokens für native Audiomodelle
  • 32.000 Tokens für andere Live API-Modelle

Bei längeren Sitzungen sammelt sich im Laufe der Unterhaltung der Verlauf von Audio- und Text-Tokens an. Wenn dieser Verlauf das Limit des Modells überschreitet, kann es zu Halluzinationen kommen, die Verarbeitung kann sich verlangsamen oder die Sitzung kann zwangsweise beendet werden. Wenn Sie längere Sitzungen ermöglichen möchten, können Sie die Kontextfensterkomprimierung aktivieren, indem Sie das Feld contextWindowCompression als Teil der Sitzungskonfiguration festlegen.

Bei der Komprimierung des Kontextfensters wird ein serverseitiges gleitendes Fenster verwendet, um die ältesten Unterhaltungen zu kürzen, wenn die Funktion aktiviert ist. Wenn die angesammelten Tokens eine definierte maximale Länge überschreiten (die mit dem Schieberegler Max. Inhaltsgröße in Vertex AI Studio oder mit „trigger_tokens“ in der API festgelegt wird), werden die ältesten Turns automatisch vom Server gekürzt oder zusammengefasst, um den Kontext innerhalb des Limits zu halten. Im ContextWindowCompressionConfig können Sie einen Gleitfenstermechanismus und die Anzahl der im Parameter target_tokens definierten Tokens konfigurieren, die die Komprimierung auslösen.

Aus Nutzersicht sind so theoretisch unendlich lange Sitzungen möglich, da der „Speicher“ ständig verwaltet wird. Ohne Komprimierung sind reine Audio-Sitzungen möglicherweise auf etwa 15 Minuten begrenzt, bevor die harten Limits erreicht werden.

Die Mindest- und Höchstlängen für die Kontextlänge und die Zielgröße sind:

Einstellung (API-Flag) Mindestwert Maximalwert
Maximale Kontextlänge (trigger_tokens) 5.000 128.000
Zielkontextgröße (target_tokens) 0 128.000

So legen Sie das Kontextfenster fest:

Console

  1. Öffnen Sie Vertex AI Studio > Stream realtime.
  2. Klicken Sie, um das Menü Erweitert zu öffnen.
  3. Legen Sie im Bereich Sitzungskontext mit dem Schieberegler Maximale Kontextgröße die Kontextgröße auf einen Wert zwischen 5.000 und 128.000 fest.
  4. Optional: Verwenden Sie im selben Bereich den Schieberegler Zielkontextgröße, um die Zielgröße auf einen Wert zwischen 0 und 128.000 festzulegen.

Python

Legen Sie in der Einrichtungsnachricht die Felder context_window_compression.trigger_tokens und context_window_compression.sliding_window.target_tokens fest: 

config = {
   "response_modalities": ["audio"],
   # Configures compression
   "context_window_compression" : {
    "trigger_tokens": 10000,
    "sliding_window": {"target_tokens" : 512}
   }
}

Audiotranskription für die Sitzung aktivieren

Sie können Transkriptionen sowohl für die Eingabe- als auch für die Ausgabesprache aktivieren.

Wenn Sie Transkriptionen erhalten möchten, müssen Sie Ihre Sitzungskonfiguration aktualisieren. Sie müssen die Objekte input_audio_transcription und output_audio_transcription hinzufügen und dafür sorgen, dass text in response_modalities enthalten ist.

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {},
    "output_audio_transcription": {},
}

Antwort verarbeiten

Das folgende Codebeispiel zeigt, wie Sie eine Verbindung mit der konfigurierten Sitzung herstellen und die Textteile (Transkriptionen) zusammen mit den Audiodaten extrahieren.

# Receive Output Loop
async for message in session.receive():
    server_content = message.server_content
    if server_content:
        # Handle Model Turns (Audio + Text)
        model_turn = server_content.model_turn
        if model_turn and model_turn.parts:
            for part in model_turn.parts:
                # Handle Text (Transcriptions)
                if part.text:
                    print(f"Transcription: {part.text}")
                # Handle Audio
                if part.inline_data:
                    audio_data = part.inline_data.data
                    # Process audio bytes...
                    pass

        # Check for turn completion
        if server_content.turn_complete:
            print("Turn complete.")

Nächste Schritte