Na API Live, uma sessão se refere a uma conexão persistente em que a entrada e a saída são transmitidas continuamente pela mesma conexão. Leia mais sobre como ela funciona. Esse design de sessão exclusivo permite baixa latência e oferece suporte a recursos exclusivos, mas também pode apresentar desafios, como limites de tempo de sessão e encerramento antecipado. Este guia aborda estratégias para superar os desafios de gerenciamento de sessões que podem surgir ao usar a API Live.
Ciclo de vida da sessão
Sem compressão, as sessões somente de áudio são limitadas a 15 minutos, e as sessões de áudio e vídeo são limitadas a 2 minutos. Exceder esses limites encerra a sessão (e, portanto, a conexão), mas é possível usar a compressão da janela de contexto para estender as sessões por um período ilimitado.
A vida útil de uma conexão também é limitada a cerca de 10 minutos. Quando a conexão termina, a sessão também é encerrada. Nesse caso, é possível configurar uma única sessão para ficar ativa em várias conexões usando a retomada de sessão. Você também vai receber uma mensagem GoAway antes do término da conexão, permitindo que você tome outras medidas.
Compactação da janela de contexto
Para ativar sessões mais longas e evitar o encerramento abrupto da conexão, é possível ativar a compactação da janela de contexto definindo o campo contextWindowCompression como parte da configuração da sessão.
Em ContextWindowCompressionConfig, é possível configurar um mecanismo de janela deslizante e o número de tokens que aciona a compactação.
Python
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
context_window_compression=(
# Configures compression with default parameters.
types.ContextWindowCompressionConfig(
sliding_window=types.SlidingWindow(),
)
),
)
JavaScript
const config = {
responseModalities: [Modality.AUDIO],
contextWindowCompression: { slidingWindow: {} }
};
Retomada da sessão
Para evitar o encerramento da sessão quando o servidor redefine periodicamente a conexão WebSocket, configure o campo sessionResumption na configuração de configuração.
A transmissão dessa configuração faz com que o servidor envie mensagens SessionResumptionUpdate, que podem ser usadas para retomar a sessão transmitindo o último token de retomada como o SessionResumptionConfig.handle da conexão subsequente.
Os tokens de retomada são válidos por duas horas após o término das últimas sessões.
Python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
model = "gemini-live-2.5-flash-preview"
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())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-live-2.5-flash-preview';
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
console.debug('Connecting to the service with handle %s...', previousSessionHandle)
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: {
responseModalities: [Modality.TEXT],
sessionResumption: { handle: previousSessionHandle }
// The handle of the session to resume is passed here, or else null to start a new session.
}
});
const inputTurns = 'Hello how are you?';
session.sendClientContent({ turns: inputTurns });
const turns = await handleTurn();
for (const turn of turns) {
if (turn.sessionResumptionUpdate) {
if (turn.sessionResumptionUpdate.resumable && turn.sessionResumptionUpdate.newHandle) {
let newHandle = turn.sessionResumptionUpdate.newHandle
// ...Store newHandle and start new session with this handle here
}
}
}
session.close();
}
async function main() {
await live().catch((e) => console.error('got error', e));
}
main();
Receber uma mensagem antes de a sessão ser desconectada
O servidor envia uma mensagem GoAway que indica que a conexão atual será encerrada em breve. Essa mensagem inclui o timeLeft, que indica o tempo restante e permite que você tome outras medidas antes que a conexão seja encerrada como ABORTED.
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)
JavaScript
const turns = await handleTurn();
for (const turn of turns) {
if (turn.goAway) {
console.debug('Time left: %s\n', turn.goAway.timeLeft);
}
}
Receber uma mensagem quando a geração for concluída
O servidor envia uma mensagem generationComplete que indica que o modelo terminou de gerar a resposta.
Python
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
JavaScript
const turns = await handleTurn();
for (const turn of turns) {
if (turn.serverContent && turn.serverContent.generationComplete) {
// The generation is complete
}
}
A seguir
Confira mais maneiras de trabalhar com a API Live no guia completo de Recursos, na página Uso de ferramentas ou no Cookbook da API Live.