Solução de problemas da API Gemini Live

Este documento fornece etapas de solução de problemas que podem ocorrer ao usar a API Gemini Live.

A conexão cai inesperadamente

Se a conexão da sessão cair inesperadamente, o motivo pode ser limites de token, tempos limite de conexão da sessão ou problemas de rede.

Comportamento

A sessão foi desconectada com o código de erro 1000 ou 1006.

Motivos possíveis

• A compactação da janela de contexto não está ativada, e o token de contexto excede o limite de tokens de contexto da sessão (até 128 mil).
• Nenhuma lógica de retomada de sessão foi implementada ou a lógica de retomada não foi implementada corretamente.
• Conexão de Internet instável.

Motivos e soluções

• Os tokens excedem o limite de tokens de contexto da sessão:para evitar isso, ative a compactação de contexto. Isso pode afetar a qualidade da conversa, já que o modelo descarta intermitentemente partes anteriores do histórico de chat.

• A conexão da sessão expira após 10 minutos:gerencie a retomada da sessão para permitir interações mais longas. Para mais detalhes, consulte as práticas recomendadas para retomada de sessão.

• Conexão de Internet instável:verifique a condição da sua conexão de Internet, já que flutuações na estabilidade podem resultar em problemas de conectividade.

O modelo não entendeu o usuário

Se o modelo não parecer entender seu comando, verifique se o áudio está formatado corretamente e considere a qualidade do microfone e o ruído de fundo.

Comportamento

O modelo responde com informações irrelevantes ou incorretas ou pede para o usuário repetir.

Motivos possíveis

• O formato de áudio de entrada está incorreto.
• A qualidade do microfone não é boa.
• O ruído de fundo está muito alto.

Motivos e soluções

• O formato de áudio de entrada não está correto:verifique se o áudio de entrada usa um formato PCM de 16 bits little-endian com uma taxa de amostragem de 16 kHz e um único canal mono.

• A qualidade do microfone não é boa:teste a qualidade do microfone gravando um áudio curto e reproduzindo-o. Se a qualidade do microfone não for boa, tente usar um microfone melhor.

• O ruído de fundo está muito alto:teste o nível de ruído de fundo gravando um áudio curto e reproduzindo-o. Se o nível de ruído de fundo estiver muito alto, tente aproximar o microfone do usuário ou use um microfone com melhor cancelamento de ruído.

O modelo não está respondendo

Se você não estiver recebendo uma resposta do modelo, verifique as opções de detecção de atividade de voz e a conexão WebSocket.

Comportamento

Nenhuma resposta do modelo.

Motivos possíveis

• As configurações de VAD não estão definidas corretamente.
• A conexão WebSocket foi interrompida.

Motivos e soluções

• VAD definido incorretamente:o usuário desativou a VAD. Nesse caso, o modelo vai continuar esperando a fala do usuário e não vai responder. Envie eventos ActivityStart e ActivityEnd ao modelo se a VAD estiver desativada.

• A conexão WebSocket foi interrompida:se a conexão WebSocket for interrompida, não haverá comunicação entre o cliente e o servidor. Verifique o status da conexão WebSocket e confira se ela foi estabelecida corretamente.

Não é possível interromper o modelo

Se não for possível interromper o modelo enquanto ele fala, verifique se você está processando o buffer de reprodução e o streaming de áudio corretamente.

Comportamento

O modelo continua falando sem interrupção do usuário.

Motivos possíveis

• Falha ao limpar o buffer de reprodução.
• Não foi possível transmitir áudio para a API Gemini Live.
• O VAD personalizado não foi implementado corretamente.

Motivos e soluções

• Falha ao limpar o buffer de reprodução:o cliente precisa limpar o buffer de reprodução imediatamente ao receber um sinal de interrupção do modelo. Caso contrário, o modelo vai continuar falando.

• Falha ao transmitir áudio para a API Gemini Live:o cliente precisa transmitir áudio para a API Gemini Live em partes entre 20 ms e 40 ms para minimizar a latência. Se o cliente não transmitir áudio para a API Gemini Live, o modelo não enviará um sinal de interrupção para ele.

• O VAD personalizado não está implementado corretamente:se o VAD personalizado não reconhecer o início da fala ou o cliente não enviar o indicador ActivityStart ao modelo, ele não vai enviar um indicador de interrupção ao cliente.

Limitações conhecidas

As seguintes limitações se aplicam à API Gemini Live. Cada item inclui uma mitigação, quando disponível.

O pagamento por uso prioritário não é compatível

A API Gemini Live não oferece suporte ao pagamento por uso prioritário como opção de consumo.

A voz pode mudar por uma única vez

Em casos raros, o modelo responde com uma voz diferente da que você definiu no campo voice_name. A mudança é limitada a uma única vez, e as vezes seguintes usam a voz configurada novamente. Nenhuma mudança de configuração é necessária.

A velocidade da fala pode acelerar durante turnos longos

Quando o modelo gera uma resposta falada extensa e ininterrupta, a cadência da fala pode acelerar gradualmente. Esse comportamento é mais perceptível em turnos únicos que excedem 60 segundos. Para manter o ritmo constante, use as seguintes abordagens:

• Segmentar saídas longas:evite pedir ao modelo para ler grandes blocos de texto em uma única vez. Divida respostas extensas em partes de menos de 100 palavras ou menos de 50 segundos de áudio falado.

• Use a troca de turnos conversacional:adote um padrão de diálogo interativo que devolva o controle ao usuário entre os segmentos.

O modelo pode mudar de idioma inesperadamente

Se o modelo determinar que um usuário está falando um idioma diferente do configurado, ele poderá responder nesse idioma. Para reduzir a chance de uma troca não intencional, forneça uma dica de idioma definindo o campo language_code e declarando o idioma esperado na instrução do sistema. Para mais informações, consulte Definir o idioma e a voz.

Sequências de dígitos podem ser repetidas de forma inconsistente

Quando um usuário fala uma sequência de dígitos individuais, como um número de telefone, número do cartão de crédito ou número da conta, o modelo pode repetir a sequência com dígitos incorretos ou ausentes. Para reduzir esses erros, adicione uma instrução do sistema que direcione o modelo a ler a sequência de volta um dígito por vez e peça ao usuário para repetir a sequência lentamente quando os dígitos não estiverem claros.