연결 열기

Speech to Text 서비스는 WSS(WebSocket Secure) 프로토콜을 사용하여 /v1/recognize 메소드를 다음 엔드포인트에서 사용할 수 있도록 합니다.

wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}/v1/recognize

여기서 {location}은 애플리케이션의 호스팅 위치를 나타냅니다.

• us-south는 댈러스
• us-east는 워싱턴 DC
• eu-de는 프랑크푸르트
• au-syd는 시드니
• jp-tok는 도쿄
• eu-gb는 런던
• kr-seo는 서울

그리고 {instance_id}은(는) 서비스 인스턴스의 고유 ID입니다.

이 문서에 있는 예에서는 wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}을(를) {ws_url}(으)로 축약합니다. 모든 WebSocket 예는 이 메소드를 {ws_url}/v1/recognize(으)로 호출합니다.

WebSocket 클라이언트는 다음 쿼리 매개변수를 사용해 /v1/recognize 메소드를 호출하여 서비스와의 사이에 인증된 연결을 설정합니다. 요청의 이러한 측면은 WebSocket URL의 쿼리 매개변수로만 지정할 수 있습니다.

access_token(필수 문자열)

유효한 액세스 토큰을 전달하여 서비스와의 사이에 인증된 연결을 설정합니다. 액세스 토큰이 만료되기 전에 연결을 설정해야 합니다. 인증된 연결을 설정하기 위해서만 액세스 토큰을 전달합니다. 연결을 설정하면 무기한으로 활성 상태로 유지할 수 있습니다. 연결이 열려 있는 동안에는 계속 인증된 상태로 유지됩니다. 토큰 만기 시간 이후 지속되는 활성 연결에 대한 액세스 토큰을 새로 고칠 필요가 없습니다. 연결은 한 번 설정되고 나면 토큰 또는 해당 인증 정보가 삭제된 후에도 활성 상태를 유지할 수 있습니다.

• IBM Cloud Identity and Access Management (IAM) 액세스 토큰을 전달하여 서비스 인증을 받습니다. 호출 시 API 키를 전달하는 대신 IAM 액세스 토큰을 전달합니다. 자세한 정보는 IBM Cloud에 대한 인증을 참조하십시오.
• IBM Cloud Pak for Data 노즈비 IBM Software Hub Authorization HTTP 요청의 액세스 토큰 헤더를 전달하는 것처럼 액세스 토큰을 전달합니다. 자세한 내용은 IBM Cloud Pak for Data 에 대한 인증을 참조하세요.

model(선택적 문자열)

변환에 사용될 언어 모델을 지정합니다. 모델을 지정하지 않은 경우, 서비스는 기본적으로 en-US_BroadbandModel을(를) 사용합니다. 자세한 정보는 다음을 참조하십시오.

• 대형 음성 언어 및 모델
• 이전 세대 언어 및 모델
• 차세대 언어 및 모델
• 기본 모델 사용

language_customization_id(선택적 문자열)

연결을 통해 전송되는 모든 요청에 사용될 사용자 정의 언어 모델의 GUID(Globally Unique Identifier)를 지정합니다. 사용자 정의 언어 모델의 기본 모델은 model 매개변수의 값과 일치해야 합니다. 사용자 정의 언어 모델 ID를 포함시키는 경우에는 해당 사용자 정의 모델을 소유하는 서비스 인스턴스에 대한 인증 정보로 요청을 수행해야 합니다. 기본적으로 사용자 정의 언어 모델은 사용되지 않습니다. 자세한 정보는 음성 인식에 사용자 정의 언어 모델 사용을 참조하십시오.

acoustic_customization_id(선택적 문자열)

연결을 통해 전송되는 모든 요청에 대해 사용될 사용자 정의 음향 모델의 GUID를 지정합니다. 사용자 정의 음향 모델의 기본 모델은 model 매개변수의 값과 일치해야 합니다. 사용자 정의 음향 모델 ID를 포함시키는 경우에는 해당 사용자 정의 모델을 소유하는 서비스 인스턴스에 대한 인증 정보로 요청을 수행해야 합니다. 기본적으로 사용자 정의 음향 모델은 사용되지 않습니다. 자세한 정보는 음성 인식에 사용자 정의 음향 모델 사용을 참조하십시오.

base_model_version(선택적 문자열)

연결을 통해 전송되는 모든 요청에 사용될 기본 model의 버전을 지정합니다. 이 매개변수는 주로 새 기본 모델용으로 업그레이드된 사용자 정의 모델과 함께 사용하기 위한 것입니다. 기본값은 매개변수가 사용자 정의 모델과 함께 사용되는지 여부에 따라 다릅니다. 자세한 정보는 업그레이드된 사용자 정의 모델을 사용하여 음성 인식 요청을 참조하십시오.

x-watson-metadata(선택적 문자열)

연결을 통해 전달되는 모든 데이터와 고객 ID를 연관시킵니다. 매개변수는 customer_id={id} 인수를 허용합니다. 여기서, id는 무작위 문자열이거나 데이터와 연관되는 일반 문자열입니다. 매개변수에 대한 인수를 URL 인코딩해야 합니다(예: customer_id%3dmy_customer_ID). 기본적으로 고객 ID가 데이터와 연관되지 않습니다. 자세한 정보는 정보 보안을 참조하십시오.

x-watson-learning-opt-out(*선택적 * 부울)

IBM Cloud 서비스에서 연결을 통해 전송된 요청 및 결과를 기록할지 여부를 나타냅니다. IBM에서 일반적인 서비스 개선을 위해 데이터에 액세스하지 못하게 하려면 이 매개변수를 true로 지정하십시오. 자세한 정보는 요청 로깅을 참조하십시오.

다음 JavaScript 코드의 스니펫을 통해 서비스와의 연결이 열립니다. /v1/recognize 메소드에 대한 호출이 access_token 및 model 조회 매개변수를 전달하며, model 매개변수는 스페인어 광대역 모델을 사용하도록 서비스에 지시합니다. 클라이언트가 연결을 설정한 후 서비스의 이벤트에 응답하기 위해 이벤트 리스너(onOpen, onClose 등)를 정의합니다. 클라이언트는 여러 인식 요청에 대해 연결을 사용할 수 있습니다.

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token
  + '&model=es-ES_BroadbandModel';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

클라이언트는 서비스에 대한 여러 개의 동시 WebSocket 연결을 열 수 있습니다. 동시 연결 수는 서비스 용량에 따라서만 제한되며 일반적으로 사용자에게는 문제가 되지 않습니다.

인식 요청 시작

인식 요청을 시작하기 위해 클라이언트가 설정된 연결을 통해 서비스에 JSON 텍스트 메시지를 전송합니다. 클라이언트는 텍스트 변환을 위해 오디오를 전송하기 전에 이 메시지를 전송해야 합니다. 이 메시지는 action 매개변수를 포함해야 하지만 content-type 매개변수는 일반적으로 생략할 수 있습니다.

action(필수 문자열)

수행될 조치를 지정합니다.

• start는 인식 요청을 시작합니다. 이는 후속 요청에 대한 새 매개변수도 지정할 수 있습니다. 자세한 정보는 추가 요청 전송 및 요청 매개변수 수정을 참조하십시오.
• stop은 요청에 대한 모든 오디오가 전송되었다는 신호를 보냅니다. 자세한 정보는 인식 요청 종료를 참조하십시오.

content-type(선택적 문자열)

요청에 대한 오디오 데이터의 형식(MIME 유형)을 식별합니다. 이 매개변수는 audio/alaw, audio/basic, audio/l16 및 audio/mulaw 형식에 필요합니다. 자세한 정보는 오디오 형식을 참조하십시오.

메시지에는 요청이 처리되는 방법 및 리턴될 정보의 다른 측면을 지정하기 위한 선택적 매개변수가 포함될 수도 있습니다. 이러한 추가 매개변수에는 interim_results 매개변수가 있으며, 이는 WebSocket 인터페이스에서만 사용할 수 있습니다.

• 모든 음성 인식 기능에 대한 자세한 정보는 매개변수 요약을 참조하십시오.
• interim_results 매개변수에 대한 자세한 정보는 중간 결과의 내용을 참조하십시오.

다음 JavaScript 코드 스니펫은 WebSocket 연결을 통해 인식 요청에 대한 초기화 매개변수를 전송합니다. 호출은 연결이 설정된 후에만 전송되도록 클라이언트의 onOpen 함수에 포함됩니다.

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/l16;rate=22050'
  };
  websocket.send(JSON.stringify(message));
}

서비스는 요청을 성공적으로 수신하는 경우 다음 텍스트 메시지를 리턴하여 자신이 listening 상태임을 표시합니다. listening 상태는 서비스 인스턴스가 구성되었으며(JSON start 메시지가 유효함) 인식 요청에 대한 오디오를 수락할 준비가 되었음을 나타냅니다.

{'state': 'listening'}

클라이언트가 인식 요청을 위해 올바르지 않은 조회 매개변수 또는 JSON 필드를 지정하면 서비스의 JSON 응답에 warnings 필드가 포함됩니다. 이 필드는 각각의 올바르지 않은 인수에 대해 설명합니다. 경고가 발생하지만 요청이 성공합니다.

오디오 전송 및 인식 결과 수신

클라이언트는 첫 start 메시지를 전송하고 나면 서비스에 오디오 데이터를 전송하기 시작할 수 있습니다. 클라이언트는 서비스가 start 메시지로 listening 메시지에 응답할 때까지 대기할 필요가 없습니다. 청취가 시작되면 서비스가 listening 메시지 이전에 전송된 오디오를 처리합니다.

클라이언트는 오디오를 2진 데이터로 전송해야 합니다. 클라이언트는 send 요청당 최대 100MB의 오디오 데이터를 전송할 수 있습니다. 모든 요청에 대해 최소한 100바이트의 오디오를 전송해야 합니다. 클라이언트는 하나의 WebSocket 연결을 통해 여러 요청을 전송할 수 있습니다. 요청으로 서비스에 전달할 수 있는 오디오의 양을 최대화하기 위해 압축을 사용하는 데 대한 정보는 데이터 한계 및 압축을 참조하십시오.

WebSocket 인터페이스는 최대 4MB의 프레임 크기를 부과합니다. 클라이언트는 최대 프레임 크기를 4MB 미만으로 설정할 수 있습니다. 프레임 크기를 설정하는 것이 실용적이지 않은 경우 클라이언트가 최대 메시지 크기를 4MB 미만으로 설정하고 오디오 데이터를 일련의 메시지로 전송할 수 있습니다. WebSocket 프레임에 대한 자세한 내용은 IETF RFC 6455를 참조하세요.

서비스가 WebSocket 연결을 통해 인식 결과를 전송하는 방식은 클라이언트의 중간 결과 요청 여부에 따라 달라집니다. 자세한 정보는 서비스의 인식 결과 전송 방식을 참조하십시오.

다음 JavaScript 코드 스니펫은 오디오 데이터를 2진 메시지(blob)로 서비스에 전송합니다.

websocket.send(blob);

다음 스니펫은 서비스가 비동기식으로 리턴하는 인식 가설을 수신합니다. 클라이언트의 onMessage 함수에서 결과를 처리합니다.

function onMessage(evt) {
  console.log(evt.data);
}

사용자의 코드는 서비스의 리턴 코드를 처리할 수 있도록 준비되어 있어야 합니다. 자세한 정보는 WebSocket 리턴 코드를 참조하십시오.

인식 요청 종료

요청에 대한 오디오 데이터를 서비스에 전송하는 작업이 완료되면 클라이언트가 다음 방법 중 하나로 서비스에 2진 오디오 전송의 종료 신호를 반드시 보내야 합니다.

• action 매개변수가 stop 값으로 설정된 JSON 텍스트 메시지 전송:

  {action: 'stop'}
  

• 비어 있는 2진 메시지(지정된 blob이 비어 있음) 전송:

  websocket.send(blob)
  

클라이언트가 전송이 완료되었음을 알리는 데 실패하는 경우에는 서비스가 최종 결과를 전송하지 않고 연결이 제한시간을 초과할 수 있습니다. 여러 인식 요청 사이에 최종 결과를 수신하려면 클라이언트가 후속 요청을 전송하기 전에 이전 요청에 대한 전송이 종료되었다는 신호를 보내야 합니다. 서비스가 첫 번째 요청에 대한 최종 결과를 리턴한 후 다른 {"state":"listening"} 메시지를 클라이언트에 리턴합니다. 이 메시지는 서비스가 다른 요청을 수신할 준비가 되었음을 표시합니다.

추가 요청 전송 및 요청 매개변수 수정

WebSocket 연결이 활성 상태로 유지되는 동안 클라이언트가 계속해서 연결을 사용하여 새 오디오로 추가 인식 요청을 전송할 수 있습니다. 기본적으로 서비스는 동일한 연결을 통해 전송된 모든 후속 요청에 대해 이전 start 메시지와 함께 전송된 매개변수를 계속 사용합니다.

클라이언트는 후속 요청에 대한 매개변수를 변경하기 위해, 서비스에서 최종 인식 결과 및 새 {"state":"listening"} 메시지를 수신한 후 새 매개변수를 포함하는 다른 start 메시지를 전송할 수 있습니다. 클라이언트는 연결이 열릴 때 지정된 매개변수(model, language_customization_id 등)를 제외한 모든 매개변수를 변경할 수 있습니다.

다음 예제에서는 연결을 통해 전송된 후속 인식 요청에 대한 새 매개변수가 포함된 start 메시지를 전송합니다. 이 메시지는 이전 예제와 동일한 content-type을 지정하지만 텍스트 변환 단어에 대한 신뢰도 측정값 및 시간소인을 리턴하도록 서비스에 지시합니다.

var message = {
  action: 'start',
  content-type: 'audio/l16;rate=22050',
  word_confidence: true,
  timestamps: true
};
websocket.send(JSON.stringify(message));

연결 활성 상태 유지

비활성 또는 세션 제한시간 초과가 발생하면 서비스가 세션을 종료하고 연결을 닫습니다.

• 클라이언트가 오디오를 전송 중이지만 서비스가 음성을 감지하지 못하는 경우 비활성 제한시간 초과가 발생합니다. 기본적으로 비활성 제한시간은 30초입니다. inactivity_timeout 매개변수를 사용하여 제한시간을 무한대로 설정하는 -1을 포함한 다른 값으로 지정할 수 있습니다. 자세한 정보는 비활성 제한시간을 참조하십시오.
• 서비스가 클라이언트로부터 데이터를 수신하지 않거나 30초 동안 중간 결과를 전송하지 않으면 세션 제한시간 초과가 발생합니다. 이 제한시간의 기간을 변경할 수는 없지만 제한시간 초과가 발생하기 전에 무음을 포함한 오디오 데이터를 서비스에 전송하여 세션을 연장할 수 있습니다. 또한 inactivity_timeout을 -1로 설정해야 합니다. 세션을 연장하기 위해 전송하는 무음을 포함하여 서비스에 전송하는 모든 데이터의 지속 시간 동안 비용이 청구됩니다. 자세한 정보는 세션 제한시간 초과를 참조하십시오.

WebSocket 클라이언트 및 서버도 적은 양의 데이터를 주기적으로 교환하여 읽기 제한시간 초과가 발생하지 않도록 ping-pong 프레임을 교환할 수 있습니다. 많은 WebSocket 스택은 핑퐁 프레임을 교환하지만 일부는 교환하지 않습니다. 사용자의 구현에서 핑퐁 프레임을 사용하는지 여부를 판별하려면 기능 목록을 확인하십시오. 프로그래밍 방식으로 핑퐁 프레임을 판별하거나 관리할 수 없습니다.

WebSocket 스택이 핑퐁 프레임을 구현하지 않고 사용자가 긴 오디오 파일을 전송하는 경우 연결 중에 읽기 제한시간 초과가 발생할 수 있습니다. 이러한 제한시간 초과가 발생하지 않도록 하려면 계속해서 오디오를 서비스에 스트리밍하거나 서비스에서 중간 결과를 요청하십시오. 둘 중 어떠한 접근 방법에서도 핑퐁 프레임의 부족으로 인해 연결이 닫히지 않습니다.

핑퐁 프레임에 대한 자세한 내용은 IETF RFC 6455의 섹션 5.5.2 핑 및 섹션 5.5.3 핑을 참조하세요.

연결 닫기

클라이언트가 서비스와의 상호작용을 완료하면 WebSocket 연결을 닫을 수 있습니다. 연결이 닫히면 클라이언트가 더 이상 요청을 전송하거나 결과를 수신할 수 없습니다. 클라이언트가 요청에 대한 모든 결과를 수신한 후에만 연결을 닫으십시오. 연결은 클라이언트가 명시적으로 닫지 않는 경우, 결국에는 제한시간을 초과하여 닫힙니다.

다음 JavaScript 코드 스니펫은 열린 연결을 닫습니다.

websocket.close();

중간 결과가 없는 요청 예

클라이언트는 interim_results 매개변수를 false(으)로 설정하거나 요청에서 이 매개변수를 생략하여 중간 결과를 사용 안함으로 설정합니다(이 매개변수의 기본 인수는 false임). 클라이언트는 stop 메시지를 전송한 후에만 응답으로 단일 JSON 오브젝트를 수신합니다.

이 응답 오브젝트는 오디오의 개별 발화에 대한 여러 최종 결과를 포함할 수 있습니다. 서비스는 요청에 대한 오디오 전송이 완료되었음을 나타내는 stop 메시지를 수신할 때까지 단일 응답 오브젝트를 전송하지 않습니다. 서비스 응답의 구조 및 형식은 이전 세대 모델 또는 차세대 모델의 사용 여부에 관계없이 동일합니다.

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    },
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

중간 결과가 있는 요청 예

클라이언트가 다음과 같이 중간 결과를 요청합니다.

• 이전 세대 모델의 경우, interim_results 매개변수를 true(으)로 설정합니다.
• 차세대 모델의 경우 interim_results 매개 변수를 true 으로 설정합니다. low_latency 을 true 으로 설정하여 모델에 대해 중간 결과와 짧은 대기 시간을 함께 사용하도록 설정할 수도 있습니다.
  • 낮은 지연 시간을 지원하는 차세대 모델에 대한 자세한 정보는 지원되는 차세대 모델을 참조하십시오.

클라이언트는 응답으로 여러 JSON 오브젝트를 수신합니다. 서비스는 오디오에 의해 생성된 각 중간 결과 및 각 최종 결과에 대해 개별 응답 오브젝트를 리턴합니다. 서비스는 각 최종 결과에 대해 하나 이상의 중간 결과를 전송합니다.

서비스는 응답을 사용 가능해지는 즉시 전송합니다. 이는 결과를 전송하는 데 stop 메시지를 기다리지 않지만, stop 메시지는 요청에 대한 전송의 종료를 나타내기 위해 여전히 필요합니다. 서비스 응답의 구조 및 형식은 이전 세대 모델 또는 차세대 모델의 사용 여부에 관계없이 동일합니다.

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one two "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three four "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

첫 번째 예제 교환

첫 번째 예제 교환에서는 클라이언트가 Name the Mayflower라는 문자열이 포함된 오디오를 전송합니다. 클라이언트가 PCM(audio/l16) 오디오 데이터의 단일 청크로 2진 메시지를 전송합니다. 이는 필수 샘플링 속도를 표시합니다. 클라이언트는 오디오 데이터 전송을 시작하고 요청 끝 신호를 보내기 위해 서비스의 {"state":"listening"} 응답을 대기하지 않습니다. 데이터를 즉시 전송하면 인식 요청을 처리할 준비가 되자마자 오디오를 서비스에 사용할 수 있으므로 대기 시간이 단축됩니다.

• 클라이언트는 다음 항목을 전송합니다.

  {
    "action": "start",
    "content-type": "audio/l16;rate=22050"
  }
  <binary audio data>
  {
    "action": "stop"
  }
  

• 서비스는 다음과 같이 응답합니다.

  {"state": "listening"}
  {"results": [{"alternatives": [{"transcript": "name the mayflower ",
               "confidence": 0.91}], "final": true}], "result_index": 0}
  {"state":"listening"}
  

두 번째 예제 교환

두 번째 교환에서는 클라이언트가 Second audio transcript라는 문자열이 포함된 오디오를 전송합니다. 클라이언트가 단일 2진 메시지로 오디오를 전송하고 첫 번째 요청에서 지정한 것과 동일한 매개변수를 사용합니다.

• 클라이언트는 다음 항목을 전송합니다.

  <binary audio data>
  {
    "action": "stop"
  }
  

• 서비스는 다음과 같이 응답합니다.

  {"results": [{"alternatives": [{"transcript": "second audio transcript ",
               "confidence": 0.99}], "final": true}], "result_index": 0}
  {"state":"listening"}
  

세 번째 예제 교환

세 번째 교환에서는 클라이언트가 Name the Mayflower라는 문자열이 포함된 오디오를 다시 전송합니다. 이는 PCM 오디오 데이터의 단일 청크를 포함하는 2진 메시지를 전송합니다. 그러나 이번에는 클라이언트가 서비스의 중간 결과를 요청하는 새 start 메시지를 전송합니다.

• 클라이언트는 다음 항목을 전송합니다.

  {
    "action": "start",
    "content-type": "audio/l16;rate=22050",
    "interim_results": true
  }
  <binary audio data>
  {
    "action": "stop"
  }
  

• 서비스는 다음과 같이 응답합니다.

  {"results": [{"alternatives": [{"transcript": "name "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name may "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name may flour "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name the mayflower ",
               "confidence": 0.91}], "final": true}], "result_index": 0}
  {"state":"listening"}