Kakao i Agent::Service Agent Interface::Recognizer

페이지 이동경로

Recognizer

Recognizer 인터페이스는 음성 및 텍스트 발화 인식과 관련된 일련의 Message를 처리합니다.

Recognizer 인터페이스
Message 인터페이스 설명
Event Speech Service Agent에서 발생한 사용자 발화를 KVS에 전달
Text 음성 발화가 아닌 텍스트 발화 입력 시에 사용
- Recognizer.Speech Event와 기본적인 동작은 동일함
Canceled Service Agent에서 발화 중 취소가 발생하여 해당 다이얼로그에 대해 모든 세션이 종료되었음을 KVS에 전달
Instruction StopCapture KVS가 사용자의 의도를 파악했거나 발화가 종료 시, 음성 캡처를 중지하도록 지시
InformRecognized KVS가 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달
ExpectSpeech KVS가 사용자에게 추가적인 발화를 원할 때, 마이크를 열고 사용자의 발화를 기다리도록 지시
RequestText Service Agent에 Text Event를 보내도록 지시
State RecognizerState 음성 웨이크업을 지원하는 기기에 설정된 Wake-up Word를 KVS에 전달

Event

Event Message의 호출 방식은 다음과 같습니다.

Event Message 호출 방식
메서드 요청 URL
POST /{{API version}}/events

Speech

Recognizer.Speech는 Service Agent에서 발생한 사용자 발화를 KVS로 전달하는 Event이며, Multipart Message로 통신합니다. Multipart의 <The First Part>에는 JSON 형식의 객체가 전달되며, <The Second Part>에는 Service Agent와 KVS 사이에 전송되는 오디오 데이터가 스트리밍 방식으로 배치됩니다. stream에는 320 bytes chunk 단위로 10ms의 캡처된 오디오 파일이 첨부됩니다.

Multipart Message
구분 설명
The First Part JSON 형식의 객체
The Second Part 마이크에서 캡처된 바이너리 오디오 파일

Request Syntax

코드예제Recognizer.Speech Request Syntax_The First Part

Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
	"state": [, , ,],
	"event": {
		"header": {
			"type": "Recognizer.Speech",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"profile": "{{STRING}}",
			"format": "{{STRING}}",
			"inflow": "{{STRING}}",
			"activator": {
				"type": "{{STRING}}",
				"botId": "{{STRING}}",
				"body": {
					"wakeWordDetection": {
						"reliableThreshold": {{FLOAT}},
						"reliability": {{FLOAT}},
						"sensitivity": {{FLOAT}}
					}
				}
			}
		}
	}
}

코드예제Recognizer.Speech Request Syntax_The Second Part (Binary Audio 첨부)

Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream

{{BINARY AUDIO ATTACHMENT}}

Request Header

Recognizer.Speech Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 선택 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Recognizer.Speech Request Body
파라미터 타입 필수 여부 설명
profile String 필수 다양한 거리에서 사용자 음성을 최적화하여 식별하는 ASR Profile 유형으로, 마이크와 사용자 음성의 거리를 나타냄
NEAR_TALK(기본값): 보통 거리
CLOSE_FIELD: 매우 가까운 거리
FAR_FIELD: 매우 먼 거리
inflow String 필수 발화 유입을 식별
REMOTE_MIC: 스피커 본체와 떨어져있는 마이크에서 음성 입력
SPEAKER:스피커 본체 마이크에서 음성 입력
format String 필수 캡처한 오디오의 형식을 식별
ex) RAWPCM/16/16000/1/_/_
activator Object 선택 발화가 개시된 이유를 명시
Service Agent: 다음 Recognizer.Speech에 이 객체를 그대로 다시 전달
- Recognizer.ExpectSpeech에 의해 수동적으로 발화가 개시된 경우, 수신된 Recognizer.ExpectSpeech의 activator 객체를 그대로 재전송
type String 필수 발화가 개시된 이유를 명시
<능동적으로 발화가 개시된 경우>
- WAKEWORD: Wake-up Word로 마이크를 열었을 때 Service Agent에서 세팅
- BUTTON_TAP: 버튼으로 마이크를 열었을 때 Service Agent에서 세팅
<수동적으로 발화가 개시된 경우>
Recognizer.ExpectSpeech Instruction에 다음의 주어진 값이 설정
- EXPECT_REPLY: 응답을 기대하는 경우
- EXPECT_CONTINUE: 대화가 이어질 수 있도록 마이크를 열어줌
- EXPECT_WAKEUP: Wake-up Word를 연속으로 발화했을 경우 다시 마이크를 열어줌
- ASYNC_REPLY: 푸시를 통한 비동기 답변
- RECORDING: 보이스프로필 등록 시 사용
botId String 선택 ExpectSpeech를 발생시킨 Bot의 ID 전달
- activator.typeEXPECT_REPLY 또는 EXPECT_CONTINUE
token String 선택 현재 대화의 스트림을 나타내는 불투명한 토큰
Object 필수 Wake-up Word에 대한 정보
Object 선택 Wake-up Word로 웨이크업이 될 때 인식 신뢰도 및 민감도 정보
reliableThreshold Float 필수 신뢰 여부(reliable)의 문턱값:
reliabilityreliableThreshold
reliability Float 필수 인식 신뢰도
sensitivity Float 필수 Wake-up Word 검증 시 활용할 민감도의 상대값
ex) 0: 보통, 100: 민감, -100: 둔감

Text

Recognizer.Text는 입력 방식이 음성이 아닌 텍스트 발화일 때, Service Agent가 해당 텍스트 발화를 KVS에 전송할 경우에 사용하는 Event입니다. 기본 동작은 Recognizer.Speech Event와 동일합니다.

Request Syntax

코드예제Recognizer.Text Request Syntax

{
	"header": {
		"type": "Recognizer.Text",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {
		"token": "{{STRING}}",
		"utterance": "{{STRING}}",
		"source": "{{STRING}}",
		"triggerType": "{{STRING}}"
	}
}

Request Header

Recognizer.Text Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Recognizer.Text Request Body
파라미터 타입 필수 여부 설명
token String 선택 유니크 식별자
utterance String 필수 텍스트 발화
source String 선택 텍스트 발화가 발생한 입력 소스
- Recognizer.RequestText Event 생성자가 임의의 Readable String을 지정하므로 생성자 또는 대리자만 해석 가능
triggerType String 선택 텍스트 발화가 발생한 타입
WORKFLOW: 내 명령어 또는 예약 실행에서 사용되는 Workflow Event로 발생한 Recognizer.RequestText에 지정
PLAYBACK_CONTROL: PlaybackController 인터페이스의 Event로 발생한 Recognizer.RequestText에 지정
QUICK_REPLY: View Template의 quickReply action에 포함된 Recognizer.RequestText에 지정
REDIRECT: 분류된 Bot에서 다른 Bot의 발화를 실행할 때 지정
UTTERANCE_INJECTION: 다른 마이크에서 입력된 음성발화의 인식결과를 전달할 때 지정
CUSTOM_BUTTON: 기기의 일반적인 버튼으로 인하여 발생한 Recognizer.RequestText에 지정

Canceled

Recognizer.Canceled는 Service Agent에서 발화 중 취소가 발생하여 해당 다이얼로그에 대해 슬롯필링 등의 모든 세션이 종료되었음을 KVS에전달하는 Event입니다.

  • Recognizer.ExpectSpeech Instruction을 수신하기 전에 Recognizer.Canceled Event를 전송하면, 서버와의 동기화 문제로 취소(Canceled)된 dialogRequestId를 포함하는 Recognizer.ExpectSpeech Instruction을 다시 수신할 수 있습니다.
  • Service Agent는 발화 중 취소하려는 dialogRequestId에 해당하는 수신된 모든 Instruction이 동작하지 않도록 처리하고, Recognizer.Canceled Event로 전송한 dialogRequestId를 일정 기간 저장하여 서버에서 비동기로 수신되는 발화 중 취소하려는 dialogRequestId에 해당하는 Instruction을 무시해야 합니다.

Request Syntax

코드예제Recognizer.Canceled Request Syntax

{
	"header": {
		"type": "Recognizer.Canceled",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {}
}

Request Header

Recognizer.Canceled Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Request Body는 없습니다.

Instruction

Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

Instruction Message 호출 방식
메서드 요청 URL
GET /{{API version}}/instructions

StopCapture

Recognizer.StopCapture는 KVS가 사용자의 의도를 파악했거나 또는 사용자가 발화를 종료했을 때, 사용자 음성 캡처를 중지하도록 Service Agent로 지시하는 Instruction입니다. Service Agent가 Recognizer.StopCapture Instruction을 전송받으면, 즉시 마이크를 닫고 사용자 발화를 더 이상 듣지 않습니다.

Request Syntax

코드예제Recognizer.StopCapture Request Syntax

{
	"header": {
		"type": "Recognizer.StopCapture",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {}
}

Request Header

Recognizer.StopCapture Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 필수 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Request Body는 없습니다.

InformRecognized

Recognizer.InformRecognized는 KVS가 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달하는 Instruction입니다.

Request Syntax

코드예제Recognizer.InformRecognized Request Syntax

{
	"header": {
		"type": "Recognizer.InformRecognized",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {
		"type": "{{STRING}}",
		"text": "{{STRING}}"
	}
}

Request Header

Recognizer.InformRecognized Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Recognizer.InformRecognized Request Body
파라미터 타입 필수 여부 설명
type String 필수 음성 인식 결과 유형
WAKEUP: 웨이크업
BPD(Begin Point Detection): 사용자가 발화 시작
EPD(End Point Detection): 사용자 발화 종료
PARTIAL:음성 인식 진행 중
FINAL: 음성 인식된 최종 스트림
text String 선택 음성 인식 결과 텍스트
- 최대 4,096자

Sample Code

코드예제Recognizer.InformRecognized Sample Code

{
	"header": {
		"type": "Recognizer.InformRecognized",
		"messageId": "123456",
		"dialogRequestId": "dialogRequestId-123"
	},
	"body": {
		"type": "PARTIAL",
		"text": "아이유"
	}
}

ExpectSpeech

Recognizer.ExpectSpeech는 KVS가 사용자로부터 추가적인 발화를 기대할 때, 마이크를 열고 사용자의 발화가 시작될 수 있도록 Service Agent에 지시하는 Instruction입니다.

Request Syntax

코드예제Recognizer.ExpectSpeech Request Syntax
{
	"header": {
		"type": "Recognizer.ExpectSpeech",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {
		"activator": {
			"type": "{{STRING}}",
			"botId": "{{STRING}}"
		}
		"waitTime": {{LONG}},
		"inflow": "{{STRING}}"
	}
}

Request Header

Recognizer.ExpectSpeech Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Recognizer.ExpectSpeech Request Body
파라미터 타입 필수 여부 설명
Object 필수 발화가 개시된 이유를 명시하며, Service Agent는 다음 Recognizer.Speech에 이 객체를 그대로 다시 전달
type String 필수 발화가 개시된 이유를 명시
<능동적으로 발화가 개시된 경우>
- WAKEWORD: Wake-up Word로 마이크를 열었을 때 Service Agent에서 세팅
- BUTTON_TAP: 버튼으로 마이크를 열었을 때 Service Agent에서 세팅
<수동적으로 발화가 개시된 경우>
Recognizer.ExpectSpeech Instruction에 다음의 주어진 값이 설정되며, 자세한 설명은 type 상세보기 참고
- EXPECT_REPLY: 응답을 기대하는 경우
- EXPECT_CONTINUE: 대화가 이어질 수 있도록 마이크를 열어줌
- EXPECT_WAKEUP: Wake-up Word 연속 발화 시 마이크를 열어줌
- ASYNC_REPLY: 푸시를 통한 비동기 답변
- RECORDING: 보이스프로필 등록 시 사용하며, 문장에 포함된 Wake-up Word를 포함하여 녹음된 전체 문장을 목소리 학습에 활용
botId String 선택 ExpectSpeech를 발생시킨 Bot의 ID 전달
- activator.typeEXPECT_REPLY 또는 EXPECT_CONTINUE
token String 선택 현재 대화의 스트림을 나타내는 불투명한 토큰
waitTime Long 필수 Service Agent가 마이크가 열린 뒤, 사용자 발화를 얼마나 오래 기다릴지 정함
- 정의된 시간 내 발화가 시작되지 않으면(BPD를 받지 못하면) 마이크를 닫음
- 단위: ms(miliseconds)
inflow String 선택 마이크를 열 유입 대상을 지정
type 상세보기

Recognizer.ExpectSpeech의 type 파라미터는 KVS가 Service Agent에 마이크를 열도록 지시한 유형을 나타냅니다.

type

구분 설명
EXPECT_REPLY 응답을 기대하는 경우
예시
- 사용자: 환율 알려줘
- 답변(EXPECT_REPLY): 알고 싶은 환율의 국가나 통화명을 알려주세요
- 사용자: 달러
- 답변: 현재 미국 환율은 xxxx원이에요
EXPECT_CONTINUE 대화가 이어질 수 있도록 마이크를 열어줌
예시
- 사용자: 안녕
- 답변(EXPECT_CONTINUE): 안녕
- 사용자: 만나서 반가워
- 답변(EXPECT_CONTINUE): 그럼 저랑 더 얘기해봐요
- 사용자: 너 누구야
- 답변(EXPECT_CONTINUE): 저는 카카오라고 해요. 친하게 지내요!
EXPECT_WAKEUP Wake-up Word를 연속으로 발화했을 경우 다시 마이크를 열도록 함
예시
- 사용자: 헤이카카오
- 답변(“띠링” 소리 후 마이크 열림)
- 사용자: 헤이카카오
- 답변(“띠링” 소리 후 마이크 열림)
ASYNC_REPLY 푸시를 통한 비동기 답변일 경우
예시
- 사용자: 카톡 읽어줘
- 답변(EXPECT_REPLY): 아이유에게 온 카톡 읽어줄까요?
- 사용자: 그래
- 답변(ASYNC_REPLY): 카톡 다 읽었어요. 다음 수지 카톡 읽어줄까요?
RECORDING 보이스프로필 등록 과정에서 사용하며, 문장에 포함된 Wake-up Word를 포함하여 녹음된 전체 문장을 목소리 학습에 활용
예시
- 사용자: 헤이카카오앱에서 스피커를 지정하고 목소리 등록 시작
- 답변(RECORDING): 목소리 등록을 시작할게요. “띠링” 소리 후 헤이카카오라고 말해주세요
- 사용자: 헤이카카오

RequestText

Recognizer.RequestText는 KVS가 Service Agent로 Text Event를 보내도록 요청하는 Instruction입니다.

Request Syntax

코드예제Recognizer.RequestText Request Syntax
{
	"instruction":{
		"header": {
			"type": "Recognizer.RequestText",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
	    },
	    "body": {
		    "token":"{{STRING}}",
		    "utterance":"{{STRING}}",
		    "source":"{{STRING}}",
		    "triggerType":"{{STRING}}",
	    }
    }
}

Request Header

Recognizer.RequestText Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Recognizer.RequestText Request Body
파라미터 타입 필수 여부 설명
token String 필수 유니크 식별자
utterance String 필수 Recognizer.Text Event의 body에 구성될 발화 내용
priority String 선택 Recognizer.RequestText를 실행하는 우선순위
- Highest(Default): 다른 작업보다 최우선으로 실행되며, 현재 Recognizer.Speak가 진행 중인 경우에도 바로 Event를 전송함
source String 선택 Text 발화가 발생한 입력 소스
- Recognizer.RequestText 생성자가 임의의 Readable String을 지정할 수 있으며, 생성자 또는 대리자만 해석 가능
- Event 발생 시 body에 동일 값을 전송해야 함
triggerType String 선택 Text 발화가 발생한 타입으로 정해진 값 중 선택
- Event 발생 시 body에 동일 값을 전송해야 함

State

RecognizerState

Recognizer.RecognizerState는 KVS에서 디바이스에 설정된 웨이크업을 확인하고, 불필요한 웨이크업을 처리하는데 사용하는 State로, 음성 웨이크업을 지원하는 디바이스에 설정되어 있는 Wake-up Word(wuw)를 선택적으로 전달합니다.

Request Syntax

코드예제Recognizer.RecognizerState Request Syntax
{
	"header": {
		"type": "Recognizer.RecognizerState",
	},
	"body": {
		"wuw": "헤이 카카오"
	}
}

Request Header

Recognizer.RecognizerState Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름

Request Body

Recognizer.RecognizerState Request Body
파라미터 타입 필수 여부 설명
wuw String 필수 현재 디바이스에 설정된 Wake-up Word
- 가능한 값: "헤이 카카오"
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.