Конфигуриране на гласова сесия
На тази страница
Обновено на 3 ноември 2026 г., въз основа на страницата Speech to Speech на xAI и ръководството за гласови подкани. Източници: Speech to Speech · Prompting Guide.
Съобщението, което определя всичко: session.update
След като WebSocket връзката се установи, все още нищо не се случва. Съобщението session.update е това, което придава характер на агента: гласът, който използва, инструкциите, които следва, начинът, по който открива смяната на говорещия, и инструментите, които може да извика. Разглеждайте го като акт за раждане на сесията. Всичко останало в разговора произтича от него.
{
"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" }
]
}
}
Сървърът потвърждава това със събитието session.updated. Не е необходимо да изпращате това съобщение само веднъж. Можете да го изпратите отново по средата на разговора, за да промените настройка в реално време, например да смените гласа, когато обаждането преминава от продажби към техническа поддръжка, без никога да прекъсвате връзката.
Пишете инструкции за ухото, а не за окото
Полето instructions играе ролята на системна подкана. Използвайте го, за да зададете личността на агента (официална, неформална, техническа), темите, които може да обхваща, ограниченията върху отговорите му (дължина, формат, език) и бизнес контекста, от който се нуждае: името на Вашата компания, гамата продукти и вътрешните процедури.
Уловката е, че това, което прави една добра писмена подкана, често прави един лош гласов агент. Оставен на собствените си устройства, моделът пише отговори от десет реда. Прочетени на глас, те се влачат и потребителят губи интерес преди края. Затова изрично поискайте кратки и директни отговори. Ако Вашето приложение работи на един език, посочете кой е той, иначе агентът може да превключи, за да съвпадне с акцента на обаждащия се. И му кажете какво да прави, когато не разбира: инструкция като „задайте уточняващ въпрос, вместо да предполагате“ предотвратява грешно чут номер на поръчка да задейства безсмислено търсене. Ръководството за гласови подкани на xAI дори предлага структура от пет части (роля и персона, цел, поток на разговора, ограничения и ескалация, стил на гласа) и препоръчва по една или две кратки изречения на реплика, освен ако обаждащият се не поиска повече детайли.
Откриване на смяна на говорещия (Turn detection)
Блокът turn_detection решава кой говори и кога, а документацията на xAI предоставя само две настройки за него. Първата е type. В режим "server_vad" сървърът самостоятелно откривая края на всяко изречение, фиксира аудиото, стартира отговора и обработва прекъсванията: всичко, което правите, е да изпращате аудио с input_audio_buffer.append. Втората настройка, idle_timeout_ms, е по избор. Ако потребителят остане тих за толкова милисекунди след отговор, сървърът го подканва и прави това отново след всяко ново мълчание със същата продължителност.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Няма праг на чувствителност или продължителност на тишината за настройка. Параметрите threshold, silence_duration_ms и prefix_padding_ms, които ще видите в примери, написани за OpenAI Realtime API, не фигурират в документацията на xAI.
Ако автоматичното поведение не Ви устройва, задайте типа на null и поемете контрола. Тогава е Ваша отговорност да буферизирате аудиото с input_audio_buffer.append, изрично да фиксирате репликата с input_audio_buffer.commit и да задействате генерирането с response.create. Ръчният режим е правилният избор за интерфейс тип „натисни и говори“ (push-to-talk) или когато искате прецизен контрол над момента, в който агентът говори.
Изберете правилния аудио формат
Блокът audio задава входния и изходния формат независимо един от друг:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Приемат се четири типа. Ако не посочите такъв, получавате PCM при 24 000 Hz:
| Type | Encoding | Sample rates |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (North American telephony) | 8000 Hz only |
audio/pcma | G.711 A-law (European telephony) | 8000 Hz only |
audio/opus | Opus, one packet per message | 24000 Hz |
Вашият канал за доставка решава. Уеб приложение в браузър се справя добре с PCM на 24 000 Hz, което е добър баланс между възприеманото качество и честотната лента. Интеграцията със SIP телефон няма избор: мрежата пренася G.711 на 8 000 Hz и налагането на формат с по-високо качество върху него само добавя безсмислено конвертиране.
Осигурете инструменти на агента
Масивът tools изброява какво агентът може да извика по време на разговора и можете да смесвате различни видове в една и съща сесия:
{
"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"]
}
}
]
}
Вие предоставяте кутията с инструменти; агентът избира инструмента. Докато разговорът се развива, той решава, че въпрос относно новините изисква уеб търсене, докато номер на поръчка изисква get_order_status. Следователно Вашата работа е по-малко свързана с оркестрирането на обажданията и повече с ясното описване на всеки инструмент, така че агентът да направи правилния избор.
Ключови изводи
- Съобщението
session.updateконфигурира гласа, инструкциите, VAD и инструментите - Сървърният VAD (
server_vad) открива смени на говорещия и обработва прекъсванията;idle_timeout_msе единствената настройка - Ръчният режим (
turn_detection.type, зададен наnull) Ви осигурява прецизен контрол, например при интерфейс „натисни и говори“ - Аудио форматите PCM, G.711 и Opus покриват както уеб, така и телефонни случаи на употреба
- Можете да промените конфигурацията по средата на сесията, без да прекъсвате връзката