Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Máistreacht ar imeachtaí WebSocket

Ceacht 4 as 14 Nuashonraithe 29 Iúil 2026 Meánleibhéal
Ar an leathanach seo
  1. Comhrá déanta d’imeachtaí JSON
  2. Cad a sheolann do aip
  3. Cad a sheolann an freastalaí ar ais
  4. Creatlach cliant
  5. An chuid dheacair: bristeachí
  6. Príomhphointí

Comhrá déanta d’imeachtaí JSON

Faoi chochall, ní mhalartú gutha leis an nGníomhaire Gutha ach sruth teachtaireachtaí JSON a shreabhann an dá bhealach thar an nasc WebSocket. Tá réimse type i ngach teachtaireacht a léiríonn cad é. Go dtí go mbeidh an stór focal seo ar eolas agat, oibreoidh do chliant de réir seans. Nuair a bheidh, beidh a fhios agat go beacht cá háit le cur isteach chun freagra a ghearradh, tras-scríbhinn a thaispeáint, nó teacht slán ó earráid.

Tá imeachtaí roinnte ina dhá fhine, ag brath ar an treo a thaistealaíonn siad. Tiomáineann na cinn a sheolann tú an seisiún; insíonn na cinn a fhaigheann tú cad atá ar siúl ar an bhfreastalaí.

Cad a sheolann do aip

Clúdaíonn do theachtaireachtaí amach ceithre riachtanas: an seisiún a chumrú, an maolán fuaime a bheathú, stair an chomhrá a bhainistiú, agus giniúint freagartha a rialú.

ImeachtCuspóir
session.updateCumraíonn nó athchumraíonn sé an seisiún (guth, treoracha, uirlisí, VAD, formáid fuaime)
input_audio_buffer.appendSeolann sé smután fuaime ionchódaithe base64, go leanúnach agus an t-úsáideoir ag caint
input_audio_buffer.commitDeimhníonn sé inneachar reatha an mhaoláin mar theachtaireacht an úsáideora; ní gá ach i mód láimhe
input_audio_buffer.clearFolmhaíonn sé an maolán fuaime gan é a phróiseáil
conversation.item.createCuireann sé mír leis an gcomhrá: teachtaireacht téacs, stair níos luaithe, nó toradh glao feidhme
conversation.item.deleteScriosann sé mír comhrá de réir a aitheantais
response.createIarrann sé ar an tsamhail freagra a ghiniúint; uathoibríoch i mód VAD, sainráite i mód láimhe
response.cancelCealaíonn sé freagra atá á ghiniúint

Tá dhá theachtaireacht díobh seo tuillte ag breathnú níos géire. Is é conversation.item.create an bealach chun comhthéacs a instealladh: is é seo a úsáideann tú chun stair glao níos luaithe a athbhunú ag tús seisiúin nua. Maidir le input_audio_buffer.clear, tagann sé i gcabhair nuair nach ndúirt an t-úsáideoir go soiléir aon rud fiú próiseáil (casacht bheag arna gabháil ag micreafón ró-íogair) agus is fearr leat tosú arís ó mhaolán glan ná ligean don tsamhail torann a léirmhíniú.

Cad a sheolann an freastalaí ar ais

Tá an sruth isteach níos gnóthaí, toisc go dtugann sé trácht reatha ar gach céim próiseála.

ImeachtBrí
session.createdTá an seisiún oscailte
session.updatedTá nuashonrú cumraíochta curtha i bhfeidhm
conversation.createdTá an comhrá socraithe suas
input_audio_buffer.speech_startedBrathann VAD go bhfuil an t-úsáideoir tar éis tosú ag caint
input_audio_buffer.speech_stoppedBrathann VAD go bhfuil an t-úsáideoir tar éis stopadh ag caint
input_audio_buffer.committedTá an maolán fuaime deimhnithe, ag VAD nó de láimh
response.createdTá freagra á ghiniúint
response.output_audio.deltaSmután d’fhreagra fuaime, i base64
response.output_audio.doneTá an fhreagra fuaime críochnaithe
response.output_audio_transcript.deltaTras-scríbhinn téacs na fuaime, á sruthú
response.doneTá an fhreagra críochnaithe go hiomlán
conversation.item.input_audio_transcription.completedTá tras-scríbhinn theachtaireacht an úsáideora ar fáil
response.text.deltaTéacs sruthaithe, le haghaidh freagraí neamh-ghutha
response.function_call_arguments.deltaArgóintí glao feidhme, á sruthú
response.function_call_arguments.doneTá an glao feidhme críochnaithe agus réidh le rith
errorTharla earráid; is féidir formhór na n-earráidí a shárú

Teastaíonn focal rabhaidh faoin gceann deireanach sin. Ní chiallaíonn fáil error go bhfuil an seisiún caillte. De réir tagairt xAI, is féidir formhór na n-earráidí a shárú agus fanann an seisiún oscailte, mar sin briseann cliant a dhúnann an nasc ag an gcéad error comhrá a d’fhéadfadh leanúint ar aghaidh. Logáil é, inis don úsáideoir más gá, ach coinnigh an soicéad oscailte.

Creatlach cliant

Go praiticiúil, tagann gach rud anuas ar lasc ar msg.type. Seo an chruth íosta de chliant JavaScript:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Seol session.update leis an gcumraíocht
      break;

    case "input_audio_buffer.speech_started":
      // Tá an t-úsáideoir ag caint: stop an fhreagra fuaime atá á seinm
      break;

    case "response.output_audio.delta":
      // Dí-chódaigh an base64 agus seinm an fhuaime
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Rith an fheidhm agus seol an toradh ar ais
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Earráid Gníomhaire Gutha:", msg.error);
      break;
  }
};

Tá ceithre chraobh leordhóthanach chun gníomhaire a rith: cumraigh nuair a osclaítear an seisiún, freagair nuair a thosaíonn an t-úsáideoir ag caint, seinm fuaime istigh, agus rith feidhmeanna. Saibhríonn na himeachtaí eile an comhéadan agus is féidir fanacht leo don dara leagan.

An chuid dheacair: bristeachí

Is é an barge-in, nuair a thosaíonn an t-úsáideoir ag caint agus an gníomhaire fós ag freagairt, an áit a léiríonn cur chun feidhme míshláintiúil é. Cealaíonn an freastalaí an fhreagra reatha leis féin agus tosaíonn sé ceann nua a ghiniúint ón méid a chuala sé díreach. Ach cé go bhfuil an freastalaí tar éis stopadh ag seoladh, tá roinnt soicind d’fhuaime a fuarthas cheana féin ag do aip fós ina mhaolán aschuir.

Mura ndéanann tú aon rud, leanfaidh an t-úsáideoir ag cloisteáil na habairte a bhris siad díreach agus iad ag caint thairis air, agus feicfear nach bhfuil an gníomhaire ag éisteacht. Mar sin, chomh luath agus a fhaigheann tú speech_started, stop an fhuaime atá á seinm, sruthlaigh an maolán aschuir ionas nach seinmfear fuaim sheanbhainte, agus lig don fhreastalaí an t-ionchur nua a phróiseáil. Tógann an dá chéim sin cúpla líne cód agus déanann siad an difríocht uile idir gníomhaire is féidir leat a bhriseadh isteach agus ceann a labhraíonn isteach sa bhfolús.

Príomhphointí

  • Clúdaíonn imeachtaí cliant cumraíocht, seoladh fuaime, bainistiú an chomhrá, agus rialú freagraí
  • Tuairiscíonn imeachtaí freastalaí brath cainte, smutáin fuaime, tras-scríbhinní, agus glaonna feidhme
  • Láimhseálann VAD bristeachí (barge-in) go huathoibríoch
  • Is féidir formhór na n-imeachtaí error a shárú: ná dún an nasc, láimhseáil an earráid
  • I mód láimhe, ní mór duit commit a ghlaow agus ansin response.create go sainráite