Costruzione della richiesta di Speech-to-Text

Questo documento è una guida alle nozioni di base sull'utilizzo di Speech-to-Text. Questa guida concettuale illustra i tipi di richieste che puoi inviare a Speech-to-Text, come costruirle e come gestirne le risposte. Consigliamo a tutti gli utenti di Speech-to-Text di leggere questa guida e uno dei tutorial associati prima di approfondire l'API stessa.

Provalo

Se non conosci Google Cloud, crea un account per valutare le prestazioni di Speech-to-Text in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti senza addebiti per l'esecuzione, il test e il deployment dei workload.

Prova Speech-to-Text gratuitamente

Richieste di sintesi vocale

Speech-to-Text prevede tre metodi principali per eseguire il riconoscimento vocale. Questi sono elencati di seguito:

  • Il riconoscimento sincrono (REST e gRPC) invia i dati audio all'API Speech-to-Text, esegue il riconoscimento su questi dati e restituisce i risultati dopo che tutto l'audio è stato elaborato. Le richieste di riconoscimento sincrono sono limitate a dati audio di durata pari o inferiore a 1 minuto.

  • Il riconoscimento asincrono (REST e gRPC) invia i dati audio all'API Speech-to-Text e avvia un'operazione di lunga durata. Utilizzando questa operazione, puoi eseguire periodicamente il polling per i risultati del riconoscimento. Utilizza le richieste asincrone per dati audio di qualsiasi durata fino a 480 minuti.

  • Streaming Recognition (solo gRPC) esegue il riconoscimento dei dati audio forniti all'interno di uno stream bidirezionale gRPC. Le richieste di streaming sono progettate per scopi di riconoscimento in tempo reale, ad esempio l'acquisizione di audio dal vivo da un microfono. Il riconoscimento in streaming fornisce risultati provvisori durante l'acquisizione dell'audio, consentendo la visualizzazione dei risultati, ad esempio, mentre un utente sta ancora parlando.

Le richieste contengono parametri di configurazione e dati audio. Le sezioni seguenti descrivono in modo più dettagliato questi tipi di richieste di riconoscimento, le risposte che generano e come gestirle.

Riconoscimento dell'API Speech-to-Text

Una richiesta di riconoscimento sincrono dell'API Speech-to-Text è il metodo più semplice per eseguire il riconoscimento sui dati audio del parlato. Speech-to-Text può elaborare fino a 1 minuto di dati audio del parlato inviati in una richiesta sincrona. Dopo che la funzionalità di Speech-to-Text elabora e riconosce tutto l'audio, restituisce una risposta.

Una richiesta sincrona è bloccante, il che significa che Speech-to-Text deve restituire una risposta prima di elaborare la richiesta successiva. Speech-to-Text in genere elabora l'audio più velocemente del tempo reale, elaborando 30 secondi di audio in 15 secondi in media. In caso di scarsa qualità audio, la richiesta di riconoscimento può richiedere molto più tempo.

Speech-to-Text dispone di metodi REST e gRPC per chiamare richieste sincrone e asincrone dell'API Speech-to-Text. Questo articolo mostra l'API REST perché è più semplice mostrare e spiegare l'utilizzo di base dell'API. Tuttavia, la composizione di base di una richiesta REST o gRPC è piuttosto simile. Le richieste di riconoscimento streaming sono supportate solo da gRPC.

Richieste di riconoscimento vocale sincrono

Una richiesta API Speech-to-Text sincrona è costituita da una configurazione del riconoscimento vocale e da dati audio. Di seguito è riportato un esempio di richiesta:

{
    "config": {
        "encoding": "LINEAR16",
        "sampleRateHertz": 16000,
        "languageCode": "en-US",
    },
    "audio": {
        "uri": "gs://bucket-name/path_to_audio_file"
    }
}

Tutte le richieste di riconoscimento sincrono dell'API Speech-to-Text devono includere un campo di riconoscimento vocale config (di tipo RecognitionConfig). Un RecognitionConfig contiene i seguenti campi secondari:

  • encoding - (obbligatorio) specifica lo schema di codifica dell'audio fornito (di tipo AudioEncoding). Se hai la possibilità di scegliere il codec, preferisci una codifica lossless come FLAC o LINEAR16 per ottenere prestazioni ottimali. Per ulteriori informazioni, vedi Codifiche audio. Il campo encoding è facoltativo per i file FLAC e WAV in cui la codifica è inclusa nell'intestazione del file.
  • sampleRateHertz - (obbligatorio) specifica la frequenza di campionamento (in hertz) dell'audio fornito. Per ulteriori informazioni sulle frequenze di campionamento, consulta la sezione Frequenze di campionamento riportata di seguito. Il campo sampleRateHertz è facoltativo per i file FLAC e WAV in cui la frequenza di campionamento è inclusa nell'intestazione del file.
  • languageCode - (obbligatorio) contiene la lingua e la regione/le impostazioni internazionali da utilizzare per il riconoscimento vocale dell'audio fornito. Il codice lingua deve essere un identificatore BCP-47. Tieni presente che i codici di lingua in genere sono costituiti da tag di lingua principali e tag secondari di regione per indicare i dialetti (ad esempio, "en" per l'inglese e "US" per gli Stati Uniti nell'esempio precedente). Per un elenco delle lingue supportate, consulta la sezione Lingue supportate.
  • maxAlternatives - (facoltativo, il valore predefinito è 1) indica il numero di trascrizioni alternative da fornire nella risposta. Per impostazione predefinita, l'API Speech-to-Text fornisce una trascrizione principale. Se vuoi valutare alternative diverse, imposta maxAlternatives su un valore più alto. Tieni presente che la funzionalità di Speech-to-Text restituirà alternative solo se il sistema di riconoscimento le ritiene di qualità sufficiente. In generale, le alternative sono più adatte alle richieste in tempo reale che richiedono il feedback dell'utente (ad esempio, i comandi vocali) e pertanto sono più adatte alle richieste di riconoscimento di streaming.
  • profanityFilter (facoltativo): indica se filtrare le parole o le frasi volgari. Al posto delle parole escluse, verrà visualizzata la prima lettera della parola e un asterisco per ogni carattere rimanente (ad esempio c****). Il filtro per il linguaggio volgare opera su singole parole e non rileva discorsi offensivi o abusivi che sono una frase o una combinazione di parole.
  • speechContext (facoltativo) contiene informazioni contestuali aggiuntive per l'elaborazione di questo audio. Un contesto contiene i seguenti campi secondari:
    • boost: contiene un valore che assegna un peso al riconoscimento di una determinata parola o frase.
    • phrases: contiene un elenco di parole e frasi che forniscono suggerimenti per l'attività di riconoscimento vocale. Per ulteriori informazioni, consulta la sezione sull'adattamento vocale.

L'audio viene fornito a Speech-to-Text tramite il parametro audio di tipo RecognitionAudio. Il campo audio contiene uno dei seguenti campi secondari:

  • content contiene l'audio da valutare, incorporato nella richiesta. Per saperne di più, consulta la sezione Incorporamento di contenuti audio di seguito. L'audio trasmesso direttamente in questo campo è limitato a 1 minuto di durata.
  • uri contiene un URI che rimanda ai contenuti audio. Il file non deve essere compresso (ad esempio, gzip). Attualmente, questo campo deve contenere un URI Google Cloud Storage (nel formato gs://bucket-name/path_to_audio_file). Vedi Trasmettere il riferimento audio tramite un URI di seguito.

Di seguito sono riportate ulteriori informazioni su questi parametri di richiesta e risposta.

Frequenze di campionamento

Specifichi la frequenza di campionamento dell'audio nel campo sampleRateHertz della configurazione della richiesta e deve corrispondere alla frequenza di campionamento dell'audio o dello stream associato. Le frequenze di campionamento comprese tra 8000 Hz e 48000 Hz sono supportate in Speech-to-Text. Puoi specificare la frequenza di campionamento per un file FLAC o WAV nell'intestazione del file anziché utilizzare il campo sampleRateHertz. Un file FLAC deve contenere la frequenza di campionamento nell'intestazione FLAC per poter essere inviato all'API Speech-to-Text.

Se hai la possibilità di scegliere la codifica del materiale sorgente, acquisisci l'audio utilizzando una frequenza di campionamento di 16000 Hz. Valori inferiori a questo potrebbero compromettere l'accuratezza del riconoscimento vocale, mentre valori superiori non hanno un effetto apprezzabile sulla qualità del riconoscimento vocale.

Tuttavia, se i dati audio sono già stati registrati a una frequenza di campionamento esistente diversa da 16.000 Hz, non ricampionarli a 16.000 Hz. La maggior parte dell'audio di telefonia legacy, ad esempio, utilizza frequenze di campionamento di 8000 Hz, che potrebbero fornire risultati meno accurati. Se devi utilizzare questo tipo di audio, fornisci l'audio all'API Speech alla sua frequenza di campionamento nativa.

Lingue

Il motore di riconoscimento di Speech-to-Text supporta una varietà di lingue e dialetti. Specifichi la lingua (e il dialetto nazionale o regionale) dell'audio nel campo languageCode della configurazione della richiesta, utilizzando un identificatore BCP-47.

Un elenco completo delle lingue supportate per ogni funzionalità è disponibile nella pagina Supporto delle lingue.

Offset temporali (timestamp)

Speech-to-Text può includere valori di offset temporale (timestamp) per l'inizio e la fine di ogni parola pronunciata riconosciuta nell'audio fornito. Un valore di offset temporale rappresenta il tempo trascorso dall'inizio dell'audio, in incrementi di 100 ms.

Gli offset temporali sono particolarmente utili per analizzare file audio più lunghi, in cui potresti dover cercare una parola specifica nel testo riconosciuto e trovarla (cercarla) nell'audio originale. Gli offset temporali sono supportati per tutti i nostri metodi di riconoscimento: recognize, streamingrecognize e longrunningrecognize.

I valori di offset temporale vengono inclusi solo per la prima alternativa fornita nella risposta di riconoscimento.

Per includere gli offset temporali nei risultati della richiesta, imposta il parametro enableWordTimeOffsets su true nella configurazione della richiesta. Per esempi che utilizzano l'API REST o le librerie client, consulta Utilizzo degli offset temporali (timestamp). Ad esempio, puoi includere il parametro enableWordTimeOffsets nella configurazione della richiesta come mostrato qui:

{
"config": {
  "languageCode": "en-US",
  "enableWordTimeOffsets": true
  },
"audio":{
  "uri":"gs://gcs-test-data/gettysburg.flac"
  }
}

Il risultato restituito dall'API Speech-to-Text conterrà valori di offset temporale per ogni parola riconosciuta, come mostrato di seguito:

{
  "name": "6212202767953098955",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata",
    "progressPercent": 100,
    "startTime": "2017-07-24T10:21:22.013650Z",
    "lastUpdateTime": "2017-07-24T10:21:45.278630Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [
      {
        "alternatives": [
          {
            "transcript": "Four score and twenty...(etc)...",
            "confidence": 0.97186122,
            "words": [
              {
                "startTime": "1.300s",
                "endTime": "1.400s",
                "word": "Four"
              },
              {
                "startTime": "1.400s",
                "endTime": "1.600s",
                "word": "score"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.600s",
                "word": "and"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.900s",
                "word": "twenty"
              },
              ...
            ]
          }
        ]
      },
      {
        "alternatives": [
          {
            "transcript": "for score and plenty...(etc)...",
            "confidence": 0.9041967,
          }
        ]
      }
    ]
  }
}

Selezione del modello

Speech-to-Text può utilizzare uno dei diversi modelli di machine learning per trascrivere il tuo file audio. Google ha addestrato questi modelli di riconoscimento vocale per tipi e sorgenti audio specifici.

Quando invii una richiesta di trascrizione audio a Speech-to-Text, puoi migliorare i risultati che ricevi specificando la sorgente dell'audio originale. In questo modo, l'API Speech-to-Text può elaborare i file audio utilizzando un modello di machine learning addestrato per riconoscere l'audio vocale di quel particolare tipo di sorgente.

Per specificare un modello per il riconoscimento vocale, includi il campo model nell'oggetto RecognitionConfig per la tua richiesta, specificando il modello che vuoi utilizzare.

Consulta l'elenco dei modelli di trascrizione Speech-to-Text per i modelli di machine learning disponibili.

Contenuti audio incorporati

L'audio incorporato è incluso nella richiesta di riconoscimento vocale quando viene passato un parametro content all'interno del campo audio della richiesta. Per l'audio incorporato fornito come contenuto all'interno di una richiesta gRPC, l'audio deve essere compatibile con la serializzazione Proto3 e fornito come dati binari. Per l'audio incorporato fornito come contenuto all'interno di una richiesta REST, l'audio deve essere compatibile con la serializzazione JSON e deve prima essere codificato in Base64. Per ulteriori informazioni, consulta Codifica Base64 dell'audio.

Quando crei una richiesta utilizzando una libreria client Google Cloud, in genere scrivi questi dati binari (o codificati in base 64) direttamente nel campo content.

Trasmettere l'audio a cui fa riferimento un URI

In genere, devi passare un parametro uri all'interno del campo audio della richiesta Speech, che punta a un file audio (in formato binario, non base64) che si trova in Google Cloud Storage nel seguente formato:

gs://bucket-name/path_to_audio_file

Ad esempio, la seguente parte di una richiesta Speech fa riferimento al file audio di esempio utilizzato nella guida rapida:

...
    "audio": {
        "uri":"gs://cloud-samples-tests/speech/brooklyn.flac"
    }
...

Devi disporre delle autorizzazioni di accesso appropriate per leggere i file di Google Cloud Storage, ad esempio una delle seguenti:

  • Leggibili pubblicamente (come i nostri file audio di esempio)
  • Leggibile dal account di servizio, se utilizzi l'autorizzazione del account di servizio.
  • Leggibile da un account utente, se si utilizza OAuth a tre vie per l'autorizzazione dell'account utente.

Per saperne di più sulla gestione dell'accesso a Google Cloud Storage, consulta la sezione Creazione e gestione degli elenchi di controllo dell'accesso nella documentazione di Google Cloud Storage.

Risposte dell'API Speech-to-Text

Come indicato in precedenza, una risposta sincrona dell'API Speech-to-Text potrebbe richiedere del tempo per restituire i risultati, proporzionale alla durata dell'audio fornito. Una volta elaborata, l'API restituirà una risposta come mostrato di seguito:

{
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.98267895,
          "transcript": "how old is the Brooklyn Bridge"
        }
      ]
    }
  ]
}

Questi campi sono spiegati di seguito:

  • results contiene l'elenco dei risultati (di tipo SpeechRecognitionResult) in cui ogni risultato corrisponde a un segmento audio (i segmenti audio sono separati da pause). Ogni risultato sarà costituito da uno o più dei seguenti campi:
    • alternatives contiene un elenco di possibili trascrizioni, di tipo SpeechRecognitionAlternatives. La visualizzazione di più alternative dipende sia dal fatto che tu abbia richiesto più di un'alternativa (impostando maxAlternatives su un valore maggiore di 1) sia dal fatto che Speech-to-Text abbia prodotto alternative di qualità sufficientemente elevata. Ogni alternativa sarà composta dai seguenti campi:

Se non è stato possibile riconoscere alcun discorso dall'audio fornito, l'elenco results restituito non conterrà elementi. Il parlato non riconosciuto è in genere il risultato di un audio di qualità molto scarsa o di valori di codifica, frequenza di campionamento o codice lingua che non corrispondono all'audio fornito.

I componenti di questa risposta sono spiegati nelle sezioni seguenti.

Ogni risposta sincrona dell'API Speech-to-Text restituisce un elenco di risultati, anziché un singolo risultato contenente tutto l'audio riconosciuto. L'elenco dell'audio riconosciuto (all'interno degli elementi transcript) verrà visualizzato in ordine contiguo.

Seleziona alternative

Ogni risultato all'interno di una risposta di riconoscimento sincrono riuscita può contenere uno o più alternatives (se il valore di maxAlternatives per la richiesta è maggiore di 1). Se Speech-to-Text determina che un'alternativa ha un valore di confidenza sufficiente, questa viene inclusa nella risposta. La prima alternativa nella risposta è sempre la migliore (più probabile).

L'impostazione di maxAlternatives su un valore superiore a 1 non implica né garantisce che verranno restituite più alternative. In generale, più di un'alternativa è più appropriata per fornire opzioni in tempo reale agli utenti che ricevono risultati tramite una richiesta di riconoscimento dello streaming.

Gestione delle trascrizioni

Ogni alternativa fornita nella risposta conterrà un transcript contenente il testo riconosciuto. Se vengono fornite alternative sequenziali, devi concatenare queste trascrizioni.

Il seguente codice Python scorre un elenco di risultati e concatena le trascrizioni. Tieni presente che in tutti i casi prendiamo la prima alternativa (la zero).

response = service_request.execute()
recognized_text = 'Transcribed Text: \n'
for i in range(len(response['results'])):
    recognized_text += response['results'][i]['alternatives'][0]['transcript']

Valori di confidenza

Il valore di confidence è una stima compresa tra 0,0 e 1,0. Viene calcolato aggregando i valori di "probabilità " assegnati a ogni parola dell'audio. Un numero più alto indica una maggiore probabilità stimata che le singole parole siano state riconosciute correttamente. Questo campo viene in genere fornito solo per l'ipotesi principale e solo per i risultati in cui is_final=true. Ad esempio, puoi utilizzare il valore confidence per decidere se mostrare risultati alternativi all'utente o chiedere una conferma.

Tieni presente, tuttavia, che il modello determina il risultato "migliore" e con il ranking più alto in base a più indicatori rispetto al solo punteggio confidence (ad esempio il contesto della frase). Per questo motivo, a volte il risultato migliore non ha il punteggio di confidenza più alto. Se non hai richiesto più risultati alternativi, il singolo risultato "migliore" restituito potrebbe avere un valore di affidabilità inferiore alle tue aspettative. Ciò può verificarsi, ad esempio, nei casi in cui vengono utilizzate parole rare. A una parola usata raramente può essere assegnato un valore di "probabilità" basso anche se viene riconosciuta correttamente. Se il modello determina che la parola rara è l'opzione più probabile in base al contesto, il risultato viene restituito in alto anche se il valore confidence del risultato è inferiore alle opzioni alternative.

Richieste e risposte asincrone

Una richiesta asincrona all'API Speech-to-Text al metodo LongRunningRecognize è identica nella forma a una richiesta sincrona all'API Speech-to-Text. Tuttavia, anziché restituire una risposta, la richiesta asincrona avvierà un'operazione a lunga esecuzione (di tipo Operation) e restituirà immediatamente questa operazione al chiamante. Puoi utilizzare il riconoscimento vocale asincrono con audio di qualsiasi durata fino a 480 minuti.

Di seguito è riportata una tipica risposta all'operazione:

{
  "name": "operation_name",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata"
    "progressPercent": 34,
    "startTime": "2016-08-30T23:26:29.579144Z",
    "lastUpdateTime": "2016-08-30T23:26:29.826903Z"
  }
}

Tieni presente che non sono ancora presenti risultati. Speech-to-Text continuerà a elaborare l'audio e utilizzerà questa operazione per archiviare i risultati. I risultati vengono visualizzati nel campo response dell'operazione restituita al termine della richiesta LongRunningRecognize.

Di seguito è riportata una risposta completa al termine della richiesta:

{
  "name": "1268386125834704889",
  "metadata": {
    "lastUpdateTime": "2016-08-31T00:16:32.169Z",
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongrunningRecognizeMetadata",
    "startTime": "2016-08-31T00:16:29.539820Z",
    "progressPercent": 100
  }
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [{
      "alternatives": [{
        "confidence": 0.98267895,
        "transcript": "how old is the Brooklyn Bridge"
      }]}]
  },
  "done": True,
}

Tieni presente che done è stato impostato su True e che response dell'operazione contiene un insieme di risultati di tipo SpeechRecognitionResult, che è lo stesso tipo restituito da una richiesta di riconoscimento sincrono dell'API Speech-to-Text.

Per impostazione predefinita, una risposta REST asincrona imposta done su False, il suo valore predefinito. Tuttavia, poiché JSON non richiede che i valori predefiniti siano presenti in un campo, quando testi se un'operazione è completata, devi verificare che il campo done sia presente e che sia impostato su True.

Richieste di riconoscimento dell'API Speech-to-Text in streaming

Una chiamata di riconoscimento dell'API Speech-to-Text in streaming è progettata per l'acquisizione e il riconoscimento in tempo reale dell'audio all'interno di un flusso bidirezionale. La tua applicazione può inviare audio nel flusso di richieste e ricevere risultati di riconoscimento intermedi e finali nel flusso di risposte in tempo reale. I risultati provvisori rappresentano il risultato di riconoscimento corrente per una sezione audio, mentre il risultato di riconoscimento finale rappresenta l'ultima e migliore ipotesi per quella sezione audio.

Richieste di streaming

A differenza delle chiamate sincrone e asincrone, in cui invii sia la configurazione che l'audio in un'unica richiesta, la chiamata all'API Speech streaming richiede l'invio di più richieste. Il primo StreamingRecognizeRequest deve contenere una configurazione di tipo StreamingRecognitionConfig senza audio di accompagnamento. I successivi StreamingRecognizeRequest inviati tramite lo stesso stream saranno costituiti da frame consecutivi di byte audio non elaborati.

Un StreamingRecognitionConfig è costituito dai seguenti campi:

  • config - (obbligatorio) contiene le informazioni di configurazione per l'audio, di tipo RecognitionConfig ed è uguale a quello mostrato nelle richieste sincrone e asincrone.
  • single_utterance - (facoltativo, il valore predefinito è false) indica se questa richiesta deve terminare automaticamente dopo che non viene più rilevata la voce. Se impostato, la funzionalitàSpeech-to-Texte rileva pause, silenzi o audio non vocale per determinare quando terminare il riconoscimento. Se non viene impostato, lo stream continuerà ad ascoltare e a elaborare l'audio finché non viene chiuso direttamente o finché non viene superata la durata limite dello stream. L'impostazione single_utterance su true è utile per l'elaborazione dei comandi vocali.
  • interim_results - (facoltativo, il valore predefinito è false) indica che questa richiesta di flusso deve restituire risultati temporanei che potrebbero essere perfezionati in un secondo momento (dopo l'elaborazione di altro audio). I risultati provvisori verranno indicati nelle risposte impostando is_final su false.

Risposte dinamiche

I risultati del riconoscimento vocale di audio in streaming vengono restituiti in una serie di risposte di tipo StreamingRecognitionResponse. Una risposta di questo tipo è costituita dai seguenti campi:

  • speechEventType contiene eventi di tipo SpeechEventType. Il valore di questi eventi indicherà quando una singola espressione è stata considerata completata. Gli eventi vocali fungono da indicatori all'interno della risposta dello stream.
  • results contiene l'elenco dei risultati, che possono essere intermedi o finali, di tipo StreamingRecognitionResult. L'elenco results contiene i seguenti sottocampi:
    • alternatives contiene un elenco di trascrizioni alternative.
    • isFinal indica se i risultati ottenuti all'interno di questa voce di elenco sono provvisori o definitivi. Google potrebbe restituire più risultati isFinal=true in un singolo stream, ma il risultato isFinal=true è garantito solo dopo la chiusura (chiusura parziale) dello stream di scrittura.
    • stability indica la volatilità dei risultati ottenuti finora, con 0.0 che indica un'instabilità completa, mentre 1.0 indica una stabilità completa. Tieni presente che, a differenza dell'attendibilità, che stima se una trascrizione è corretta, stability stima se il risultato parziale fornito potrebbe cambiare. Se isFinal è impostato su true, stability non verrà impostato.