Best Practices für die Gemini Live API

Um bessere Ergebnisse mit der Gemini Live API zu erzielen, sollten Sie die folgenden Best Practices beachten:

Klare Systemanweisungen entwerfen

Um die bestmögliche Leistung der Gemini Live API zu erzielen, empfehlen wir, einen klar definierten Satz von Systemanweisungen zu verwenden, in denen die Persona des Agenten, die Konversationsregeln und die Schutzmaßnahmen in dieser Reihenfolge festgelegt sind.

Für optimale Ergebnisse sollten Sie für jeden Agenten eine eigene Systemanweisung erstellen.

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

  2. Konversationsregeln angeben:Geben Sie diese Regeln in der Reihenfolge an, in der das Modell sie befolgen soll. Unterscheiden Sie zwischen einmaligen Elementen der Konversation und Konversationsschleifen. Beispiel:

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

  3. Tool-Aufrufe in einem Ablauf in separaten Sätzen angeben:Wenn beispielsweise ein einmaliger Schritt zum Erfassen der Kundendetails den Aufruf einer get_user_info-Funktion erfordert, können Sie Folgendes sagen: Der erste Schritt besteht darin, Nutzerinformationen zu erfassen. Bitten Sie den Nutzer zuerst, seinen Namen, Standort und seine Kundenkartennummer anzugeben. Rufen Sie dann get_user_info mit diesen Details auf.

  4. Erforderliche Schutzmaßnahmen hinzufügen:Geben Sie alle allgemeinen Konversationsschutzmaßnahmen an, die das Modell nicht ausführen soll. Sie können auch spezifische Beispiele angeben, z. B. wenn x passiert, soll das Modell y tun. Wenn Sie immer noch nicht die gewünschte Genauigkeit erreichen, verwenden Sie das Wort unmissverständlich, um das Modell zu einer präzisen Antwort zu bewegen.

Tools genau definieren

Wenn Sie Tools mit der Gemini Live API verwenden, sollten Sie Ihre Tooldefinitionen genau angeben. Teilen Sie Gemini mit, unter welchen Bedingungen ein Tool-Aufruf erfolgen soll. Weitere Informationen finden Sie im Beispielabschnitt unter Tooldefinitionen in.

Effektive Prompts erstellen

  • Klare Prompts verwenden:Geben Sie in den Prompts Beispiele dafür an, was die Modelle tun und was sie nicht tun sollen. Beschränken Sie die Prompts auf jeweils einen Prompt pro Persona oder Rolle. Verwenden Sie anstelle von langen, mehrseitigen Prompts lieber Prompt-Chaining. Das Modell erzielt bei Aufgaben mit einzelnen Funktionsaufrufen die besten Ergebnisse.
  • Startbefehle und Informationen angeben:Die Gemini Live API erwartet eine Nutzereingabe, bevor sie antwortet. Wenn die Gemini Live API die Konversation starten soll, fügen Sie einen Prompt hinzu, in dem sie aufgefordert wird, den Nutzer zu begrüßen oder die Konversation 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, sodass Funktionen wie das erneute Abspielen nicht verwendeter Nachrichten nach dem Wiederherstellen der Verbindung möglich sind.
from google.genai import types

session_handle: str | None = None

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

  1. Sitzungshandle verwalten und aktualisieren: Achten Sie auf session_resumption_update Nachrichten vom Server. Wenn resumable auf „true“ gesetzt ist und ein new_handle angegeben wird, speichern Sie dieses Handle. 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 Unterbrechung der Verbindung keine Clientnachrichten verloren gehen, sollten Sie einen Puffer mit Nachrichten verwalten, die an die Gemini Live API gesendet werden. Die Nachricht session_resumption_update enthält last_consumed_client_message_index, wenn die transparente Sitzungswiederaufnahme aktiviert ist. Dieser Wert gibt die letzte vom Server verarbeitete Nachricht an. Verwenden Sie diesen Index, um bestätigte Nachrichten aus dem Puffer zu entfernen.

  3. Unterbrechungen der Verbindung ordnungsgemäß behandeln:

    • GoAway-Signal: Der Server sendet vor einer erwarteten Unterbrechung der Verbindung (z. B. bei einem Zeitlimit) eine go_away-Nachricht. Der Manager sollte auf diese Nachricht achten und dann mit dem neuesten Handle proaktiv die Verbindung wiederherstellen.
    • 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 den Sende- als auch in den Empfangsschleifen abfangen und den Prozess zur Aktualisierung der Sitzung oder zur Wiederherstellung der Verbindung auslösen.

  4. Wiederherstellung der Verbindung mit Nachrichtenwiedergabe implementieren: Wenn die Verbindung unterbrochen wird, erstellen Sie mit client.aio.live.connect und dem neuesten Sitzungshandle eine neue Sitzung. Nachdem die neue Verbindung hergestellt wurde, senden Sie alle Nachrichten im Puffer noch einmal, die vor der Unterbrechung der Verbindung nicht vom Server bestätigt wurden.

Kontextfensterkomprimierung aktivieren

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

Warnung:Durch die Kontextkomprimierung geht der Unterhaltungsverlauf verloren.

from google.genai import types

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

Erkennung der Sprachaktivitäten

Standardmäßig verwendet die Gemini Live API die von Gemini bereitgestellte Erkennung der Sprachaktivitäten.

Wenn Sie ein benutzerdefiniertes System zur Erkennung von Aktivitäten verwenden möchten, müssen Sie die standardmäßige Erkennung der Sprachaktivitäten deaktivieren und die Nutzerrunden 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 empfiehlt sich, den Sprach- und Sprachcode in Ihrer Konfiguration explizit festzulegen, um die Konsistenz zu wahren. Ohne diese Definition kann Gemini die Konversationssprache je nach Kontext ändern.

from google.genai import types

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

Geben Sie in der Systemanweisung auch Folgendes an:

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

Sprachcode für das Transkript festlegen

Geben Sie die Sprachcodes für das Transkript im BCP-47-Sprachcodeformat an, um die Genauigkeit des Transkripts 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']
  ),
)

Clientseitiges Puffern

Puffern Sie die Audioeingabe nicht wesentlich (z. B. 1 Sekunde), bevor Sie sie senden. Senden Sie kleine Teile (zwischen 20 und 40 ms), um die Latenz zu minimieren.

Resampling

Achten Sie darauf, dass Ihre Clientanwendung die Mikrofoneingabe (oft 44,1 kHz oder 48 kHz) vor der Übertragung auf 16 kHz resampelt.

Beispiel

In diesem Beispiel werden die Best Practices und 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 back what the client says back to them.
Each response you give should be a net new addition to the conversation, not a
recap of 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 werden die relevanten Funktionen definiert, die im Beispiel für den Karrierecoach aufgerufen werden. Für optimale Ergebnisse sollten 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: