Die Live API ermöglicht bidirektionale Sprach- und Videointeraktionen mit geringer Latenz mit Gemini.
In diesem Leitfaden wird beschrieben, wie Sie eine interaktive Zwei-Wege-Unterhaltung einrichten, Audioeinstellungen anpassen und Sitzungen verwalten.
Unterstützte Modelle
Sie können die Live API mit den folgenden Modellen verwenden:
Modellversion | Verfügbarkeitsstufe |
---|---|
gemini-live-2.5-flash |
Privater GA-Release* |
gemini-live-2.5-flash-preview-native-audio |
Öffentliche Vorschau |
* Wenden Sie sich an Ihren Google-Kundenbetreuer, um Zugriff anzufordern.
Unterhaltung beginnen
Console
- Öffnen Sie Vertex AI Studio > Stream realtime.
- Klicken Sie auf Sitzung starten, um das Gespräch zu beginnen.
Klicken Sie auf
Sitzung beenden, um die Sitzung zu beenden.Python
Wenn Sie interaktive Unterhaltungen in Echtzeit ermöglichen möchten, führen Sie das folgende Beispiel auf einem lokalen Computer mit Mikrofon- und Lautsprecherzugriff aus (nicht in einem Colab-Notebook). In diesem Beispiel wird eine Konversation mit der API eingerichtet, sodass Sie Audio-Prompts senden und Audio-Antworten erhalten können:
""" # Installation # on linux sudo apt-get install portaudio19-dev # on mac brew install portaudio python3 -m venv env source env/bin/activate pip install google-genai """ import asyncio import pyaudio from google import genai from google.genai import types CHUNK=4200 FORMAT=pyaudio.paInt16 CHANNELS=1 RECORD_SECONDS=5 MODEL = 'gemini-live-2.5-flash' INPUT_RATE=16000 OUTPUT_RATE=24000 client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) config = { "response_modalities": ["AUDIO"], "input_audio_transcription": {}, # Configure input transcription "output_audio_transcription": {}, # Configure output transcription } async def main(): print(MODEL) p = pyaudio.PyAudio() async with client.aio.live.connect(model=MODEL, config=config) as session: #exit() async def send(): stream = p.open( format=FORMAT, channels=CHANNELS, rate=INPUT_RATE, input=True, frames_per_buffer=CHUNK) while True: frame = stream.read(CHUNK) await session.send(input={"data": frame, "mime_type": "audio/pcm"}) await asyncio.sleep(10**-12) async def receive(): output_stream = p.open( format=FORMAT, channels=CHANNELS, rate=OUTPUT_RATE, output=True, frames_per_buffer=CHUNK) async for message in session.receive(): if message.server_content.input_transcription: print(message.server_content.model_dump(mode="json", exclude_none=True)) if message.server_content.output_transcription: print(message.server_content.model_dump(mode="json", exclude_none=True)) if message.server_content.model_turn: for part in message.server_content.model_turn.parts: if part.inline_data.data: audio_data=part.inline_data.data output_stream.write(audio_data) await asyncio.sleep(10**-12) send_task = asyncio.create_task(send()) receive_task = asyncio.create_task(receive()) await asyncio.gather(send_task, receive_task) asyncio.run(main())
Python
So richten Sie eine Konversation mit der API ein, in der Sie Text-Prompts senden und Audioantworten erhalten können:
# Set model generation_config CONFIG = {"response_modalities": ["AUDIO"]} headers = { "Content-Type": "application/json", "Authorization": f"Bearer {bearer_token[0]}", } async def main() -> None: # Connect to the server async with connect(SERVICE_URL, additional_headers=headers) as ws: # Setup the session async def setup() -> None: await ws.send( json.dumps( { "setup": { "model": "gemini-live-2.5-flash", "generation_config": CONFIG, } } ) ) # Receive setup response raw_response = await ws.recv(decode=False) setup_response = json.loads(raw_response.decode("ascii")) print(f"Connected: {setup_response}") return # Send text message async def send() -> bool: text_input = input("Input > ") if text_input.lower() in ("q", "quit", "exit"): return False msg = { "client_content": { "turns": [{"role": "user", "parts": [{"text": text_input}]}], "turn_complete": True, } } await ws.send(json.dumps(msg)) return True # Receive server response async def receive() -> None: responses = [] # Receive chucks of server response async for raw_response in ws: response = json.loads(raw_response.decode()) server_content = response.pop("serverContent", None) if server_content is None: break model_turn = server_content.pop("modelTurn", None) if model_turn is not None: parts = model_turn.pop("parts", None) if parts is not None: for part in parts: pcm_data = base64.b64decode(part["inlineData"]["data"]) responses.append(np.frombuffer(pcm_data, dtype=np.int16)) # End of turn turn_complete = server_content.pop("turnComplete", None) if turn_complete: break # Play the returned audio message display(Markdown("**Response >**")) display(Audio(np.concatenate(responses), rate=24000, autoplay=True)) return await setup() while True: if not await send(): break await receive()
Starten Sie die Unterhaltung, geben Sie Ihre Prompts ein oder geben Sie q
, quit
oder exit
ein, um die Unterhaltung zu beenden.
await main()
Sprach- und Spracherkennungseinstellungen ändern
Die Live API verwendet Chirp 3, um synthetische Sprachantworten in einer Vielzahl von HD-Stimmen und Sprachen zu unterstützen. Eine vollständige Liste und Demos der einzelnen Stimmen finden Sie unter Chirp 3: HD-Stimmen.
So legen Sie die Stimme und Sprache für die Antwort fest:
Console
- Öffnen Sie Vertex AI Studio > Stream realtime.
- Wählen Sie im Bereich Ausgaben im Drop-down-Menü Stimme eine Stimme aus.
- Wählen Sie im selben Bereich eine Sprache aus dem Drop-down-Menü Sprache aus.
- Klicken Sie auf Sitzung starten, um die Sitzung zu starten.
Python
config = LiveConnectConfig( response_modalities=["AUDIO"], speech_config=SpeechConfig( voice_config=VoiceConfig( prebuilt_voice_config=PrebuiltVoiceConfig( voice_name=voice_name, ) ), language_code="en-US", ), )
Einstellungen für die Spracherkennung ändern
Die Erkennung von Sprachaktivität (Voice Activity Detection, VAD) ermöglicht es dem Modell, zu erkennen, wann eine Person spricht. Dies ist für natürliche Unterhaltungen unerlässlich, da Nutzer das Modell jederzeit unterbrechen können.
Das Modell führt automatisch eine kontinuierliche Spracherkennung (Voice Activity Detection, VAD) für einen kontinuierlichen Audioeingabestream durch. Sie können die VAD-Einstellungen über das Feld realtimeInputConfig.automaticActivityDetection
der Einrichtungsnachricht konfigurieren. Wenn VAD eine Unterbrechung erkennt, wird die laufende Generierung abgebrochen und verworfen. Im Sitzungsverlauf werden nur die Informationen aufbewahrt, die bereits an den Client gesendet wurden. Der Server sendet dann eine Nachricht, um die Unterbrechung zu melden.
Wenn der Audiostream länger als eine Sekunde pausiert wird (z. B. wenn der Nutzer das Mikrofon deaktiviert), senden Sie ein audioStreamEnd
-Ereignis, um zwischengespeicherte Audioinhalte zu leeren. Der Client kann das Senden von Audiodaten jederzeit fortsetzen.
Alternativ können Sie die automatische VAD deaktivieren, indem Sie realtimeInputConfig.automaticActivityDetection.disabled
in der Einrichtungsnachricht auf true
setzen. Bei dieser Konfiguration erkennt der Client die Sprache des Nutzers und sendet die Nachrichten activityStart
und activityEnd
zu den entsprechenden Zeiten. Es wird keine audioStreamEnd
gesendet. Unterbrechungen werden durch activityEnd
gekennzeichnet.
Python
config = LiveConnectConfig( response_modalities=["TEXT"], realtime_input_config=RealtimeInputConfig( automatic_activity_detection=AutomaticActivityDetection( disabled=False, # default start_of_speech_sensitivity=StartSensitivity.START_SENSITIVITY_LOW, # Either START_SENSITIVITY_LOW or START_SENSITIVITY_HIGH end_of_speech_sensitivity=EndSensitivity.END_SENSITIVITY_LOW, # Either END_SENSITIVITY_LOW or END_SENSITIVITY_HIGH prefix_padding_ms=20, silence_duration_ms=100, ) ), ) async with client.aio.live.connect( model=MODEL_ID, config=config, ) as session: audio_bytes = Path("sample.pcm").read_bytes() await session.send_realtime_input( media=Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000") ) # if stream gets paused, send: # await session.send_realtime_input(audio_stream_end=True) response = [] async for message in session.receive(): if message.server_content.interrupted is True: # The model generation was interrupted response.append("The session was interrupted") if message.text: response.append(message.text) display(Markdown(f"**Response >** {''.join(response)}"))
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 Sitzungswiederaufnahme aktivieren und deaktivieren.
Verlaufszeitraum
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.
Wenn das Kontextfenster die maximale Länge überschreitet (die mit dem Schieberegler Max. Inhaltsgröße in Vertex AI Studio oder mit trigger_tokens
in der API festgelegt wird), werden die ältesten Turns mithilfe der Kontextfensterkomprimierung abgeschnitten, um ein abruptes Beenden der Sitzung zu verhindern. Die Komprimierung des Kontextfensters wird ausgelöst, sobald das Kontextfenster seine maximale Länge erreicht hat (die entweder in Vertex AI Studio mit dem Schieberegler Zielkontextgröße oder mit target_tokens
in der API festgelegt wird). Dabei werden die ältesten Teile der Unterhaltung gelöscht, bis die Gesamtzahl der Tokens wieder auf diese Zielgröße gesunken ist.
Wenn Ihre maximale Kontextlänge beispielsweise auf 32000
Tokens und Ihre Zielgröße auf 16000
Tokens festgelegt ist:
- 1. Zug:Das Gespräch beginnt. In diesem Beispiel werden für die Anfrage 12.000 Tokens verwendet.
- Gesamtkontextgröße: 12.000 Tokens
- 2. Zug:Sie stellen eine weitere Anfrage. Für diese Anfrage werden weitere 12.000 Tokens verwendet.
- Gesamtkontextgröße: 24.000 Tokens
- 3. Zug:Sie stellen eine weitere Anfrage. Für diese Anfrage werden 14.000 Tokens verwendet.
- Gesamtkontextgröße: 38.000 Tokens
Da die Gesamtkontextgröße nun höher als das Maximum von 32.000 Tokens ist, wird die Kontextfensterkomprimierung ausgelöst. Das System kehrt zum Anfang der Unterhaltung zurück und löscht alte Turns,bis die Gesamtanzahl der Tokens unter dem Zielwert von 16.000 Tokens liegt:
- Dabei wird Turn 1 (12.000 Tokens) gelöscht. Die Gesamtzahl beträgt jetzt 26.000 Tokens, was immer noch über dem Ziel von 16.000 Tokens liegt.
- Dadurch wird Turn 2 (12.000 Tokens) gelöscht. Die Gesamtzahl beträgt jetzt 14.000 Tokens.
Das Endergebnis ist, dass nur Zug 3 im aktiven Speicher verbleibt und die Unterhaltung ab diesem Punkt fortgesetzt wird.
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
- Öffnen Sie Vertex AI Studio > Stream realtime.
- Klicken Sie, um das Menü Erweitert zu öffnen.
- Legen Sie im Bereich Sitzungskontext mit dem Schieberegler Maximale Kontextgröße die Kontextgröße auf einen Wert zwischen 5.000 und 128.000 fest.
- 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 = types.LiveConnectConfig( temperature=0.7, response_modalities=['TEXT'], system_instruction=types.Content( parts=[types.Part(text='test instruction')], role='user' ), context_window_compression=types.ContextWindowCompressionConfig( trigger_tokens=1000, sliding_window=types.SlidingWindow(target_tokens=10), ), )
Gleichzeitig geöffnete Sitzungen
Sie können pro Projekt bis zu 5.000 gleichzeitige Sitzungen haben.
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 oder den Tonfall ändern.
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 )
Sitzungswiederaufnahme aktivieren und deaktivieren
Mit der Sitzungswiederaufnahme können Sie innerhalb von 24 Stunden eine Verbindung zu einer vorherigen Sitzung wiederherstellen. Dies wird durch das Speichern von Cache-Daten erreicht, einschließlich Text-, Video- und Audio-Prompts sowie Modellausgaben. Für diese im Cache gespeicherten Daten wird der Datenschutz auf Projektebene erzwungen.
Die Sitzungswiederaufnahme ist standardmäßig deaktiviert.
Wenn Sie die Funktion zum Fortsetzen von Sitzungen aktivieren möchten, legen Sie das Feld sessionResumption
der Nachricht BidiGenerateContentSetup
fest. Wenn diese Option aktiviert ist, erstellt der Server regelmäßig einen Snapshot der aktuellen im Cache gespeicherten Sitzungskontexte und speichert ihn im internen Speicher.
Wenn ein Snapshot erfolgreich erstellt wurde, wird ein resumptionUpdate
mit der Handle-ID zurückgegeben, die Sie aufzeichnen und später verwenden können, um die Sitzung aus dem Snapshot fortzusetzen.
Hier ist 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 client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) model = "gemini-live-2.5-flash" 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())
Um eine nahtlose Wiederaufnahme der Sitzung zu ermöglichen, aktivieren Sie den transparenten Modus:
Python
types.LiveConnectConfig( response_modalities=["AUDIO"], session_resumption=types.SessionResumptionConfig( transparent=True, ), )
Nachdem der transparente Modus aktiviert wurde, 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.
Weitere Informationen
Weitere Informationen zur Verwendung der Live API finden Sie hier: