Szerver-kliens események
Ezen az oldalon
A kapott üzenetek
A szerver számos eseményt küld, hogy tájékoztasson a beszélgetés állapotáról, kézbesítse a válaszhangot, és jelentse a hibákat. Ezeknek az eseményeknek a megértése elengedhetetlen egy reagálóképes és megbízható alkalmazás felépítéséhez.
Munkamenet- és beszélgetésesemények
Ezek az események a kapcsolat létrejöttekor, valamint minden konfigurációs módosítás után érkeznek:
session.created: a munkamenet megnyílt; az esemény tartalmazza a munkamenet konfigurációjátsession.updated: a konfiguráció sikeresen frissültconversation.created: a beszélgetési csatorna beállítva
Hangpuffer-események
Ezek az események a VAD (hangaktivitás-észlelés) által észlelt hangtevékenységről tájékoztatnak:
input_audio_buffer.speech_started: a VAD észleli, hogy a felhasználó beszélni kezdettinput_audio_buffer.speech_stopped: a VAD észleli a beszéd végétinput_audio_buffer.committed: a hangpuffer üzenetként véglegesítve
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// A felhasználó beszél: jeleníts meg egy vizuális jelzőt
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// A felhasználó befejezte: tüntesd el a jelzőt
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// A hangüzenet feldolgozás alatt áll
showProcessingIndicator(true);
break;
}
});
Válaszhang-események
A válaszhang két eseményen keresztül streamelődik.
response.output_audio.delta
Minden delta egy base64-kódolt hangdarabkát tartalmaz. Gyűjtsd össze őket, és játszd le sorrendben:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Jelzi, hogy az összes válaszhang elküldésre került:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Átirat-események
Az API képes átírni mind a felhasználó hangját, mind a válaszhangot:
conversation.item.input_audio_transcription.completed: a felhasználó által elmondottak átírataresponse.output_audio_transcript.delta: az ügynök válaszának streamelt átírata
case "conversation.item.input_audio_transcription.completed":
console.log("A felhasználó ezt mondta:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Szöveges események
Ha az ügynök szöveget generál (hang mellett vagy helyett), a következőt kapod:
response.text.delta: egy streamelt szövegrészlet
{
"type": "response.text.delta",
"delta": "A rendelésed"
}
Függvényhívási események
Amikor az ügynök úgy dönt, hogy meghív egy függvényt, két esemény következik be:
response.function_call_arguments.delta: a függvényargumentumok, streamelveresponse.function_call_arguments.done: a teljes függvényhívás az összes argumentumával
A 13. lecke, amely a hangalapú függvényhívást tárgyalja, részletesen kitér ezekre az eseményekre.
response.done
Ez az esemény jelzi egy válasz teljes befejeződését. Összefoglalót tartalmaz a válaszról, beleértve a használati statisztikákat is:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Hibaesemény
Ez az esemény hibákat jelent. Az xAI referenciája szerint a legtöbb hiba helyreállítható, és a WebSocket-kapcsolat nyitva marad:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Érvénytelen hangformátum megadva"
}
}
Az alkalmazásodnak naplóznia kell ezeket a hibákat, és súlyosságuktól függően üzenetet kell megjelenítenie a felhasználónak, vagy automatikusan meg kell próbálnia megoldani a problémát.
Főbb megállapítások
- A szerver minden lépéshez küld eseményeket: hangészlelés, hang, átírás, szöveg és hibák
- A válaszhang base64-darabkákként érkezik a
response.output_audio.deltaeseményen keresztül - Átiratok elérhetők mind a felhasználói bemenethez, mind az ügynök kimenetéhez
- A
response.donejelzi egy teljes válasz végét - A legtöbb, az
erroreseményen keresztül jelentett hiba helyreállítható: a kapcsolat nyitva marad