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 costruire queste richieste 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 addentrarci nell'API stessa.

Provalo

Se non hai mai utilizzato Google Cloud, crea un account per valutare le prestazioni di Speech-to-Text in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Prova Speech-to-Text gratuitamente

Richieste vocali

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

  • Il Riconoscimento sincrono (REST e gRPC) invia dati audio all'API Speech-to-Text, esegue il riconoscimento su tali dati e restituisce i risultati dopo l'elaborazione di tutto l'audio. 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 dati audio all'API Speech-to-Text e avvia un'operazione di lunga durata. Con questa operazione, puoi eseguire periodicamente il polling dei risultati del riconoscimento. Utilizza le richieste asincrone per i dati audio di qualsiasi durata fino a 480 minuti.

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

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

Riconoscimento dell'API Speech-to-Text

Una richiesta di riconoscimento sincrono dell'API Speech-to-Text è il metodo più semplice per eseguire il riconoscimento di dati audio vocali. Speech-to-Text può elaborare fino a 1 minuto di dati audio vocali inviati in una richiesta sincrona. Dopo aver elaborato e riconosciuto tutto l'audio, Speech-to-Text restituisce una risposta.

Una richiesta sincrona è in fase di blocco, il che significa che Speech-to-Text deve restituire una risposta prima di elaborare la richiesta successiva. Speech-to-Text elabora l'audio più velocemente del 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 REST e gRPC per chiamare le richieste sincrone e asincrone dell'API Speech-to-Text. Questo articolo illustra l'API REST perché è più semplice da mostrare e spiegare l'utilizzo di base. Tuttavia, la composizione di base di una richiesta REST o gRPC è abbastanza simile. Le richieste di riconoscimento dei flussi 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 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 config di riconoscimento vocale (di tipo RecognitionConfig). A RecognitionConfig contiene i seguenti campi secondari:

  • encoding (obbligatorio) specifica lo schema di codifica dell'audio fornito (di tipo AudioEncoding). Se puoi scegliere il codec, preferisci una codifica senza perdita di dati come FLAC o LINEAR16 per ottenere prestazioni ottimali. Per ulteriori informazioni, consulta la sezione 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 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 + la regione/l'area geografica da utilizzare per il riconoscimento vocale dell'audio fornito. Il codice lingua deve essere un identificatore BCP-47. Tieni presente che i codici lingua in genere sono costituiti da tag della lingua principale e sottotag secondari della 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, vedi 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 Speech-to-Text restituirà alternative solo se il riconoscimento stabilisce che le alternative sono di qualità sufficiente. In generale, le alternative sono più appropriate per le richieste in tempo reale che richiedono il feedback degli utenti (ad esempio, i comandi vocali) e pertanto sono più adatte per le richieste di riconoscimento dei flussi.
  • profanityFilter: (facoltativo) indica se filtrare parole o frasi volgari. Le parole filtrate conterranno la prima lettera e asterischi per i caratteri rimanenti (ad es. f***). Il filtro per il linguaggio volgare opera su singole parole e non rileva contenuti offensivi o offensivi costituiti da una frase o una combinazione di parole.
  • speechContext: (facoltativo) contiene ulteriori informazioni contestuali per l'elaborazione dell'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 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 ulteriori informazioni, consulta la sezione Incorporamento di contenuti audio di seguito. L'audio trasmesso direttamente in 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 la sezione Passaggio del riferimento audio tramite un URI di seguito.

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

Frequenze di campionamento

Puoi specificare la frequenza di campionamento dell'audio nel campo sampleRateHertz della configurazione della richiesta e deve corrispondere alla frequenza di campionamento dello stream o del contenuto audio associato. Le frequenze di campionamento comprese tra 8000 Hz e 48.000 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 essere inviato all'API Speech-to-Text.

Se puoi scegliere di codificare il materiale originale, acquisisci l'audio utilizzando una frequenza di campionamento di 16.000 Hz. Valori inferiori a questo valore potrebbero compromettere la precisione del riconoscimento vocale e i livelli più alti 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 16.000 Hz, non ricampionare l'audio a 16.000 Hz. La maggior parte dei dati audio delle telefonate precedenti, ad esempio, utilizza frequenze di campionamento di 8000 Hz, che potrebbero fornire risultati meno precisi. Se devi utilizzare questo tipo di audio, fornisci l'audio all'API Speech alla frequenza di campionamento nativa.

Linguaggi

Il motore di riconoscimento di Speech-to-Text supporta una varietà di lingue e dialetti. Puoi specificare 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 parlata riconosciuta nell'audio fornito. Un valore di offset temporale rappresenta la quantità di tempo trascorso dall'inizio dell'audio, in incrementi di 100 ms.

Gli scarti temporali sono particolarmente utili per analizzare file audio più lunghi, nei quali potrebbe essere necessario cercare una determinata parola nel testo riconosciuto e localizzarla (ricerca) nell'audio originale. Gli scarti 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 scarti 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 scarti 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 numerosi modelli di machine learning per trascrivere il file audio. Google ha addestrato questi modelli di riconoscimento vocale per origini e tipi audio specifici.

Quando invii una richiesta di trascrizione di audio a Speech-to-Text, puoi migliorare i risultati ricevuti specificando la fonte dell'audio originale. Ciò consente all'API Speech-to-Text di elaborare i file audio utilizzando un modello di machine learning addestrato a riconoscere l'audio vocale proveniente da quel determinato tipo di origine.

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

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

Contenuti audio incorporati

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

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

Trasmettere l'audio a cui fa riferimento un URI

Più in genere, passerai un parametro uri all'interno del campo audio della richiesta vocale, che rimanda a un file audio (in formato binario, non in base64) situato su Google Cloud Storage con il seguente formato:

gs://bucket-name/path_to_audio_file

Ad esempio, la parte seguente 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 opzioni:

  • Leggibilità pubblicamente (come 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.

Ulteriori informazioni sulla gestione dell'accesso a Google Cloud Storage sono disponibili nella 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, la risposta sincrona dell'API Speech-to-Text potrebbe richiedere del tempo per restituire i risultati, in proporzione alla lunghezza 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 (del tipo SpeechRecognitionResult) in cui ogni risultato corrisponde a un segmento di audio (i segmenti di audio sono separati da pause). Ogni risultato sarà composto da uno o più dei seguenti campi:
    • alternatives contiene un elenco di possibili trascrizioni, di tipo SpeechRecognitionAlternatives. La visualizzazione di più alternative dipende dalla tua richiesta di più di un'alternativa (impostando maxAlternatives su un valore maggiore di 1) e dalla capacità di Speech-to-Text di avere prodotto alternative di qualità sufficientemente elevata. Ogni alternativa sarà costituita dai seguenti campi:

Se non viene riconosciuto alcun comando dell'audio fornito, l'elenco results restituito non conterrà alcun elemento. La voce non riconosciuta è in genere il risultato di un audio di qualità molto scadente o di valori del codice lingua, della codifica o della frequenza di campionamento che non corrispondono all'audio fornito.

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

Seleziona alternative

Ciascun risultato in una risposta di riconoscimento sincrona riuscita può contenere uno o più alternatives (se il valore maxAlternatives per la richiesta è maggiore di 1). Se Speech-to-Text determina che un'alternativa ha un valore di affidabilità sufficiente, l'alternativa 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 all'interno della risposta conterrà un elemento transcript contenente il testo riconosciuto. Se ti vengono fornite alternative sequenziali, devi concatenare le trascrizioni.

Il seguente codice Python esegue l'iterazione di un elenco di risultati e concatena le trascrizioni. Tieni presente che prendiamo la prima alternativa (il numero zero) in tutti i casi.

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 affidabilità

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

Tieni presente, tuttavia, che il modello determina il risultato "migliore" con il miglior posizionamento 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 affidabilità più alto. Se non hai richiesto più risultati alternativi, il singolo "migliore" restituito potrebbe avere un valore di affidabilità inferiore al previsto. Questo può verificarsi, ad esempio, nei casi in cui vengono utilizzate parole rare. A una parola che viene usata raramente può essere assegnato un valore basso di "probabilità", 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 rispetto alle opzioni alternative.

Richieste e risposte asincrone

Una richiesta dell'API Speech-to-Text asincrona al metodo LongRunningRecognize è identica in forma a una richiesta API Speech-to-Text sincrona. Tuttavia, invece di restituire una risposta, la richiesta asincrona avvia un'operazione a lunga esecuzione (di tipo operazione) e restituisce immediatamente questa operazione al destinatario della chiamata. Puoi utilizzare il riconoscimento vocale asincrono con audio di qualsiasi durata, fino a 480 minuti.

Di seguito è riportata una tipica risposta di un'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 a utilizzare questa operazione per archiviare i risultati. I risultati verranno visualizzati nel campo response dell'operazione restituita al completamento 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 il criterio done è stato impostato su True e che il valore response dell'operazione contiene un set di risultati di tipo SpeechRecognitionResult, lo stesso tipo restituito da una richiesta di riconoscimento sincrona dell'API Speech-to-Text.

Per impostazione predefinita, una risposta REST asincrona imposta il valore predefinito done su False. Tuttavia, poiché JSON non richiede che siano presenti valori predefiniti all'interno di un campo, quando verifichi il completamento di un'operazione, devi verificare sia 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 dell'audio in tempo reale, all'interno di uno stream bidirezionale. L'applicazione può inviare audio nel flusso di richieste e ricevere risultati di riconoscimento provvisori e finali in tempo reale nel flusso di risposta. I risultati temporanei rappresentano il risultato del riconoscimento corrente per una sezione di audio, mentre il risultato del riconoscimento finale rappresenta l'ultima ipotesi migliore per quella sezione di audio.

Richieste di flussi di dati

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

Un StreamingRecognitionConfig è costituito dai seguenti campi:

  • config (obbligatorio) contiene informazioni di configurazione per l'audio, di tipo RecognitionConfig e corrisponde a quello mostrato nelle richieste sincrone e asincrone.
  • single_utterance: (facoltativo, il valore predefinito è false) indica se la richiesta deve terminare automaticamente quando non viene più rilevato un parlato. Se questa preferenza è impostata, Speech-to-Text rileverà pause, silenziamenti o audio non vocale per determinare quando terminare il riconoscimento. Se il criterio non viene configurato, lo stream continuerà ad ascoltare ed elaborare l'audio fino alla chiusura diretta dello stream o fino al superamento del limite della lunghezza 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 streaming deve restituire risultati temporanei che potrebbero essere perfezionati in un secondo momento (dopo l'elaborazione di ulteriore audio). I risultati temporanei verranno annotati all'interno delle risposte tramite l'impostazione da is_final a 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 una singola frase è stata determinata per essere completata. Gli eventi vocali fungono da indicatori all'interno della risposta dello stream.
  • results contiene l'elenco dei risultati, che possono essere risultati provvisori 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 in questa voce dell'elenco sono provvisori o definitivi. Google potrebbe restituire più risultati isFinal=true durante un singolo stream, ma il risultato isFinal=true è garantito solo dopo la chiusura del flusso di scrittura (metà chiusura).
    • stability indica la volatilità dei risultati ottenuti finora, con 0.0 che indica una completa instabilità, mentre 1.0 indica una stabilità completa. Tieni presente che, a differenza dell'affidabilità, che stima la correttezza di una trascrizione, stability valuta se il risultato parziale specificato potrebbe cambiare. Se isFinal viene impostato su true, stability non verrà impostato.