Live-Sitzungen starten und verwalten

Die Gemini 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 mit der Gemini Live API eine Unterhaltungssitzung mit Gemini-Modellen starten. Sie können eine Sitzung mit Vertex AI Studio, dem Google 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
• Sitzungsdaten mit einem kundenverwalteten Verschlüsselungsschlüssel (CMEK) verschlüsseln

Sitzungslebensdauer

Ohne die Komprimierung des Kontextfensters sind reine Audio-Sitzungen aufgrund von Token-Limits auf 15 Minuten und Audio-Video-Sitzungen auf 2 Minuten begrenzt. Wenn diese Grenzwerte überschritten werden, wird die Sitzung beendet. Sie können jedoch die Komprimierung des Kontextfensters verwenden, um Sitzungen auf unbegrenzte Zeit zu verlängern.

Die Lebensdauer einer Verbindung ist aufgrund von WebSocket-Verbindungseinschränkungen 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. 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 bis zu 1.000 gleichzeitige Sitzungen pro Projekt in einem PayGo-Tarif („Pay as you go“) haben. Dieses Limit gilt nicht für Kunden, die bereitgestellten Durchsatz verwenden.

Sitzung starten

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

Console

1. Öffnen Sie Vertex AI Studio > Stream realtime.
2. Klicken Sie auf Sitzung starten, um das Gespräch 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 der Gemini Enterprise Agent Platform authentifizieren:

gcloud auth application-default login
      

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

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-3.8-live"
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-Bearertokens für die Authentifizierung. In diesem Fall wird das Authentifizierungstoken in der Regel in den WebSocket-Headern (z. B. Authorization: Bearer [TOKEN]) übergeben.

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-3.8-live"
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())
      

Hinweis :Einige Parameter, einschließlich Systemanweisungen, können während der Sitzung angepasst werden. Das Modell und andere Parameter sind jedoch in der Regel unveränderlich, sobald die Einrichtungsnachricht verarbeitet wurde.

Sitzung verlängern

Hinweis :Die Sitzungsverlängerung ist nur verfügbar, wenn Sie das Google Gen AI SDK verwenden, nicht Vertex AI Studio.

Die maximale Länge einer Unterhaltungssitzung beträgt standardmäßig 10 Minuten. Sie können sie jedoch mithilfe von „goAway“-Benachrichtigungen verlängern. 60 Sekunden vor dem Ende der Sitzung wird eine goAway-Benachrichtigung (BidiGenerateContentServerMessage.goAway) an den Client gesendet.

Wenn Sie eine Sitzung über das 10‑Minuten-Verbindungslimit hinaus verlängern möchten, müssen Sie die Verbindung über die Sitzungswiederaufnahme neu herstellen. Wenn Sie eine goAway-Benachrichtigung erhalten oder die Verbindung aus anderen Gründen beendet wird, können Sie eine neue Verbindung mit einem Sitzungshandle starten, das während der Sitzung abgerufen wurde. Dadurch wird Ihre Sitzung mit dem ursprünglichen Kontext in der neuen Verbindung fortgesetzt. Sie können dies beliebig oft tun. Ein Beispiel für das Fortsetzen einer Sitzung finden Sie unter Vorherige Sitzung fortsetzen.

Das folgende Beispiel zeigt, wie Sie das bevorstehende Ende einer Sitzung erkennen, indem Sie auf eine goAway-Benachrichtigung warten:

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

Wichtig :Wenn Sie sicherstellen müssen, dass in Ihrer Anwendung keine Datenaufbewahrung erfolgt, aktivieren Sie die Sitzungswiederaufnahme nicht.

Die Gemini 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 frühere 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. Für diese im Cache gespeicherten Daten wird der Datenschutz auf Projektebene erzwungen.

Standardmäßig ist die Sitzungswiederaufnahme deaktiviert. Wenn Sie die Wiederaufnahme von Sitzungen 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 Fortsetzungs-Token. Wenn die WebSocket-Verbindung getrennt wird, kann der Client die Verbindung wiederherstellen 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 Beispiel wird eine Verbindung zum Dienst hergestellt, ein Handle für die Wiederaufnahme der Sitzung abgerufen, eine Trennung simuliert und dann mithilfe des Handles eine erneute Verbindung hergestellt, um die Sitzung fortzusetzen:

Python

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

# 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-3.8-live"

async def resumable_session_example():
    """Demonstrates session resumption by connecting, disconnecting, and reconnecting."""
    session_handle = None

    print("Starting a new session...")
    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption=types.SessionResumptionConfig(handle=None),
            ),
        ) as session:
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="Hello!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received session handle: {session_handle}")
                        # For demonstration, we break to simulate a disconnect
                        # after receiving a handle.
                        break
                if message.server_content and message.server_content.turn_complete:
                    break
    except websockets.exceptions.WebSocketException as e:
        print(f"Initial connection failed: {e}")
        return

    if not session_handle:
        print("Did not receive a session handle. Cannot demonstrate resumption.")
        return

    print(f"\nSimulating disconnect and reconnecting with handle {session_handle}...")

    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption=types.SessionResumptionConfig(handle=session_handle),
            ),
        ) as session:
            print("Successfully resumed session.")
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="I am back!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received updated session handle: {session_handle}")
                if message.server_content:
                    print(f"Received server content: {message.server_content}")
                    if message.server_content.turn_complete:
                        break
            print("Resumed session finished.")
    except websockets.exceptions.WebSocketException as e:
        print(f"Failed to resume session: {e}")

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

Nahtlose Wiederaufnahme von Sitzungen mit Transparenzmodus aktivieren

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 Fortsetzungshandle fortsetzen.

So aktivieren Sie den Transparenzmodus:

Python

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

Sitzungsdaten mit CMEK verschlüsseln

Bei der Sitzungswiederaufnahme werden im Cache gespeicherte Sitzungsdaten bis zu 24 Stunden lang im Ruhezustand gespeichert. Wenn Sie diese Daten mit Ihrem eigenen Schlüssel anstelle einesGoogle-owned and Google-managed encryption keyschützen möchten, verwenden Sie ein Bereitstellungsprofil. In einem Bereitstellungsprofil wird ein Cloud KMS-Schlüssel mit einem Projekt, einem Standort und einem API-Bereich verknüpft. Wenn ein Serving-Profil vorhanden ist, verschlüsselt die Agent Platform die Daten automatisch. Ihre Sitzungskonfiguration und Ihr Anfrageformat ändern sich nicht.

Die Bereitstellung von CMEK für das Profil für die Gemini Live API wird in den Multiregionen us und eu unterstützt. Die globale Region wird nicht unterstützt.

So richten Sie CMEK für die Gemini Live API ein:

1. Aktivieren Sie die Cloud KMS API und die Agent Platform API für Ihr Projekt. Siehe Vorbereitung.
2. Erstellen Sie einen Cloud KMS-Schlüssel in der Multiregion us oder eu. Weitere Informationen finden Sie unter Schlüsselbund und Schlüssel erstellen.
3. Gewähren Sie dem Dienst-Agent der Gemini Enterprise Agent Platform die Rolle roles/cloudkms.cryptoKeyEncrypterDecrypter für den Schlüssel. Weitere Informationen
4. Erstellen Sie ein Bereitstellungsprofil, in dem scope auf GEMINI_LIVE und cmekConfig.encryptionSpec.kmsKeyName auf Ihren Schlüssel festgelegt ist. Weitere Informationen finden Sie unter Bereitstellungsprofil erstellen.

Hinweis :Daten, die vor der Erstellung des Bereitstellungsprofils gespeichert wurden, werden nicht nachträglich mit Ihrem Schlüssel neu verschlüsselt.

Systemanweisungen während einer Sitzung aktualisieren

Mit der Gemini 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 oder den Ton ändern.

Wenn Sie die Systemanweisungen während einer 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(
      content=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )
      

Kontextfenster der Sitzung konfigurieren

Das Kontextfenster der Gemini 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. Alle Gemini Live API-Modelle haben ein Kontextfensterlimit von 128.000 Tokens.

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, das Modell kann langsamer werden 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 Anfragen zu kürzen, wenn die Funktion aktiviert ist. Wenn die angesammelten Tokens eine definierte maximale Länge überschreiten (die mit dem Schieberegler Maximale 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 Mechanismus für das gleitende Fenster und die Anzahl der im Parameter target_tokens definierten Tokens konfigurieren, die die Komprimierung auslösen.

Aus Nutzersicht sind so theoretisch unendlich lange Sitzungsdauern 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: Legen Sie im selben Bereich mit dem Schieberegler Zielkontextgröße die Zielgröße auf einen Wert zwischen 0 und 128.000 fest.

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 das Eingabe- als auch für das Ausgabesignal 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.

Um die Transkriptionsqualität für die mehrsprachige automatische Spracherkennung (ASR) zu verbessern, können Sie mit dem Feld language_codes in input_audio_transcription oder output_audio_transcription Sprachhinweise angeben. Es wird empfohlen, Hinweise zu geben, um die Qualität der Transkription zu verbessern, da dadurch das Risiko einer falschen Spracherkennung verringert wird, insbesondere bei kurzen Prompts. Im Feld language_codes kann eine Liste von BCP-47-Sprachcodes angegeben werden (z. B. „en-US“, „es-US“).

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {
        "language_codes": ["en-US"]
    },
    "output_audio_transcription": {},
}

Antwort verarbeiten

Im folgenden Codebeispiel wird gezeigt, 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

• Audio- und Videostreams senden
• Best Practices für die Gemini Live API
• Multimodale Prompts entwerfen
• Einführung in Funktionsaufrufe