REST API를 이용한 음성 인식 시작하기 (PowerShell, cUrl, C#)

등록일시: 2018-02-01 08:00,  수정일시: 2018-02-01 08:00
조회수: 1,300
이 문서는 Cognitive Services 기술을 널리 알리고자 하는 개인적인 취지로 제공되는 번역문서입니다. 이 문서에 대한 모든 저작권은 마이크로소프트에 있으며 요청이 있을 경우 언제라도 게시가 중단될 수 있습니다. 번역 내용에 오역이 존재할 수 있고 주석은 번역자 개인의 의견일 뿐이며 마이크로소프트는 이에 관한 어떠한 보장도 하지 않습니다. 번역이 완료된 이후에도 대상 제품 및 기술이 개선되거나 변경됨에 따라 원문의 내용도 변경되거나 보완되었을 수 있으므로 주의하시기 바랍니다.
본문에서는 다양한 언어 및 도구로 REST API를 이용해서 Speech API를 사용하는 방법을 살펴봅니다.

클라우드 기반의 음성 서비스를 이용하면 REST API를 사용해서 음성 오디오를 텍스트로 변환하는 응용 프로그램을 개발할 수 있습니다.

요구 사항

Speech API 구독 및 무료 평가판 구독 키 발급받기

Speech API는 Microsoft Cognitive Services의 (구 프로젝트 Oxford) 일부분입니다. 무료 평가판 구독 키는 Cognitive Services 체험하기 페이지에서 발급받을 수 있습니다. 음성 탭에서 Bing Speech API를 선택한 다음, API 키 가져오기(Get API Key) 버튼을 클릭합니다. 그러면 기본 키와 보조 키가 발급됩니다. 두 키 모두 동일한 할당량에 연결되어 있으므로 두 키 중 아무 키나 사용해도 무방합니다.

중요
  • 구독 키 발급받기. REST API에 접근하려면 반드시 구독 키가 필요합니다.

  • 구독 키 사용하기. 본문의 REST 예제에서 YOUR_SUBSCRIPTION_KEY 부분을 여러분의 구독 키로 대체합니다.

  • 구독 키의 사용 방법은 Authentication 문서를 참고하시기 바랍니다.

미리 녹음된 오디오 파일

본문의 예제에서는 미리 녹음된 오디오 파일을 이용해서 REST API를 사용하는 방법을 살펴봅니다. 직접 짧은 문장을 말해서 오디오 파일로 녹음해도 무방합니다. 가령, "오늘 날씨는 어때?" 또는 "볼만한 재미있는 영화를 찾아줘."라고 말하면 됩니다. 음성 인식 API는 외부 마이크 입력도 지원합니다.

노트

본문의 예제에서는 PCM 단일 채널 (모노), 16KHz로 녹음된 WAV 오디오 파일이 필요합니다.

역주

아쉽지만 Interactive 모드와 Dictation 모드에서만 한국어를 지원하고, Conversation 모드에서는 한국어를 지원하지 않습니다.

인식 요청을 만들고 음성 인식 서비스로 전송하기

음성 인식을 위한 다음 단계는, 올바른 요청 헤더와 본문을 사용해서 Speech HTTP 끝점에 POST 요청을 전송하는 것입니다.

서비스 URI

음성 인식 서비스의 URI는 인식 모드인식 언어를 기반으로 정의됩니다:

https://speech.platform.bing.com/speech/recognition/<RECOGNITION_MODE>/cognitiveservices/v1?language=<LANGUAGE_TAG>&format=<OUTPUT_FORMAT>

<RECOGNITION_MODE>는 인식 모드를 지정하며, 그 값은 interactive, conversation, 또는 dictation 중 하나이어야 합니다. 이 값은 URI의 필수 자원 경로입니다. 보다 자세한 정보는 Recognition modes 절을 참고하시기 바랍니다.

<LANGUAGE_TAG>는 쿼리 문자열의 필수 매개 변수입니다. 이 값은 오디오를 변환하기 위한 대상 언어를 정의하는데, 가령 en-US는 영어(미국)을 뜻합니다. 보다 자세한 정보는 Recognition languages 절을 참고하시기 바랍니다.

<OUTPUT_FORMAT>는 쿼리 문자열의 선택적 매개 변수입니다. 값으로는 simpledetailed를 지정할 수 있습니다. 기본적으로 서비스는 simple 형식으로 결과를 반환합니다. 보다 자세한 정보는 Output format 절을 참고하시기 바랍니다.

다음 표는 서비스 URI의 몇 가지 사례를 보여줍니다.

노트

응용 프로그램에서 REST API를 이용해서 음성 인식 서비스를 호출하는 경우에만 서비스 URI가 필요합니다. 클라이언트 라이브러리 중 하나를 사용할 경우에는 일반적으로 사용되는 URI를 알아야 할 필요가 없습니다. 클라이언트 라이브러리에 따라서는 특정 클라이언트 라이브러리에만 적용되는 별도의 서비스 URI를 사용할 수도 있습니다. 더 자세한 내용은 해당 클라이언트 라이브러리를 참고하시기 바랍니다.

요청 헤더

요청 헤더에는 반드시 다음 필드들이 설정되어 있어야 합니다:

  • Ocp-Apim-Subscription-Key: 서비스를 호출할 때마다 Ocp-Apim-Subscription-Key 헤더에 구독 키를 전달해야 합니다. 음성 서비스는 구독 키 대신 인증 토큰을 전달하는 기능도 지원합니다. 더 자세한 정보는 Authentication 문서를 참고하시기 바랍니다.

  • Content-type: Content-type 필드는 오디오 스트림의 형식과 코덱을 기술합니다. 현재는 WAV 파일 및 PCM 모노 16000 인코딩만 지원됩니다. 이 형식에 대한 Content-type 값은 audio/wav; codec=audio/pcm; samplerate=16000 입니다.

Transfer-Encoding 필드는 선택 사항입니다. 이 필드를 chunked로 설정하면 오디오를 작은 청크로 자를 수 있습니다. 보다 자세한 정보는 Chunked transfer 문서를 참고하시기 바랍니다.

다음은 요청 헤더의 사례입니다:

POST https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codec=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: speech.platform.bing.com
Transfer-Encoding: chunked
Expect: 100-continue

서비스에 요청 전송하기

다음 예제는 Speech REST 끝점에 음성 인식 요청을 전송하는 방법을 보여줍니다. 이 예제는 interactive 인식 모드를 사용합니다.

노트

YOUR_AUDIO_FILE의 값을 미리 녹음한 오디오 파일의 경로로 변경합니다. 그리고 YOUR_SUBSCRIPTION_KEY 값도 여러분의 구독 키로 변경합니다.

$SpeechServiceURI =
'https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-us&format=detailed'

# $OAuthToken is the authorization token returned by the token service.
$RecoRequestHeader = @{
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY';
  'Transfer-Encoding' = 'chunked'
  'Content-type' = 'audio/wav; codec=audio/pcm; samplerate=16000'
}

# Read audio into byte array
$audioBytes = [System.IO.File]::ReadAllBytes("YOUR_AUDIO_FILE")

$RecoResponse = Invoke-RestMethod -Method POST -Uri $SpeechServiceURI -Headers $RecoRequestHeader -Body $audioBytes

# Show the result
$RecoResponse

음성 인식 응답 처리하기

Speech Service는 요청을 처리한 다음, 그 결과를 JSON 형식의 응답으로 반환합니다.

노트

예제 코드가 오류를 반환할 경우, Troubleshooting 문서를 참고해서 원인을 찾습니다.

다음 코드 스니핏은 스트림에서 응답을 읽는 방법을 보여줍니다.

# show the response in JSON format
ConvertTo-Json $RecoResponse

다음은 JSON 응답 예제입니다:

OK
{
  "RecognitionStatus": "Success",
  "Offset": 22500000,
  "Duration": 21000000,
  "NBest": [{
    "Confidence": 0.941552162,
    "Lexical": "find a funny movie to watch",
    "ITN": "find a funny movie to watch",
    "MaskedITN": "find a funny movie to watch",
    "Display": "Find a funny movie to watch."
  }]
}

제한사항

REST API에는 몇 가지 제한사항이 존재합니다:

  • 최대 15 초까지만 오디오 스트림을 지원합니다.
  • 인식 중간에 중간 결과를 지원하지 않습니다. 사용자는 최종 인식 결과만 반환받습니다.

이런 제한사항을 해소하기 위해서는 음성 클라이언트 라이브러리를 사용해야 합니다. 또는 Speech WebSocket 프로토콜을 사용해서 직접 작업을 수행할 수도 있습니다.

다음 단계

라이센스

모든 Cognitive Services SDK 및 예제는 MIT 라이센스가 적용됩니다. 보다 자세한 정보는 라이센스를 참고하시기 바랍니다.