トラブルシューティング

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 認識リクエストの一部です。音声文字変換を正しく実行するには、次の主なカテゴリに分類されるフィールドを設定します。

音声構成
モデルと言語

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

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

次の例で示すのは、この音声サンプルのメタデータを取得するためにコマンドを使用する方法です。

$ 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

このファイルでは 8,000 Hz、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: 16000 Hz
```
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 Aborted

問題: 409 Max duration of 5 minutes reached for stream エラーが表示される。
解決策: ストリーミング認識の上限である 5 分間の音声に達しています。この上限に近づいたら、ストリームを閉じて新しいストリームを開きます。

文字起こしの品質が低い

自動音声認識（ASR）は、さまざまなユースケースをサポートしています。品質に関するほとんどの問題は、さまざまな API オプションを試すことで解決できます。認識の精度を向上させるには、ベストプラクティスのガイドラインを守ってください。

短い発話が認識されない

問題: 「はい」、「いいえ」、「次へ」といったエンドユーザーの短い発話が API によってキャプチャされず、文字起こしに表示されない。
解決策: 次の操作を行います。
1. 同じリクエストを異なるモデルでテストします。
2. 音声適応を追加し、不足している単語をブーストします。
3. ストリーミング入力を使用している場合は、single_utterance=true を設定してみます。

常に認識されない単語やフレーズ

問題: 特定の単語やフレーズが常に誤って認識される（「a」が「8」と認識されるなど）。
解決策: 次の操作を行います。
1. 同じリクエストを異なるモデルでテストします。
2. 音声適応を追加し、不足している単語をブーストします。クラストークンを使用すると、数字列や住所など、単語のセット全体をブーストできます。使用可能なクラストークンを確認します。
3. 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 Aborted

文字起こしの品質が低い

短い発話が認識されない

常に認識されない単語やフレーズ

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

アクセスが拒否される

引数が無効です

リソースが不足している

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

データロギング

トラブルシューティング

`RecognitionConfig` のトラブルシューティング

タイムアウトエラー

`LongRunningRecognize` または `BatchRecognize`

`StreamingRecognize`

`StreamingRecognize` 409 Aborted

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