Bonnes pratiques concernant l'API Gemini Live

Pour obtenir de meilleurs résultats avec l'API Gemini Live, concentrez-vous sur les bonnes pratiques suivantes :

Concevoir des instructions système claires

Pour obtenir les meilleures performances de l'API Gemini Live, nous vous recommandons de disposer d'un ensemble d'instructions système (IS) clairement défini qui définit le persona de l'agent, les règles de conversation et les garde-fous, dans cet ordre.

Pour obtenir les meilleurs résultats, séparez chaque agent dans une IS distincte.

  1. Spécifiez le persona de l'agent : fournissez des informations détaillées sur le nom, le rôle et les caractéristiques préférées de l'agent. Si vous souhaitez spécifier l'accent, veillez également à spécifier la langue de sortie préférée (par exemple, un accent britannique pour un anglophone).

  2. Spécifiez les règles de conversation : placez ces règles dans l'ordre dans lequel vous souhaitez que le modèle les suive. Faites la distinction entre les éléments ponctuels de la conversation et les boucles de conversation. Exemple :

    • Élément ponctuel : collectez les informations d'un client une seule fois (par exemple, son nom, son adresse, son numéro de carte de fidélité).
    • Boucle de conversation : l'utilisateur peut discuter de recommandations, de prix, de retours et de livraisons, et peut vouloir passer d'un sujet à l'autre. Indiquez au modèle qu'il peut s'engager dans cette boucle de conversation aussi longtemps que l'utilisateur le souhaite.

  3. Spécifiez les appels d'outils dans un flux dans des phrases distinctes : par exemple, si une étape ponctuelle de collecte des informations d'un client nécessite d'appeler une fonction get_user_info, vous pouvez dire : Votre première étape consiste à collecter des informations sur l'utilisateur. Tout d'abord, demandez à l'utilisateur de fournir son nom, son adresse et son numéro de carte de fidélité. Appelez ensuite get_user_info avec ces informations.

  4. Ajoutez les garde-fous nécessaires : fournissez tous les garde-fous de conversation généraux que vous ne souhaitez pas que le modèle utilise. N'hésitez pas à fournir des exemples spécifiques de ce que vous souhaitez que le modèle fasse si x se produit. Si vous n'obtenez toujours pas le niveau de précision souhaité, utilisez le mot indubitablement pour guider le modèle afin qu'il soit précis.

Définir les outils avec précision

Lorsque vous utilisez des outils avec l'API Gemini Live, soyez précis dans vos définitions d'outils. Veillez à indiquer à Gemini dans quelles conditions un appel d'outil doit être appelé. Pour en savoir plus, consultez Définitions d'outils dans la section Exemple.

Créer des requêtes efficaces

  • Utilisez des requêtes claires : fournissez des exemples de ce que les modèles doivent et ne doivent pas faire dans les requêtes, et essayez de limiter les requêtes à une requête par persona ou rôle à la fois. Au lieu de requêtes longues et de plusieurs pages, envisagez plutôt d'utiliser l'enchaînement de requêtes. Le modèle fonctionne mieux sur les tâches avec des appels de fonction uniques.
  • Fournissez des commandes et des informations de démarrage : l'API Gemini Live attend une entrée utilisateur avant de répondre. Pour que l'API Gemini Live lance la conversation, incluez une requête lui demandant de saluer l'utilisateur ou de commencer la conversation. Incluez des informations sur l'utilisateur pour que l'API Gemini Live personnalise ce message d'accueil.

Reprise de session

  1. Utilisez la reprise de session transparente: Configurez la connexion avec SessionResumptionConfig(transparent=True) dans genai.types.LiveConnectConfig. Cela indique que le client a l'intention de gérer la reprise de session de manière transparente, ce qui permet d'utiliser des fonctionnalités telles que la relecture des messages non consommés lors de la reconnexion.
from google.genai import types

session_handle: str | None = None

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

  1. Gérez et mettez à jour le handle de session: écoutez les messages session_resumption_update du serveur. Si resumable est défini sur "true" et qu'un new_handle est fourni, stockez ce handle. Ce handle est essentiel pour se reconnecter au même état de session en cas de déconnexion.

  2. Mettez en mémoire tampon les messages envoyés et supprimez ceux qui ont été reconnus: pour vous assurer qu'aucun message client n'est perdu lors d'une déconnexion, conservez un tampon de messages envoyés à l'API Gemini Live. Le message session_resumption_update contient last_consumed_client_message_index lorsque la reprise de session transparente est activée, ce qui indique le dernier message traité par le serveur. Utilisez cet index pour supprimer les messages reconnus du tampon.

  3. Gérez les déconnexions de manière appropriée :

    • Signal GoAway : le serveur envoie un message go_away avant une déconnexion prévue (par exemple, un délai avant expiration). Le gestionnaire doit écouter ce message, puis se reconnecter de manière proactive à l'aide du dernier handle.
    • Erreurs d'API : les problèmes de réseau peuvent entraîner des erreurs genai_errors.APIError (par exemple, les codes 1000 ou 1006 pour les erreurs WebSocket). Le gestionnaire doit intercepter ces erreurs dans les boucles d'envoi et de réception, et déclencher le processus de mise à jour ou de reconnexion de la session.

  4. Implémentez la reconnexion avec la relecture des messages: en cas de déconnexion, créez une session à l’aide de client.aio.live.connect avec le dernier handle de session. Une fois la nouvelle connexion établie, renvoyez tous les messages du tampon qui n'ont pas été reconnus par le serveur avant la déconnexion.

Activer la compression de la fenêtre de contexte

Utilisez ContextWindowCompressionConfig pour configurer la fenêtre de contexte de la session pour les sessions longues, car les jetons audio natifs s'accumulent rapidement (environ 25 jetons par seconde d'audio).

Avertissement : La compression du contexte entraînera une perte de l'historique des conversations.

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

Détection de l'activité vocale (VAD)

Par défaut, l'API Gemini Live utilise la VAD fournie par Gemini.

Si vous préférez utiliser un système de détection d'activité personnalisé, vous devez désactiver la détection de l'activité vocale (VAD) par défaut et signaler manuellement les tours de l'utilisateur au modèle Gemini. Pour ce faire, transmettez des événements ActivityStart ou ActivityEnd afin de définir les limites de l'interaction.

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

Définir le code de langue audio

Il est recommandé de définir explicitement le code de langue et de voix dans votre configuration pour assurer la cohérence. Sans cette définition, Gemini peut modifier la langue de la conversation en fonction du contexte fourni.

from google.genai import types

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

Mentionnez également dans l'instruction système :

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

Définir le code de langue de transcription

Spécifiez les codes de langue de transcription pour améliorer la précision de la transcription au format de code de langue BCP-47.

Remarque : L'activation de la transcription introduit davantage de jetons.

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']
  ),
)

Mise en mémoire tampon côté client

Ne mettez pas en mémoire tampon l'audio d'entrée de manière significative (par exemple, 1 seconde) avant de l'envoyer. Envoyez de petits blocs (entre 20 et 40 ms) pour réduire la latence.

Rééchantillonnage

Assurez-vous que votre application cliente rééchantillonne l'entrée du microphone (souvent 44,1 kHz ou 48 kHz) à 16 kHz avant la transmission.

Exemple

Cet exemple combine les bonnes pratiques et les consignes de conception des instructions système pour guider les performances du modèle en tant que coach de carrière.

**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.

Définitions d'outils

Ce code JSON définit les fonctions pertinentes appelées dans l'exemple de coach de carrière. Pour obtenir les meilleurs résultats lors de la définition des fonctions, incluez leurs noms, descriptions, paramètres et conditions d'appel.

[
 {
   "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"]
   }
 }
]

En savoir plus

Pour en savoir plus sur l'utilisation de l'API Gemini Live, consultez les ressources suivantes :