Configurarea unei sesiuni vocale
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginii Speech to Speech xAI și a ghidului de promptare vocală. Surse: Speech to Speech · Prompting Guide.
Mesajul care setează totul: session.update
Odată ce conexiunea WebSocket este deschisă, nu se întâmplă nimic încă. Mesajul session.update este cel care oferă agentului personalitatea sa: vocea pe care o folosește, instrucțiunile pe care le urmează, modul în care detectează schimbul de vorbitor și instrumentele pe care le poate apela. Gândiți-vă la el ca la certificatul de naștere al sesiunii. Tot restul conversației decurge din acest mesaj.
{
"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" }
]
}
}
Serverul confirmă recepția prin evenimentul session.updated. Nu trebuie să trimiteți acest mesaj o singură dată. Îl puteți retrimite în mijlocul conversației pentru a modifica o setare din mers, de exemplu pentru a schimba vocea atunci când apelul trece de la vânzări la suport tehnic, fără a întrerupe niciodată conexiunea.
Scrieți instrucțiuni pentru ureche, nu pentru ochi
Câmpul instructions joacă rolul de prompt de sistem. Folosiți-l pentru a stabili personalitatea agentului (formală, casual, tehnică), subiectele pe care le poate aborda, constrângerile privind răspunsurile sale (lungime, format, limbă) și contextul comercial necesar: numele companiei dumneavoastră, gama de produse și procedurile interne.
Problema este că ceea ce funcționează pentru un prompt scris devine adesea un agent vocal slab. Lăsat liber, un model generează răspunsuri de zece rânduri. Citite cu voce tare, acestea se lungesc excesiv, iar utilizatorul își pierde atenția înainte de final. Prin urmare, cereți explicit răspunsuri scurte și directe. Dacă aplicația dumneavoastră funcționează într-o singură limbă, specificați-o, altfel agentul ar putea schimba limba pentru a se potrivi cu accentul apelantului. Indicați-i, de asemenea, ce să facă atunci când nu înțelege: o instrucțiune de genul „puneți o întrebare de clarificare în loc să ghiciți“ împiedică un număr de comandă auzit greșit să declanșeze o căutare inutilă. Ghidul de promptare vocală xAI sugerează chiar o structură în cinci părți (rol și personaj, obiectiv, fluxul conversației, limite și escaladare, stil vocal) și recomandă una sau două propoziții scurte per intervenție,除非 apelantul cere mai multe detalii.
Detectarea schimbului de vorbitor (Turn detection)
Blocul turn_detection decide cine vorbește și când, iar documentația xAI oferă doar două setări pentru acesta. Prima este type. În modul "server_vad", serverul detectează singur sfârșitul fiecărei intervenții, validează audio-ul, începe generarea răspunsului și gestionează întreruperile: tot ce trebuie să faceți este să trimiteți audio prin input_audio_buffer.append. A doua setare, idle_timeout_ms, este opțională. Dacă utilizatorul rămâne tăcut pentru atâtea milisecunde după un răspuns, serverul îl solicită din nou, repetând acest lucru după fiecare nouă perioadă de liniște de aceeași durată.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Nu există niciun prag de sensibilitate sau durată a tăcerii de ajustat. Parametrii threshold, silence_duration_ms și prefix_padding_ms pe care îi veți vedea în exemplele scrise pentru API-ul OpenAI Realtime nu apar în documentația xAI.
Dacă comportamentul automat nu vi se potrivește, setați tipul pe null și preluați controlul. În acest caz, dumneavoastră trebuie să buffer-ați audio-ul cu input_audio_buffer.append, să validați explicit schimbul de vorbitor cu input_audio_buffer.commit și să declanșați generarea cu response.create. Modul manual este alegerea corectă pentru o interfață de tip „apăsați pentru a vorbi“ (push-to-talk) sau ori de câte ori doriți un control precis asupra momentului în care agentul vorbește.
Alegeți formatul audio potrivit
Blocul audio setează independent formatele de intrare și de ieșire:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Sunt acceptate patru tipuri. Dacă nu specificați niciunul, veți obține PCM la 24.000 Hz:
| Tip | Codare | Rate de eșantionare |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (telefonie nord-americană) | Doar 8000 Hz |
audio/pcma | G.711 A-law (telefonie europeană) | Doar 8000 Hz |
audio/opus | Opus, un pachet per mesaj | 24000 Hz |
Canalul de livrare dictează alegerea. O aplicație web într-un browser funcționează bine cu PCM la 24.000 Hz, un echilibru bun între calitatea percepută și lățimea de bandă. O integrare cu un telefon SIP nu are de ales: rețeaua transportă G.711 la 8.000 Hz, iar forțarea unui format de calitate superioară nu face decât să adauge o conversie inutilă.
Oferiți instrumente agentului
Array-ul tools listează ceea ce agentul poate apela în timpul conversației, iar dumneavoastră puteți amesteca diferite tipuri în aceeași sesiune:
{
"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"]
}
}
]
}
Dumneavoastră furnizați trusa de scule; agentul alege instrumentul. Pe măsură ce conversația se desfășoară, el decide că o întrebare despre știri necesită o căutare pe web, în timp ce un număr de comandă necesită get_order_status. Astfel, rolul dumneavoastră este mai puțin despre orchestrarea apelurilor și mai mult despre descrierea clară a fiecărui instrument, astfel încât agentul să facă alegerea corectă.
Puncte cheie
- Mesajul
session.updateconfigurează vocea, instrucțiunile, VAD și instrumentele - VAD lato de server (
server_vad) detectează schimburile de vorbitor și gestionează întreruperile;idle_timeout_mseste singura setare - Modul manual (
turn_detection.typesetat penull) vă oferă un control precis, de exemplu pentru interfețe de tip push-to-talk - Formatele audio PCM, G.711 și Opus acoperă atât cazurile de utilizare web, cât și pe cele de telefonie
- Puteți modifica configurația în timpul sesiunii fără a întrerupe conexiunea