Evenimente server-to-client
Pe această pagină
Mesajele pe care le primiți
Serverul trimite numeroase evenimente pentru a vă menține informat cu privire la starea conversației, pentru a livra audio-ul de răspuns și pentru a raporta erorile. Înțelegerea acestor evenimente este esențială pentru construirea unei aplicații reactive și fiabile.
Evenimente de sesiune și conversație
Aceste evenimente sosesc la stabilirea conexiunii și după fiecare modificare de configurație:
session.created: sesiunea este deschisă; evenimentul conține configurația sesiuniisession.updated: configurația a fost actualizată cu succesconversation.created: canalul de conversație este configurat
Evenimente ale buffer-ului audio
Aceste evenimente vă informează despre activitatea vocală detectată de VAD (Voice Activity Detection):
input_audio_buffer.speech_started: VAD detectează că utilizatorul a început să vorbeascăinput_audio_buffer.speech_stopped: VAD detectează sfârșitul vorbiriiinput_audio_buffer.committed: buffer-ul audio a fost confirmat ca mesaj
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Utilizatorul vorbește: afișați un indicator vizual
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Utilizatorul a terminat: ascundeți indicatorul
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Mesajul audio este în curs de procesare
showProcessingIndicator(true);
break;
}
});
Evenimente pentru audio-ul de răspuns
Audio-ul de răspuns este transmis în flux prin două evenimente.
response.output_audio.delta
Fiecare delta conține o porțiune de audio codificată în base64. Colectați-le și redați-le în ordine:
{
"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
Semnalează faptul că tot audio-ul de răspuns a fost trimis:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Evenimente de transcriere
API-ul poate transcrie atât audio-ul utilizatorului, cât și audio-ul de răspuns:
conversation.item.input_audio_transcription.completed: o transcriere a ceea ce a spus utilizatorulresponse.output_audio_transcript.delta: o transcriere în flux a răspunsului agentului
case "conversation.item.input_audio_transcription.completed":
console.log("Utilizatorul a spus:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Evenimente text
Dacă agentul generează text (în plus sau în loc de audio), veți primi:
response.text.delta: un fragment de text transmis în flux
{
"type": "response.text.delta",
"delta": "Comanda dumneavoastră a fost"
}
Evenimente de apelare a funcțiilor
Când agentul decide să apeleze o funcție, sunt emise două evenimente:
response.function_call_arguments.delta: argumentele funcției, transmise în fluxresponse.function_call_arguments.done: apelul complet al funcției cu toate argumentele sale
Lecția 13, despre apelarea funcțiilor vocale, acoperă aceste evenimente în detaliu.
response.done
Acest eveniment marchează sfârșitul complet al unui răspuns. Conține un rezumat al răspunsului, inclusiv statistici de utilizare:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Evenimentul de eroare
Acest eveniment raportează erorile. Conform documentației de referință xAI, majoritatea erorilor sunt recuperabile, iar conexiunea WebSocket rămâne deschisă:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Format audio invalid specificat"
}
}
Aplicația dumneavoastră ar trebui să înregistreze aceste erori și, în funcție de gravitatea lor, să afișeze un mesaj utilizatorului sau să încerce să remedieze problema automat.
Puncte cheie
- Serverul trimite evenimente pentru fiecare etapă: detectarea vocii, audio, transcriere, text și erori
- Audio-ul de răspuns sosește sub formă de porțiuni base64 prin
response.output_audio.delta - Transcrierile sunt disponibile atât pentru intrarea utilizatorului, cât și pentru ieșirea agentului
response.donemarchează sfârșitul unui răspuns complet- Majoritatea erorilor raportate prin evenimentul
errorsunt recuperabile: conexiunea rămâne deschisă