Solução de problemas

Saiba mais sobre as etapas de solução de problemas que podem ser úteis se você tiver problemas ao usar o Speech-to-Text.

Não é possível se autenticar no Speech-to-Text

Talvez você receba uma mensagem de erro indicando que o Application Default Credentials não está disponível. Ou talvez você queira saber como receber uma chave de API para usar ao chamar o Speech-to-Text.

O Speech-to-Text usa o Application Default Credentials (ADC) para a autenticação.

As credenciais do ADC precisam estar disponíveis no contexto em que você chama o API Speech-to-Text. Por exemplo, se você configurar o ADC no terminal, mas executar o código no depurador do ambiente de desenvolvimento integrado, o contexto de execução do seu código poderá não ter acesso às credenciais. Nesse caso, sua solicitação para o Speech-to-Text pode apresentar uma falha.

Para saber como fornecer credenciais ao ADC, consulte Configurar o Application Default Credentials.

O Speech-to-Text retorna uma resposta vazia

Há vários motivos para o Speech-to-Text retornar uma resposta vazia. A origem do problema pode ser a RecognitionConfig ou o próprio áudio.

Resolver problemas da `RecognitionConfig`

O objeto RecognitionConfig (ou StreamingRecognitionConfig) faz parte de uma solicitação de reconhecimento do Speech-to-Text. Para fazer uma transcrição corretamente, defina os campos que se enquadram nas seguintes categorias principais:

Configuração de áudio
Modelo e linguagem

Uma causa comum de respostas vazias (como uma resposta JSON {} vazia) é fornecer informações incorretas sobre os metadados de áudio. Se os campos de configuração de áudio não estiverem definidos corretamente, a transcrição provavelmente falhará e o modelo de reconhecimento retornará resultados vazios.

A configuração de áudio contém os metadados do áudio fornecido. É possível conseguir os metadados do arquivo de áudio usando o comando ffprobe, que faz parte do FFMPEG.

O exemplo a seguir demonstra o uso do comando para receber os metadados desta amostra de fala.

$ ffprobe commercial_mono.wav
[...]
Input #0, wav, from 'commercial_mono.wav':
  Duration: 00:00:35.75, bitrate: 128 kb/s
  Stream #0:0: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 8000 Hz, 1 channels, s16, 128 kb/s

O arquivo tem claramente 8.000 Hz, um canal e codificação LINEAR16 (s16) e você pode usar essas informações na RecognitionConfig.

Solução de problemas relacionados à codificação

Siga estas etapas para resolver outros possíveis motivos de uma resposta vazia:

Reproduza o arquivo e ouça o áudio. Ele está claro? A fala está compreensível?

Para reproduzir arquivos, use o comando SoX (Sound eXchange) play. Confira alguns exemplos baseados em diferentes codificações de áudio.

Os arquivos FLAC incluem um cabeçalho que indica a taxa de amostra, o tipo de codificação e o número de canais. Eles podem ser reproduzidos da seguinte maneira:
```
play audio.flac
```
Os arquivos LINEAR16 não incluem cabeçalho. Para reproduzi-los, especifique a taxa de amostra, o tipo de codificação e o número de canais. A codificação LINEAR16 precisa ser 16 bits, de número inteiro assinado e little endian.
```
play --channels=1 --bits=16 --rate=16000 --encoding=signed-integer \
--endian=little audio.raw
```
Os arquivos MULAW também não incluem um cabeçalho e geralmente usam uma taxa de amostragem menor.
```
play --channels=1 --rate=8000 --encoding=u-law audio.raw
```
Verifique se a codificação de áudio de seus dados corresponde aos parâmetros que você enviou em RecognitionConfig. Por exemplo, se sua solicitação for especificada, os parâmetros de dados de áudio "encoding":"FLAC" e "sampleRateHertz":16000, listados pelo comando SoX play, deverão corresponder a estes parâmetros da seguinte maneira:
```
play audio.flac
```
Precisa listar:
```
Encoding: FLAC
Channels: 1 @ 16-bit
Sampleratehertz: 16000 Hz
```
Se a lista do SoX mostrar um Sampleratehertz diferente de 16000Hz, altere o "sampleRateHertz" em InitialRecognizeRequest para corresponder. Se o Encoding não for FLAC ou o Channels não for 1 @ 16-bit, você não poderá usar esse arquivo diretamente e será necessário convertê-lo em uma codificação compatível (consulte a próxima etapa).
Se o arquivo de áudio não estiver em codificação FLAC , tente convertê-lo para esse formato usando o SoX. Repita as etapas acima para reproduzir o arquivo e verificar a codificação, o sampleRateHertz e os canais. Exemplos de conversão de vários formatos de arquivos de áudio para a codificação FLAC:
```
sox audio.wav --channels=1 --bits=16 audio.flac
sox audio.ogg --channels=1 --bits=16 audio.flac
sox audio.au --channels=1 --bits=16 audio.flac
sox audio.aiff --channels=1 --bits=16 audio.flac
```
Para converter um arquivo RAW para FLAC, é preciso conhecer a codificação de áudio do arquivo. Por exemplo, para converter um arquivo estéreo de 16 bits little endian em 16.000 Hz para FLAC, siga este exemplo:
```
sox --channels=2 --bits=16 --rate=16000 --encoding=signed-integer \
--endian=little audio.raw --channels=1 --bits=16 audio.flac
```
Execute o exemplo do Guia de início rápido ou um dos Aplicativos de exemplo com o arquivo de áudio de exemplo fornecido. Depois que o exemplo estiver sendo executado com sucesso, substitua o arquivo de áudio de exemplo pelo seu.

Configuração de modelo e linguagem

A seleção de modelos é muito importante para conseguir resultados de transcrição de alta qualidade. O Speech-to-Text fornece vários modelos que foram ajustados para diferentes casos de uso e precisam ser escolhidos para corresponder ao áudio. Por exemplo, alguns modelos, como latest_short e command_and_search, são modelos curtos, o que significa que são mais adequados para áudios e prompts curtos. Esses modelos provavelmente retornarão resultados assim que detectarem um período de silêncio. Modelos longos, por outro lado, como latest_short, phone_call, video and default, são mais adequados para áudios mais longos e não são tão sensíveis à interpretação do silêncio como o fim do áudio.

Se o reconhecimento terminar muito abruptamente ou não retornar rapidamente, teste outros modelos usando a IU de Fala para melhorar a qualidade da transcrição.

Erros de tempo limite

Esses problemas são causados, na maior parte, por configuração incorreta ou uso indevido do Speech-to-Text.

`LongRunningRecognize` ou `BatchRecognize`

Problema: você está recebendo TimeoutError: Operation did not complete within the designated timeout.
Solução: envie uma transcrição para o bucket do Cloud Storage ou aumente o tempo limite na solicitação.

Esse problema ocorre quando a solicitação LongRunningRecognize ou BatchRecognize não é concluída no tempo limite especificado e não é um erro que indica falha na transcrição de voz. Isso significa que os resultados da transcrição não estão prontos para serem extraídos.

`StreamingRecognize`

Problema: você está recebendo Timeout Error: Long duration elapsed without audio. Audio should be sent close to real time.
Solução: o tempo entre os trechos de áudio enviados precisa diminuir. Se o Speech-to-Text não receber um novo bloco a cada poucos segundos, ele vai fechar a conexão e acionar esse erro.

`StreamingRecognize` 409 cancelado

Problema: você está recebendo o erro 409 Max duration of 5 minutes reached for stream.
Solução: você está atingindo o limite de reconhecimento de streaming de cinco minutos de áudio. Quando você estiver chegando perto desse limite, feche o stream e abra um novo.

Qualidade da transcrição baixa

O reconhecimento automático de fala (ASR) oferece suporte a uma grande variedade de casos de uso. A maioria dos problemas de qualidade pode ser resolvida testando diferentes opções de API. Para melhorar a acurácia do reconhecimento, siga as diretrizes em Práticas recomendadas;

Enunciados curtos não são reconhecidos

Problema: respostas curtas do usuário final, como Sim, Não e Próximo, não são capturadas pela API e não aparecem na transcrição.
Solução: siga estas etapas.
1. Teste a mesma solicitação com diferentes modelos.
2. Adicione a adaptação de fala e otimize palavras ausentes.
3. Se você estiver usando a entrada de streaming, tente definir single_utterance=true.

Palavra ou frase consistentemente não reconhecida

Problema: algumas palavras ou frases são reconhecidas incorretamente de forma consistente, como a é reconhecido como 8.
Solução: siga estas etapas.
1. Teste a mesma solicitação com diferentes modelos.
2. Adicione a adaptação de fala e otimize palavras ausentes. É possível usar tokens de classe para aumentar conjuntos inteiros de palavras, como sequências de dígitos ou endereços. Confira os tokens de classe disponíveis.
3. Tente aumentar max_alternatives. Em seguida, marque SpeechRecognitionResult alternatives e escolha o primeiro que corresponder ao formato desejado.

A formatação pode ser um desafio para a ASR. A adaptação de fala geralmente ajuda a conseguir um formato necessário, mas o pós-processamento pode ser necessário para ajustar o formato exigido.

Entradas em vários idiomas ou misturadas

Problema: o áudio contém fala em vários idiomas, como uma conversa entre um falante de inglês e um de espanhol, resultando em uma transcrição incorreta.
Solução: esse recurso não é compatível. O Speech-to-Text só pode transcrever um idioma por solicitação.

Permissão negada

Problema: você está recebendo o erro a seguir.

Permission denied to access GCS object BUCKET-PATH.
Source error: PROJECT-ID@gcp-sa-speech.iam.gserviceaccount.com does not have
storage.buckets.get access to the Google Cloud Storage bucket.
Permission 'storage.buckets.get' denied on resource (or it may not exist).

Solução: conceda permissão a PROJECT_ID@gcp-sa-speech.iam.gserviceaccount.com para acessar o arquivo no bucket BUCKET-PATH.

Argumento inválido

Problema: você está recebendo o erro a seguir.

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

Solução: verifique os argumentos e compare-os com a documentação da API. Depois, valide se eles estão corretos. Verifique se o endpoint selecionado corresponde ao local na solicitação/recurso.

Recurso esgotado

Problema: você está recebendo o erro a seguir.

RESOURCE_EXHAUSTED: Resource has been exhausted (e.g. check quota)

Solução: consulte Solicitar um ajuste de cota.

O bloco de streaming é muito grande

Problema: você está recebendo o erro a seguir.

INVALID_ARGUMENT: Request audio can be a maximum of 10485760 bytes.
[type.googleapis.com/util.MessageSetPayload='[google.rpc.error_details_ext]
{ message: "Request audio can be a maximum of 10485760 bytes." }']

Solução: diminua o tamanho dos trechos de áudio enviados. Recomendamos enviar partes de 100 ms para ter a melhor latência e evitar atingir o limite de áudio.

Geração de registros de dados

Problema: o Speech-to-Text não oferece o Cloud Logging.
Solução: como o Speech-to-Text tem a geração de registros de dados desativada por padrão, os clientes precisam ativá-la para envolvidos no projeto.

Solução de problemas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Não é possível se autenticar no Speech-to-Text

O Speech-to-Text retorna uma resposta vazia

Resolver problemas da RecognitionConfig

Solução de problemas relacionados à codificação

Configuração de modelo e linguagem

Erros de tempo limite

LongRunningRecognize ou BatchRecognize

StreamingRecognize

StreamingRecognize 409 cancelado

Qualidade da transcrição baixa

Enunciados curtos não são reconhecidos

Palavra ou frase consistentemente não reconhecida

Entradas em vários idiomas ou misturadas

Permissão negada

Argumento inválido

Recurso esgotado

O bloco de streaming é muito grande

Geração de registros de dados

Solução de problemas

Resolver problemas da `RecognitionConfig`

`LongRunningRecognize` ou `BatchRecognize`

`StreamingRecognize`

`StreamingRecognize` 409 cancelado