Trascrizioni e strategie di commit
Guida pratica · Presuppone che tu abbia completato la guida sullo streaming lato client o sullo streaming lato server.
Panoramica
Durante la trascrizione dell’audio, riceverai trascrizioni parziali e confermate.
- Trascrizioni parziali - i risultati intermedi della trascrizione
- Trascrizioni confermate - i risultati finali del segmento di trascrizione inviati alla ricezione di un messaggio “commit”. Una sessione può avere più trascrizioni confermate.
La trascrizione confermata può facoltativamente contenere timestamp a livello di parola. Viene ricevuta soltanto quando l’opzione “include timestamps” è impostata su true.
Strategie di commit
Quando invii chunk audio tramite WebSocket, i segmenti di trascrizione possono essere confermati in tre modi: commit manuale, rilevamento dell’attività vocale (VAD) o previsione del turno. La previsione del turno è disponibile soltanto con Scribe v3 Live.
Commit manuale
Con la strategia di commit manuale, controlli quando confermare i segmenti di trascrizione. È la strategia usata per impostazione predefinita. La conferma di un segmento cancella la trascrizione accumulata elaborata e avvia un nuovo segmento senza perdere il contesto. Per migliorare la latenza, è buona pratica confermare ogni 20-30 secondi. Anche se non esegui il commit manualmente, il modello conferma automaticamente dopo circa 36 secondi di audio accumulato.
Per risultati ottimali, esegui il commit durante i periodi di silenzio o in un altro punto logico, come un cambio di turno.
Eseguire manualmente il commit più volte in una breve sequenza può ridurre le prestazioni del modello.
Invio del contesto testuale precedente
Quando invii audio per la trascrizione, puoi inviare il contesto testuale precedente insieme al primo chunk audio per aiutare il modello a comprendere il contesto del parlato. È utile in alcuni scenari:
- Testo dell’agente per casi d’uso di IA conversazionale - Consente al modello di comprendere più facilmente il contesto della conversazione e produrre trascrizioni migliori.
- Riconnessione dopo un errore di rete - Consente al modello di continuare a trascrivere, usando il testo precedente come riferimento.
- Informazioni contestuali generali - Una breve descrizione dell’argomento della trascrizione aiuta il modello a comprendere il contesto.
L’invio del contesto previous_text è possibile soltanto quando invii il primo chunk audio tramite
connection.send(). Inviarlo nei chunk successivi genera un errore. Il testo precedente funziona
meglio se è lungo meno di 50 caratteri.
Rilevamento dell’attività vocale (VAD)
Con la strategia VAD, il motore di trascrizione rileva automaticamente i segmenti di parlato e silenzio. Quando viene raggiunta una soglia di silenzio, il motore di trascrizione conferma automaticamente il segmento di trascrizione.
Quando trascrivi l’audio dal microfono nell’integrazione lato client, è consigliabile usare la strategia VAD.
vad_silence_threshold_secs accetta valori da 0.192 a 3.0 secondi. Gli SDK JavaScript e React accettano soltanto valori da 0.3 a 3.0.
Previsione del turno
La previsione del turno è disponibile soltanto con Scribe v3 Live
(scribe_v3_live). Gli altri modelli rifiutano commit_strategy=turn_prediction con un errore
invalid_request e chiudono la connessione.
Una breve soglia di silenzio VAD può interrompere i parlanti quando fanno una pausa, mentre una soglia lunga aggiunge ritardo prima di ogni commit. La previsione del turno usa il contesto della conversazione, non soltanto il silenzio, per stimare se il parlante ha terminato il proprio turno. È meno probabile che venga interrotto un chiamante che fa una pausa a metà della lettura di un numero di telefono.
Scribe v3 Live include turn_probability, la probabilità stimata che il parlante abbia terminato il proprio turno, in ogni messaggio partial_transcript:
Con commit_strategy=turn_prediction, il server conferma il segmento corrente quando una trascrizione parziale raggiunge un valore turn_probability pari o superiore a 0.9. Il VAD rimane attivo, quindi il server conferma anche quando viene raggiunta la soglia di silenzio vad_silence_threshold_secs. I parametri VAD (vad_silence_threshold_secs, vad_threshold, min_speech_duration_ms e min_silence_duration_ms) si applicano alla previsione del turno nello stesso modo in cui si applicano al VAD.
La strategia di commit predefinita è manual per ogni modello, incluso Scribe v3 Live. Imposta esplicitamente commit_strategy=turn_prediction per abilitare la previsione del turno.
Gli enum CommitStrategy negli SDK Python e JavaScript non includono ancora turn_prediction.
Per usare la previsione del turno, connettiti direttamente all’API WebSocket e imposta il parametro query.
turn_probability viene inviato con ogni strategia di commit quando il modello è Scribe v3 Live. Con la strategia manual, puoi leggerlo per decidere quando eseguire il commit nella tua applicazione.
Filtrare l’audio di sottofondo
Imposta il parametro query filter_background_audio=true per ridurre le attivazioni errate causate dal parlato di sottofondo, come conversazioni nelle vicinanze, e dal rumore ambientale. Con il filtro abilitato, il rilevamento dell’attività vocale usa un modello ottimizzato per ignorare il parlato di sottofondo e vad_threshold assume per impostazione predefinita il valore 0.15, a meno che tu non lo imposti diversamente.
filter_background_audio non può essere combinato con include_timestamps. Se li imposti entrambi, il server
invia un errore invalid_request e chiude la connessione.
Il filtro non modifica la fatturazione: viene fatturato tutto l’audio che trasmetti, incluso quello ignorato dal filtro.
Mantenere attiva la connessione durante il silenzio
Gli SDK ufficiali non interrompono la connessione quando non arrivano messaggi, quindi la maggior parte delle integrazioni non ne ha bisogno. Se il tuo client WebSocket, oppure un proxy o un load balancer intermedio, chiude la connessione quando per un certo periodo non arrivano frame, passa il parametro query facoltativo keepalive_interval_ms durante la connessione. È importante durante lunghi periodi di silenzio, ad esempio una telefonata con pause di 10-15 secondi. Circa una volta per intervallo, il server invia un partial_transcript keepalive: vuoto (text: "") se il segmento corrente non contiene testo non confermato, oppure una ripetizione dell’ultimo testo parziale se lo contiene.
I keepalive non sono ping a esecuzione continua: devi continuare a trasmettere audio (vanno bene i frame di silenzio). Se smetti di inviare audio, non vengono inviati keepalive e il server chiude la connessione dopo 15 secondi senza messaggi del client. Questo limite del server non è configurabile.
- Accetta un numero intero tra
500e10000(millisecondi). È disabilitato per impostazione predefinita; ometti il parametro per mantenere il comportamento esistente. - I valori fuori intervallo o non interi fanno sì che il server invii un errore
invalid_requeste chiuda la connessione. - I keepalive dipendono dal fatto che il modello elabori effettivamente l’audio silenzioso inviato, non da un timer a esecuzione continua, quindi confermano anche che il percorso di trascrizione è attivo.
- L’audio viene elaborato in chunk di circa 1 secondo, quindi i keepalive arrivano approssimativamente una volta per intervallo arrotondato a questa cadenza (ad esempio,
1000si attiva circa una volta al secondo,3000circa una volta ogni 3 secondi). Il primo keepalive di una sessione arriva circa 2 secondi dopo l’avvio, poiché il server memorizza nel buffer i primi ~2 secondi di audio prima di trascrivere. Imposta l’intervallo a non più di circa un terzo del timeout di lettura per lasciare un margine. - Il
textdi un keepalive è vuoto soltanto quando il segmento corrente non contiene ancora testo non confermato. Se si verifica una pausa dopo il parlato ma prima di un commit — più evidente confilter_background_audio=trueo in modalità di commit manuale senza eseguire il commit — il keepalive ripete invece l’ultimo testo parziale, quindi non cancella mai il testo intermedio. Dopo un commit, i keepalive tornano vuoti finché non arriva nuovo parlato. - Funziona sia con
commit_strategy=manualsia concommit_strategy=vad, e confilter_background_audio=true. Non ha alcun impatto sulla fatturazione oltre all’audio che stai già trasmettendo. - Il
configdel messaggiosession_startedrestituiscekeepalive_interval_ms(nullquando è disabilitato).
Un partial_transcript vuoto (text: "") significa “nessun parlato nel segmento corrente”. Anche un
partial_transcript ripetuto e identico durante una pausa è un keepalive: i client devono semplicemente visualizzare
i parziali come già fanno, anziché gestire la ripetizione come caso speciale.
Aggiungi il parametro all’URL WebSocket:
Formati audio supportati
Best practice
Qualità audio
- Per risultati ottimali, usa una frequenza di campionamento di 16 kHz per un equilibrio ottimale tra qualità e larghezza di banda.
- Assicurati che l’input audio sia pulito e con rumore di fondo minimo.
- Usa un guadagno del microfono appropriato per evitare il clipping.
- Al momento è supportato soltanto l’audio mono.
Dimensione dei chunk
- Invia chunk audio da 0,1 a 1 secondo per uno streaming fluido.
- I chunk più piccoli riducono la latenza, ma aumentano l’overhead.
- I chunk più grandi sono più efficienti, ma possono introdurre latenza.