Best Practices für die Gemini Live API

Beachten Sie die folgenden Best Practices, um bessere Ergebnisse mit der Gemini Live API zu erzielen:

Klare Systemanweisungen entwerfen

Für eine optimale Leistung der Gemini Live API empfehlen wir, eine klar definierte Reihe von Systemanweisungen (SIs) zu erstellen, die die Agenten-Persona, die Gesprächsregeln und die Guardrails in dieser Reihenfolge definieren.

Die besten Ergebnisse erzielen Sie, wenn Sie jeden Agent in eine separate SI aufteilen.

  1. Persona des KI-Agenten angeben: Geben Sie Details zum Namen, zur Rolle und zu bevorzugten Eigenschaften des KI-Agenten an. Wenn Sie den Akzent angeben möchten, müssen Sie auch die bevorzugte Ausgabesprache angeben (z. B. einen britischen Akzent für einen englischsprachigen Sprecher).

  2. Geben Sie die Konversationsregeln an: Bringen Sie diese Regeln in die Reihenfolge, in der das Modell sie befolgen soll. Unterscheiden Sie zwischen einmaligen Elementen der Unterhaltung und Unterhaltungsschleifen. Beispiel:

    • Einmaliges Element: Erfassen Sie die Details eines Kunden einmal (z. B. Name, Standort, Kundenkartennummer).
    • Konversationsschleife: Der Nutzer kann Empfehlungen, Preise, Rücksendungen und Lieferungen besprechen und möchte möglicherweise von Thema zu Thema wechseln. Teilen Sie dem Modell mit, dass es diese Unterhaltungsschleife so lange fortsetzen kann, wie der Nutzer möchte.

  3. Geben Sie Toolaufrufe innerhalb eines Ablaufs in separaten Sätzen an: Wenn beispielsweise ein einmaliger Schritt zum Erfassen der Kundendetails den Aufruf einer get_user_info-Funktion erfordert, könnten Sie Folgendes sagen: Ihr erster Schritt besteht darin, Nutzerinformationen zu erfassen. First, ask the user to provide their name, location, and loyalty card number. Rufen Sie dann get_user_info mit diesen Details auf.

  4. Fügen Sie alle erforderlichen Schutzmaßnahmen hinzu: Geben Sie alle allgemeinen Schutzmaßnahmen für Unterhaltungen an, die das Modell nicht ausführen soll. Sie können auch konkrete Beispiele angeben, z. B. wenn x passiert, soll das Modell y tun. Wenn Sie immer noch nicht die gewünschte Genauigkeit erhalten, verwenden Sie das Wort unmistakably, um das Modell zu einer präzisen Antwort zu bewegen.

Tools genau definieren

Wenn Sie Tools mit der Gemini Live API verwenden, sollten Sie die Tooldefinitionen möglichst genau angeben. Geben Sie Gemini unbedingt an, unter welchen Bedingungen ein Toolaufruf erfolgen soll. Weitere Informationen finden Sie unter Tooldefinitionen.

Effektive Prompts erstellen

  • Klare Prompts verwenden: Geben Sie in den Prompts Beispiele dafür an, was das Modell tun und was es nicht tun soll. Versuchen Sie, Prompts auf einen Prompt pro Persona oder Rolle zu beschränken. Anstatt lange, mehrseitige Prompts zu verwenden, sollten Sie Prompt-Chaining in Betracht ziehen. Das Modell schneidet bei Aufgaben mit einzelnen Funktionsaufrufen am besten ab.

    # Prompt chaining example.
chainable_long_prompt = """
You need to perform a sequence of tasks.
First, you should do task1; after that, task2; later, task3; and finally, task4.
"""

# New initial prompt
"""
You need to perform a sequence of tasks. Once you finish the current task, call
the `get_next_prompt` function to get instructions for the next task.
"""

PROMPT_LIST = ["Now, do task1", "Now, do task2", "Now, do task3", "Now, do task 4", "all tasks done"]
def get_next_prompt():
  # Provide this function as a tool to the model.
  for prompt in PROMPT_LIST:
    yield prompt

# Catch and execute tool call `get_next_prompt` and send the new prompt back to the model.

  • Startbefehle und Informationen bereitstellen: Die Gemini Live API erwartet Nutzereingaben, bevor sie antwortet. Wenn die Gemini Live API die Unterhaltung initiieren soll, fügen Sie einen Prompt hinzu, in dem Sie sie auffordern, den Nutzer zu begrüßen oder die Unterhaltung zu beginnen. Fügen Sie Informationen zum Nutzer hinzu, damit die Gemini Live API die Begrüßung personalisieren kann.

Sitzungswiederaufnahme

  1. Transparente Sitzungswiederaufnahme verwenden: Konfigurieren Sie die Verbindung mit SessionResumptionConfig(transparent=True) in genai.types.LiveConnectConfig. Dies signalisiert, dass der Client die Sitzungswiederaufnahme nahtlos verarbeiten möchte, was Funktionen wie die erneute Wiedergabe nicht verarbeiteter Nachrichten nach der Wiederherstellung der Verbindung ermöglicht.
from google.genai import types

session_handle: str | None = None

live_config = types.LiveConnectConfig(
  session_resumption=types.SessionResumptionConfig(
      handle=session_handle,
      transparent=True,
  ),
)

  1. Sitzungs-Handle verwalten und aktualisieren: Achten Sie auf session_resumption_update-Nachrichten vom Server. Wenn resumable „true“ ist und ein new_handle angegeben wird, wird dieses Handle gespeichert. Dieses Handle ist wichtig, um die Verbindung zum selben Sitzungsstatus wiederherzustellen, wenn die Verbindung unterbrochen wird.

  2. Gesendete Nachrichten puffern und bestätigte Nachrichten entfernen: Damit bei einer Verbindungsunterbrechung keine Clientnachrichten verloren gehen, sollten Sie einen Puffer für Nachrichten einrichten, die an die Gemini Live API gesendet werden. Die session_resumption_update-Nachricht enthält last_consumed_client_message_index, wenn die transparente Sitzungswiederaufnahme aktiviert ist. Dies gibt die letzte vom Server verarbeitete Nachricht an. Verwenden Sie diesen Index, um bestätigte Nachrichten aus dem Zwischenspeicher zu entfernen. Damit Nachrichten korrekt verfolgt werden können, muss der vom Nutzer verwaltete Index bei 1 beginnen, da Index 0 angibt, dass the session is not resumable. Bei jeder nachfolgenden Nachricht, die an das Modell gesendet wird, sollte dieser Index um 1 erhöht werden. Achten Sie bei jeder Wiederaufnahme der Sitzung darauf, dass der Index für die erste Nachricht, die über die neue Verbindung übertragen wird, auf 1 zurückgesetzt wird.

  3. Verbindungsabbrüche ordnungsgemäß verarbeiten:

    • GoAway-Signal: Der Server sendet vor einer erwarteten Trennung der Verbindung (z. B. einer Zeitüberschreitung) eine go_away-Nachricht. Der Manager sollte darauf achten und dann proaktiv eine neue Verbindung mit dem neuesten Handle herstellen.
    • API-Fehler: Netzwerkprobleme können genai_errors.APIError verursachen (z. B. die Codes 1000 oder 1006 für WebSocket-Fehler). Der Manager sollte diese Fehler sowohl in Sende- als auch in Empfangsschleifen abfangen und die Sitzungsaktualisierung oder den Wiederverbindungsprozess auslösen.

  4. Wiederverbindung mit Nachrichtenwiederholung implementieren: Wenn eine Verbindung getrennt wird, erstellen Sie eine neue Sitzung mit client.aio.live.connect und dem neuesten Sitzungshandle. Nachdem die neue Verbindung hergestellt wurde, senden Sie alle Nachrichten im Zwischenspeicher, die vor der Trennung nicht vom Server bestätigt wurden, noch einmal. Die erste im Zwischenspeicher gesendete Nachricht sollte für die neue Verbindung als Index 1 markiert werden.

Komprimierung des Kontextfensters aktivieren

Verwenden Sie ContextWindowCompressionConfig, um das Kontextfenster der Sitzung für lange Sitzungen zu konfigurieren, da sich Live-Audio-Tokens schnell ansammeln (ca. 25 Tokens pro Sekunde Audio).

Warnung: Die Kontextkomprimierung führt zum Verlust des Unterhaltungsverlaufs.

from google.genai import types

live_config = types.LiveConnectConfig(
  context_window_compression=types.ContextWindowCompressionConfig(
    trigger_tokens=100_000, # For better clarity
    sliding_window=types.SlidingWindow(target_tokens=4_000),
  ),
)

Berechnung der Tokennutzung

Die Abrechnungsstruktur der Gemini Live API wird auf der Preisseite beschrieben. In jeder Runde werden alle Kontext-Tokens in Rechnung gestellt. Dazu gehören sowohl der Unterhaltungsverlauf als auch die vom Nutzer bereitgestellte Systemanweisung. Entwickler können diese Gebühren überwachen und berechnen, indem sie das Feld usage_metadata aus der Antwort des Modells extrahieren.

# Example code to get token usage
from google.genai import live

session: live.AsyncSession
async for response in session.receive():
  if response.usage_metadata is not None:
    print("Token usage:", response.usage_metadata)

Erkennung von Sprachaktivität (VAD)

Standardmäßig verwendet die Gemini Live API die von Gemini bereitgestellte VAD.

Wenn Sie die VAD der Gemini Live API verwenden, können Sie das Modell so konfigurieren, dass VAD-Ereignisse explizit zurückgegeben werden. Wenn Sie explicit_vad_signal in Ihrer Konfiguration aktivieren, können Sie diese Ereignisse direkt aus den Antworten des Modells überwachen und erfassen.

from google.genai import types
from google.genai import live

live_config = types.LiveConnectConfig(
  explicit_vad_signal=True
)

session: live.AsyncSession
# In receive loop
async for response in session.receive():
  if response.voice_activity is not None:
    print("Get VAD event", response.voice_activity)

Wenn Sie ein benutzerdefiniertes System zur Aktivitätserkennung verwenden möchten, müssen Sie die standardmäßige Spracherkennung (Voice Activity Detection, VAD) deaktivieren und die Nutzerbeiträge manuell an das Gemini-Modell signalisieren. Dazu werden ActivityStart- oder ActivityEnd-Ereignisse übertragen, um die Interaktionsgrenzen zu definieren.

from google.genai import live
from google.genai import types

# Disable VAD in config
live_config = types.LiveConnectConfig(
  realtime_input_config=types.RealtimeInputConfig(
    automatic_activity_detection=types.AutomaticActivityDetection(
        disabled=True
    ),
  ),
)

session: live.AsyncSession
await session.send_realtime_input( # Send activity start
    activity_start=types.ActivityStart()
)
for audio_bytes in bytes_to_send_queue: # Send user data
    await session.send_realtime_input(
        audio=types.Blob(
            data=audio_bytes,
            mime_type=f"audio/pcm;rate=16000",
        )
    )
await session.send_realtime_input(activity_end=types.ActivityEnd()) # Send activity end

Sprachcode für Audio festlegen

Es wird empfohlen, den Code für die Sprache und Stimme explizit in Ihrer Konfiguration festzulegen, um die Konsistenz zu wahren. Ohne diese Definition kann Gemini die Sprache der Unterhaltung je nach Kontext ändern.

from google.genai import types

config = types.LiveConnectConfig(
  speech_config=types.SpeechConfig(
    language_code="en-US",
  ),
)

Erwähnen Sie in der Systemanweisung auch Folgendes:

RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.

Bei Live-Audiomodellen wie gemini-3.8-live können Sie die Transkriptionsqualität für die mehrsprachige automatische Spracherkennung (Automatic Speech Recognition, ASR) verbessern, indem Sie in Ihrer Sitzungskonfiguration Sprachhinweise angeben. Weitere Informationen finden Sie unter Audiotranskription für die Sitzung aktivieren.

Sprechtempo mit einer Referenzstimme steuern

Bei Live-Audiomodellen wie Gemini 3.8 Live ändern Systemanweisungen, die das Modell auffordern, schneller oder langsamer zu sprechen, die synthetisierte Sprechgeschwindigkeit nicht zuverlässig. Wenn Sie die Sprechgeschwindigkeit steuern möchten, konfigurieren Sie im Feld replicated_voice_config eine benutzerdefinierte Stimme mit einem beschleunigten oder verlangsamten Referenzaudiobeispiel. Synthetisierte Antworten übernehmen die Sprechgeschwindigkeit und den Rhythmus des Beispiels, das Sie im Feld voice_sample_audio übergeben.

So passen Sie das Sprechtempo mit einer Referenzstimme an:

  1. Nehmen Sie eine 10–20 Sekunden lange, klare Audioprobe der Zielstimme auf. Sie können ein eigenes Sprachbeispiel aufnehmen oder eine Antwort von einer vordefinierten Stimme mit einer neutralen Systemanweisung ohne Tempoanweisungen erfassen. Richtlinien für die Aufnahme finden Sie unter Benutzerdefinierte Stimme verwenden.

  2. Wenden Sie eine tonhöhenerhaltende Zeitdehnung an, um das Sample zu beschleunigen oder zu verlangsamen, und exportieren Sie das Ergebnis als Mono-WAV-Datei mit 24 kHz, 16 Bit, vorzeichenbehaftet, Little Endian. Verwenden Sie einen Filter, der die Tonhöhe beibehält, z. B. den Filter ffmpeg atempo mit einem Multiplikator zwischen 0.8 und 1.5, damit sich die Sprechgeschwindigkeit ändert, ohne die Tonhöhe oder das Timbre der Stimme zu verschieben. Werte unter 1.0 verlangsamen die Stimme, Werte über 1.0 beschleunigen sie.

    Mit dem folgenden ffmpeg-Befehl wird beispielsweise eine Referenzaufnahme auf das 1, 25-Fache beschleunigt, wobei die Tonhöhe beibehalten und die Ausgabe als 24-kHz-16-Bit-Mono-WAV-Datei formatiert wird:

    ffmpeg -i INPUT_WAV \
  -filter:a "atempo=1.25" -ar 24000 -ac 1 -sample_fmt s16 \
  PACED_WAV

    Ersetzen Sie Folgendes:

    • INPUT_WAV: der Pfad zu Ihrem ursprünglichen Sprachbeispiel.
    • PACED_WAV: der Ausgabepfad für die zeitlich skalierte 24-kHz-Mono-WAV-Datei.

  3. Lesen Sie die zeitlich skalierte WAV-Datei und übergeben Sie ihre Byte an ReplicatedVoiceConfig in LiveConnectConfig:

    from google.genai import types

with open("PACED_WAV", "rb") as f:
  voice_sample_bytes = f.read()

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            replicated_voice_config=types.ReplicatedVoiceConfig(
                mime_type="audio/wav",
                voice_sample_audio=voice_sample_bytes,
            ),
        ),
    ),
)

    Ersetzen Sie PACED_WAV durch den Pfad zu Ihrer zeitlich skalierten 24-kHz-Mono-WAV-Datei.

Sprachcode für die Transkription festlegen

Geben Sie die Sprachcodes für die Transkription im BCP-47-Sprachcodeformat an, um die Transkriptionsgenauigkeit zu erhöhen.

Hinweis: Wenn Sie die Transkription aktivieren, werden mehr Tokens verwendet.

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']  # This supports multiple language codes.
  ),
  output_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']
  ),
)

Transkription mit einem benutzerdefinierten Vokabular beeinflussen

Produktnamen, interne Codenamen, Medikamentennamen und stilisierte Kennungen fehlen oft im Standardvokabular eines Spracherkennungsmodells. Das Modell transkribiert stattdessen das am nächsten liegende gängige Wort. Listen Sie diese Begriffe im Feld custom_vocabulary von input_audio_transcription auf, um die Erkennung auf die Wörter auszurichten, die Ihre Nutzer tatsächlich sagen.

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US'],
      custom_vocabulary=['QwikPay', 'Xylotek', 'Traefik', 'oatmilk'],
  ),
)

Die vorherige Konfiguration führt zu den folgenden Transkriptionsunterschieden für dieselbe Audioaufnahme:

Gesprochener Begriff Ohne custom_vocabulary Mit custom_vocabulary
QwikPay QuickPay QwikPay
Xylotek Xilotech Xylotek
Traefik Trafic Traefik
Hafermilch Hafermilch Hafermilch

Die genaue Schreibweise ist wichtig, wenn Sie Transkripte an Tools, Suchanfragen oder Kundendatensätze übergeben, bei denen eine fast richtige Schreibweise wie QuickPay zu keinen Ergebnissen führt.

Wenn Sie benutzerdefiniertes Vokabular in der Systemanweisung auflisten, führt das nicht zum selben Ergebnis. Wenn Sie custom_vocabulary verwenden, wird die Spracherkennung bei der Verarbeitung der Audiodaten beeinflusst. Die Systemanweisung erreicht das Modell dagegen erst, nachdem die Audiodaten transkribiert wurden.

Die Liste sollte auf bestimmte Domainbegriffe, Markennamen und Eigennamen beschränkt sein und keine gängigen Alltagswörter enthalten. Sie können bis zu 1.000 Begriffe angeben.

Client-Zwischenspeicherung

Puffern Sie die Audioeingabe vor dem Senden nicht zu lange (z. B. 1 Sekunde). Senden Sie kleine Blöcke (zwischen 20 ms und 40 ms), um die Latenz zu minimieren.

Resampling

Achten Sie darauf, dass Ihre Clientanwendung die Mikrofoneingabe (häufig 44,1 kHz oder 48 kHz) vor der Übertragung auf 16 kHz herunterskaliert.

Beispiel

In diesem Beispiel werden sowohl die Best Practices als auch die Richtlinien für das Design von Systemanweisungen kombiniert, um die Leistung des Modells als Karrierecoach zu steuern.

**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data-driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat what the client says back to them.
Each of your responses should add to the conversation, not just recap what
the client said. Be relatable by bringing in your own background
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.

Tooldefinitionen

In diesem JSON-Code werden die relevanten Funktionen definiert, die im Beispiel für den Karrierecoach aufgerufen werden. Die besten Ergebnisse erzielen Sie, wenn Sie beim Definieren von Funktionen deren Namen, Beschreibungen, Parameter und Aufrufbedingungen angeben.

[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]

Weitere Informationen

Weitere Informationen zur Verwendung der Gemini Live API finden Sie hier: