Live-Sitzungen starten und verwalten

Die Gemini Live API ermöglicht Sprach- und Textinteraktionen mit geringer Latenz, indem sie kontinuierliche Audio- oder Textstreams, sogenannte Sitzungen, verarbeitet, 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 Unterhaltung 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 außerdem Folgendes beschrieben:

• Sitzung über das Standardzeitlimit hinaus verlängern
• Vorherige Sitzung fortsetzen
• Systemanweisungen während einer Sitzung aktualisieren
• Systemanweisungen und Tools während einer Sitzung mit Gemini 3.8 Live aktualisieren
• Kontextfenster einer Sitzung konfigurieren
• Transkription für eine Sitzung aktivieren
• Sitzungsdaten mit einem kundenverwalteten Verschlüsselungsschlüssel (CMEK) verschlüsseln

Sitzungsdauer

Ohne Kontextfensterkomprimierung sind reine Audiositzungen aufgrund von Tokenlimits auf 15 Minuten und Audio-Video-Sitzungen auf 2 Minuten beschränkt. Wenn diese Limits überschritten werden, wird die Sitzung beendet. Sie können jedoch die Kontextfensterkomprimierung verwenden, um Sitzungen unbegrenzt 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. Dazu verwenden Sie die Sitzungswiederaufnahme. Außerdem erhalten Sie eine GoAway-Nachricht, bevor die Verbindung beendet wird, sodass Sie weitere Maßnahmen ergreifen können.

Maximale Anzahl gleichzeitiger Sitzungen

Sie können bis zu 1.000 gleichzeitige Sitzungen pro Projekt im Rahmen eines „Pay as you go“-Tarifs (PayGo) 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:

gcloud auth application-default login
      

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

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

Sitzung verlängern

Die standardmäßige maximale Länge einer Unterhaltungssitzung beträgt 10 Minuten. Sie können sie mit 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-minütige Verbindungslimit hinaus verlängern möchten, müssen Sie die Verbindung über die Sitzungswiederaufnahme wiederherstellen. 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 Sie während der Sitzung erhalten haben. Dadurch wird Ihre Sitzung mit dem Kontext auf 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.

Im folgenden Beispiel wird gezeigt, wie Sie eine bevorstehende Sitzungsbeendigung erkennen, indem Sie auf eine goAway-Benachrichtigung warten:

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 Gemini Live API unterstützt die Wiederaufnahme von Sitzungen, damit der Nutzer bei einer kurzen Unterbrechung der Verbindung (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 Fortsetzung der Sitzung wird durch das Speichern von im Cache gespeicherten Daten erreicht, 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, die ein session_id und ein Fortsetzungstoken enthalten. 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 Zeitfenster für die Wiederaufnahme ist begrenzt (normalerweise etwa 10 Minuten). Wenn der Client innerhalb dieses Zeitraums keine neue 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 die Verbindung mithilfe des Handles wiederhergestellt, um die Sitzung fortzusetzen:

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 Fortsetzung der Sitzung im Transparenzmodus aktivieren

Wenn Sie die Sitzungswiederaufnahme aktivieren, können Sie auch den Transparenzmodus aktivieren, um die Wiederaufnahme 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 Fortsetzungs-Handle fortsetzen.

So aktivieren Sie den Transparenzmodus:

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 Cloud-powered encryption keyschützen möchten, verwenden Sie ein Bereitstellungsprofil. Ein Bereitstellungsprofil verknüpft einen Cloud KMS-Schlüssel mit einem Projekt, einem Standort und einem API-Bereich. Solange ein Bereitstellungsprofil vorhanden ist, verschlüsselt die Agent Platform die Daten automatisch. Ihre Sitzungskonfiguration und das Anfrageformat ändern sich nicht.

CMEK für Bereitstellungsprofile für die Gemini Live API werden 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 in Ihrem 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-Agenten der Gemini Enterprise Agent Platform die Rolle roles/cloudkms.cryptoKeyEncrypterDecrypter für den Schlüssel. Weitere Informationen finden Sie unter Berechtigungen für die Agent Platform gewähren.
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.

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 Antwortsprache oder den Tonfall ändern.

Die folgende Methode gilt für Gemini 2.5 Flash Live API Native Audio. Informationen zu Gemini 3.8 Live finden Sie unter Systemanweisungen und Tools mit Gemini 3.8 Live aktualisieren.

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 den Rest der Sitzung gültig.

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

Systemanweisungen und Tools mit Gemini 3.8 Live aktualisieren

Mit Gemini 3.8 Live können Sie die Systemanweisungen und Tools einer aktiven Sitzung aktualisieren, indem Sie eine BidiGenerateContentContextUpdate-Nachricht senden. Sie können beispielsweise die Sprache oder den Ton der Antwort ändern oder dem Modell andere Funktionen zuweisen, wenn die Unterhaltung zu einer neuen Aufgabe wechselt. Rufen Sie mit dem Google Gen AI SDK send_context_update auf. Legen Sie bei WebSockets das Feld context_update der Clientnachricht fest. Senden Sie keine Clientinhalte mit der Rolle system an Gemini 3.8 Live.

Legen Sie die Felder fest, die Sie ändern möchten:

• system_instruction: Ersetzt die Systemanweisung aus der Einrichtungsnachricht für den Rest der Sitzung.
• tools: Ersetzt die gesamte Liste der Tools der Sitzung. Geben Sie alle Tools an, die das Modell weiterhin verwenden können soll. Wenn Sie alle Tools entfernen möchten, senden Sie eine leere Liste.

Felder, die Sie nicht festlegen, behalten ihre aktuellen Werte. Aktualisierungen werden in der Reihenfolge mit den restlichen Eingaben der Sitzung verarbeitet.

from google.genai import types

# Replace the system instruction.
await session.send_context_update(
    system_instruction="Respond only in Spanish."
)

# Replace the tool list.
get_current_weather = types.FunctionDeclaration(
    name="get_current_weather",
    description="Get the current weather in a given location",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={"location": types.Schema(type=types.Type.STRING)},
    ),
)
await session.send_context_update(
    tools=[types.Tool(function_declarations=[get_current_weather])]
)

# Remove all tools.
await session.send_context_update(tools=[])
      

Serverseitige Tools werden beim Start der Sitzung eingerichtet. Daher gelten die folgenden Einschränkungen, wenn sie in einem Tool-Update enthalten sind. Funktionsdeklarationen sind davon nicht betroffen und können in jedem Tool-Update hinzugefügt werden.

• Wenn Sie die Fundierung mit der Google Suche nach einem Tool-Update verwenden möchten, müssen Sie auch google_search in der Einrichtungsnachricht deklarieren.
• Die Tools „Web-Fundierung für Unternehmen“, „Agent Search“ und „RAG Engine“ können nur in der Einrichtungsnachricht deklariert werden. Eine context_update, die sie enthält, gibt einen INVALID_ARGUMENT-Fehler zurück.

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, einschließlich Texteingaben und Modellausgaben, zu speichern. Alle Gemini Live API-Modelle haben ein Kontextfensterlimit von 128.000 Tokens.

In lang andauernden 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 oder Verlangsamungen kommen oder die Sitzung wird möglicherweise zwangsweise beendet. 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 Kontextfensterkomprimierung wird ein serverseitiges gleitendes Fenster verwendet, um die ältesten Turns zu kürzen, wenn sie aktiviert sind. Wenn die akkumulierten Tokens eine definierte maximale Länge überschreiten (festgelegt mit dem Schieberegler Maximale Inhaltsgröße in Vertex AI Studio oder trigger_tokens in der API), kürzt der Server automatisch die ältesten Turns oder fasst sie zusammen, um den Kontext innerhalb des Limits beizubehalten. In der ContextWindowCompressionConfig können Sie einen Sliding-Window-Mechanismus und die Anzahl der Tokens konfigurieren, die im Parameter target_tokens definiert sind und die Komprimierung auslösen.

Dies ermöglicht aus Sicht des Nutzers theoretisch unbegrenzte Sitzungsdauern, da der „Speicher“ ständig verwaltet wird. Ohne Komprimierung sind reine Audio-Sitzungen möglicherweise auf etwa 15 Minuten begrenzt, bevor harte Limits erreicht werden.

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

So legen Sie das Kontextfenster 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 Ausgabe-Audioinhalte 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 darauf achten, dass text in response_modalities enthalten ist.

Wenn Sie die Transkriptionsqualität für die mehrsprachige automatische Spracherkennung (Automatic Speech Recognition, ASR) verbessern möchten, können Sie im Feld language_codes in input_audio_transcription oder output_audio_transcription Sprachhinweise angeben. Es wird empfohlen, Hinweise anzugeben, um die Transkriptionsqualität zu verbessern, da dadurch das Risiko einer fehlerhaften Spracherkennung verringert wird, insbesondere bei kurzen Prompts. Das Feld language_codes akzeptiert eine Liste von BCP-47-Sprachcodes (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