Egy hangalapú munkamenet konfigurálása
Ezen az oldalon
Frissítve: 2026. november 3., az xAI Speech to Speech oldala és a hangalapú promptolási útmutató alapján. Források: Speech to Speech · Prompting Guide.
Az üzenet, ami mindent beállít: session.update
Miután a WebSocket-kapcsolat létrejött, még semmi sem történik. A session.update üzenet adja meg az ügynök személyiségét: a használt hangot, a követendő utasításokat, a beszélőváltás észlelésének módját és a hívható eszközöket. Tekints úgy erre, mint a munkamenet születési anyakönyvi kivonatára. A beszélgetés minden egyéb eleme ebből indul ki.
{
"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" }
]
}
}
A szerver egy session.updated eseménnyel igazolja vissza ezt. Nem csak egyszer kell elküldened ezt az üzenetet. Küldheted újra beszélgetés közben is, hogy menet közben megváltoztass egy beállítást; például hangot válthatsz, amikor a hívás az értékesítésről a műszaki támogatásra kerül, anélkül, hogy megszakítanád a kapcsolatot.
Írj utasításokat a fülnek, ne a szemnek
Az instructions mező tölti be a rendszerprompt szerepét. Használd az ügynök személyiségének (hivatalos, laza, műszaki), a lefedhető témáknak, a válaszokra vonatkozó korlátozásoknak (hossz, formátum, nyelv) és a szükséges üzleti kontextusnak (cégnév, termékkör, belső eljárások) meghatározására.
A csavar az, hogy ami jó írott promptnak számít, az gyakran gyenge hangalapú ügynököt eredményez. Ha magára hagyják, a modell tízsoros válaszokat ír. Hangosan felolvasva ezek elnyúlnak, és a felhasználó még a vég előtt elveszíti a fonalat. Ezért kérj kifejezetten rövid, tömör válaszokat. Ha az alkalmazásod egyetlen nyelven működik, add meg melyiken, különben az ügynök átválthat a hívó akcentusához igazodva. És mondd meg neki, mit tegyen, ha nem ért valamit: egy olyan utasítás, mint „kérdezz vissza tisztázásképpen találgatás helyett“, megakadályozza, hogy egy félrehallott rendelésszám értelmetlen keresést indítson el. Az xAI hangalapú promptolási útmutatója akár ötrészes struktúrát is javasol (szerep és személyiség, cél, beszélgetés menete, korlátok és eszkaláció, hangstílus), és fordulatonként egy-két rövid mondatot ajánl, hacsak a hívó nem kér részletesebb magyarázatot.
Beszélőváltás észlelése
A turn_detection blokk dönti el, ki mikor beszél, és az xAI dokumentációja ehhez csak két beállítást kínál. Az első a type. A "server_vad" módban a szerver önállóan érzékeli minden egyes megnyilvánulás végét, rögzíti az audiót, elindítja a választ, és kezeli a megszakításokat: neked csak annyi a dolgod, hogy elküldöd az audiót az input_audio_buffer.append segítségével. A második beállítás, az idle_timeout_ms, opcionális. Ha a felhasználó ennyi milliszekundumig csendben marad egy válasz után, a szerver felszólítja őt, és ezt megismétli minden ugyanilyen hosszúságú új csend után.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Nincs állítható érzékenységi küszöbérték vagy csendidőtartam. A threshold, silence_duration_ms és prefix_padding_ms paraméterek, amelyeket az OpenAI Realtime API-hoz írt példákban láthatsz, nem szerepelnek az xAI dokumentációjában.
Ha az automatikus viselkedés nem felel meg neked, állítsd a típust null értékre, és vedd át az irányítást. Ekkor rajtad múlik, hogy az input_audio_buffer.append segítségével puffereld az audiót, az input_audio_buffer.commit parancsokkal explicit módon lezárd a fordulót, és a response.create hívással indítsd el a generálást. A kézi mód a helyes választás egy „nyomd a beszéléshez“ (push-to-talk) felülethez, vagy amikor pontosan akarod szabályozni, mikor szólal meg az ügynök.
Válaszd ki a megfelelő hangformátumot
Az audio blokk függetlenül állítja be a bemeneti és kimeneti formátumokat:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Négy típus elfogadott. Ha nem adsz meg egyet sem, akkor 24 000 Hz-es PCM-t kapsz:
| Típus | Kódolás | Mintavételezési ráták |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (észak-amerikai távközlés) | Csak 8000 Hz |
audio/pcma | G.711 A-law (európai távközlés) | Csak 8000 Hz |
audio/opus | Opus, csomagonként egy üzenet | 24000 Hz |
A kézbesítési csatornád dönt. Egy böngészőben futó webes alkalmazásnál a 24 000 Hz-es PCM teljesen megfelel, jó egyensúlyt teremtve az érzékelt minőség és a sávszélesség között. Egy SIP-telefonos integrációnak nincs választása: a hálózat 8000 Hz-en szállítja a G.711-et, és egy magasabb minőségű formátum ráerőltetése csak felesleges konverziót jelent.
Adj eszközöket az ügynök kezébe
A tools tömb felsorolja, mit hívhat meg az ügynök a beszélgetés során, és ugyanabban a munkamenetben különböző típusokat is keverhetsz:
{
"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"]
}
}
]
}
Te biztosítod az eszköztárat; az ügynök választja ki az eszközt. Ahogy a beszélgetés halad, eldönti, hogy egy hírekkel kapcsolatos kérdés webes keresést igényel, míg egy rendelésszám a get_order_status hívását. A te feladatod tehát kevésbé a hívások orchestrálása, sokkal inkább az egyes eszközök világos leírása, hogy az ügynök a helyes döntést hozza.
Főbb megállapítások
- A
session.updateüzenet konfigurálja a hangot, az utasításokat, a VAD-ot és az eszközöket - A szerveroldali VAD (
server_vad) észleli a beszélőváltást és kezeli a megszakításokat; azidle_timeout_msaz egyetlen beállítási lehetőség - A kézi mód (a
turn_detection.typebeállításanullértékre) pontos vezérlést biztosít, például „nyomd a beszéléshez“ felületeknél - A PCM, G.711 és Opus hangformátumok lefedik mind a webes, mind a távközlési használati eseteket
- A kapcsolatot megszakítása nélkül is megváltoztathatod a konfigurációt a munkamenet közben