Démarrer et gérer des sessions en direct

L'API Gemini Live permet des interactions vocales et textuelles à faible latence en traitant des flux continus d'audio ou de texte appelés sessions pour fournir des réponses vocales immédiates et naturelles. La gestion du cycle de vie des sessions, de la première prise de contact à la fermeture en douceur, est contrôlée par le développeur.

Cette page vous explique comment démarrer une session de conversation avec les modèles Gemini à l'aide de l'API Gemini Live. Vous pouvez démarrer une session à l'aide de Vertex AI Studio, du SDK Gen AI ou des WebSockets.

Cette page vous explique également comment :

• Prolonger une session au-delà de la limite de temps par défaut
• Reprendre une session précédente
• Mettre à jour les instructions système pendant une session
• Configurer la fenêtre de contexte d'une session
• Activer la transcription pour une session

Durée de vie de la session

Sans compression, les sessions audio uniquement sont limitées à 15 minutes et les sessions audio-vidéo à 2 minutes. Si vous dépassez ces limites, la session se terminera. Toutefois, vous pouvez utiliser la compression de la fenêtre de contexte pour prolonger les sessions pour une durée illimitée.

La durée de vie d'une connexion est limitée à environ 10 minutes. Lorsque la connexion se termine, la session se termine également. Dans ce cas, vous pouvez configurer une seule session pour qu'elle reste active sur plusieurs connexions à l'aide de la reprise de session. Vous recevrez également un message GoAway avant la fin de la connexion, ce qui vous permettra de prendre d'autres mesures.

Nombre maximal de sessions simultanées

Vous pouvez avoir jusqu'à 1 000 sessions simultanées par projet avec un forfait avec paiement à l'usage (PayGo). Cette limite ne s'applique pas aux clients qui utilisent le débit provisionné.

Démarrer une session

Les onglets suivants montrent comment démarrer une session de conversation en direct à l'aide de Vertex AI Studio, du SDK Gen AI ou des WebSockets :

Console

1. Ouvrez Vertex AI Studio > Diffuser en temps réel.
2. Cliquez sur Démarrer la session pour lancer la conversation.

Pour mettre fin à la session, cliquez sur Arrêter la session.

Python

Avant de commencer, vous devez vous authentifier auprès de Vertex AI à l'aide d'une clé API ou des identifiants par défaut de l'application (ADC) :

gcloud auth application-default login
      

Pour en savoir plus sur la configuration de l'authentification, consultez notre démarrage rapide.

import asyncio
from google import genai

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"
config = {
   "response_modalities": ["audio"],
}

async def main():
   # Establish WebSocket session
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       print("Session established. Sending audio...")

if __name__ == "__main__":
    asyncio.run(main())
      

Python

Lorsque vous utilisez WebSockets, la connexion est établie avec un handshake WebSocket standard. Le point de terminaison est régional et utilise des jetons porteurs OAuth 2.0 pour l'authentification. Dans ce scénario, le jeton d'authentification est généralement transmis dans les en-têtes WebSocket (tels que Authorization: Bearer [TOKEN]).

import asyncio
import websockets

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

# Authentication
token_list = !gcloud auth application-default print-access-token
ACCESS_TOKEN = token_list[0]

# Configuration
MODEL_ID = "gemini-live-2.5-flash-preview-native-audio-09-2025"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"
config = {
   "response_modalities": ["audio"],
}

# Construct the WSS URL
HOST = f"{LOCATION}-aiplatform.googleapis.com"
URI = f"wss://{HOST}/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"

async def main():
   headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
  
   async with websockets.connect(URI, additional_headers=headers) as ws:
       print("Session established.")

       # Send Setup (Handshake)
       await ws.send(json.dumps({
           "setup": {
               "model": MODEL,
               "generation_config": config
           }
       }))
    # Send audio/video ...

if __name__ == "__main__":
    asyncio.run(main())
      

Remarque : Bien que certains paramètres, y compris les instructions système, puissent être ajustés en cours de session, le modèle et les autres paramètres sont généralement immuables une fois le message de configuration traité.

Prolonger une session

Remarque : L'extension de session n'est disponible que lorsque vous utilisez le SDK Gen AI, et non Vertex AI Studio.

La durée maximale par défaut d'une session de conversation est de 10 minutes. Une notification goAway (BidiGenerateContentServerMessage.goAway) est envoyée au client 60 secondes avant la fin de la session.

Pour prolonger une session au-delà de la limite de connexion de 10 minutes, vous devez vous reconnecter à l'aide de la reprise de session. Lorsque vous recevez une notification goAway ou que la connexion est interrompue pour d'autres raisons, vous pouvez démarrer une nouvelle connexion à l'aide d'un handle de session obtenu lors de la session. Votre session reprend avec son contexte intact sur la nouvelle connexion. Vous pouvez le faire autant de fois que vous le souhaitez. Pour obtenir un exemple de reprise d'une session, consultez Reprendre une session précédente.

L'exemple suivant montre comment détecter l'arrêt imminent d'une session en écoutant une notification goAway :

Python

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)
      

Reprendre une session précédente

Important : Si vous devez vous assurer qu'aucune donnée n'est conservée dans votre application, n'activez pas la reprise de session.

L'API Gemini Live prend en charge la reprise de session pour éviter que l'utilisateur ne perde le contexte de la conversation en cas de brève déconnexion (par exemple, en passant du Wi-Fi à la 5G). Vous pouvez reprendre une session précédente dans un délai de 24 heures. La reprise de session est possible grâce au stockage des données mises en cache, y compris les requêtes textuelles, vidéo et audio, ainsi que les sorties du modèle. La confidentialité au niveau du projet est appliquée à ces données mises en cache.

Par défaut, la reprise de session est désactivée. Pour activer la reprise de session, définissez le champ sessionResumption du message BidiGenerateContentSetup. Si cette option est activée, le serveur envoie régulièrement des messages SessionResumptionUpdate contenant un session_id et un jeton de reprise. Si la connexion WebSocket est interrompue, le client peut se reconnecter et inclure ces identifiants dans le nouveau message de configuration. Le serveur restaure ensuite le contexte précédent, ce qui permet à la conversation de se poursuivre de manière fluide.

La fenêtre de reprise est limitée (généralement d'environ 10 minutes). Si le client ne se reconnecte pas dans ce délai, l'état de la session est supprimé pour libérer des ressources serveur.

L'exemple suivant se connecte au service, obtient un handle de reprise de session, simule une déconnexion, puis se reconnecte à l'aide du handle pour reprendre la session :

Python

import asyncio
from google import genai
from google.genai import types
import websockets

# Replace the PROJECT_ID and LOCATION with your Project ID and location.
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"

async def resumable_session_example():
    """Demonstrates session resumption by connecting, disconnecting, and reconnecting."""
    session_handle = None

    print("Starting a new session...")
    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=None),
            ),
        ) as session:
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="Hello!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received session handle: {session_handle}")
                        # For demonstration, we break to simulate a disconnect
                        # after receiving a handle.
                        break
                if message.server_content and message.server_content.turn_complete:
                    break
    except websockets.exceptions.WebSocketException as e:
        print(f"Initial connection failed: {e}")
        return

    if not session_handle:
        print("Did not receive a session handle. Cannot demonstrate resumption.")
        return

    print(f"\nSimulating disconnect and reconnecting with handle {session_handle}...")

    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=session_handle),
            ),
        ) as session:
            print("Successfully resumed session.")
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="I am back!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received updated session handle: {session_handle}")
                if message.server_content:
                    print(f"Received server content: {message.server_content}")
                    if message.server_content.turn_complete:
                        break
            print("Resumed session finished.")
    except websockets.exceptions.WebSocketException as e:
        print(f"Failed to resume session: {e}")

if __name__ == "__main__":
    asyncio.run(resumable_session_example())
      

Activer la reprise de session fluide avec le mode transparent

Lorsque vous activez la reprise de session, vous pouvez également activer le mode transparent pour rendre le processus de reprise plus fluide pour l'utilisateur. Lorsque le mode transparent est activé, l'index du message client correspondant à l'instantané de contexte est renvoyé explicitement. Cela permet d'identifier le message client que vous devez renvoyer lorsque vous reprenez la session à partir du handle de reprise.

Pour activer le mode transparent :

Python

config = {
   "response_modalities": ["audio"],
   "session_resumption_config": {
    "transparent": True,
   }
}
      

Mettre à jour les instructions système pendant une session

L'API Gemini Live vous permet de mettre à jour les instructions système pendant une session active. Cela vous permet d'adapter les réponses du modèle, par exemple en changeant la langue de la réponse ou en modifiant le ton.

Pour mettre à jour les instructions système en cours de session, vous pouvez envoyer du contenu textuel avec le rôle system. Les instructions système modifiées resteront en vigueur pour le reste de la session.

Python

session.send_content(
      content=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )
      

Configurer la fenêtre de contexte de la session

La fenêtre de contexte de l'API Gemini Live est utilisée pour stocker les données diffusées en temps réel (25 jetons par seconde (TPS) pour l'audio et 258 TPS pour la vidéo) et d'autres contenus, y compris les entrées textuelles et les sorties de modèle. La limite de la fenêtre de contexte d'une session est la suivante :

• 128 000 jetons pour les modèles audio natifs
• 32 000 jetons pour les autres modèles de l'API Live

Dans les sessions de longue durée, l'historique des jetons audio et de texte s'accumule à mesure que la conversation progresse. Si cet historique dépasse la limite du modèle, celui-ci peut halluciner, ralentir ou la session peut être arrêtée de force. Pour activer des sessions plus longues, vous pouvez activer la compression de la fenêtre de contexte en définissant le champ contextWindowCompression dans la configuration de la session.

Lorsque la compression de la fenêtre de contexte est activée, elle utilise une fenêtre glissante côté serveur pour tronquer les tours les plus anciens. Lorsque le nombre de jetons accumulés dépasse une longueur maximale définie (à l'aide du curseur Taille maximale du contenu dans Vertex AI Studio ou de trigger_tokens dans l'API), le serveur supprime automatiquement les tours les plus anciens ou les résume pour maintenir le contexte dans la limite. Dans ContextWindowCompressionConfig, vous pouvez configurer un mécanisme de fenêtre glissante et le nombre de jetons définis dans le paramètre target_tokens qui déclenche la compression.

Cela permet des durées de session théoriquement infinies du point de vue de l'utilisateur, car la "mémoire" est constamment gérée. Sans compression, les sessions audio uniquement peuvent être limitées à environ 15 minutes avant d'atteindre les limites strictes.

Les longueurs minimale et maximale pour la longueur du contexte et la taille cible sont les suivantes :

Paramètre (indicateur d'API)	Valeur minimale	Valeur maximale
Longueur maximale du contexte (trigger_tokens)	5 000	128 000
Taille du contexte cible (target_tokens)	0	128 000

Pour définir la fenêtre de contexte :

Console

1. Ouvrez Vertex AI Studio > Diffuser en temps réel.
2. Cliquez pour ouvrir le menu Avancé.
3. Dans la section Contexte de la session, utilisez le curseur Taille maximale du contexte pour définir la taille du contexte sur une valeur comprise entre 5 000 et 128 000.
4. (Facultatif) Dans la même section, utilisez le curseur Taille du contexte cible pour définir la taille cible sur une valeur comprise entre 0 et 128 000.

Python

Définissez les champs context_window_compression.trigger_tokens et context_window_compression.sliding_window.target_tokens dans le message de configuration :

config = {
   "response_modalities": ["audio"],
   # Configures compression
   "context_window_compression" : {
    "trigger_tokens": 10000,
    "sliding_window": {"target_tokens" : 512}
   }
}
      

Activer la transcription audio pour la session

Vous pouvez activer les transcriptions pour l'audio d'entrée et de sortie.

Pour recevoir des transcriptions, vous devez mettre à jour la configuration de votre session. Vous devez ajouter les objets input_audio_transcription et output_audio_transcription, et vous assurer que text est inclus dans response_modalities.

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {},
    "output_audio_transcription": {},
}

Traiter la réponse

L'exemple de code suivant montre comment se connecter à l'aide de la session configurée et extraire les parties de texte (transcriptions) ainsi que les données audio.

# Receive Output Loop
async for message in session.receive():
    server_content = message.server_content
    if server_content:
        # Handle Model Turns (Audio + Text)
        model_turn = server_content.model_turn
        if model_turn and model_turn.parts:
            for part in model_turn.parts:
                # Handle Text (Transcriptions)
                if part.text:
                    print(f"Transcription: {part.text}")
                # Handle Audio
                if part.inline_data:
                    audio_data = part.inline_data.data
                    # Process audio bytes...
                    pass

        # Check for turn completion
        if server_content.turn_complete:
            print("Turn complete.")

Étapes suivantes

• Envoyer des flux audio et vidéo
• Bonnes pratiques avec l'API Gemini Live
• Concevoir des requêtes multimodales
• Présentation de l'appel de fonction