실시간 스트리밍 인식

Classic/VPC 환경에서 이용 가능합니다.

실시간으로 16kHZ, 1 Channel, 16 bits per sample의 PCM(헤더가 없는 WAV 파일) 형식의 음성 데이터를 인식하고 텍스트로 변환합니다. gRPC 방식을 통해서만 접근이 가능합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 순서

gRPC 방식을 통해 인식을 요청하는 방법은 다음과 같습니다.

1. 사전 준비
2. Config JSON
3. 인식(Recognize)

1. Protoc Compiler 설치 및 준비

API를 사용하기 위한 사전 준비를 위해 gRPC 사이트를 참조하여 Protoc Compiler를 설치합니다. 설치 후 Python과 Java 중 원하는 언어를 선택한 다음 API의 인터페이스가 정의된 'nest.proto' 파일을 통해 Compiler를 호출합니다.
Protoc Compiler를 설치하고 gRPC 코드를 생성하는 방법은 다음과 같습니다.

1. Protoc Compiler를 설치할 서버에 원격 접속해 주십시오.

2. gRPC 사용을 위한 패키지와 플러그인을 설치해 주십시오.

   • Rocky Linux: Python

     # 최신 상태 확인
     sudo dnf update
     
     # Python 설치 : Linux 서버에 Python을 설치합니다.
     sudo dnf install python3
     
     # pip 설치 및 업그레이드 : pip는 Python용 패키지 설치 프로그램입니다.
     sudo dnf install python3-pip
     pip3 install --upgrade pip
     
     # grpcio-tools 설치 : pip를 사용하여 'grpcio-tools'를 설치합니다.
     pip3 install grpcio-tools
     
     # nest.proto 파일 생성
     touch nest.proto
     
     # protoc compiler로 nest.proto 파일 컴파일
     python3 -m grpc_tools.protoc -I=. --python_out=. --grpc_python_out=. nest.proto
     

   • Rocky Linux: Java

     # protoc-gen-grpc-java 플러그인 다운로드 (버전 번호는 확인 필요 https://github.com/grpc/grpc-java/releases)
     curl -OL https://repo1.maven.org/maven2/io/grpc/protoc-gen-grpc-java/1.66.0/protoc-gen-grpc-java-1.66.0-linux-x86_64.exe
     
     # PATH에 추가
     mv protoc-gen-grpc-java-1.66.0-linux-x86_64.exe /usr/local/bin/protoc-gen-grpc-java
     
     # 실행 권한으로 바꾸기
     chmod +x /usr/local/bin/protoc-gen-grpc-java
     
     # 설치 확인
     protoc-gen-grpc-java --version
     
     # nest.proto 파일 생성
     touch nest.proto
     
     # protoc compiler로 nest.proto 파일 컴파일
     protoc --proto_path=. --java_out=output/directory --grpc-java_out=output/directory nest.proto
     

3. 'nest.proto' 파일을 열어 다음 코드를 입력하고 gRPC 코드를 생성해 주십시오.

   syntax = "proto3";
   option java_multiple_files = true;
   package com.nbp.cdncp.nest.grpc.proto.v1;
   
   enum RequestType {
     CONFIG = 0;
     DATA = 1;
   }
   
   message NestConfig {
     string config = 1;
   }
   
   message NestData {
     bytes chunk = 1;
     string extra_contents = 2;
   }
   message NestRequest {
     RequestType type = 1;
     oneof part {
       NestConfig config = 2;
       NestData data = 3;
     }
   }
   
   message NestResponse {
     string contents = 1;
   }
   service NestService {
     rpc recognize(stream NestRequest) returns (stream NestResponse){};
   }
   

2. 인증(Authorization)

Protoc Compiler를 통해 gRPC 코드 생성을 완료한 후 인증을 진행합니다. 인증은 API 호출 시 Authorization 헤더에 Bearer 토큰을 포함하여 서버에 무결성을 인증하는 방식으로 진행합니다. 인증 진행 시 다음 내용을 주의해 주십시오.

• gRPC Channel을 설정하고, nest_grpc_pb2의 Client Side Proxy인 stub을 생성합니다.
• stub 생성 후 recognize 메서드에 인증 키가 있는 Metadata(메타 데이터)를 포함시켜 원하는 함수를 실행합니다.
  • 실시간 스트리밍 인식 API는 Free 플랜에서는 지원하지 않으며, Basic 장문 인식 플랜에서만 지원합니다.

인증 헤더

인증 헤더는 다음과 같습니다.

인증 순서

인증 방법은 다음과 같습니다.

Python

Rocky Linux 환경에서 Python을 사용하여 인증하는 방법은 다음과 같습니다.

1. Python 파일을 생성해 주십시오. 여기에서는 파일 이름을 main.py로 지정했습니다.

   touch main.py
   

2. main.py에 다음 내용을 추가해 주십시오.

   import grpc
   import json
   
   import nest_pb2
   import nest_pb2_grpc
   
   channel = grpc.secure_channel(
           'clovaspeech-gw.ncloud.com:50051',
           grpc.ssl_channel_credentials()
   )
   client = NestServiceStub(channel)
   metadata = (("authorization", f"Bearer {secretKey}"),) #소문자 authorization 필수 / secretkey는 장문인식 도메인에서 확인
   call = client.YourMethod(YourRequest(), metadata=metadata)
   

Java

Rocky Linux 환경에서 Java를 사용하여 인증하는 방법은 다음과 같습니다.

1. Java 파일을 생성해 주십시오. 여기에서는 파일 이름을 main.java로 지정했습니다.

   touch main.java
   

2. main.java에 다음 내용을 추가해 주십시오.

   ManagedChannel channel = NettyChannelBuilder
               .forTarget("clovaspeech-gw.ncloud.com:50051")
               .useTransportSecurity()
               .build();
   NestServiceGrpc.NestServiceStub client = NestServiceGrpc.newStub(channel);
   Metadata metadata = new Metadata();
   metadata.put(Metadata.Key.of("Authorization", Metadata.ASCII_STRING_MARSHALLER),
                "Bearer ${secretKey}");
   client = MetadataUtils.attachHeaders(client, metadata);
   

3. Config JSON

Protoc에서 생성된 nest_pb2의 NestRequest 객체를 통해 스트리밍 엔드포인트로 전달되는 Config JSON에 대해 설명합니다. Config JSON은 실시간 스트리밍 인식 API를 처음 호출 시 전송해야 합니다.
Config JSON에는 다음과 같은 필드를 제공하고 있습니다.

• transcription: 음성 인식 언어 설정
• keywordBoosting: 입력된 단어들에 대해 인식률을 높이는 설정
• forbidden: 금칙어 설정
• semanticEpd: 음성 인식 결과 생성 기준 설정

요청 바디

Config JSON의 요청 바디에 대한 설명은 다음과 같습니다.

Transcription

Transcription에 대한 설명은 다음과 같습니다.

Keyword Boosting

Keyword Boosting 필드에 대한 설명은 다음과 같습니다.

boostings

keywordBoosting.boostings에 대한 설명은 다음과 같습니다.

Forbidden

Forbidden 필드에 대한 설명은 다음과 같습니다.

SemanticEpd

SemanticEpd 필드에 대한 설명은 다음과 같습니다.

요청 예시

Config JSON의 요청 예시는 다음과 같습니다.

{
  "keywordBoosting": {                  
    "boostings": [
      {
        "words": "test,test1,test2",
        "weight": 1
      },
      {
        "words": "테스트,테스트1,테스트2",
        "weight": 0.5
      }
    ],
  },
  "forbidden": {
    "forbiddens":  "금칙어1,금칙어2",
  }
}

응답 바디

Config JSON의 응답 바디에 대한 설명은 다음과 같습니다.

오류 메시지

요청 실패 시 나타나는 오류 메시지에 대한 설명은 다음과 같습니다.

응답 예시

Config JSON의 응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

{
  "uid": "{uid}",
  "responseType": [ "config" ],
  "config": {
    "status": "Success",
    "keywordBoosting": {
      "status": "Success"
    },
    "forbidden" : {
      "status": "Success"
    }
}

실패

요청에 hobidden 입력 시 호출이 실패한 경우의 응답 예시는 다음과 같습니다.

{
  "uid": "{uid}",
  "responseType": [ "config" ]
  "config": {
    "status": "Unknown key: hobidden"
  }
}

4. 인식(Recognize)

Config JSON을 통해 원하는 설정을 진행한 후 recognize를 통해 음성 인식 API를 호출하여 실시간으로 음성 데이터를 처리하여 인식합니다. Protoc에서 생성한 코드에 있는 NestRequest와 인증 메타 데이터를 stub의 메서드인 recognize를 통해 음성 인식 API를 호출하게 됩니다.

요청 바디

Recognize의 요청 바디에 대한 설명은 다음과 같습니다.

응답 바디

Recognize의 응답 바디에 대한 설명은 다음과 같습니다.

alignInfos

config.alignInfos에 대한 설명은 다음과 같습니다.

오류 메시지

Recognize 요청 실패 시 나타나는 오류 메시지에 대한 설명은 다음과 같습니다.

응답 예시

응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

• 응답 성공 및 "responseType": [ "transcription" ]일 때

{
  "uid": "{uid}"
  "responseType": [ "transcription" ]
  "transcription": {
    "text": "입니다.",
    "position": 0,
    "periodPositions": [3],
    "periodAlignIndices": [3],
    "epFlag": false,
    "seqId": 0,
    "epdType": "durationThreshold",
    "startTimestamp": 190,
    "endTimestamp": 840,
    "confidence": 0.997389124199423,
    "alignInfos": [
      {"word":"입","start":190,"end":340,"confidence":0.9988637124943075},
      {"word":"니","start":341,"end":447,"confidence":0.9990018488549978},
      {"word":"다","start":448,"end":580,"confidence":0.9912501264550316},
      {"word":".","start":581,"end":700,"confidence":0.9994397226648595},
      {"word":" ","start":701,"end":840,"confidence":0.9984142043105126}
    ]
  }
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

{
  "uid": string,                     # required
  "responseType": [ "recognize" ],    # required
  "recognize": {                     # required
    "status": string,                # required
    "epFlag": {                      # optional
      "status": string
    },
    "seqId": {                       # optional
      "status": string
    },
    "audio": {                       # op
      "status": 
    }
  }
}

5. 기타 API

현재 활성화된 Stub 호출 수와 해당 도메인의 허용된 최대 Stub 수 등을 조회합니다.

curl --location 'https://clovaspeech-gw.ncloud.com:50051/api/v1/1064/active-calls' \
--header 'Authorization: Bearer ${API_KEY}'

응답

응답 파라미터

응답 예시

{
    "activeCalls": 3,
    "maxCalls": 15,
    "timestamp": "2025-04-25T12:09:27.382+09:00"
}