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

Interrupções e Gestão de Turnos

Aula 5 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Interrupções e Gestão de Turnos
  2. Deteção de Atividade de Voz (VAD)
  3. Tratamento de Interrupções
  4. Modo de Controlo Manual
  5. Arquitetura de Gestão de Estado
  6. Pontos-chave

Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarã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-realtime e 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-transcribe e /v1/audio/translations a 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.update colocavam anteriormente turn_detection na raiz da sessão, um formato da antiga beta: com a atual Realtime API, a definição reside em session.audio.input.turn_detection, e a sessão inclui "type": "realtime". O tratamento de interrupções enviava anteriormente response.cancel, mas com o VAD o servidor cancela a resposta automaticamente, e o código utilizava uma variável indefinida. Esta lição aborda agora semantic_vad, create_response e interrupt_response, distinguindo entre WebSocket e WebRTC. As formas dos eventos foram verificadas com os tipos do SDK openai 3.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:

  1. Parar a reprodução imediatamente e descartar qualquer áudio na fila, registando quantos milissegundos o utilizador ouviu efetivamente.
  2. 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_vad por defeito) é configurado em session.audio.input.turn_detection
  • O semantic_vad segmenta com base no significado; eagerness controla 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_detection definido como None) adequa-se a push-to-talk, menus IVR e ditado
  • Uma máquina de estados explícita previne comportamentos inconsistentes em casos limite