Bonnes pratiques avec 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 tirer le meilleur parti de l'API Gemini Live, nous vous recommandons de définir un ensemble d'instructions système (IS) clairement définies qui définissent le persona de l'agent, les règles de conversation et les garde-fous, dans cet ordre.

Pour de meilleurs résultats, séparez chaque agent dans un SI distinct.

  1. Spécifiez le persona de l'agent : fournissez des détails 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 à spécifier également la langue de sortie préférée (par exemple, un accent britannique pour un locuteur anglophone).

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

    • Élément ponctuel : collectez les informations d'un client une seule fois (par exemple, son nom, sa position géographique ou son numéro de carte de fidélité).
    • Boucle de conversation : l'utilisateur peut discuter des recommandations, des prix, des retours et de la livraison, 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 l'appel d'une fonction get_user_info, vous pouvez dire : La première étape consiste à collecter les informations utilisateur. Tout d'abord, demande à l'utilisateur de fournir son nom, sa position et son numéro de carte de fidélité. Ensuite, appelez get_user_info avec ces informations.

  4. Ajoutez les garde-fous nécessaires : fournissez des garde-fous généraux pour les conversations que vous ne souhaitez pas que le modèle effectue. N'hésitez pas à fournir des exemples spécifiques de ce que vous souhaitez que le modèle fasse si x se produit, par exemple y. Si vous n'obtenez toujours pas le niveau de précision souhaité, utilisez le mot unmistakably (sans équivoque) pour guider le modèle vers la précision.

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 invoqué. Pour en savoir plus, consultez Définitions des outils.

Créer des prompts efficaces

  • Utilisez des prompts clairs : fournissez des exemples de ce que le modèle doit et ne doit pas faire dans les prompts, et essayez de limiter les prompts à un seul par persona ou rôle à la fois. Au lieu de prompts longs de plusieurs pages, envisagez d'utiliser le chaînage de prompts. Le modèle est plus performant pour les tâches avec des appels de fonction uniques.

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

  • Fournissez des commandes et des informations de départ : 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. Utiliser 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 fluide, 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érer et mettre à 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. Mettre en mémoire tampon les messages envoyés et supprimer ceux qui ont été confirmés : pour vous assurer qu'aucun message client n'est perdu lors d'une déconnexion, conservez une mémoire tampon des messages envoyés à l'API Gemini Live. Le message session_resumption_update contiendra last_consumed_client_message_index lorsque la reprise de session transparente est activée, indiquant le dernier message traité par le serveur. Utilisez cet index pour supprimer les messages confirmés du tampon. Pour suivre correctement les messages, l'index géré par l'utilisateur doit commencer à 1, car l'index 0 indique que the session is not resumable. Chaque message suivant envoyé au modèle doit incrémenter cet index de 1. À chaque reprise de session, assurez-vous que l'index est réinitialisé à 1 pour le message initial transmis à l'aide de la nouvelle connexion.

  3. Gérer les déconnexions de manière fluide :

    • Signal GoAway : le serveur envoie un message go_away avant une déconnexion attendue (par exemple, un délai avant expiration). Le gestionnaire doit écouter cet événement, puis se reconnecter de manière proactive à l'aide du dernier handle.
    • Erreurs d'API : des 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émenter la reconnexion avec la relecture des messages : lorsqu'une déconnexion se produit, 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é confirmés par le serveur avant la déconnexion. Le premier message envoyé dans le tampon doit être marqué comme index 1 pour la nouvelle 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 en direct s'accumulent rapidement (environ 25 jetons par seconde d'audio).

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

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

Calcul de l'utilisation des jetons

La structure de facturation de l'API Gemini Live est détaillée sur la page des tarifs. À chaque tour, l'API facture tous les jetons de contexte, ce qui englobe à la fois l'historique de la conversation et l'instruction système fournie par l'utilisateur. Les développeurs peuvent surveiller et calculer ces frais en extrayant le champ usage_metadata fourni dans la réponse du modèle.

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

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

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

Lorsque vous utilisez la VAD de l'API Gemini Live, vous pouvez configurer le modèle pour qu'il renvoie explicitement des événements de VAD. En activant explicit_vad_signal dans votre configuration, vous pouvez surveiller et capturer ces événements directement à partir des réponses du modèle.

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)

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 parole 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 la langue et la 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 les points suivants dans l'instruction système :

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

Pour les modèles audio en direct comme gemini-3.8-live, vous pouvez améliorer la qualité de la transcription pour la reconnaissance vocale automatique (ASR) multilingue en fournissant des indices de langue dans la configuration de votre session. Pour en savoir plus, consultez Activer la transcription audio pour la session.

Contrôler le rythme de la voix avec une voix de référence

Sur les modèles audio en direct tels que Gemini 3.8 Live, les requêtes d'instructions système qui demandent au modèle de parler plus vite ou plus lentement ne modifient pas de manière fiable le débit de parole synthétisé. Pour contrôler le rythme de la voix, configurez une voix personnalisée dans le champ replicated_voice_config avec un échantillon audio de référence accéléré ou ralenti. Les réponses synthétisées héritent du débit et du rythme de l'échantillon que vous transmettez dans le champ voice_sample_audio.

Pour ajuster le rythme de la voix à l'aide d'une voix de référence, procédez comme suit :

  1. Obtenez un échantillon audio clair de 10 à 20 secondes de la voix cible. Vous pouvez enregistrer votre propre échantillon vocal ou capturer une réponse à partir d'une voix prédéfinie à l'aide d'une instruction système neutre sans directives de rythme. Pour obtenir des consignes d'enregistrement, consultez Utiliser une voix personnalisée.

  2. Appliquez un étirement temporel préservant la hauteur pour accélérer ou ralentir l'échantillon, puis exportez le résultat sous la forme d'un fichier WAV mono 24 kHz, 16 bits signé little-endian. Utilisez un filtre qui préserve la hauteur, tel que le filtre ffmpeg atempo avec un multiplicateur compris entre 0.8 et 1.5, afin que le débit de parole change sans modifier la hauteur ni le timbre de la voix. Les valeurs inférieures à 1.0 ralentissent la voix, tandis que celles supérieures à 1.0 l'accélèrent.

    Par exemple, la commande ffmpeg suivante accélère un enregistrement de référence à 1,25x tout en préservant la hauteur et en formatant la sortie sous la forme d'un fichier WAV mono 24 kHz, 16 bits :

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

    Remplacez les éléments suivants :

    • INPUT_WAV : chemin d'accès à votre échantillon vocal d'origine.
    • PACED_WAV : chemin de sortie du fichier WAV mono 24 kHz mis à l'échelle.

  3. Lisez le fichier WAV à l'échelle temporelle et transmettez ses octets à ReplicatedVoiceConfig dans 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,
            ),
        ),
    ),
)

    Remplacez PACED_WAV par le chemin d'accès à votre fichier WAV mono 24 kHz étiré dans le temps.

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 à l'aide du 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']
  ),
)

Orienter la transcription avec un vocabulaire personnalisé

Les noms de produits, les noms de code internes, les noms de médicaments et les identifiants stylisés sont souvent absents du vocabulaire par défaut d'un modèle de reconnaissance vocale. Le modèle transcrit donc le mot commun le plus proche. Répertoriez ces termes dans le champ custom_vocabulary de input_audio_transcription pour orienter la reconnaissance vers les mots que vos utilisateurs prononcent réellement.

from google.genai import types

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

La configuration précédente produit les différences de transcription suivantes pour le même contenu audio :

Terme parlé Sans custom_vocabulary Avec custom_vocabulary
QwikPay QuickPay QwikPay
Xylotek Xilotech Xylotek
Traefik Trafic Traefik
lait d'avoine lait d'avoine lait d'avoine

L'orthographe exacte est importante lorsque vous transmettez des transcriptions à des outils, des requêtes de recherche ou des fiches client, où une approximation telle que QuickPay ne correspond à rien.

Lister un vocabulaire personnalisé dans l'instruction système ne produit pas le même résultat. L'utilisation de custom_vocabulary biaise l'outil de reconnaissance vocale lorsqu'il traite l'audio, tandis que l'instruction système n'atteint le modèle qu'une fois l'audio transcrit.

La liste doit cibler des termes de domaine, des noms de marque et des noms propres distincts, plutôt que des mots courants. Vous pouvez fournir jusqu'à 1 000 termes.

Mise en mémoire tampon du client

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

Rééchantillonnage

Assurez-vous que votre application cliente rééchantillonne l'entrée du micro (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 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.

Définitions d'outils

Ce JSON définit les appels de fonction pertinents dans l'exemple de coach de carrière. Pour obtenir de 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 :