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 effettuare a Speech-to-Text, come crearle e come gestire le relative risposte. Prima di iniziare a utilizzare l'API stessa, consigliamo a tutti gli utenti di Speech-to-Text di leggere questa guida e uno dei tutorial associati.

Richieste vocali

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 ai 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 a lungo termine. Con questa operazione, puoi eseguire periodicamente un polling per i risultati del riconoscimento. Utilizza richieste asincrone per dati audio di qualsiasi durata fino a 480 minuti.

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

Le richieste contengono parametri di configurazione e dati audio. Le sezioni che seguono descrivono in modo più dettagliato questo tipo 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 vocali. Speech-to-Text può elaborare fino a un minuto di dati audio vocali inviati in una richiesta sincrona. Dopo che la funzionalità Speech-to-Text ha elaborato e riconosciuto tutto l'audio, restituisce una risposta.

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

Speech-to-Text dispone di metodi sia REST che gRPC per chiamare le 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 struttura di base di una richiesta REST o gRPC è abbastanza simile. Le richieste di riconoscimento in streaming sono supportate solo da gRPC.

Richieste di riconoscimento vocale sincrono

Una richiesta sincrona dell'API Speech-to-Text è composta da una configurazione di riconoscimento vocale e da dati audio. Di seguito è riportata una richiesta di esempio:

{
    "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 vocaleconfig (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 senza perdita di dati come FLAC o LINEAR16 per ottenere le migliori prestazioni. Per ulteriori informazioni, consulta la pagina relativa alle codici 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 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 lingua generalmente consistono di tag lingua principali e sottotag regione secondari per indicare i dialetti (ad esempio, "it" per l'italiano e "US" per gli Stati Uniti nell' esempio precedente). Per un elenco delle lingue supportate, consulta 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 diverse alternative, imposta maxAlternatives su un valore più alto. Tieni presente che Speech-to-Text restituisce le alternative solo se il sistema di riconoscimento determina che sono di qualità sufficiente. In generale, le alternative sono più appropriate per le richieste in tempo reale che richiedono il feedback dell'utente (ad esempio i comandi vocali) e sono quindi più adatte per le richieste di riconoscimento in streaming.
• profanityFilter (facoltativo) indica se escludere le parole o le frasi profane. 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 agisce su singole parole e non rileva il linguaggio offensivo o illecito che si presenta sotto forma di frase o 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 all'attività di riconoscimento vocale. Per ulteriori informazioni, consulta le informazioni 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 Incorporare contenuti audio di seguito. L'audio trasmesso direttamente all'interno di questo campo ha una durata massima di 1 minuto.
• 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). Consulta Passare il riferimento audio tramite un URI di seguito.

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

Frequenze di campionamento

La frequenza di campionamento dell'audio deve essere specificata nel campo sampleRateHertz della configurazione della richiesta e deve corrispondere a quella dei contenuti o dello stream audio associati. All'interno di Speech-to-Text sono supportate frequenze di campionamento comprese tra 8000 Hz e 48000 Hz. 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 durante la codifica del materiale di origine, acquisisci l'audio utilizzando una frequenza di campionamento di 16000 Hz. Valori inferiori a questo potrebbero compromettere l'accuratezza del riconoscimento vocale e i livelli più elevati non hanno alcun effetto apprezzabile sulla qualità del riconoscimento vocale.

Tuttavia, se i dati audio sono già stati registrati a una frequenza di campionamento esistente diversa da 16000 Hz, non eseguire il campionamento dell'audio a 16000 Hz. La maggior parte dell'audio di telefonia legacy, ad esempio, utilizza frequenze di campionamento di 8000 Hz, il che potrebbe dare risultati meno accurati. Se devi utilizzare questo audio, forniscilo all'API Speech con la frequenza di campionamento nativa.

Lingue

Il motore di riconoscimento di Speech-to-Text supporta una serie di lingue e dialetti. Specifica 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, con incrementi di 100 ms.

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

I valori dell'offset di tempo sono inclusi solo per la prima alternativa fornita nella risposta al riconoscimento.

Per includere gli offset di tempo nei risultati della richiesta, imposta il parametroenableWordTimeOffsets su true nella configurazione della richiesta. Per esempi sull'utilizzo dell'API REST o delle librerie client, consulta Utilizzare gli offset di tempo (timestamp). Ad esempio, puoi includere il parametro enableWordTimeOffsets nella configurazione della richiesta come mostrato di seguito:

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

Il risultato restituito dall'API Speech-to-Text conterrà i 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 di diversi modelli di machine learning per trascrivere il 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 a riconoscere l'audio vocale da quel determinato tipo di sorgente.

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

Consulta l'elenco dei modelli di trascrizione di 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 nel campo audio della richiesta. L'audio incorporato fornito come contenuto all'interno di una richiesta gRPC deve essere compatibile con la serializzazione Proto3 e fornito come dati binari. L'audio incorporato fornito come contenuto all'interno di una richiesta REST deve essere compatibile con la serializzazione JSON e deve essere prima codificato in Base64. Per ulteriori informazioni, consulta Codifica audio in Base64.

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.

Passare l'audio a cui fa riferimento un URI

In genere, trasmetti un parametro uri nel campo audio della richiesta di Speech, che rimanda a un file audio (in formato binario, non base64) situato su Google Cloud Storage del seguente tipo:

gs://bucket-name/path_to_audio_file

Ad esempio, la seguente parte di una richiesta Speech fa riferimento al file audio di esempio utilizzato all'interno della guida rapida:

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

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

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

Per saperne di più sulla gestione dell'accesso a Google Cloud Storage, consulta Creare e gestire gli elenchi di controllo dell'accesso nella documentazione di Google Cloud Storage.

Risposte dell'API Speech-to-Text

Come indicato in precedenza, una risposta dell'API Speech-to-Text sincrona potrebbe richiedere del tempo per restituire i risultati, in proporzione 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 descritti di seguito:

• results contiene l'elenco dei risultati (di tipo SpeechRecognitionResult) dove ogni risultato corrisponde a un segmento di audio (i segmenti di 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:
    • transcript contiene il testo trascritto. Consulta la sezione Gestione delle trascrizioni di seguito.
    • confidence contiene un valore compreso tra 0 e 1 che indica il grado di confidenza di Speech-to-Text sulla trascrizione data. Consulta la sezione Interpretazione dei valori di confidenza di seguito.

Se non è stato possibile riconoscere alcun parlato 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 codice lingua, codifica o frequenza di campionamento che non corrispondono all'audio fornito.

I componenti di questa risposta sono descritti 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 di audio riconosciuto (all'interno degli elementi transcript) verrà visualizzato in ordine contiguo.

Seleziona le alternative

Ogni risultato all'interno di una risposta di riconoscimento sincrono riuscita può contenere uno o più alternatives (se il valore maxAlternatives per la richiesta è superiore a 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 (la 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 in streaming.

Gestione delle trascrizioni

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

Il seguente codice Python esegue l'iterazione su un elenco di risultati e concatena le trascrizioni. Tieni presente che in tutti i casi viene scelta 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 confidence è una stima compresa tra 0,0 e 1,0. Viene calcolato aggregando i valori di "probabilità " assegnati a ogni parola nell'audio. Un numero più alto indica una maggiore probabilità stimata che le singole parole siano state riconosciute correttamente. In genere, questo campo viene 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 all'utente risultati alternativi o chiedere una conferma.

Tieni presente, però, che il modello determina il risultato "migliore" con il ranking più alto in base a più indicatori rispetto al solo punteggio confidence (ad esempio il contesto della frase). Per questo motivo, in alcuni casi 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 a quello previsto. Questo 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 a quello delle opzioni alternative.

Richieste e risposte asincrone

Una richiesta asincrona dell'API Speech-to-Text al metodo LongRunningRecognize è identica in forma a una richiesta dell'API Speech-to-Text sincrona. Tuttavia, instead of returning a response, the asynchronous request will initiate a Long Running Operation (of type Operation) and return this operation to the callee immediately. Puoi utilizzare il riconoscimento vocale asincrono con audio di qualsiasi durata fino a 480 minuti.

Di seguito è riportata una risposta di operazione tipica:

{
  "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 a utilizzare questa operazione per memorizzare i risultati. I risultati verranno visualizzati nel campo response dell'operazione restituita al termine della richiesta LongRunningRecognize.

Di seguito è riportata una risposta completa dopo il completamento 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 relativo valore predefinito. Tuttavia, poiché JSON non richiede che i valori predefiniti siano presenti in un campo, quando testi se un'operazione è stata completata, devi verificare sia che il campo done sia presente sia 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 uno stream bidirezionale. La tua applicazione può inviare audio sullo stream di richiesta e ricevere risultati di riconoscimento provvisori e finali sullo stream di risposta in tempo reale. I risultati intermedi rappresentano il risultato corrente del riconoscimento per una sezione di audio, mentre il risultato finale del riconoscimento rappresenta l'ultima e migliore supposizione per quella sezione di audio.

Richieste di streaming

A differenza delle chiamate sincrone e asincrone, in cui invii sia la configurazione sia l'audio in una singola richiesta, la chiamata dell'API Speech con streaming richiede l'invio di più richieste. Il primo StreamingRecognizeRequest deve contenere una configurazione di tipo StreamingRecognitionConfig senza audio aggiuntivo. I StreamingRecognizeRequest successivi inviati sullo 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 quando non viene più rilevato alcun parlato. Se impostato, Speech-to-Text rileverà pause, silenzio o audio non vocale per determinare quando terminare il riconoscimento. Se non viene impostato, lo stream continuerà a ascoltare e elaborare l'audio finché non viene chiuso direttamente o non viene superata la durata massima dello stream. L'impostazione di single_utterance su true è utile per l'elaborazione dei comandi vocali.
• interim_results - (facoltativo, il valore predefinito è false) indica che questa richiesta di stream deve restituire risultati temporanei che possono essere perfezionati in un secondo momento (dopo aver elaborato altro audio). I risultati intermedi verranno indicati nelle risposte impostando is_final su false.

Risposte dinamiche

I risultati del riconoscimento vocale in streaming vengono restituiti all'interno di una serie di risposte di tipo StreamingRecognitionResponse. Questa risposta è composta dai seguenti campi:

• speechEventType contiene eventi di tipo SpeechEventType. Il valore di questi eventi indicherà quando è stato stabilito che un singolo enunciato è stato completato. Gli eventi vocali fungono da indicatori all'interno della risposta sviluppata dallo stream.
• results contiene l'elenco dei risultati, che possono essere risultati intermedi o finali, di tipo StreamingRecognitionResult. L'elenco results contiene i seguenti campi secondari:
  • alternatives contiene un elenco di trascrizioni alternative.
  • isFinal indica se i risultati ottenuti all'interno di questa voce dell'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 dello stream di scrittura (chiusura parziale).
  • stability indica la volatilità dei risultati ottenuti finora, con 0.0 che indica instabilità completa, mentre 1.0 indica stabilità completa. Tieni presente che, a differenza dell'affidabilità, che stima se una trascrizione è corretta, stability stima se il risultato parziale dato può cambiare. Se isFinal è impostato su true, stability non verrà impostato.