トラブルシューティング

Speech-to-Text の使用中に問題が発生した場合に役立つトラブルシューティング手順について説明します。

Speech-to-Text を認証できない

「アプリケーションのデフォルト認証情報」が利用できないことを示すエラーメッセージが表示される場合や、Speech-to-Text を呼び出すときに使用する API キーを取得する方法がわからない場合があります。

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 認識リクエストの一部です。音声文字変換を正しく実行するには、主に次の 2 つのフィールドを設定する必要があります。

音声構成。
モデルと言語。

空のレスポンス（空の {} JSON レスポンスを受け取る場合など）の最も一般的な原因の一つは、音声メタデータに関する誤った情報が提供されることです。音声構成フィールドが正しく設定されていない場合、ほとんどのケースで音声文字変換が失敗し、認識モデルは空の結果を返します。

音声構成には、提供された音声のメタデータが含まれます。音声ファイルのメタデータは、FFMPEG の一部である ffprobe コマンドを使用して取得できます。

次の例では、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 ファイルを再生するには、サンプルレート、エンコードタイプ、チャンネル数を指定する必要があります。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 のリストに 16000Hz 以外の Sampleratehertz が示されている場合は、一致するように 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 に変換するには、ファイルの音声エンコードを知る必要があります。たとえば、16,000 Hz のステレオ 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 UI を使用して、複数のモデルを試すことができます。

タイムアウトエラー

これらの問題のほとんどは、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」と認識されるなど）。
解決策: 次の手順を行います。

同じリクエストを異なるモデルでテストします。
音声適応を追加し、不足している単語をブーストします。クラストークンを使用すると、数字のシーケンスや住所など、単語のセット全体をブーストできます。使用可能なクラストークンを確認します。
max_alternatives を増やしてみてください。次に、SpeechRecognitionResult alternatives を確認し、目的の形式に一致する最初のものを選択します。

ASR では、フォーマットが難しい場合があります。多くの場合、音声適応によって必要な形式を取得できますが、必要な形式に合わせて後処理が必要になる場合があります。

混合または複数の言語入力

問題: 音声に複数の言語の音声が含まれている（英語とスペイン語の話し手との会話など）ため、正しく音声文字変換されない。
解決策: この機能はサポートされていません。Speech-to-Text では、リクエストごとに文字起こしできる言語は 1 つのみです。

アクセスが拒否されました

問題: 次のエラーが表示される。

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 が中止される

ストリーミングチャンクが大きすぎる