Démarrer et gérer des sessions en direct

L'API 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 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())

Prolonger une session

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.

Vous pouvez prolonger la durée de la session par incréments de 10 minutes à l'aide du SDK Gen AI. Vous pouvez prolonger une session autant de fois que vous le souhaitez. Pour obtenir un exemple, consultez Reprendre une session précédente.

Pour prolonger une session :

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

L'API 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.

Voici un exemple d'activation de la reprise de session et de récupération de l'ID de handle :

Python

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


# 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 main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=MODEL,
        config=types.LiveConnectConfig(
            response_modalities=["audio"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

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

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": {
     "session_resumption_config": {
        "transparent": True,
     }
   }
}

Mettre à jour les instructions système pendant une session

L'API 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_client_content(
      turns=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 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