Ir para o conteúdo principal
Português— Escolher um idioma
Menu

VAD: deteção automática de fala

Aula 6 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Como funciona a deteção de turnos
  2. Dois modos, um campo
  3. Eventos VAD
  4. Estimular um utilizador em silêncio: idle_timeout_ms
  5. Modo manual: turn_detection.type definido como null
  6. Escolha o seu modo
  7. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Speech to Speech da xAI e na referência da Voice API: a deteção de turnos configura-se através de turn_detection.type ("server_vad" ou null) e, opcionalmente, turn_detection.idle_timeout_ms. Fontes: Speech to Speech · Voice API.

Como funciona a deteção de turnos

Numa conversa por voz, o sistema tem de saber quando o utilizador começa e quando para de falar. Essa é a função do VAD (deteção de atividade de voz). A Voice Agent API da xAI fornece um VAD no lado do servidor, server_vad: o servidor analisa o fluxo de áudio, identifica o fim de cada enunciado e aciona a resposta automaticamente.

Dois modos, um campo

Escolhe o modo no objeto turn_detection do evento session.update:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad" }
  }
}
turn_detection.typeQuem decide quando o turno terminaO que envia
"server_vad"O servidorinput_audio_buffer.append, nada mais
nullO utilizadorinput_audio_buffer.append, seguido de input_audio_buffer.commit e response.create

No modo server_vad, o servidor divide os turnos, confirma o áudio e inicia a resposta. As interrupções também são geridas automaticamente: a xAI recomenda este modo para uma troca de turnos natural, quando o utilizador interrompe o agente a meio de uma frase. A documentação não oferece qualquer definição de sensibilidade ou duração do silêncio: a divisão de turnos é da exclusiva responsabilidade do servidor.

Eventos VAD

Com server_vad, o servidor reporta cada transição:

  • input_audio_buffer.speech_started: o VAD detetou o início da fala;
  • input_audio_buffer.speech_stopped: detetou o fim;
  • input_audio_buffer.committed: o áudio foi confirmado como mensagem do utilizador.
ws.on("message", (data) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case "input_audio_buffer.speech_started":
      stopPlayback();       // o utilizador está a falar: pare o áudio do agente já recebido
      break;
    case "input_audio_buffer.speech_stopped":
      showThinking();       // fim da fala detetado: a resposta está a chegar
      break;
  }
});

No lado do servidor, a interrupção é automática; no lado do cliente, o áudio que já recebeu continuaria a ser reproduzido se não o parasse. O evento speech_started é o momento certo para esvaziar a sua fila de reprodução.

Estimular um utilizador em silêncio: idle_timeout_ms

A única configuração documentada relacionada com o VAD, idle_timeout_ms, faz com que o agente retome a conversa quando o utilizador fica em silêncio após uma resposta:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
  }
}

Se não for detetada fala durante esse período após o fim de uma resposta, o servidor emite input_audio_buffer.timeout_triggered, confirma um turno silencioso do utilizador e gera uma verificação de estado. O temporizador reinicia após cada resposta, pelo que é acionado novamente a cada idle_timeout_ms enquanto o utilizador não disser nada. Está desativado por padrão (null). Numa central telefónica, uma verificação após alguns segundos impede que os silêncios se arrastem; escreva a frase de acompanhamento que o agente deve utilizar nas suas instruções.

Modo manual: turn_detection.type definido como null

Para uma interface de «carregar para falar» (push-to-talk), ou sempre que quiser decidir quando um turno termina, defina o tipo como null:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": null }
  }
}

Envia então o áudio com input_audio_buffer.append e, quando o utilizador largar o botão, envie input_audio_buffer.commit para confirmar o turno e response.create para solicitar a resposta. O comando input_audio_buffer.commit só está disponível no modo manual. O comando input_audio_buffer.clear descarta o áudio enviado mas ainda não confirmado, e response.cancel para uma resposta em curso, uma vez que a interrupção deixa de ser automática no modo manual.

Escolha o seu modo

  • Conversa fluida (assistente, central telefónica, quiosque): server_vad, com idle_timeout_ms para estimular utilizadores em silêncio, se necessário.
  • Walkie-talkie, ditado, ambientes muito ruidosos: modo manual, onde o fim do turno segue o botão e o ruído de fundo já não aciona nada.

Pontos-chave

  • turn_detection.type é "server_vad" (o servidor divide os turnos e gere as interrupções) ou null (modo manual)
  • A documentação da xAI não oferece limiar de sensibilidade nem duração de silêncio para ajustar
  • speech_started, speech_stopped e committed reportam as transições do VAD
  • idle_timeout_ms estimula um utilizador em silêncio, através do evento input_audio_buffer.timeout_triggered
  • No modo manual: append, depois commit e response.create