Konfiguracja sesji głosowej
Na tej stronie
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:
| Typ | Kodowanie | Częstotliwości próbkowania |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (telefonia północnoamerykańska) | Tylko 8000 Hz |
audio/pcma | G.711 A-law (telefonia europejska) | Tylko 8000 Hz |
audio/opus | Opus, 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.updatekonfiguruje głos, instrukcje, VAD i narzędzia. - VAD po stronie serwera (
server_vad) wykrywa zmiany mówcy i obsługuje przerwania;idle_timeout_msto jedyne dostępne ustawienie. - Tryb ręczny (ustawienie
turn_detection.typenanull) 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.