문제 해결

Speech-to-Text를 사용할 때 문제가 발생할 경우에 유용한 문제 해결 단계에 대해 알아보세요.

Speech-to-Text에 인증할 수 없음

'애플리케이션 기본 사용자 인증 정보'를 사용할 수 없다는 오류 메시지가 표시되거나 Speech-to-Text를 호출할 때 사용할 API 키를 가져오는 방법이 궁금할 수 있습니다.

Speech-to-Text는 인증에 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용합니다.

Speech-to-Text API를 호출하는 컨텍스트 내에서 ADC의 사용자 인증 정보를 사용할 수 있어야 합니다. 예를 들어 터미널에서 ADC를 설정했는데 IDE의 디버거에서 코드를 실행하면 코드의 실행 컨텍스트가 사용자 인증 정보에 액세스하지 못할 수 있습니다. 이 경우 Speech-to-Text 요청이 실패할 수 있습니다.

ADC에 사용자 인증 정보를 제공하는 방법은 애플리케이션 기본 사용자 인증 정보 설정을 참조하세요.

Speech-to-Text에서 빈 응답을 반환함

Speech-to-Text에서 빈 응답을 반환하는 이유는 여러 가지가 있습니다. 문제의 원인은 RecognitionConfig 또는 오디오 자체일 수 있습니다.

문제 해결 RecognitionConfig

RecognitionConfig 객체(또는 StreamingRecognitionConfig)는 Speech-to-Text 인식 요청의 일부입니다. 스크립트 작성을 올바르게 수행하기 위해 설정해야 하는 두 가지 주요 필드 카테고리가 있습니다.

  • 오디오 구성.
  • 모델 및 언어.

빈 응답(예시: 빈 {} 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에서 사용할 수 있습니다.

빈 응답의 추가 오디오 관련 이유는 오디오 인코딩과 관련이 있을 수 있습니다. 다음과 같은 몇 가지 도구 및 작업을 사용해 볼 수 있습니다.

  1. 파일을 재생하여 출력을 듣습니다. 오디오가 깨끗하고 말을 이해할 수 있나요?

    파일을 재생하려면 SoX(Sound eXchange)play 명령어를 사용하면 됩니다. 서로 다른 오디오 인코딩을 바탕으로 한 몇 가지 예가 아래에 있습니다.

    FLAC 파일에는 샘플링 레이트, 인코딩 유형, 채널 수를 나타내는 헤더가 포함되어 있으며 다음과 같이 FLAC 파일을 재생할 수 있습니다.

    play audio.flac

    LINEAR16 파일에는 헤더가 없습니다. 이 파일을 재생하려면 샘플링 레이트, 인코딩 유형, 채널 수를 지정해야 합니다. LINEAR16 인코딩은 16비트, 부호 있는 정수, little-endian이어야 합니다.

    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

  2. 데이터의 오디오 인코딩이 RecognitionConfig에 전송한 매개변수와 일치하는지 확인합니다. 예를 들어 요청으로 "encoding":"FLAC" 및 "sampleRateHertz":16000이 지정된 경우 SoXplay 명령어로 나열되는 오디오 데이터 매개변수는 다음과 같이 해당 매개변수와 일치해야 합니다.

    play audio.flac

    다음과 같아야 합니다.

    Encoding: FLAC
Channels: 1 @ 16-bit
Sampleratehertz: 16000Hz

    SoX 목록에 16000Hz가 아닌 Sampleratehertz가 표시되면 InitialRecognizeRequest의 "sampleRateHertz"를 변경하여 일치시킵니다. Encoding이 FLAC이 아니거나 Channels가 1 @ 16-bit가 아닌 경우, 이 파일을 직접 사용할 수 없으며 호환 인코딩으로 변환해야 합니다(다음 단계 참조).

  3. 오디오 파일이 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비트 부호 있는 little-endian을 FLAC으로 변환하려면 다음과 같이 합니다.

    sox --channels=2 --bits=16 --rate=16000 --encoding=signed-integer \
--endian=little audio.raw --channels=1 --bits=16 audio.flac

  4. 빠른 시작의 예시 또는 샘플 애플리케이션 중 하나를 제공된 샘플 오디오 파일과 함께 실행합니다. 예가 성공적으로 실행되면 샘플 오디오 파일을 원하는 오디오 파일로 바꿉니다.

모델 및 언어 구성

모델 선택은 고품질 스크립트 작성 결과를 얻는 데 매우 중요합니다. Speech-to-Text는 다양한 사용 사례에 맞게 조정된 여러 모델을 제공하며, 오디오와 가장 가깝게 일치하도록 선택해야 합니다. 예를 들어 일부 모델(예: latest_short 및 command_and_search)은 짧은 양식 모델이므로 짧은 오디오와 프롬프트에 더 적합합니다. 이러한 모델은 무음 기간이 감지되는 즉시 결과를 반환할 가능성이 높습니다. 반면 긴 형식 모델(예: latest_short, phone_call, video and default)은 긴 오디오에 더 적합하며 무음을 오디오의 끝으로 민감하게 해석하지 않습니다.

인식이 너무 갑자기 종료되거나 신속하게 반환되지 않으면 다른 모델을 확인하고 실험하여 스크립트 작성 품질을 향상시킬 수 있는지 확인하는 것이 좋습니다. 음성 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로 인식됨).

  • 해결 방법: 다음 단계를 따르세요.

    1. 동일한 요청을 서로 다른 모델로 테스트합니다.

    2. 음성 적응을 추가하고 누락된 단어를 부스트합니다. 클래스 토큰을 사용하여 숫자 시퀀스나 주소와 같은 단어의 전체 집합을 부스트할 수 있습니다. 사용 가능한 클래스 토큰을 확인하세요.

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

  • 해결 방법: 전송되는 오디오 청크의 크기를 줄여야 합니다. 최적의 지연 시간을 달성하고 오디오 한도에 도달하지 않도록 100ms의 청크를 전송하는 것이 좋습니다.

데이터 로깅

  • 문제: Speech-to-Text가 Cloud Logging을 제공하지 않습니다.

  • 해결 방법: Speech-to-Text는 기본적으로 데이터 로깅이 사용 중지되어 있으므로 고객이 프로젝트 수준에서 사용 설정해야 합니다.