Interrupções e Gestão de Turnos
Nesta página
Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (substituição:gpt-realtime-2.1-mini, que o guia TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de voz passa para a Realtime API);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Corrigido a 3 de novembro de 2026. Os eventos
session.updatecolocavam anteriormenteturn_detectionna raiz da sessão, um formato da antiga beta: com a atual Realtime API, a definição reside emsession.audio.input.turn_detection, e a sessão inclui"type": "realtime". O tratamento de interrupções enviava anteriormenteresponse.cancel, mas com o VAD o servidor cancela a resposta automaticamente, e o código utilizava uma variável indefinida. Esta lição aborda agorasemantic_vad,create_responseeinterrupt_response, distinguindo entre WebSocket e WebRTC. As formas dos eventos foram verificadas com os tipos do SDKopenai3.42.1. Fontes: Deteção de atividade de voz · Conversas em tempo real.
Interrupções e Gestão de Turnos
Numa conversa natural, as pessoas interrompem-se mutuamente, falam umas por cima das outras e cortam a fala alheia. Um agente de voz incapaz de lidar com estas situações parecerá robótico e frustrante. A Realtime API fornece dois mecanismos para gerir a tomada de turno: a Deteção Automática de Atividade de Voz (VAD) e o controlo manual.
Deteção de Atividade de Voz (VAD)
O VAD está ativado por defeito numa sessão de conversa por voz, operando no modo server_vad: o servidor analisa continuamente o áudio de entrada, segmenta com base no silêncio e sinaliza o início e o fim da fala do utilizador. Configura-o em session.audio.input.turn_detection:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"audio": {
"input": {
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"prefix_padding_ms": 300,
"silence_duration_ms": 500,
"create_response": True, # responder imediatamente quando o turno termina
"interrupt_response": True, # interromper o agente se o utilizador falar
}
}
},
},
}))
Parâmetros do VAD
| Parâmetro | Descrição | Impacto |
|---|---|---|
| threshold | Limiar de deteção (0.0 a 1.0) | Alto = menos sensível, Baixo = mais sensível |
| prefix_padding_ms | Áudio retido antes da deteção | Evita cortar o início das palavras |
| silence_duration_ms | Duração de silêncio necessária para terminar o turno | Curto = responsivo, Longo = paciente |
Um silence_duration_ms demasiado curto desencadeará uma resposta durante pausas naturais na fala do utilizador; se for demasiado longo, o agente parecerá pouco responsivo. A OpenAI não publica valores padrão específicos por idioma: comece com o exemplo da documentação (500 ms) e ajuste com base em gravações dos seus utilizadores. Um threshold mais elevado exige um som mais alto para ser acionado, o que ajuda em ambientes ruidosos.
VAD Semântico
O segundo modo, semantic_vad, não depende do silêncio, mas das palavras: um classificador estima se o utilizador terminou a sua frase. Uma frase deixada em suspenso ganha mais tempo do que uma afirmação clara, e o modelo interrompe com menos frequência. A sua definição eagerness pode ser low (deixar o utilizador tomar o seu tempo), medium, high (responder o mais rápido possível) ou auto, o valor padrão, que equivale a medium:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"audio": {"input": {"turn_detection": {"type": "semantic_vad", "eagerness": "low"}}},
},
}))
Tratamento de Interrupções
Quando o utilizador fala enquanto o agente está a responder, o servidor emite input_audio_buffer.speech_started. Com o VAD e interrupt_response ativados, o servidor cancela a resposta atual: envia então response.done com o estado cancelled. Ainda precisa de fazer duas coisas do seu lado, numa ligação WebSocket onde está a reproduzir o áudio:
- Parar a reprodução imediatamente e descartar qualquer áudio na fila, registando quantos milissegundos o utilizador ouviu efetivamente.
- Truncar o item do agente para essa duração usando
conversation.item.truncate.
Não espere pelo response.done para fazer qualquer uma destas ações.
async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
"""Trata a fala do utilizador enquanto o agente fala (WebSocket)."""
if event["type"] != "input_audio_buffer.speech_started":
return
# 1. Parar a reprodução e limpar o buffer de áudio na fila
player.stop_stream()
# 2. Remover do histórico a parte que o utilizador não ouviu
if item_id:
await ws.send(json.dumps({
"type": "conversation.item.truncate",
"item_id": item_id,
"content_index": 0,
"audio_end_ms": ms_played,
}))
# 3. Reabrir a reprodução para a próxima resposta
player.start_stream()
Calcule o ms_played com base no que enviou efetivamente para o altifalante: em PCM mono de 16 bits a 24 kHz, 48.000 bytes equivalem a um segundo. Em WebRTC ou SIP, o servidor gere o buffer de saída por si próprio, sabe o que foi reproduzido e trunca automaticamente: não precisa de enviar nada.
Por que truncar a resposta?
Sem truncagem, o histórico da conversa conteria a resposta completa do modelo, mesmo que o utilizador só tenha ouvido parte dela. Se o utilizador perguntar «O que foi a última coisa que disse?», o modelo pensaria que tinha dito tudo. Truncar alinha o histórico com o que o utilizador ouviu efetivamente. A documentação nota uma limitação: a truncagem corta o áudio e remove a transcrição da parte não reproduzida, mas não fornece uma transcrição truncada palavra por palavra.
Modo de Controlo Manual
Para certos casos de uso (menus IVR, ditado, questionários), o VAD automático não é adequado. O modo manual dá-lhe controlo total:
# Desativar VAD
await ws.send(json.dumps({
"type": "session.update",
"session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))
# Botão pressionado: se o agente ainda estiver a falar, cancelar a sua resposta e truncar o áudio não reproduzido
await ws.send(json.dumps({"type": "response.cancel"}))
# Botão libertado: o áudio foi enviado via input_audio_buffer.append, confirmar o turno...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
# ...depois acionar a resposta
await ws.send(json.dumps({"type": "response.create"}))
Sem VAD, nada é automático: é aqui que entra o response.cancel, quando uma resposta está em curso e o utilizador retoma o controlo. Entre turnos, input_audio_buffer.clear esvazia o buffer de entrada.
Existe um meio-termo: manter o VAD ativado para que continue a segmentar turnos e a emitir eventos, mas definir create_response e interrupt_response como False. Nenhuma resposta é enviada sem o seu response.create explícito, dando-lhe tempo para verificar ou enriquecer a entrada (moderação, recuperação de documentos), ao custo de alguma latência.
Casos de Uso do Modo Manual
- Menu IVR: Aguardar um tom DTMF ou palavra-chave específica antes de responder
- Ditado: Acumular longos segmentos de áudio sem interrupção
- Confirmação: Aguardar um «sim» ou «não» explícito
- Push-to-talk: O utilizador pressiona um botão para falar
Arquitetura de Gestão de Estado
Para uma gestão robusta de turnos, mantenha uma máquina de estados:
from enum import Enum
class ConversationState(Enum):
IDLE = "idle" # À espera
USER_SPEAKING = "user_speaking" # Utilizador a falar
PROCESSING = "processing" # Modelo a processar
AGENT_SPEAKING = "agent_speaking" # Agente a responder
INTERRUPTED = "interrupted" # Interrupção em curso
class TurnManager:
def __init__(self):
self.state = ConversationState.IDLE
self.current_response_item_id = None
self.played_audio_ms = 0
def on_event(self, event_type: str):
if event_type == "input_audio_buffer.speech_started":
if self.state == ConversationState.AGENT_SPEAKING:
self.state = ConversationState.INTERRUPTED
else:
self.state = ConversationState.USER_SPEAKING
elif event_type == "input_audio_buffer.speech_stopped":
self.state = ConversationState.PROCESSING
elif event_type == "response.output_audio.delta":
self.state = ConversationState.AGENT_SPEAKING
elif event_type == "response.done":
self.state = ConversationState.IDLE
Pontos-chave
- O VAD (
server_vadpor defeito) é configurado emsession.audio.input.turn_detection - O
semantic_vadsegmenta com base no significado;eagernesscontrola a sua paciência - Com VAD, o servidor cancela a resposta interrompida; no WebSocket, pare a reprodução e trunque com
conversation.item.truncate(automático em WebRTC e SIP) - O modo manual (
turn_detectiondefinido comoNone) adequa-se a push-to-talk, menus IVR e ditado - Uma máquina de estados explícita previne comportamentos inconsistentes em casos limite