问题排查

如果您在使用 Speech-to-Text 时遇到问题，请查阅以下实用的问题排查步骤。

无法通过针对 Speech-to-Text 的身份验证

您可能会收到一条错误消息，指出您的“应用默认凭据”不可用，或者您可能想了解如何获取 API 密钥以在调用 Speech-to-Text 时使用。

Speech-to-Text 使用应用默认凭据 (ADC) 进行身份验证。

ADC 凭据必须在您调用 Speech-to-Text API 的上下文中可用。例如，如果您在终端中设置 ADC，但在 IDE 的调试程序中运行代码，则代码的执行上下文可能无权访问凭据。在这种情况下，对 Speech-to-Text 的请求可能会失败。

如需了解如何向 ADC 提供凭据，请参阅设置应用默认凭据。

Speech-to-Text 返回一个空响应

Speech-to-Text 可能返回空响应的原因有很多。问题的根源可能是 RecognitionConfig 或音频本身。

`RecognitionConfig` 问题排查

RecognitionConfig 对象（或 StreamingRecognitionConfig）是 Speech-to-Text 识别请求的一部分。为了正确执行转录，必须设置两个主要类别的字段：

音频配置。
模型和语言。

空响应（例如，您收到空的 {} JSON 响应）的最常见原因之一是提供有关音频元数据的信息错误。如果音频配置字段未正确设置，转录很可能失败，识别模型将返回空的结果。

音频配置包含所提供音频的元数据。您可以使用 ffprobe 命令（它是 FFMPEG 的一部分）来获取音频文件的元数据。

以下示例演示了如何使用 ffprobe 来获取 https://storage.googleapis.com/cloud-samples-tests/speech/commercial_mono.wav 的元数据。

$ 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

通过使用上述命令，我们可以看到该文件包含：

sample_rate_hertz：8000
渠道：1
编码 LINEAR16 (s16)

您可以在 RecognitionConfig 中使用此信息。

空响应的其他与音频相关的原因可能与音频编码有关。以下是一些其他工具和可以尝试的操作：

播放文件并听一听输出。音频是否清晰，语音是否易于理解？

如需播放文件，您可以使用 SoX (Sound eXchange) play 命令。下面显示了基于不同音频编码的几个示例。

FLAC 文件含有文件头，用于指示采样率、编码类型和声道数量。此类文件可通过以下命令进行播放：
```
play audio.flac
```
LINEAR16 文件不含文件头。要播放此类文件，您必须指定采样率、编码类型和声道数量。LINEAR16 编码必须是 16 位带符号整数，小端字节序。
```
play --channels=1 --bits=16 --rate=16000 --encoding=signed-integer \
--endian=little audio.raw
```
MULAW 文件也不含文件头，通常使用较低的采样率。
```
play --channels=1 --rate=8000 --encoding=u-law audio.raw
```
检查数据的音频编码是否与您在 RecognitionConfig 中发送的参数相匹配。例如，如果您的请求指定了 "encoding":"FLAC" 和 "sampleRateHertz":16000，则 SoX play 命令列出的音频数据参数应与这些参数匹配，如下所示：
```
play audio.flac
```
列出的参数应为：
```
Encoding: FLAC
Channels: 1 @ 16-bit
Sampleratehertz: 16000Hz
```
如果 SoX 列表显示的 Sampleratehertz 并非 16000Hz，请更改 InitialRecognizeRequest 中的 "sampleRateHertz" 以便匹配。如果 Encoding 不是 FLAC 或 Channels 不是 1 @ 16-bit，则不能直接使用此文件，需要将其转换为兼容的编码（请参阅下一步）。
如果音频文件不是 FLAC 编码，请尝试使用 SoX 将其转换为 FLAC，然后重复上述步骤播放该文件并验证编码、sampleRateHertz 和声道数。以下是将各种音频文件格式转换为 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
```
要将原始文件转换为 FLAC，您需要知道该文件的音频编码。例如，要将 16000Hz 的立体声 16 位带符号小端字节序转换为 FLAC，可使用以下代码：
```
sox --channels=2 --bits=16 --rate=16000 --encoding=signed-integer \
--endian=little audio.raw --channels=1 --bits=16 audio.flac
```
使用提供的示例音频文件运行快速入门示例或某个示例应用。如果该示例可成功运行，则将示例音频文件替换为您自己的音频文件。

模型和语言配置

选择正确的模型是获得高质量转录结果的关键。Speech-to-Text 提供了多种模型，这些模型已针对不同的使用场景进行了调整，必须选择最适合您的音频的模型。例如，某些模型（如 latest_short 和 command_and_search）是短形式模型，这意味着更适合简短的音频和提示。这些模型可能会在检测到静默期后立即返回结果。另一方面，长模型（例如 latest_short, phone_call, video and default）更适合较长的音频，并且将静默解读音频结尾的敏感度略低。

如果识别结束得太突然或未快速返回，您可能需要进行检查并用其他模型进行试验，以确定是否可以获得更好的转录质量。您可以使用语音界面试验多个模型。

超时错误

这些问题在大多数情况下是由错误配置或滥用 Speech-to-Text 导致的。

`LongRunningRecognize` 或 `BatchRecognize`

问题：您收到 TimeoutError: Operation did not complete within the designated timeout。
解决方案：您可以将转写内容发送到 Cloud Storage 存储桶，也可以在请求中延长超时时间。

如果 LongRunningRecognize 或 BatchRecognize 请求未在指定的超时时间内完成，并且此问题不是指示语音转写失败的错误，则会出现此问题。这意味着转写结果尚未准备好进行提取。

`StreamingRecognize`

问题：您收到 Timeout Error: Long duration elapsed without audio. Audio should be sent close to real time。
解决方案：需要缩短发送音频数据块之间的时间。如果 Speech-to-Text 每隔几秒钟未收到新的音频数据块，则会关闭连接并触发此错误。

`StreamingRecognize` 409 已取消

问题：您收到 409 Max duration of 5 minutes reached for stream 错误。
解决方案：您已达到5 分钟音频的流式识别限制。当您即将达到此上限时，请关闭数据流并打开新的数据流。

转写质量较低

自动语音识别 (ASR) 支持各种各样的用例。大多数质量问题都可以通过尝试不同的 API 选项来解决。为提高识别准确率，请遵循最佳做法中的准则。

系统无法识别短语

问题：“是”“否”和“下一步”等最终用户的短语不会被 API 捕获，在转写内容中缺失。
解决方案：请按以下步骤操作。
1. 使用不同的模型测试同一请求。
2. 添加语音自适应功能，并加强对缺失字词的识别。
3. 如果您使用的是流式输入，请尝试设置 single_utterance=true。

始终无法识别的字词或词组

问题：某些字词或词组始终被错误识别，例如 a 被识别为 8。
解决方案：请按以下步骤操作。

使用不同的模型测试同一请求。
添加语音自适应功能，并加强对缺失字词的识别。您可以使用类 token 来加强对整组字词（例如数字序列或地址）的识别。查看可用的类 token。
请尝试提高 max_alternatives。然后，检查 SpeechRecognitionResult alternatives，并选择第一个与所需格式匹配的结果。

格式设置可能对 ASR 来说是一个挑战。语音自适应通常有助于获取所需的格式，但可能需要进行后期处理以适应所需的格式。

混合或多语言输入

问题：音频包含多种语言的语音（例如英语说话者和西班牙语说话者之间的对话），导致转写内容有误。
解决方案：此功能不受支持。Speech-to-Text 每次请求只能转写一种语言。

权限遭拒

问题：您收到以下错误。

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).

解决方案：为 PROJECT_ID@gcp-sa-speech.iam.gserviceaccount.com提供权限，以便访问 BUCKET-PATH 存储桶中的文件。

参数无效

问题：您收到以下错误。

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

解决方案：检查参数并将其与 API 文档进行比较，然后验证它们是否正确。确保所选端点与请求 / 资源中的位置匹配。

资源已用完

问题：您收到以下错误。

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

解决方案：请参阅如何申请增加配额。

串流数据块过大

问题：您收到以下错误。

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." }']

解决方案：您需要减小发送的音频数据块的大小。我们建议您发送 100 毫秒的数据块，以获得最佳延迟时间并避免达到音频限制。

数据日志记录

问题：Speech-to-Text 不提供任何 Cloud Logging 日志。
解决方案：由于 Speech-to-Text 默认停用数据日志记录，因此客户需要在项目级别启用该功能。

问题排查

无法通过针对 Speech-to-Text 的身份验证

Speech-to-Text 返回一个空响应

RecognitionConfig 问题排查

模型和语言配置

超时错误

LongRunningRecognize 或 BatchRecognize

StreamingRecognize

StreamingRecognize 409 已取消

转写质量较低

系统无法识别短语

始终无法识别的字词或词组

混合或多语言输入

权限遭拒

参数无效

资源已用完

串流数据块过大

数据日志记录

`RecognitionConfig` 问题排查

`LongRunningRecognize` 或 `BatchRecognize`

`StreamingRecognize`

`StreamingRecognize` 409 已取消