WebSocket multi-contesto
Questa guida mostra come creare agenti vocali in tempo reale usando l’API WebSocket multi-contesto.
L’orchestrazione di agenti vocali tramite questa API WebSocket multi-contesto è un’attività complessa, consigliata agli sviluppatori esperti. Per una soluzione più gestita, scopri il nostro prodotto piattaforma Agents, che semplifica molte di queste sfide.
Panoramica
Per creare agenti vocali reattivi, devi poter gestire dinamicamente i flussi audio, gestire le interruzioni in modo fluido e mantenere un parlato naturale nei vari turni di conversazione. La nostra API WebSocket multi-contesto per Text to Speech (TTS) è progettata specificamente per questi scenari.
Questa API estende la nostra funzionalità WebSocket TTS standard introducendo il concetto di “contesti”. Ogni contesto funziona come un flusso indipendente di generazione audio all’interno di una singola connessione WebSocket. Ciò ti consente di:
- Gestire più linee di parlato contemporaneamente, ad esempio l’agente che parla mentre prepara una risposta a un’interruzione dell’utente.
- Gestire senza interruzioni le sovrapposizioni dell’utente chiudendo un contesto di parlato esistente e avviandone uno nuovo.
- Mantenere la coerenza prosodica per gli enunciati nello stesso contesto logico.
- Ottimizzare l’uso delle risorse chiudendo selettivamente i contesti che non sono più necessari.
L’API WebSocket multi-contesto è ottimizzata per le applicazioni vocali e non è pensata per generare contemporaneamente più flussi audio non correlati. Per questo, ogni connessione è limitata a 5 contesti simultanei.
Questa guida ti accompagnerà nella connessione al WebSocket multi-contesto, nella gestione dei contesti e nell’applicazione delle best practice per creare agenti vocali coinvolgenti.
Best practice
Queste best practice sono essenziali per creare agenti vocali reattivi ed efficienti con la nostra API WebSocket multi-contesto.
Usa una singola connessione WebSocket
Stabilisci una connessione WebSocket per ogni sessione dell’utente finale. In questo modo riduci overhead e latenza rispetto alla creazione di più connessioni. All’interno di questa singola connessione, puoi gestire più contesti per diverse parti della conversazione.
Trasmetti le risposte in blocchi, genera frasi
Quando generi risposte lunghe, trasmetti il testo in blocchi più piccoli e usa il flag flush: true
alla fine delle frasi complete. Questo migliora la qualità dell’audio generato e la reattività.
Gestisci le interruzioni in modo fluido
Trasmetti il testo in un contesto finché non si verifica un’interruzione, quindi crea un nuovo contesto e chiudi quello esistente. Questo approccio garantisce transizioni fluide quando cambia il flusso della conversazione.
Gestisci il ciclo di vita dei contesti
Chiudi tempestivamente i contesti inutilizzati. Il server può mantenere fino a 5 contesti simultanei per connessione, ma dovresti chiuderli quando non sono più necessari.
Evita i timeout dei contesti
Per impostazione predefinita, i contesti vanno in timeout dopo 20 secondi e vengono chiusi automaticamente. Il timeout di inattività è un parametro a livello di websocket che si applica a tutti i contesti e, se necessario, può arrivare a 180 secondi. Invia un messaggio di testo vuoto in un contesto per reimpostare il timer del timeout.
Gestione delle interruzioni
Quando un utente interrompe il tuo agente, dovresti chiudere il contesto corrente e crearne uno nuovo:
Mantenere attivo un contesto
I contesti vanno automaticamente in timeout dopo 20 secondi di inattività per impostazione predefinita. Se devi mantenere attivo un contesto senza generare testo, ad esempio durante un ritardo di elaborazione, puoi inviare un messaggio di testo vuoto per reimpostare il timer del timeout.
Chiusura della connessione WebSocket
Al termine della conversazione, puoi ripulire tutti i contesti chiudendo il socket:
Esempio completo di agente conversazionale
Requisiti
- Un account ElevenLabs con una chiave API (scopri come trovare la tua chiave API).
- Python o Node.js, oppure un altro runtime JavaScript, installato sul tuo computer.
- Familiarità con la comunicazione WebSocket. Ti consigliamo di leggere la nostra guida sullo streaming WebSocket standard per i concetti di base.
Configurazione
Installa le dipendenze necessarie per il linguaggio scelto:
Crea un file .env nella directory del progetto per archiviare la chiave API: