Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määritä äänistunto

Oppitunti 2 / 14 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Viesti, joka määrittää kaiken: session.update
  2. Kirjoita ohjeet korvalle, ei silmälle
  3. Vuoron tunnistus
  4. Valitse oikea äänimuoto
  5. Anna agentille työkaluja
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech -sivun ja äänikehotteiden oppaan perusteella. Lähteet: Speech to Speech · Prompting Guide.

Viesti, joka määrittää kaiken: session.update

Kun WebSocket-yhteys on avattu, mitään ei vielä tapahdu. session.update-viesti on se, joka antaa agentille sen luonteen: käytettävän äänen, noudatettavat ohjeet, vuoron tunnistustavan ja kutsuttavat työkalut. Ajattele sitä istunnon syntymätodistuksena. Kaikki muu keskustelussa seuraa tästä.

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

Palvelin vahvistaa tämän session.updated-tapahtumalla. Sinun ei tarvitse lähettää tätä viestiä vain kerran. Voit lähettää sen uudelleen keskellä keskustelua muuttaaksesi asetuksia lennosta, esimerkiksi vaihtaaksesi ääntä, kun puhelu siirtyy myynnistä tekniseen tukeen, ilman että yhteyttä katkaistaan.

Kirjoita ohjeet korvalle, ei silmälle

instructions-kenttä toimii järjestelmäkehotteena. Käytä sitä määrittääksesi agentin persoonallisuuden (muodollinen, rento, tekninen), käsiteltävät aiheet, vastauksille asetetut rajoitukset (pituus, muoto, kieli) sekä tarvittavan liiketoimintakontekstin: yrityksesi nimi, tuotevalikoima ja sisäiset menettelytavat.

Ongelmana on, että mikä toimii hyvin kirjallisena kehotteena, toimii usein huonosti ääniagenttina. Yksin jätettynä malli kirjoittaa kymmenen rivin vastauksia. Ääneen luettuina ne venyvät, ja käyttäjä kyllästyy ennen loppua. Pyydä siis nimenomaisesti lyhyitä ja suoria vastauksia. Jos sovelluksesi toimii yhdellä kielellä, määritä se, muuten agentti saattaa vaihtaa kieltä soittajan aksentin mukaan. Kerro myös, mitä sen tulee tehdä, jos se ei ymmärrä: ohje kuten “kysy tarkentava kysymys arvaamisen sijaan” estää väärin kuultua tilausnumeroa laukaisemasta turhaa hakua. xAI:n äänikehotteiden opas ehdottaa jopa viisiosaista rakennetta (rooli ja persoona, tavoite, keskustelun kulku, suojaukset ja eskalointi, äänityyli) ja suosittelee yhtä tai kahta lyhyttä lausetta per vuoro, ellei soittaja pyydä lisätietoja.

Vuoron tunnistus

turn_detection-lohko päättää, kuka puhuu ja milloin, ja xAI:n dokumentaatio tarjoaa siihen vain kaksi asetusta. Ensimmäinen on type. Tilassa "server_vad" palvelin havaitsee jokaisen puheenvuoron lopun itse, sitoo äänen, aloittaa vastauksen ja hallitsee keskeytykset: sinun tehtäväsi on vain lähettää ääntä käyttämällä input_audio_buffer.append. Toinen asetus, idle_timeout_ms, on valinnainen. Jos käyttäjä pysyy hiljaa tämän millisekuntimäärän vastauksen jälkeen, palvelin kehottaa häntä puhumaan, ja tekee niin uudelleen jokaisen samanpituisen hiljaisuuden jälkeen.

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

Herkkyyskynnystä tai hiljaisuuden kestoa ei voi säätää. Parametreja threshold, silence_duration_ms ja prefix_padding_ms, jotka näet OpenAI Realtime API:lle kirjoitetuissa esimerkeissä, ei esiinny xAI:n dokumentaatiossa.

Jos automaattinen toiminta ei sovi tarpeisiisi, aseta tyypiksi null ja ota ohjat itseesi. Tällöin sinun tehtäväsi on puskuroida ääni komennolla input_audio_buffer.append, sitoa vuoro nimenomaisesti komennolla input_audio_buffer.commit ja käynnistää generointi komennolla response.create. Manuaalinen tila on oikea valinta paina-puhu-liittymälle tai aina, kun haluat tarkan kontrollin siitä, milloin agentti puhuu.

Valitse oikea äänimuoto

audio-lohko määrittää syöte- ja tulostemuodot toisistaan riippumatta:

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

Hyväksyttyjä tyyppejä on neljä. Jos et määritä tyyppiä, saat PCM-muodon taajuudella 24 000 Hz:

TyyppiKoodausNäytetaajuudet
audio/pcmPCM Linear16, little-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (pohjoisamerikkalainen telefonia)Vain 8000 Hz
audio/pcmaG.711 A-law (eurooppalainen telefonia)Vain 8000 Hz
audio/opusOpus, yksi paketti per viesti24000 Hz

Jakelukanavasi ratkaisee valinnan. Selaimessa toimiva verkkosovellus pärjää hyvin 24 000 Hz PCM-muodolla, joka on hyvä tasapaino koetun laadun ja kaistanleveyden välillä. SIP-puhelinintegraatiolla ei ole vaihtoehtoja: verkko kuljettaa G.711-muotoa taajuudella 8 000 Hz, ja korkealaatuisemman muodon pakottaminen siihen aiheuttaa vain turhaa muunnosta.

Anna agentille työkaluja

tools-taulukko luettelee työkalut, joita agentti saa kutsua keskustelun aikana, ja voit sekoittaa eri tyyppejä samassa istunnossa:

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

Sinä tarjoat työkalupakin; agentti valitsee työkalun. Keskustelun edetessä se päättää, että uutisia koskeva kysymys vaatii verkkohakua, kun taas tilausnumero vaatii get_order_status-funktiota. Tehtäväsi ei siis ole niinkään orkestroida kutsuja kuin kuvata jokainen työkalu selkeästi, jotta agentti tekee oikean valinnan.

Keskeiset asiat

  • session.update-viesti määrittää äänen, ohjeet, VAD:n ja työkalut
  • Palvelinpohjainen VAD (server_vad) tunnistaa vuorot ja hallitsee keskeytykset; idle_timeout_ms on ainoa säädettävä asetus
  • Manuaalinen tila (turn_detection.type asetettu arvoon null) antaa tarkan kontrollin, esimerkiksi paina-puhu-käyttöliittymissä
  • PCM-, G.711- ja Opus-äänimuodot kattavat sekä web- että telekäyttötapaukset
  • Voit muuttaa kokoonpanoa kesken istunnon katkaisematta yhteyttä