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

VAD: puheen automaattinen havaitseminen

Oppitunti 6 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miten vuoron havaitseminen toimii
  2. Kaksi tilaa, yksi kenttä
  3. VAD-tapahtumat
  4. Kehota hiljaista käyttäjää: idle_timeout_ms
  5. Manuaalinen tila: turn_detection.type asetettu arvoon null
  6. Valitse tilasi
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech -sivun ja Voice API -viitteen perusteella: vuoron havaitseminen määritetään kohdassa turn_detection.type ("server_vad" tai null) ja valinnaisesti kohdassa turn_detection.idle_timeout_ms. Lähteet: Speech to Speech · Voice API.

Miten vuoron havaitseminen toimii

Äänikeskustelussa järjestelmän on tiedettävä, milloin käyttäjä alkaa puhua ja milloin hän lopettaa. Tämä on VAD:n (voice activity detection, puheen aktiivisuuden havaitseminen) tehtävä. xAI Voice Agent API tarjoaa palvelinpuoleisen VAD:n, server_vad: palvelin analysoi äänivirtaa, tunnistaa jokaisen puheenvuoron lopun ja käynnistää vastauksen itse.

Kaksi tilaa, yksi kenttä

Valitset tilan session.update-objektin turn_detection-kentässä:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad" }
  }
}
turn_detection.typeKuka päättää vuoron lopunMitä lähetät
"server_vad"Palvelininput_audio_buffer.append, ei muuta
nullSinäinput_audio_buffer.append, sitten input_audio_buffer.commit ja response.create

server_vad-tilassa palvelin jakaa vuorot, sitoo äänen ja käynnistää vastauksen. Keskeytykset hoidetaan myös automaattisesti: xAI suosittelee tätä tilaa luontevaan vuorotteluun, kun käyttäjä keskeyttää agentin lauseen keskellä. Dokumentaatiossa ei kuitenkaan ole tarjolla herkkyyden tai hiljaisuuden keston asetuksia: vuorojen jakaminen on palvelinpuolen asia.

VAD-tapahtumat

server_vad-tilassa palvelin raportoi jokaisen tilanmuutoksen:

  • input_audio_buffer.speech_started: VAD havaitsi puheen alun;
  • input_audio_buffer.speech_stopped: se havaitsi puheen lopun;
  • input_audio_buffer.committed: ääni sidottiin käyttäjän viestiksi.
ws.on("message", (data) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case "input_audio_buffer.speech_started":
      stopPlayback();       // käyttäjä puhuu: pysäytä jo vastaanotettu agentin ääni
      break;
    case "input_audio_buffer.speech_stopped":
      showThinking();       // puheen loppu havaittu: vastaus on tulossa
      break;
  }
});

Palvelinpuolella keskeytys on automaattinen; asiakaspuolella jo vastaanotettu ääni jatkaisi toistoa, ellei sitä pysäytettäisi. speech_started on oikea hetki tyhjentää toistojono.

Kehota hiljaista käyttäjää: idle_timeout_ms

Ainoa dokumentoitu VAD-asetus, idle_timeout_ms, saa agentin jatkamaan keskustelua, kun käyttäjä vaikenee vastauksen jälkeen:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
  }
}

Jos puhetta ei havaita tämän ajan kuluessa vastauksen päättymisestä, palvelin lähettää tapahtuman input_audio_buffer.timeout_triggered, sitoo hiljaisen käyttäjävuoron ja generoi tarkistuskysymyksen. Ajastin nollautuu jokaisen vastauksen jälkeen, joten se laukeaa uudelleen joka idle_timeout_ms niin kauan kuin käyttäjä ei sano mitään. Oletusarvoisesti se on pois päältä (null). Puhelinvaihteessa muutaman sekunnin välein tehtävä tarkistus estää hiljaisuuden venymisen; kirjoita ohjeisiisi seurantalause, jota agentin tulee käyttää.

Manuaalinen tila: turn_detection.type asetettu arvoon null

Push-to-talk-käyttöliittymää varten tai aina kun haluat päättää itse vuoron lopun, aseta tyypiksi null:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": null }
  }
}

Lähetät sitten ääntä komennolla input_audio_buffer.append, ja kun käyttäjä vapauttaa painikkeen, lähetät input_audio_buffer.commit sitoaaksesi vuoron ja response.create pyytääksesi vastausta. input_audio_buffer.commit on käytettävissä vain manuaalisessa tilassa. input_audio_buffer.clear hylkää lähetetyn mutta vielä sitomattoman äänen, ja response.cancel pysäyttää käynnissä olevan vastauksen, sillä keskeytys ei ole enää automaattinen manuaalisessa tilassa.

Valitse tilasi

  • Vapaasti virtaava keskustelu (avustaja, puhelinvaihde, kioski): server_vad, käytä tarvittaessa idle_timeout_ms:ää kehottaaksesi hiljaisia käyttäjiä
  • Puheradio, sanelu, erittäin meluisat ympäristöt: manuaalinen tila, jossa vuoron loppu seuraa painiketta eikä taustamelu laukaise mitään

Keskeiset asiat

  • turn_detection.type on joko "server_vad" (palvelin jakaa vuorot ja hoitaa keskeytykset) tai null (manuaalinen tila)
  • xAI:n dokumentaatio ei tarjoa herkkyyden kynnysarvoa tai hiljaisuuden kestoa säädettäväksi
  • speech_started, speech_stopped ja committed raportoivat VAD-tilanmuutoksista
  • idle_timeout_ms kehottaa hiljaista käyttäjää tapahtuman input_audio_buffer.timeout_triggered kautta
  • Manuaalisessa tilassa: append, sitten commit ja response.create