Przerywanie i zarządzanie turami
Na tej stronie
Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych:
tts-1,tts-1-hdorazgpt-4o-mini-ttsprzestaną działać 6 stycznia 2027 (zamiennik:gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez/v1/audio/speech: migracja syntezy mowy przechodzi do Realtime API);gpt-realtime,gpt-4o-realtimeoraz starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoraz/v1/audio/translations26 lutego 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). W przypadku pełnego dupleksu głosowego, GPT-Live 1 jest dostępny w API od 10 września 2026.
Skorygowano 3 listopada 2026. Zdarzenia
session.updatewcześniej umieszczałyturn_detectionw głównym obiekcie sesji, co było formatem ze starej wersji beta: w obecnej wersji Realtime API ustawienie to znajduje się wsession.audio.input.turn_detection, a sesja zawiera"type": "realtime". Obsługa przerywania wcześniej wysyłałaresponse.cancel, ale przy użyciu VAD serwer sam anuluje odpowiedź, a kod używał niezdefiniowanej zmiennej. Ta lekcja omawia terazsemantic_vad,create_responseiinterrupt_response, rozróżniając połączenia WebSocket i WebRTC. Kształty zdarzeń zweryfikowano względem typów SDKopenaiw wersji 3.42.1. Źródła: Wykrywanie aktywności głosowej · Rozmowy w czasie rzeczywistym.
Przerywanie i zarządzanie turami
W naturalnej rozmowie ludzie wchodzą sobie w słowo, mówią jednocześnie i przerywają nawzajem. Agent głosowy, który nie potrafi obsłużyć takich sytuacji, będzie wydawał się robotyczny i irytujący. Realtime API udostępnia dwa mechanizmy zarządzania zmianą mówcy: automatyczne wykrywanie aktywności głosowej (VAD) oraz sterowanie ręczne.
Wykrywanie aktywności głosowej (VAD)
VAD jest domyślnie włączone w sesji rozmowy głosowej, działając w trybie server_vad: serwer ciągle analizuje przychodzące audio, segmentuje je na podstawie ciszy i sygnalizuje początek oraz koniec wypowiedzi użytkownika. Konfigurujesz to w 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, # odpowiedz natychmiast po zakończeniu tury
"interrupt_response": True, # przerwij agenta, jeśli użytkownik zacznie mówić
}
}
},
},
}))
Parametry VAD
| Parametr | Opis | Wpływ |
|---|---|---|
| threshold | Próg wykrywania (od 0.0 do 1.0) | Wysoki = mniejsza czułość, Niski = większa czułość |
| prefix_padding_ms | Audio zachowane sprzed momentu wykrycia | Zapobiega ucinaniu początku słów |
| silence_duration_ms | Czas ciszy wymagany do zakończenia tury | Krótki = responsywny, Długi = cierpliwy |
Zbyt krótkie silence_duration_ms spowoduje wywołanie odpowiedzi podczas naturalnych pauz w mowie użytkownika; zbyt długie sprawi, że agent będzie wydawał się nieodpowiadający. OpenAI nie publikuje domyślnych wartości specyficznych dla języka: zacznij od przykładu z dokumentacji (500 ms) i dostosuj go na podstawie nagrań swoich użytkowników. Wyższy threshold wymaga głośniejszego dźwięku do wyzwolenia, co pomaga w hałaśliwym otoczeniu.
Semantic VAD
Drugi tryb, semantic_vad, nie opiera się na ciszy, lecz na słowach: klasyfikator szacuje, czy użytkownik zakończył zdanie. Niedokończone zdanie zyskuje więcej czasu niż jasna wypowiedź, a model przerywa rzadziej. Jego ustawienie eagerness może przyjąć wartości: low (pozwalaj użytkownikowi na czas), medium, high (odpowiadaj tak szybko, jak to możliwe) lub auto (wartość domyślna), co jest równoważne medium:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"audio": {"input": {"turn_detection": {"type": "semantic_vad", "eagerness": "low"}}},
},
}))
Obsługa przerywania
Gdy użytkownik zaczyna mówić, podczas gdy agent odpowiada, serwer emituje zdarzenie input_audio_buffer.speech_started. Przy włączonym VAD i interrupt_response, serwer anuluje bieżącą odpowiedź: wysyła następnie response.done ze statusem cancelled. Musisz jednak wykonać dwie czynności po swojej stronie, w przypadku połączenia WebSocket, gdzie to Ty odtwarzasz audio:
- Natychmiast zatrzymaj odtwarzanie i odrzuć wszelkie audio z kolejki, notując, ile milisekund użytkownik faktycznie usłyszał.
- Skróć element odpowiedzi agenta do tego czasu, używając
conversation.item.truncate.
Nie czekaj na response.done, aby wykonać którąkolwiek z tych czynności.
async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
"""Obsługuje mowę użytkownika podczas mówienia agenta (WebSocket)."""
if event["type"] != "input_audio_buffer.speech_started":
return
# 1. Zatrzymaj odtwarzanie i wyczyść bufor audio w kolejce
player.stop_stream()
# 2. Usuń z historii część, której użytkownik nie usłyszał
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. Ponownie otwórz odtwarzanie dla następnej odpowiedzi
player.start_stream()
Oblicz ms_played na podstawie tego, co faktycznie wysłałeś do głośnika: w 16-bitowym mono PCM przy 24 kHz, 48 000 bajtów równa się jednej sekundzie. W przypadku WebRTC lub SIP serwer sam zarządza buforem wyjściowym, wie, co zostało odtworzone, i automatycznie skraca odpowiedź: nie musisz nic wysyłać.
Dlaczego skracać odpowiedź?
Bez skracania historia rozmowy zawierałaby pełną odpowiedź modelu, mimo że użytkownik usłyszał tylko jej część. Jeśli użytkownik zapyta: „Co ostatnio powiedziałeś?“, model myślałby, że wypowiedział całość. Skracanie dopasowuje historię do tego, co użytkownik faktycznie usłyszał. Dokumentacja wskazuje na ograniczenie: skracanie ucina audio i usuwa transkrypcję nieodtworzonej części, ale nie zapewnia transkrypcji słowo w słowo dla uciętego fragmentu.
Tryb sterowania ręcznego
W niektórych przypadkach użycia (menu IVR, dyktowanie, quizy) automatyczne VAD nie jest odpowiednie. Tryb ręczny daje Ci pełną kontrolę:
# Wyłącz VAD
await ws.send(json.dumps({
"type": "session.update",
"session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))
# Naciśnięto przycisk: jeśli agent wciąż mówi, anuluj jego odpowiedź i skróć nieodtworzone audio
await ws.send(json.dumps({"type": "response.cancel"}))
# Zwolniono przycisk: audio zostało wysłane przez input_audio_buffer.append, zatwierdź turę...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
# ...a następnie wyzwól odpowiedź
await ws.send(json.dumps({"type": "response.create"}))
Bez VAD nic nie dzieje się automatycznie: tutaj wchodzi do gry response.cancel, gdy odpowiedź jest w toku, a użytkownik przejmuje kontrolę. Pomiędzy turami input_audio_buffer.clear czyści bufor wejściowy.
Istnieje rozwiązanie pośrednie: pozostaw VAD włączone, aby nadal segmentowało tury i emitowało zdarzenia, ale ustaw create_response i interrupt_response na False. Żadna odpowiedź nie zostanie wysłana bez Twojego wyraźnego response.create, co daje czas na weryfikację lub wzbogacenie danych wejściowych (moderacja, pobieranie dokumentów), kosztem pewnego opóźnienia.
Przypadki użycia trybu ręcznego
- Menu IVR: Czekaj na ton DTMF lub konkretne słowo kluczowe przed odpowiedzią
- Dyktowanie: Gromadź długie segmenty audio bez przerywania
- Potwierdzenie: Czekaj na wyraźne „tak“ lub „nie“
- Naciśnij-i-mów: Użytkownik naciska przycisk, aby mówić
Architektura zarządzania stanem
Aby zapewnić solidne zarządzanie turami, utrzymuj automat stanów:
from enum import Enum
class ConversationState(Enum):
IDLE = "idle" # Oczekiwanie
USER_SPEAKING = "user_speaking" # Użytkownik mówi
PROCESSING = "processing" # Model przetwarza
AGENT_SPEAKING = "agent_speaking" # Agent odpowiada
INTERRUPTED = "interrupted" # Trwa przerywanie
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
Kluczowe wnioski
- VAD (domyślnie
server_vad) konfiguruje się wsession.audio.input.turn_detection semantic_vadsegmentuje na podstawie znaczenia;eagernesskontroluje jego cierpliwość- Przy VAD serwer anuluje przerwaną odpowiedź; w przypadku WebSocket zatrzymaj odtwarzanie i skróć za pomocą
conversation.item.truncate(automatyczne w WebRTC i SIP) - Tryb ręczny (
turn_detectionustawione naNone) nadaje się do „naciśnij-i-mów“, menu IVR i dyktowania - Jawny automat stanów zapobiega niespójnemu zachowaniu w przypadkach brzegowych