Ir al contenido principal
Español— Elegir un idioma
Menú

Interrupciones y gestión de turnos

Lección 5 de 18 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Interrupciones y gestión de turnos
  2. Detección de Actividad de Voz (VAD)
  3. Gestión de interrupciones
  4. Modo de control manual
  5. Arquitectura de gestión de estado
  6. Puntos clave

Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos: tts-1, tts-1-hd y gpt-4o-mini-tts dejarán de funcionar el 6 de enero de 2027 (sustituto: gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con /v1/audio/speech: la migración de la síntesis de voz se traslada a la Realtime API); gpt-realtime, gpt-4o-realtime y los modelos de audio heredados el 20 de enero de 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe y /v1/audio/translations el 26 de febrero de 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Para la voz a dúplex completo, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026.

Corregido el 3 de noviembre de 2026. Los eventos session.update situaban anteriormente turn_detection en la raíz de la sesión, un formato de la beta antigua: con la Realtime API actual, la configuración reside en session.audio.input.turn_detection, y la sesión lleva "type": "realtime". La gestión de interrupciones enviaba antes response.cancel, pero con VAD el servidor cancela la respuesta por sí mismo, y el código usaba una variable no definida. Esta lección cubre ahora semantic_vad, create_response e interrupt_response, y distingue entre WebSocket y WebRTC. Las formas de los eventos se han verificado frente a los tipos del SDK openai 3.42.1. Fuentes: Detección de actividad de voz · Conversaciones en tiempo real.

Interrupciones y gestión de turnos

En una conversación natural, las personas se interrumpen, hablan unas encima de otras y se cortan mutuamente. Un agente de voz que no pueda manejar estas situaciones parecerá robótico y resultará frustrante. La Realtime API ofrece dos mecanismos para gestionar la toma de turnos: la Detección de Actividad de Voz (VAD) automática y el control manual.

Detección de Actividad de Voz (VAD)

La VAD está activada por defecto en una sesión de conversación de voz, operando en modo server_vad: el servidor analiza continuamente el audio entrante, lo segmenta basándose en el silencio y señala el inicio y el final del habla del usuario. Lo configuras en 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 inmediatamente al finalizar el turno
                    "interrupt_response": True,   # cortar al agente si el usuario habla
                }
            }
        },
    },
}))

Parámetros de la VAD

Parámetro Descripción Impacto
threshold Umbral de detección (0,0 a 1,0) Alto = menos sensible, Bajo = más sensible
prefix_padding_ms Audio retenido antes de la detección Evita cortar el inicio de las palabras
silence_duration_ms Duración del silencio necesaria para finalizar el turno Corto = receptivo, Largo = paciente

Un silence_duration_ms demasiado corto activará una respuesta durante las pausas naturales del habla del usuario; si es demasiado largo, el agente parecerá poco receptivo. OpenAI no publica valores predeterminados específicos por idioma: comienza con el ejemplo de la documentación (500 ms) y ajústalo basándote en grabaciones de tus usuarios. Un threshold más alto requiere un sonido más fuerte para activarse, lo cual ayuda en entornos ruidosos.

VAD semántica

El segundo modo, semantic_vad, no se basa en el silencio, sino en las palabras: un clasificador estima si el usuario ha terminado su frase. Una frase dejada en suspenso gana más tiempo que una afirmación clara, y el modelo interrumpe con menos frecuencia. Su configuración eagerness puede ser low (dejar que el usuario se tome su tiempo), medium, high (responder lo antes posible) o auto, el valor por defecto, que equivale a medium:

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "audio": {"input": {"turn_detection": {"type": "semantic_vad", "eagerness": "low"}}},
    },
}))

Gestión de interrupciones

Cuando el usuario habla mientras el agente está respondiendo, el servidor emite input_audio_buffer.speech_started. Con la VAD y interrupt_response activados, el servidor cancela la respuesta actual: a continuación envía response.done con el estado cancelled. Aun así, debes hacer dos cosas en tu extremo, en una conexión WebSocket donde estás reproduciendo el audio:

  1. Detener la reproducción inmediatamente y descartar cualquier audio en cola, anotando cuántos milisegundos ha escuchado realmente el usuario.
  2. Truncar el elemento del agente a esa duración usando conversation.item.truncate.

No esperes a recibir response.done para hacer ninguna de las dos cosas.

async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
    """Gestiona el habla del usuario mientras el agente está hablando (WebSocket)."""
    if event["type"] != "input_audio_buffer.speech_started":
        return

    # 1. Detener la reproducción y limpiar el búfer de audio en cola
    player.stop_stream()

    # 2. Eliminar del historial la parte que el usuario no ha oído
    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 la reproducción para la siguiente respuesta
    player.start_stream()

Calcula ms_played basándote en lo que realmente has enviado al altavoz: en PCM mono de 16 bits a 24 kHz, 48.000 bytes equivalen a un segundo. En WebRTC o SIP, el servidor gestiona el búfer de salida por sí mismo, sabe qué se ha reproducido y trunca automáticamente: no necesitas enviar nada.

¿Por qué truncar la respuesta?

Sin el truncamiento, el historial de la conversación contendría la respuesta completa del modelo, aunque el usuario solo haya oído una parte. Si el usuario pregunta: «¿Qué fue lo último que dijiste?», el modelo creería que lo había dicho todo. Truncar alinea el historial con lo que el usuario ha escuchado realmente. La documentación señala una limitación: el truncamiento corta el audio y elimina la transcripción de la parte no reproducida, pero no proporciona una transcripción truncada palabra por palabra.

Modo de control manual

Para ciertos casos de uso (menús IVR, dictado, cuestionarios), la VAD automática no es adecuada. El modo manual te da control total:

# Desactivar VAD
await ws.send(json.dumps({
    "type": "session.update",
    "session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))

# Botón pulsado: si el agente aún está hablando, cancelar su respuesta y truncar el audio no reproducido
await ws.send(json.dumps({"type": "response.cancel"}))

# Botón liberado: el audio se envió vía input_audio_buffer.append, confirmar el turno...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))

# ...y luego activar la respuesta
await ws.send(json.dumps({"type": "response.create"}))

Sin VAD, nada es automático: aquí es donde entra response.cancel, cuando hay una respuesta en curso y el usuario retoma el control. Entre turnos, input_audio_buffer.clear vacía el búfer de entrada.

Existe un punto medio: mantener la VAD activada para que siga segmentando turnos y emitiendo eventos, pero establecer create_response e interrupt_response en False. No se envía ninguna respuesta sin tu response.create explícito, lo que te da tiempo para verificar o enriquecer la entrada (moderación, recuperación de documentos), a costa de cierta latencia.

Casos de uso del modo manual

  • Menú IVR: Esperar un tono DTMF o una palabra clave específica antes de responder.
  • Dictado: Acumular segmentos de audio largos sin interrupción.
  • Confirmación: Esperar un «sí» o un «no» explícitos.
  • Pulsar para hablar: El usuario pulsa un botón para hablar.

Arquitectura de gestión de estado

Para una gestión robusta de turnos, mantén una máquina de estados:

from enum import Enum

class ConversationState(Enum):
    IDLE = "idle"                    # Esperando
    USER_SPEAKING = "user_speaking"  # El usuario está hablando
    PROCESSING = "processing"        # El modelo está procesando
    AGENT_SPEAKING = "agent_speaking" # El agente está respondiendo
    INTERRUPTED = "interrupted"       # Interrupción en 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

Puntos clave

  • La VAD (server_vad por defecto) se configura en session.audio.input.turn_detection.
  • semantic_vad segmenta basándose en el significado; eagerness controla su paciencia.
  • Con VAD, el servidor cancela la respuesta interrumpida; en WebSocket, detén la reproducción y trunca con conversation.item.truncate (automático en WebRTC y SIP).
  • El modo manual (turn_detection establecido en None) es adecuado para pulsar para hablar, menús IVR y dictado.
  • Una máquina de estados explícita evita comportamientos inconsistentes en casos límite.