Interrupciones y gestión de turnos
En esta página
Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejará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-realtimey 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-transcribey/v1/audio/translationsel 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.updatesituaban anteriormenteturn_detectionen la raíz de la sesión, un formato de la beta antigua: con la Realtime API actual, la configuración reside ensession.audio.input.turn_detection, y la sesión lleva"type": "realtime". La gestión de interrupciones enviaba antesresponse.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 ahorasemantic_vad,create_responseeinterrupt_response, y distingue entre WebSocket y WebRTC. Las formas de los eventos se han verificado frente a los tipos del SDKopenai3.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:
- Detener la reproducción inmediatamente y descartar cualquier audio en cola, anotando cuántos milisegundos ha escuchado realmente el usuario.
- 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_vadpor defecto) se configura ensession.audio.input.turn_detection. semantic_vadsegmenta basándose en el significado;eagernesscontrola 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_detectionestablecido enNone) 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.