Przejdź do głównej treści
Polski— Wybierz język
Menu

Przerywanie i zarządzanie turami

Lekcja 5 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Przerywanie i zarządzanie turami
  2. Wykrywanie aktywności głosowej (VAD)
  3. Obsługa przerywania
  4. Tryb sterowania ręcznego
  5. Architektura zarządzania stanem
  6. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych: tts-1, tts-1-hd oraz gpt-4o-mini-tts przestaną 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-realtime oraz starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe oraz /v1/audio/translations 26 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.update wcześniej umieszczały turn_detection w głównym obiekcie sesji, co było formatem ze starej wersji beta: w obecnej wersji Realtime API ustawienie to znajduje się w session.audio.input.turn_detection, a sesja zawiera "type": "realtime". Obsługa przerywania wcześniej wysyłała response.cancel, ale przy użyciu VAD serwer sam anuluje odpowiedź, a kod używał niezdefiniowanej zmiennej. Ta lekcja omawia teraz semantic_vad, create_response i interrupt_response, rozróżniając połączenia WebSocket i WebRTC. Kształty zdarzeń zweryfikowano względem typów SDK openai w 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:

  1. Natychmiast zatrzymaj odtwarzanie i odrzuć wszelkie audio z kolejki, notując, ile milisekund użytkownik faktycznie usłyszał.
  2. 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ę w session.audio.input.turn_detection
  • semantic_vad segmentuje na podstawie znaczenia; eagerness kontroluje 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_detection ustawione na None) nadaje się do „naciśnij-i-mów“, menu IVR i dyktowania
  • Jawny automat stanów zapobiega niespójnemu zachowaniu w przypadkach brzegowych