Avviare e gestire sessioni live

L'API Live consente interazioni vocali e testuali a bassa latenza elaborando flussi continui di audio o testo chiamati sessioni per fornire risposte immediate e simili a quelle umane. La gestione del ciclo di vita della sessione, dall'handshake iniziale alla chiusura controllata, è controllata dallo sviluppatore.

Questa pagina mostra come avviare una sessione di conversazione con i modelli Gemini utilizzando l'API Live. Puoi avviare una sessione utilizzando Vertex AI Studio, Gen AI SDK o WebSocket.

Questa pagina mostra anche come:

  • Estendere una sessione oltre il limite di tempo predefinito
  • Riprendere una sessione precedente
  • Aggiornare le istruzioni di sistema durante una sessione
  • Configurare la finestra contestuale di una sessione
  • Attivare la trascrizione per una sessione

Durata della sessione

Senza compressione, le sessioni solo audio sono limitate a 15 minuti e le sessioni audio-video sono limitate a 2 minuti. Il superamento di questi limiti terminerà la sessione, ma puoi utilizzare la compressione della finestra contestuale per estendere le sessioni per un periodo di tempo illimitato.

La durata di una connessione è limitata a circa 10 minuti. Quando la connessione termina, anche la sessione termina. In questo caso, puoi configurare una singola sessione in modo che rimanga attiva su più connessioni utilizzando il ripristino della sessione. Riceverai anche un messaggio GoAway prima che la connessione termini, per consentirti di intraprendere ulteriori azioni.

Numero massimo di sessioni simultanee

Puoi avere fino a 1000 sessioni simultanee per progetto con un piano con pagamento a consumo (PayGo). Questo limite non si applica ai clienti che utilizzano la velocità effettiva di provisioning.

Avviare una sessione

Le seguenti schede mostrano come avviare una sessione di conversazione live utilizzando Vertex AI Studio, Gen AI SDK o WebSocket:

Console

  1. Apri Vertex AI Studio > Stream realtime.
  2. Fai clic su Avvia sessione per iniziare la conversazione.

Per terminare la sessione, fai clic su Interrompi sessione.

Python

Prima di iniziare, devi autenticarti in Vertex AI utilizzando una chiave API o le credenziali predefinite dell'applicazione (ADC): 

gcloud auth application-default login

Per ulteriori informazioni sulla configurazione dell'autenticazione, consulta la nostra guida rapida. 

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

Quando utilizzi WebSocket, la connessione viene stabilita con un handshake WebSocket standard. L'endpoint è regionale e utilizza token di autenticazione OAuth 2.0. In questo scenario, il token di autenticazione viene in genere passato nelle intestazioni WebSocket (ad esempio 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())

Estendere una sessione

La durata massima predefinita di una sessione di conversazione è di 10 minuti. Una goAway notifica (BidiGenerateContentServerMessage.goAway) viene inviata al cliente 60 secondi prima della fine della sessione.

Puoi estendere la durata della sessione con incrementi di 10 minuti utilizzando l'SDK Gen AI. Non esiste un limite al numero di volte in cui puoi estendere una sessione. Per un esempio, vedi Riprendere una sessione precedente.

Per estendere una sessione:

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)

Riprendere una sessione precedente

L'API Live supporta la ripresa della sessione per evitare che l'utente perda il contesto della conversazione durante una breve disconnessione (ad esempio, il passaggio dal Wi-Fi al 5G). Puoi riprendere una sessione precedente entro 24 ore. La ripresa della sessione viene ottenuta memorizzando i dati memorizzati nella cache, inclusi testo, video, prompt audio e output del modello. La privacy a livello di progetto viene applicata a questi dati memorizzati nella cache.

Per impostazione predefinita, la ripresa della sessione è disattivata. Per attivare la ripresa della sessione, imposta il campo sessionResumption del messaggio BidiGenerateContentSetup. Se attivato, il server invia periodicamente messaggi SessionResumptionUpdate contenenti un session_id e un token di ripresa. Se la connessione WebSocket si interrompe, il client può riconnettersi e includere queste credenziali nel nuovo messaggio di configurazione. Il server ripristina quindi il contesto precedente, consentendo alla conversazione di continuare senza problemi.

Il periodo di ripresa è finito (in genere circa 10 minuti). Se il client non si riconnette entro questo periodo di tempo, lo stato della sessione viene eliminato per liberare le risorse del server.

Di seguito è riportato un esempio di attivazione della ripresa della sessione e recupero dell'ID 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())

Attivare la ripresa della sessione senza interruzioni con la modalità trasparente

Quando attivi la ripresa della sessione, puoi anche attivare la modalità trasparente per rendere più semplice il processo di ripresa per l'utente. Quando la modalità trasparente è abilitata, viene restituito esplicitamente l'indice del messaggio del client che corrisponde all'istantanea del contesto. In questo modo è più facile identificare il messaggio del client che devi inviare di nuovo quando riprendi la sessione dal punto di ripresa.

Per attivare la modalità Trasparenza:

Python

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

Aggiornare le istruzioni di sistema durante una sessione

L'API Live ti consente di aggiornare le istruzioni di sistema durante una sessione attiva. Utilizzalo per adattare le risposte del modello, ad esempio modificando la lingua della risposta o il tono.

Per aggiornare le istruzioni di sistema a metà sessione, puoi inviare contenuti di testo con il ruolo system. L'istruzione di sistema aggiornata rimarrà in vigore per la sessione rimanente.

Python

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

Configurare la finestra contestuale della sessione

La finestra contestuale dell'API Live viene utilizzata per archiviare i dati trasmessi in streaming in tempo reale (25 token al secondo (TPS) per l'audio e 258 TPS per il video) e altri contenuti, inclusi input di testo e output del modello. Una sessione ha un limite della finestra contestuale di:

  • 128.000 token per i modelli audio nativi
  • 32.000 token per altri modelli dell'API Live

Nelle sessioni di lunga durata, man mano che la conversazione prosegue, si accumula la cronologia dei token audio e di testo. Se la cronologia supera il limite del modello, il modello potrebbe generare allucinazioni, rallentare o la sessione potrebbe essere interrotta forzatamente. Per attivare sessioni più lunghe, puoi attivare la compressione della finestra contestuale impostando il campo contextWindowCompression nell'ambito della configurazione della sessione.

La compressione della finestra contestuale utilizza una finestra scorrevole lato server per troncare le conversazioni più vecchie quando è attivata. Quando i token accumulati superano una lunghezza massima definita (impostata utilizzando il cursore Dimensioni massime dei contenuti in Vertex AI Studio o trigger_tokens nell'API), il server elimina automaticamente i turni più vecchi o li riepiloga per mantenere il contesto entro il limite. In ContextWindowCompressionConfig, puoi configurare un meccanismo di finestra scorrevole e il numero di token definiti nel parametro target_tokens che attiva la compressione.

Ciò consente durate delle sessioni teoricamente infinite dal punto di vista dell'utente, poiché la "memoria" viene gestita costantemente. Senza compressione, le sessioni solo audio potrebbero essere limitate a circa 15 minuti prima di raggiungere i limiti rigidi.

Le lunghezze minime e massime per la lunghezza del contesto e le dimensioni del target sono:

Impostazione (flag API) Valore minimo Valore massimo
Lunghezza massima del contesto (trigger_tokens) 5000 128.000
Dimensioni del contesto target (target_tokens) 0 128.000

Per impostare la finestra contestuale:

Console

  1. Apri Vertex AI Studio > Stream realtime.
  2. Fai clic per aprire il menu Avanzate.
  3. Nella sezione Contesto della sessione, utilizza il cursore Dimensione massima del contesto per impostare la dimensione del contesto su un valore compreso tra 5000 e 128.000.
  4. (Facoltativo) Nella stessa sezione, utilizza il cursore Dimensione contesto target per impostare la dimensione target su un valore compreso tra 0 e 128.000.

Python

Imposta i campi context_window_compression.trigger_tokens e context_window_compression.sliding_window.target_tokens nel messaggio di configurazione: 

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

Attivare la trascrizione audio per la sessione

Puoi attivare le trascrizioni sia per l'audio di input che per quello di output.

Per ricevere le trascrizioni, devi aggiornare la configurazione della sessione. Devi aggiungere gli oggetti input_audio_transcription e output_audio_transcription e assicurarti che text sia incluso in response_modalities.

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

Elaborazione della risposta

Il seguente esempio di codice mostra come connettersi utilizzando la sessione configurata ed estrarre le parti di testo (trascrizioni) insieme ai dati 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.")

Passaggi successivi