Impara

Crea un agente vocale con Pipecat e Cartesia

Rene 
Crea un agente vocale con Pipecat e Cartesia

Pipecat è un framework Python open source per agenti vocali in tempo reale. Cartesia fornisce servizi vocali integrati: Sonic per la sintesi vocale in streaming e Ink per la trascrizione. In questa guida eseguirai nel browser un agente vocale con entrambi i servizi, poi userai le previsioni anticipate di fine turno di Ink per togliere circa mezzo secondo a ogni risposta.

L’intera configurazione richiede la clonazione del repository e due variabili d’ambiente. L’agente risultante ascolta, decide quando hai finito di parlare, pensa e risponde ad alta voce.

Panoramica

Un agente vocale Pipecat è una sequenza di processori. L’audio entra tramite un trasporto, viene trascritto, passa attraverso un LLM ed esce come parlato:

transport.input() → STT → LLM → TTS → transport.output()

Due passaggi decidono se la conversazione sembra umana o uno scambio al walkie-talkie: sapere quando l’utente ha davvero finito di parlare e pronunciare presto la risposta. Qui entrano in gioco i servizi Cartesia. CartesiaTurnsSTTService esegue Ink 2, il modello STT in streaming di Cartesia, e lascia che il server decida quando termina un turno invece di stimarlo localmente. CartesiaTTSService trasmette l’audio Sonic mentre viene generato, con timestamp per parola se necessari.

La documentazione di Pipecat indica un percorso completo tipico tra 500 e 800 millisecondi. I passaggi seguenti servono a dedicare quel tempo al modello anziché ai silenzi.

Prerequisiti

  1. Python 3.11 o successivo. Il README del repository Pipecat indica la versione minima attuale.
  2. Una chiave API Cartesia: creala nella dashboard.
  3. Una chiave API per il LLM che prende le decisioni. L’esempio usa OpenAI (OPENAI_API_KEY); Pipecat include anche servizi per Anthropic, Gemini, Groq, Ollama e altri modelli.

Una limitazione: Ink 2 supporta attualmente solo l’inglese, quindi questo agente ascolta in inglese. Sonic parla oltre 40 lingue, perciò la risposta vocale non è il vincolo.

1. Installa gli extra importati dall’esempio

Il repository Pipecat contiene un agente Cartesia pronto in examples/voice/voice-cartesia-turns.py:

git clone https://github.com/pipecat-ai/pipecat.git
cd pipecat
uv sync --extra cartesia --extra daily --extra websocket --extra runner --extra webrtc

Un semplice uv sync installa il framework, ma non gli extra importati dall’esempio. Il file importa all’inizio i trasporti Daily e FastAPI WebSocket e il runner di Pipecat, anche quando lo esegui con -t webrtc. Questi extra devono quindi essere presenti, altrimenti l’importazione fallisce con No module named 'daily'. cartesia e webrtc sono le parti che usi effettivamente.

Se crei un tuo progetto invece di lavorare nel repository Pipecat, installa lo stesso insieme:

pip install "pipecat-ai[cartesia,daily,websocket,runner,webrtc]"

Poi copia examples/voice/voice-cartesia-turns.py dal repository al progetto. L’esempio richiede CARTESIA_API_KEY e OPENAI_API_KEY; inseriscile in un file .env accanto allo script:

CARTESIA_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here

2. Esegui l’agente

uv run examples/voice/voice-cartesia-turns.py -t webrtc

Il runner avvia un server locale e stampa un URL, per impostazione predefinita http://localhost:7860. Aprilo, consenti l’accesso al microfono e parla. Ecco cosa succede internamente:

  1. Il browser invia il tuo audio tramite WebRTC.
  2. CartesiaTurnsSTTService lo trascrive con Ink 2. Il server osserva i confini dei turni ed emette eventi turn.start, turn.update, turn.eager_end e turn.end.
  3. Il LLM scrive una risposta.
  4. CartesiaTTSService trasmette la risposta con Sonic e il trasporto la riproduce man mano che arriva.

Il passaggio interessante è il secondo. Le vecchie configurazioni aggiungono un rilevatore di attività vocale all’audio e stimano quando finisce una frase. Il rilevamento dei turni di Ink 2 avviene sul server, rendendo possibile il passaggio successivo.

3. Scegli voce e LLM

L’esempio include un ID vocale e un semplice prompt di sistema. Puoi cambiare entrambi:

tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    settings=CartesiaTTSService.Settings(
        voice="86e30c1d-714b-4074-a1f2-1cb6b552fb49",
    ),
)

Scegli una voce nel Playground e incolla qui il suo ID, oppure generane una da un breve campione con la clonazione vocale. Il modello pronuncia il testo, quindi scrivi il prompt per il parlato: l’esempio originale indica al LLM di evitare emoji, elenchi puntati e formattazioni che non si possono sentire.

Se preferisci un modello Sonic specifico, passalo nello stesso oggetto di impostazioni. Il servizio usa attualmente sonic-3.6 per impostazione predefinita.

4. Risparmia mezzo secondo con la fine turno anticipata

Quando termini una frase, Ink prevede che tu abbia finito prima della conclusione tecnica ed emette turn.eager_end. Pipecat espone la previsione come evento on_turn_eager_end(service, transcript), così puoi iniziare subito a generare la risposta e riprendere l’ascolto se l’utente continua:

stt = CartesiaTurnsSTTService(
    api_key=os.environ["CARTESIA_API_KEY"],
    enable_eager_end_of_turn=True,
)

@stt.event_handler("on_turn_eager_end")
async def on_turn_eager_end(service, transcript):
    # Ink predicted the user's turn is ending. Start the LLM now.
    ...

L’opzione enable_eager_end_of_turn=True conta: indica a Pipecat di agire sulla previsione anticipata del server invece di aspettare la fine turno confermata. Pipecat pubblica un esempio di aggregatore utente speculativo che gestisce l’intero ciclo: avvia il LLM sulla previsione e continua ad ascoltare nel caso tu riprenda. La documentazione Cartesia stima un risparmio di circa mezzo secondo, la differenza tra un agente che risponde e uno che aspetta il proprio turno.

Se l’agente interviene mentre stai pensando, regola le soglie invece di disattivare la fine anticipata. I quattro parametri, con i valori predefiniti Cartesia, sono turn_start_threshold (0.8), turn_eager_end_threshold (0.4), turn_end_threshold (0.2) e turn_end_timeout_ms (5600). Un agente paziente aspetta di più prima di scommettere che hai finito: richiede maggiore certezza prima di interrompere. Abbassa la soglia di fine anticipata verso 0.3 e aumenta il timeout verso 8000.

Inserisci i nomi che gli utenti diranno davvero, come nomi di prodotti e termini aziendali, in Settings(keyterm=["Pipecat", "Ink 2"]), per aiutare la trascrizione a riconoscerli.

Prossimi passi

  1. Collega l’agente a un numero telefonico: riesegui lo stesso esempio con -t twilio e un proxy pubblico. Il flusso funziona sulle chiamate senza modifiche.
  2. Se preferisci non gestire il flusso, crea lo stesso agente su Managed Agents, che gestisce telefonia, strumenti e conoscenza.
  3. Ti servono file audio invece di una conversazione dal vivo? La sintesi in batch usa CartesiaHttpTTSService, nello stesso pacchetto.

Documentazione correlata

Domande frequenti

Pipecat supporta Cartesia?

Sì. Cartesia è un servizio integrato nel repository di Pipecat, con un servizio TTS in streaming (CartesiaTTSService) e due servizi STT, incluso CartesiaTurnsSTTService, che esegue Ink 2 e lascia che il server Cartesia determini i confini dei turni. Installa pipecat-ai con l'extra cartesia, oltre agli extra di trasporto e runner importati dal punto di ingresso, e imposta CARTESIA_API_KEY.

Quali modelli usa l'integrazione Cartesia?

Il servizio TTS trasmette Sonic, il modello vocale in tempo reale di Cartesia, e nelle versioni attuali di Pipecat usa sonic-3.6 per impostazione predefinita. Il servizio STT per i turni esegue Ink 2 (ink-2), che rileva i turni sul server ed emette previsioni turn.eager_end. Passa model= in Settings per scegliere una versione diversa di Sonic.

Quanto è veloce un agente vocale Pipecat?

La documentazione di Pipecat indica un percorso completo tipico tra 500 e 800 millisecondi. Puoi accorciare il rilevamento dei turni e la sintesi vocale: la previsione anticipata di Ink può togliere circa mezzo secondo al tempo di risposta, avviandola prima della fine formale del turno dell'utente.

L'agente può gestire chiamate telefoniche?

Sì. Pipecat include trasporti telefonici per Twilio, Exotel e Plivo. Lo stesso flusso funziona al telefono con -t twilio e un proxy pubblico. Se preferisci non gestire il flusso, Cartesia Managed Agents permette di creare senza codice agenti per chiamate in entrata e in uscita.

Devo usare OpenAI per il LLM?

No. L'esempio usa OpenAILLMService perché è breve, ma Pipecat implementa servizi per molti fornitori, tra cui Anthropic, Gemini, Groq e Ollama locale. Sostituisci il servizio nel flusso e mantieni i servizi STT e TTS di Cartesia.