Inicie e faça a gestão de sessões em direto

A API Live permite interações de voz e texto de baixa latência através do processamento de streams contínuas de áudio ou texto denominadas sessões para fornecer respostas faladas imediatas e semelhantes às humanas. A gestão do ciclo de vida da sessão, desde o handshake inicial até à terminação elegante, é controlada pelo programador.

Esta página mostra como iniciar uma sessão de conversa com os modelos Gemini através da API Live. Pode iniciar uma sessão através do Vertex AI Studio, do SDK de IA gen ou dos WebSockets.

Esta página também mostra como fazer o seguinte:

  • Prolongue uma sessão para além do limite de tempo predefinido
  • Retome uma sessão anterior
  • Atualize as instruções do sistema durante uma sessão
  • Configure a capacidade de resposta de uma sessão
  • Ative a transcrição para uma sessão

Duração da sessão

Sem compressão, as sessões apenas de áudio estão limitadas a 15 minutos e as sessões de áudio e vídeo estão limitadas a 2 minutos. Exceder estes limites termina a sessão, mas pode usar a compressão da janela de contexto para prolongar as sessões por um período ilimitado.

A duração de uma ligação está limitada a cerca de 10 minutos. Quando a ligação termina, a sessão também termina. Neste caso, pode configurar uma única sessão para permanecer ativa em várias ligações através da retoma da sessão. Também recebe uma mensagem GoAway antes de a ligação terminar, o que lhe permite tomar medidas adicionais.

Sessões simultâneas máximas

Pode ter até 1000 sessões simultâneas por projeto num plano de pagamento conforme o uso (PayGo). Este limite não se aplica a clientes que usam débito processado.

Inicie uma sessão

Os seguintes separadores mostram como iniciar uma sessão de conversa em direto através do Vertex AI Studio, do SDK de IA gen ou dos WebSockets:

Consola

  1. Abra o Vertex AI Studio > Transmitir em tempo real.
  2. Clique em Iniciar sessão para iniciar a conversa.

Para terminar a sessão, clique em Parar sessão.

Python

Antes de começar, tem de autenticar-se no Vertex AI através de uma chave da API ou das credenciais predefinidas da aplicação (ADC): 

gcloud auth application-default login

Para mais informações sobre a configuração da autenticação, consulte o nosso início rápido. 

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 usa WebSockets, a ligação é estabelecida com um handshake WebSocket padrão. O ponto final é regional e usa tokens de portador OAuth 2.0 para autenticação. Neste cenário, o token de autenticação é normalmente transmitido nos cabeçalhos WebSocket (como 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())

Prolongue uma sessão

O comprimento máximo predefinido de uma sessão de conversa é de 10 minutos. É enviada uma goAway notificação (BidiGenerateContentServerMessage.goAway) ao cliente 60 segundos antes do fim da sessão.

Pode prolongar a duração da sessão em incrementos de 10 minutos através do SDK de IA gen. Não existe um limite para o número de vezes que pode prolongar uma sessão. Para ver um exemplo, consulte o artigo Retome uma sessão anterior.

Para prolongar uma sessão:

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)

Retome uma sessão anterior

A API Live suporta a retoma da sessão para impedir que o utilizador perca o contexto da conversa durante uma breve desconexão (por exemplo, mudar do Wi-Fi para 5G). Pode retomar uma sessão anterior no prazo de 24 horas. A retoma da sessão é alcançada através do armazenamento de dados em cache, incluindo comandos de texto, vídeo e áudio, bem como resultados do modelo. A privacidade ao nível do projeto é aplicada a estes dados em cache.

Por predefinição, o recomeço da sessão está desativado. Para ativar a retoma da sessão, defina o campo sessionResumption da mensagem BidiGenerateContentSetup. Se estiver ativado, o servidor envia periodicamente mensagens SessionResumptionUpdate que contêm um session_id e um token de retoma. Se o WebSocket for desligado, o cliente pode voltar a ligar-se e incluir estas credenciais na nova mensagem de configuração. Em seguida, o servidor restaura o contexto anterior, o que permite que a conversa continue sem problemas.

O período de retoma é finito (normalmente, cerca de 10 minutos). Se o cliente não voltar a estabelecer ligação dentro deste período, o estado da sessão é rejeitado para libertar recursos do servidor.

Segue-se um exemplo de como ativar a retoma da sessão e obter o ID do identificador:

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

Ative a retoma da sessão perfeita com o modo transparente

Quando ativa a retoma da sessão, também pode ativar o modo transparente para ajudar a tornar o processo de retoma mais integrado para o utilizador. Quando o modo transparente está ativado, o índice da mensagem do cliente que corresponde ao instantâneo do contexto é devolvido explicitamente. Isto ajuda a identificar a mensagem do cliente que tem de enviar novamente quando retoma a sessão a partir do identificador de retoma.

Para ativar o modo transparente:

Python

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

Atualize as instruções do sistema durante uma sessão

A API Live permite-lhe atualizar as instruções do sistema durante uma sessão ativa. Use esta opção para adaptar as respostas do modelo, como alterar o idioma da resposta ou modificar o tom.

Para atualizar as instruções do sistema durante a sessão, pode enviar conteúdo de texto com a função system. A instrução do sistema atualizada permanece em vigor durante a sessão restante.

Python

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

Configure a capacidade de resposta da sessão

A janela de contexto da API Live é usada para armazenar dados transmitidos em tempo real (25 tokens por segundo [TPS] para áudio e 258 TPS para vídeo) e outro conteúdo, incluindo entradas de texto e resultados do modelo. Uma sessão tem um limite de capacidade de resposta de:

  • 128 000 tokens para modelos de áudio nativos
  • 32 mil tokens para outros modelos da API Live

Em sessões de longa duração, à medida que a conversa avança, o histórico de tokens de áudio e texto acumula-se. Se este histórico exceder o limite do modelo, o modelo pode ter alucinações, ficar mais lento ou a sessão pode ser terminada à força. Para ativar sessões mais longas, pode ativar a compressão da janela de contexto definindo o campo contextWindowCompression como parte da configuração da sessão.

A compressão da janela de contexto usa uma janela deslizante do lado do servidor para truncar as interações mais antigas quando ativada. Quando os tokens acumulados excedem um comprimento máximo definido (definido através do controlo de deslize Tamanho máximo do conteúdo no Vertex AI Studio ou trigger_tokens na API), o servidor remove automaticamente as interações mais antigas ou resume-as para manter o contexto dentro do limite. No ContextWindowCompressionConfig, pode configurar um mecanismo de janela deslizante e o número de tokens definidos no parâmetro target_tokens que aciona a compressão.

Isto permite durações de sessões teoricamente infinitas do ponto de vista do utilizador, uma vez que a "memória" é gerida constantemente. Sem compressão, as sessões apenas de áudio podem estar limitadas a aproximadamente 15 minutos antes de atingir os limites rígidos.

Os comprimentos mínimo e máximo para o comprimento do contexto e o tamanho do alvo são:

Definição (sinalização da API) Valor mínimo Valor máximo
Comprimento máximo do contexto (trigger_tokens) 5000 128 000
Tamanho do contexto de destino (target_tokens) 0 128 000

Para definir a capacidade de resposta:

Consola

  1. Abra o Vertex AI Studio > Transmitir em tempo real.
  2. Clique para abrir o menu Avançadas.
  3. Na secção Contexto da sessão, use o controlo de deslize Tamanho máximo do contexto para definir o tamanho do contexto para um valor entre 5000 e 128 000.
  4. (Opcional) Na mesma secção, use o controlo de deslize Tamanho do contexto de destino para definir o tamanho de destino para um valor entre 0 e 128 000.

Python

Defina os campos context_window_compression.trigger_tokens e context_window_compression.sliding_window.target_tokens na mensagem de configuração: 

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

Ative a transcrição de áudio para a sessão

Pode ativar as transcrições para o áudio de entrada e saída.

Para receber transcrições, tem de atualizar a configuração da sessão. Tem de adicionar os objetos input_audio_transcription e output_audio_transcription e garantir que text está incluído em response_modalities.

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

A processar a resposta

O exemplo de código seguinte demonstra como estabelecer ligação através da sessão configurada e extrair as partes de texto (transcrições) juntamente com os dados de áudio.

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

O que se segue?