Konfigurácia hlasovej relácie
Na tejto strane
Aktualizované 3. novembra 2026 na základe stránky xAI Speech to Speech a sprievodcu hlasovými promptmi. Zdroje: Speech to Speech · Prompting Guide.
Správa, ktorá nastavuje všetko: session.update
Akonáhle je WebSocket spojenie otvorené, zatiaľ sa nedeje nič. Správa session.update je tým, čo dáva agentovi jeho charakter: hlas, ktorý používa, pokyny, ktorými sa riadi, spôsob detekcie striedania reči a nástroje, ktoré môže volať. Ber to ako rodný list relácie. Všetko ostatné v konverzácii z toho vyplýva.
{
"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" }
]
}
}
Server ju potvrdí udalosťou session.updated. Túto správu nemusíš odoslať len raz. Môžeš ju poslať znova uprostred konverzácie a zmeniť nastavenie za behu, napríklad prepnuť hlasy, keď sa hovor presunie z predaja na technickú podporu, a to bez prerušenia spojenia.
Píš pokyny pre ucho, nie pre oko
Pole instructions zohráva úlohu systémového promptu. Použi ho na nastavenie osobnosti agenta (formálna, neformálna, technická), tém, ktorým sa môže venovať, obmedzení jeho odpovedí (dĺžka, formát, jazyk) a obchodného kontextu, ktorý potrebuje: názov tvojej firmy, sortiment produktov a interné postupy.
Háčik je v tom, že to, čo robí dobrý písaný prompt, často robí zlého hlasového agenta. Ak ho necháš na seba, model napíše odpovede dlhé na desať riadkov. Po prečítaní nahlas sa vlečú a používateľ sa vypne skôr, než skončia. Preto explicitne požaduj krátke a priame odpovede. Ak tvoja aplikácia funguje v jednom jazyku, povedz, v ktorom, inak môže agent prepnúť jazyk, aby zodpovedal prízvuku volajúceho. A povedz mu, čo má robiť, keď nerozumie: inštrukcia typu „namiesto hádania sa opýtaj na objasnenie“ zabráni tomu, aby zle počuté číslo objednávky spustilo zbytočné vyhľadávanie. Sprievodca hlasovými promptmi od xAI dokonca navrhuje päťdielnu štruktúru (rola a persona, cieľ, priebeh konverzácie, ochranné mechanizmy a eskalácia, štýl hlasu) a odporúča jednu až dve krátke vety na obrátku, pokiaľ volajúci nepožiada o viac podrobností.
Detekcia striedania reči
Blok turn_detection rozhoduje o tom, kto a kedy hovorí, a dokumentácia xAI preň poskytuje iba dve nastavenia. Prvým je type. V režime "server_vad" server sám deteguje koniec každého výroku, potvrdí audio, spustí odpoveď a rieši prerušenia: ty len posielaš audio pomocou input_audio_buffer.append. Druhým nastavením je voliteľné idle_timeout_ms. Ak používateľ po odpovedi zostane ticho po daný počet milisekúnd, server ho vyzve na odpoveď a urobí to znova po každom novom tichu rovnakej dĺžky.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Neexistuje tu žiadny prah citlivosti ani dĺžka ticha na ladenie. Parametre threshold, silence_duration_ms a prefix_padding_ms, ktoré uvidíš v príkladoch písaných pre OpenAI Realtime API, sa v dokumentácii xAI nevyskytujú.
Ak ti automatické správanie nevyhovuje, nastav typ na null a preber kontrolu. Potom je na tebe, aby si bufferoval audio pomocou input_audio_buffer.append, explicitne potvrdil obrátku pomocou input_audio_buffer.commit a spustil generovanie pomocou response.create. Manuálny režim je správnou voľbou pre rozhranie typu „stlač a hovoriť“ alebo kedykoľvek, keď chceš mať presnú kontrolu nad tým, kedy agent hovorí.
Vyber správny audio formát
Blok audio nastavuje vstupné a výstupné formáty nezávisle:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Akceptujú sa štyri typy. Ak žiadny nešpecifikuješ, dostaneš PCM pri 24 000 Hz:
| Typ | Kódovanie | Vzorkovacie frekvencie |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (severoamerická telefónia) | Iba 8000 Hz |
audio/pcma | G.711 A-law (európska telefónia) | Iba 8000 Hz |
audio/opus | Opus, jeden paket na správu | 24000 Hz |
Rozhoduje tvoj doručovací kanál. Webová aplikácia v prehliadači si vystačí s PCM na 24 000 Hz, čo je dobrý kompromis medzi vnímanou kvalitou a šírkou pásma. Integrácia so SIP telefónom nemá na výber: sieť prenáša G.711 na 8 000 Hz a vynucovanie formátu s vyššou kvalitou by len pridalo zbytočnú konverziu.
Daj agentovi nástroje
Pole tools vymenúva, čo môže agent počas konverzácie volať, a v rámci jednej relácie môžeš miešať rôzne druhy:
{
"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 poskytuješ sadu nástrojov; agent si nástroj vyberá. Ako konverzácia pokračuje, rozhodne sa, že otázka o správach si vyžaduje webové vyhľadávanie, zatiaľ čo číslo objednávky si vyžaduje get_order_status. Tvoja práca teda nie je až tak o orchestrácii volaní, ale skôr o jasnom popise každého nástroja, aby sa agent rozhodol správne.
Kľúčové poznatky
- Správa
session.updatekonfiguruje hlas, pokyny, VAD a nástroje - VAD na strane servera (
server_vad) deteguje obrátky a rieši prerušenia;idle_timeout_msje jediné nastavenie - Manuálny režim (
turn_detection.typenastavené nanull) ti dáva presnú kontrolu, napríklad pri funkciách typu „stlač a hovoriť“ - Audio formáty PCM, G.711 a Opus pokrývajú webové aj telefónne prípady použitia
- Konfiguráciu môžeš zmeniť uprostred relácie bez prerušenia spojenia