194 lines
5.8 KiB
Markdown
194 lines
5.8 KiB
Markdown
# VAD pause logs
|
|
|
|
Este documento resume como analisar pausas de fala do usuario nos logs locais do agente LiveKit.
|
|
|
|
## Onde procurar
|
|
|
|
Os logs por chamada ficam em `logs/`.
|
|
|
|
O arquivo costuma trazer os identificadores principais logo no inicio:
|
|
|
|
```text
|
|
CALL_START | room=dev-room-75a205ec | protocol=PRT-20260409-0001 | session_id=hf05d7c2-1a1a-42e9-8651-ccd6351faff4 | bridge=ws-bridge-dev-2755fb53
|
|
```
|
|
|
|
Use principalmente:
|
|
|
|
- `room`: identifica a sala LiveKit e permite cruzar com `timeline/<room>.jsonl`.
|
|
- `session_id`: identifica a conversa/sessao.
|
|
- `message_id`: identifica cada turno de usuario ou resposta do agente.
|
|
- `user_seq`: sequencia de falas finais do usuario.
|
|
|
|
## Evento principal: `vad_user_pause`
|
|
|
|
`vad_user_pause` indica que o wrapper de VAD registrou uma pausa relevante na fala do usuario.
|
|
|
|
Exemplo:
|
|
|
|
```text
|
|
FLOW | step=vad_user_pause | decision=end_of_speech | silence_ms=704 | pause_min_ms=700 | speech_duration_ms=896 | min_interrupt_ms=1600 | eligible=False | probability=0.000 | raw_speech_ms=0 | raw_silence_ms=0
|
|
```
|
|
|
|
Campos essenciais:
|
|
|
|
| Campo | Como usar |
|
|
| --- | --- |
|
|
| `decision` | Tipo de pausa detectada. `end_of_speech` e o principal para segmentacao real. `pause_threshold_reached` e um alerta intermediario. |
|
|
| `silence_ms` | Silencio observado pelo VAD, em milissegundos. E o campo mais importante para pausa. |
|
|
| `pause_min_ms` | Minimo de silencio necessario para fechar a fala. Vem de `LIVEKIT_VAD_MIN_SILENCE_DURATION_S`. |
|
|
| `speech_duration_ms` | Duracao do trecho de fala fechado pelo VAD. Trechos muito baixos indicam fala picotada. |
|
|
| `min_interrupt_ms` | Minimo de fala para considerar interrupcao do bot. Nao e o limite de pausa. |
|
|
| `eligible` | Se a fala passou de `min_interrupt_ms`. Mais util para barge-in do que para pausa. |
|
|
| `probability` | Probabilidade de fala no frame atual. Ajuda a entender ruido/atividade fraca. |
|
|
| `raw_speech_ms` | Acumulo bruto usado pelo VAD para detectar inicio de fala. |
|
|
| `raw_silence_ms` | Acumulo bruto usado pelo VAD para detectar silencio. |
|
|
|
|
## Como interpretar pausas
|
|
|
|
### Pausa que fechou fala
|
|
|
|
Priorize `decision=end_of_speech`.
|
|
|
|
Exemplo:
|
|
|
|
```text
|
|
decision=end_of_speech | silence_ms=704 | pause_min_ms=700 | speech_duration_ms=896
|
|
```
|
|
|
|
Leitura:
|
|
|
|
- o VAD fechou o trecho apos observar `704ms` de silencio;
|
|
- o minimo configurado era `700ms`;
|
|
- como passou apenas `4ms` do minimo, a configuracao esta bem sensivel;
|
|
- se isso acontece varias vezes durante uma frase natural, a fala esta sendo segmentada cedo demais.
|
|
|
|
### Alerta intermediario
|
|
|
|
`decision=pause_threshold_reached` significa que o silencio passou do limite minimo antes do fechamento final.
|
|
|
|
Exemplo:
|
|
|
|
```text
|
|
decision=pause_threshold_reached | silence_ms=960 | pause_min_ms=700 | speech_duration_ms=0 | raw_speech_ms=32
|
|
```
|
|
|
|
Esse evento deve ser lido com cuidado quando:
|
|
|
|
- `speech_duration_ms=0`;
|
|
- `raw_speech_ms` e muito baixo, como `32`;
|
|
- `silence_ms` e muito alto, como dezenas de segundos.
|
|
|
|
Nesses casos, pode ser artefato de estado acumulado ou ruido antes de uma fala real. Para confirmar impacto na conversa, cruze com `stt_final`.
|
|
|
|
## Eventos auxiliares
|
|
|
|
### `vad_speech_start`
|
|
|
|
Indica inicio de fala detectado pelo VAD.
|
|
|
|
```text
|
|
FLOW | step=vad_speech_start | speech_duration_ms=128 | min_interrupt_ms=1600
|
|
```
|
|
|
|
Use para ver quando o sistema saiu de `listening` para `speaking`.
|
|
|
|
### `vad_speech_end`
|
|
|
|
Indica fechamento do trecho de fala.
|
|
|
|
```text
|
|
FLOW | step=vad_speech_end | decision=too_short | speech_duration_ms=896 | eligible=False | silence_ms=704 | pause_min_ms=700
|
|
```
|
|
|
|
Use junto com `vad_user_pause`. Se `speech_duration_ms` for baixo varias vezes, a fala pode estar sendo picotada.
|
|
|
|
### `vad_interrupt_check`
|
|
|
|
Indica que a fala atingiu duracao suficiente para interrupcao do bot.
|
|
|
|
```text
|
|
FLOW | step=vad_interrupt_check | decision=eligible_by_duration | speech_duration_ms=1600 | min_interrupt_ms=1600
|
|
```
|
|
|
|
Esse evento ajuda mais a analisar barge-in/interrupcao do bot do que pausa final de fala.
|
|
|
|
### `stt_final`
|
|
|
|
Mostra o texto final enviado como turno de usuario.
|
|
|
|
```text
|
|
FLOW | step=stt_final | message_id=12345678-1234-4234-9234-123456789abc | user_seq=3 | text=Veio mais cara
|
|
```
|
|
|
|
Use este evento para validar o efeito real da segmentacao. Se uma frase natural virou varios `stt_final`, o VAD/STT segmentou demais.
|
|
|
|
## Checklist de analise
|
|
|
|
1. Encontre o `CALL_START` e anote `room`, `session_id` e `protocol`.
|
|
2. Filtre os eventos `vad_user_pause`.
|
|
3. Priorize `decision=end_of_speech`.
|
|
4. Compare `silence_ms` com `pause_min_ms`.
|
|
5. Verifique se `speech_duration_ms` esta muito baixo.
|
|
6. Cruze com os `stt_final` seguintes.
|
|
7. Se uma frase esperada virou varias mensagens curtas, a segmentacao esta agressiva.
|
|
|
|
## Sinais de segmentacao agressiva
|
|
|
|
Exemplo de fala esperada:
|
|
|
|
```text
|
|
por que a minha fatura veio mais cara
|
|
```
|
|
|
|
Exemplo de saida segmentada:
|
|
|
|
```text
|
|
stt_final | text=porque
|
|
stt_final | text=a minha fatura
|
|
stt_final | text=Veio mais cara
|
|
```
|
|
|
|
Se isso vier acompanhado de pausas assim:
|
|
|
|
```text
|
|
vad_user_pause | decision=end_of_speech | silence_ms=704 | pause_min_ms=700
|
|
```
|
|
|
|
provavelmente o limite de pausa esta fechando a fala cedo demais.
|
|
|
|
## Parametro de ajuste
|
|
|
|
O limite principal e:
|
|
|
|
```env
|
|
LIVEKIT_VAD_MIN_SILENCE_DURATION_S=0.7
|
|
```
|
|
|
|
Ele aparece no log como:
|
|
|
|
```text
|
|
pause_min_ms=700
|
|
```
|
|
|
|
Aumentar esse valor tende a juntar mais frases, porque o VAD espera mais silencio antes de encerrar a fala. O custo e aumentar a latencia percebida: o agente demora um pouco mais para responder depois que o usuario termina.
|
|
|
|
Valores para teste manual:
|
|
|
|
- `0.85`: ajuste conservador.
|
|
- `1.0`: tende a reduzir mais a segmentacao.
|
|
- `1.2`: pode ajudar em fala pausada, mas pode deixar a conversa lenta.
|
|
|
|
## Regra pratica
|
|
|
|
Para pausa, olhe primeiro:
|
|
|
|
```text
|
|
decision + silence_ms + pause_min_ms
|
|
```
|
|
|
|
Para impacto na conversa, cruze com:
|
|
|
|
```text
|
|
stt_final + user_seq + message_id
|
|
```
|