Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Häälesezansi konfigureerimine

Õppetund 2 / 14 Värskendatud 3. november 2026 Kesktase
Sellel lehel
  1. Sõnum, mis määrab kõik: session.update
  2. Kirjuta juhised kõrva, mitte silma jaoks
  3. Kõnevoorude tuvastamine
  4. Vali õige helivorming
  5. Anna agendile tööriistu
  6. Peamised punktid

Uuendatud 3. novembril 2026, tuginedes xAI Speech to Speech lehele ja häälekäskluste juhendile. Allikad: Speech to Speech · Prompting Guide.

Sõnum, mis määrab kõik: session.update

Kui WebSocketi ühendus on avatud, ei juhtu veel midagi. Sõnum session.update on see, mis annab agendile iseloomu: hääl, mida ta kasutab, juhised, mida ta järgib, kõnevoorude tuvastamise viis ja tööriistad, mida ta võib kutsuda. Mõtle sellele kui seansi sünnitunnistusele. Kõik muu vestluses tuleneb sellest.

{
  "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 kinnitab seda sündmusega session.updated. Sa ei pea seda sõnumit saatma ainult üks kord. Saad seda saata uuesti vestluse käigus, et muuta seadet lennult, näiteks vahetada häält, kui kõne liigub müügilt tehnilisele toele, ilma ühendust katkestamata.

Kirjuta juhised kõrva, mitte silma jaoks

Väli instructions täidab süsteemikäskluse rolli. Kasuta seda agendi isiksuse määramiseks (formaalne, vaba, tehniline), teemade jaoks, mida ta võib käsitleda, vastuste piiranguteks (pikkus, vorming, keel) ja ärikontekstiks, mida ta vajab: sinu ettevõtte nimi, tootevalik ja sisemised protseduurid.

Konks on selles, et see, mis teeb kirjaliku käskluse heaks, teeb hääleagendi sageli halvaks. Omapead jäetuna kirjutab mudel kümne reagi pikkuseid vastuseid. Ette loetuna venivad need ja kasutaja kaotab tähelepanu enne lõppu. Seega küsi otseselt lühikesi ja otsekoheseid vastuseid. Kui sinu rakendus töötab ühes keeles, ütle, millises, vastasel juhul võib agent vahetada keelt, et sobituda helistaja aktsendiga. Ja ütle talle, mida teha, kui ta aru ei saa: juhised nagu „küsi täpsustav küsimus selle asemel, et arvata“ hoiavad ära valesti kuuldud tellimuse numbri põhjustatud mõttetu otsingu. xAI häälekäskluste juhend soovitab isegi viieosalist struktuuri (roll ja isiksus, eesmärk, vestluse voog, piirangud ja eskaleerimine, hääle stiil) ning soovitab ühe või kahe lühikese lause kasutamist vooru kohta, välja arvatud juhul, kui helistaja küsib rohkem detaile.

Kõnevoorude tuvastamine

Plokk turn_detection otsustab, kes räägib ja millal, ning xAI dokumentatsioon pakub selleks ainult kahte seadet. Esimene on type. Režiimis "server_vad" tuvastab server iga ütluse lõpu ise, fikseerib heli, alustab vastust ja haldab katkestusi: sinu ülesandeks on ainult saata heli käsuga input_audio_buffer.append. Teine säte, idle_timeout_ms, on valikuline. Kui kasutaja püsib vaikuses nii palju millisekundeid pärast vastust, küsib server temalt uuesti ja teeb seda iga sama pikkuse vaikuse järel.

{
  "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}

Tundlikkuse lävendit ega vaikuse kestust pole võimalik häälestada. Parameetreid threshold, silence_duration_ms ja prefix_padding_ms, mida näed OpenAI Realtime API jaoks kirjutatud näidetes, xAI dokumentatsioonis ei esine.

Kui automaatne käitumine ei sobi, määra tüübiks null ja võta kontroll enda kätte. Seejärel on sinu ülesanne puhverdada heli käsuga input_audio_buffer.append, fikseerida voor otseselt käsuga input_audio_buffer.commit ja käivitada genereerimine käsuga response.create. Manuaalne režiim on õige valik vajuta-et-rääkida (push-to-talk) liidese jaoks või igal juhul, kui soovid täpset kontrolli selle üle, millal agent räägib.

Vali õige helivorming

Plokk audio määrab sisendi ja väljundi vormingud sõltumatult:

{
  "audio": {
    "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
    "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
  }
}

Aktsepteeritakse nelja tüüpi. Kui sa ühtegi ei määra, saad PCM-i sagedusega 24 000 Hz:

TüüpKodeeringDiskreetimissagedused
audio/pcmPCM Linear16, väike-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (Põhja-Ameerika telefonside)Ainult 8000 Hz
audio/pcmaG.711 A-law (Euroopa telefonside)Ainult 8000 Hz
audio/opusOpus, üks pakett sõnumi kohta24000 Hz

Sinu edastuskanal otsustab. Veebirakendus brauseris saab hästi hakkama 24 000 Hz PCM-iga, mis on hea tasakaal tajutava kvaliteedi ja ribalaiuse vahel. SIP-telefoni integratsioonil pole valikut: võrk edastab G.711 sagedusega 8000 Hz ja kõrgema kvaliteediga vormingu pealesurumine lisab ainult mõttetu teisenduse.

Anna agendile tööriistu

Massiiv tools loetleb, mida agent võib vestluse ajal kutsuda, ja saad samas seansis segada erinevaid liike:

{
  "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"]
      }
    }
  ]
}

Sina pakud tööriistakasti; agent valib tööriista. Vestluse arenedes otsustab ta, et uudiste kohta käiv küsimus nõuab veebiotsingut, samas kui tellimuse number nõuab get_order_status kasutamist. Seega on sinu töö vähem kõnede orkestreerimine ja rohkem iga tööriista selge kirjeldamine, et agent teeks õige valiku.

Peamised punktid

  • Sõnum session.update konfigureerib hääle, juhised, VAD-i ja tööriistad
  • Serveripoolne VAD (server_vad) tuvastab voorud ja haldab katkestusi; idle_timeout_ms on ainus säte
  • Manuaalne režiim (turn_detection.type väärtusega null) annab täpse kontrolli, näiteks vajuta-et-rääkida korral
  • PCM, G.711 ja Opus helivormingud katavad nii veebi kui ka telefonside kasutusjuhtumeid
  • Saad muuta konfiguratsiooni seansi keskel, ilma ühendust katkestamata