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

Konfiguracja sesji głosowej

Lekcja 2 z 14 Zaktualizowano 3 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Wiadomość, która ustawia wszystko: session.update
  2. Pisz instrukcje dla ucha, nie dla oka
  3. Wykrywanie zmiany mówcy (Turn detection)
  4. Wybierz odpowiedni format audio
  5. Daj agentowi narzędzia
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Speech to Speech oraz przewodnika po promptach głosowych. Źródła: Speech to Speech · Prompting Guide.

Wiadomość, która ustawia wszystko: session.update

Gdy połączenie WebSocket jest już otwarte, na razie nic się nie dzieje. To wiadomość session.update nadaje agentowi jego charakter: głos, którego używa, instrukcje, których przestrzega, sposób wykrywania zmiany mówcy oraz narzędzia, z których może korzystać. Potraktuj ją jak akt urodzenia sesji. Wszystko inne w rozmowie wynika właśnie z niej.

{
  "type": "session.update",
  "session": {
    "instructions": "You are a professional voice assistant for an e-commerce company. Keep your answers short and help customers with their orders.",
    "voice": "Ara",
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    },
    "tools": [
      { "type": "web_search" }
    ]
  }
}

Serwer potwierdza odbiór zdarzeniem session.updated. Nie musisz wysyłać tej wiadomości tylko raz. Możesz ją wysłać ponownie w trakcie rozmowy, aby dynamicznie zmienić ustawienie – na przykład przełączyć głos, gdy połączenie przechodzi z działu sprzedaży do wsparcia technicznego – bez zrywania połączenia.

Pisz instrukcje dla ucha, nie dla oka

Pole instructions pełni rolę promptu systemowego. Użyj go, aby zdefiniować osobowość agenta (formalna, luźna, techniczna), tematy, które może poruszać, ograniczenia dotyczące odpowiedzi (długość, format, język) oraz kontekst biznesowy: nazwę firmy, asortyment produktów i procedury wewnętrzne.

Haczyk polega na tym, że to, co sprawdza się w przypadku dobrego promptu tekstowego, często zawodzi w przypadku agenta głosowego. Pozostawiony sam sobie model generuje dziesięcioliniowe odpowiedzi. Czytane na głos są przeciągłe, a użytkownik przestaje słuchać, zanim dotrzesz do końca. Dlatego wyraźnie zażądaj krótkich i bezpośrednich odpowiedzi. Jeśli Twoja aplikacja działa w jednym języku, określ go, inaczej agent może przełączyć się, aby dopasować do akcentu rozmówcy. Poinstruuj go również, co ma robić, gdy czegoś nie zrozumie: polecenie typu „zadaj pytanie doprecyzowujące zamiast zgadywać“ zapobiegnie bezsensownemu wyszukiwaniu w przypadku błędnie usłyszanego numeru zamówienia. Przewodnik po promptach głosowych xAI sugeruje nawet pięcioczęściową strukturę (rola i persona, cel, przebieg rozmowy, zabezpieczenia i eskalacja, styl głosu) i zaleca jedną lub dwie krótkie wypowiedzi na turę, chyba że rozmówca poprosi o więcej szczegółów.

Wykrywanie zmiany mówcy (Turn detection)

Blok turn_detection decyduje o tym, kto i kiedy mówi. Dokumentacja xAI udostępnia tylko dwa ustawienia dla tego mechanizmu. Pierwszym jest type. W trybie "server_vad" serwer samodzielnie wykrywa koniec każdej wypowiedzi, zatwierdza audio, uruchamia odpowiedź i obsługuje przerwanie: Ty jedynie wysyłasz audio za pomocą input_audio_buffer.append. Drugim ustawieniem jest opcjonalny parametr idle_timeout_ms. Jeśli użytkownik milczy przez określoną liczbę milisekund po odpowiedzi, serwer ponawia zachętę do mówienia i robi to ponownie po każdej kolejnej przerwie o tej samej długości.

{
  "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}

Nie ma tu progu czułości ani czasu trwania ciszy do dostrojenia. Parametry threshold, silence_duration_ms i prefix_padding_ms, które możesz zobaczyć w przykładach napisanych dla OpenAI Realtime API, nie występują w dokumentacji xAI.

Jeśli automatyczne zachowanie Ci nie odpowiada, ustaw typ na null i przejmij kontrolę. Wtedy to Ty buforujesz audio za pomocą input_audio_buffer.append, jawnie zatwierdzasz turę poleceniem input_audio_buffer.commit i wyzwalasz generowanie odpowiedzi przez response.create. Tryb ręczny jest właściwym wyborem dla interfejsu typu „naciśnij i mów“ (push-to-talk) lub whenever chcesz mieć precyzyjną kontrolę nad momentem, w którym agent zaczyna mówić.

Wybierz odpowiedni format audio

Blok audio ustawia formaty wejścia i wyjścia niezależnie od siebie:

{
  "audio": {
    "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
    "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
  }
}

Akceptowane są cztery typy. Jeśli nie określisz żadnego, domyślnie otrzymasz PCM przy 24 000 Hz:

TypKodowanieCzęstotliwości próbkowania
audio/pcmPCM Linear16, little-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (telefonia północnoamerykańska)Tylko 8000 Hz
audio/pcmaG.711 A-law (telefonia europejska)Tylko 8000 Hz
audio/opusOpus, jeden pakiet na wiadomość24000 Hz

Decyduje kanał dostarczania. Aplikacja webowa w przeglądarce dobrze radzi sobie z PCM 24 000 Hz, co stanowi dobry kompromis między postrzeganą jakością a przepustowością. Integracja z telefonem SIP nie ma wyboru: sieć przenosi G.711 przy 8000 Hz, a wymuszanie formatu wyższej jakości jedynie dodaje bezsensowną konwersję.

Daj agentowi narzędzia

Tablica tools wymienia zasoby, z których agent może korzystać podczas rozmowy. W jednej sesji możesz mieszać różne ich rodzaje:

{
  "tools": [
    { "type": "web_search" },
    { "type": "x_search", "allowed_x_handles": ["gaborit_music"] },
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Ty dostarczasz przybornik, a agent wybiera narzędzie. W miarę rozwoju rozmowy decyduje, że pytanie o wiadomości wymaga wyszukiwania w sieci, podczas gdy numer zamówienia wywołuje funkcję get_order_status. Twoim zadaniem jest więc mniej orchestrowanie wywołań, a bardziej jasny opis każdego narzędzia, aby agent dokonywał właściwych wyborów.

Kluczowe wnioski

  • Wiadomość session.update konfiguruje głos, instrukcje, VAD i narzędzia.
  • VAD po stronie serwera (server_vad) wykrywa zmiany mówcy i obsługuje przerwania; idle_timeout_ms to jedyne dostępne ustawienie.
  • Tryb ręczny (ustawienie turn_detection.type na null) daje precyzyjną kontrolę, na przykład w interfejsach typu push-to-talk.
  • Formaty audio PCM, G.711 i Opus pokrywają zarówno przypadki użycia w sieci, jak i w telefonii.
  • Możesz zmienić konfigurację w trakcie sesji bez zrywania połączenia.