gRPC API

gRPC API

3.0에서 도입되었어요. Bulk와 k-NN 검색은 3.2에서 일반 공개(GA)되었어요.

OpenSearch 버전 3.2부터 gRPC Bulk API와 k-NN 검색 쿼리가 일반 공개 상태예요. 이들은 protobuf 버전 1.2.0을 사용해요. 다만 기능이 다음 버전에서 성숙해짐에 따라 protobuf 구조의 업데이트가 예상돼요. 다른 gRPC 검색 기능은 여전히 실험적이며 프로덕션 사용에는 권장되지 않아요. 이 기능들의 진행 상황이나 피드백은 관련 GitHub 이슈를 참고하세요.

OpenSearch gRPC 기능은 gRPC를 사용해 OpenSearch와 통신하는 대안적인 고성능 전송 계층을 제공해요. gRPC 위의 프로토콜 버퍼를 사용해 오버헤드를 낮추고 직렬화를 빠르게 해요. 초기 벤치마킹 결과를 기반으로 오버헤드를 줄이고, 직렬화를 가속화하며, 요청 측 지연 시간을 개선해요. 자세한 내용은 Performance Benefits를 참고하세요.

출처: 문서

본문

지원되는 API (Supported APIs)

현재 지원되는 gRPC API는 다음과 같아요.

  • Bulk — 3.2에서 일반 공개
  • k-NN — 3.2에서 일반 공개
  • Search (선택 쿼리 유형용)
  • Predict Model Stream
  • Execute Agent Stream

gRPC API 사용 방법 (How to use gRPC APIs)

gRPC API를 사용하려면 다음 단계를 따르세요.

  1. 필요한 gRPC 설정을 구성해 gRPC 전송을 활성화해요.
  2. gRPC 요청을 제출하려면 클라이언트 쪽에 protobuf 세트가 있어야 해요. protobuf는 다음 방법으로 얻을 수 있어요.
언어 배포 방법 지침
Java Maven Central 저장소 Maven Central 저장소에서 opensearch-protobufs jar를 다운로드해요.
Python PyPI 저장소 PyPI 저장소에서 opensearch-protobufs 패키지를 다운로드해요.
기타 언어 GitHub 저장소 (raw protobufs) OpenSearch Protobufs GitHub 저장소(v1.2.0)에서 원시 protobuf 스키마를 다운로드해요. 그런 다음 지원되는 언어용 프로토콜 버퍼 컴파일러로 클라이언트 쪽 코드를 생성할 수 있어요.

gRPC 설정 (gRPC settings)

transport-grpc 모듈은 OpenSearch 설치에 기본으로 포함돼요. 활성화하려면 opensearch.yml에 다음 설정을 추가해요.

aux.transport.types: [transport-grpc]
aux.transport.transport-grpc.port: '9400-9500' // optional

또는 다음 설정으로 보안 전송 프로토콜을 구성해요.

aux.transport.types: [secure-transport-grpc]
aux.transport.transport-grpc.port: '9400-9500' // optional

필요하면 추가 설정을 구성해요(고급 gRPC 설정 참고).

grpc.host: localhost
grpc.publish_host: 10.74.124.163
grpc.bind_host: 0.0.0.0

고급 gRPC 설정 (Advanced gRPC settings)

OpenSearch는 gRPC 통신을 위한 다음 고급 설정을 지원해요. 이 설정들은 opensearch.yml에서 구성할 수 있어요.

설정 이름 설명 예제 값 기본값
grpc.publish_port 이 노드가 gRPC 전송을 위해 피어들에게 스스로를 게시하는 데 사용하는 외부 포트 번호예요. 9400 -1 (비활성화)
grpc.host gRPC 서버가 바인딩할 주소 목록이에요. ["0.0.0.0"] []
grpc.bind_host gRPC 서버를 바인딩할 주소 목록이에요. publish 호스트와 다를 수 있어요. ["0.0.0.0", "::"] grpc.host의 값
grpc.publish_host 클라이언트 연결을 위해 피어들에게 게시되는 호스트 이름 또는 IP 목록이에요. ["thisnode.example.com"] grpc.host의 값
grpc.netty.worker_count gRPC 서버의 Netty 워커 스레드 수예요. 동시성과 병렬성을 제어해요. 2 프로세서 수
grpc.netty.executor_count gRPC 서비스 호출을 처리하기 위한 fork-join 풀의 스레드 수예요. 요청 처리 병렬성을 제어해요. 32 프로세서 수 * 2
grpc.netty.max_concurrent_connection_calls 클라이언트 연결당 허용되는 최대 동시 진행 중 요청 수예요. 200 100
grpc.netty.max_connection_age 연결이 정상적으로 닫히기 전에 도달할 수 있는 최대 수명이에요. ms, s, m 같은 시간 단위를 지원해요. Time units를 참고하세요. 500ms 설정되지 않음 (제한 없음)
grpc.netty.max_connection_idle 연결이 닫히기 전에 유휴 상태일 수 있는 최대 기간이에요. ms, s, m 같은 시간 단위를 지원해요. Time units를 참고하세요. 2m 설정되지 않음 (제한 없음)
grpc.netty.keepalive_timeout 연결을 닫기 전에 keepalive ping 확인을 기다리는 시간이에요. 시간 단위를 지원해요. 1s 설정되지 않음
grpc.netty.max_msg_size gRPC 요청의 최대 인바운드 메시지 크기예요. b, kb, mb, gb 같은 단위를 지원해요. Supported units를 참고하세요. 10mb 또는 10485760 10mb

예제 구성 (Example configuration)

다음은 opensearch.yml의 완전한 gRPC 구성 예제예요.

# Basic gRPC transport configuration
aux.transport.types: [transport-grpc]
aux.transport.transport-grpc.port: '9400-9500'

# Advanced gRPC settings
grpc.host: ["0.0.0.0"]
grpc.bind_host: ["0.0.0.0", "::"]
grpc.publish_host: ["thisnode.example.com"]
grpc.publish_port: 9400
grpc.netty.worker_count: 4
grpc.netty.max_concurrent_connection_calls: 200
grpc.netty.max_connection_age: 500ms
grpc.netty.max_connection_idle: 2m
grpc.netty.keepalive_timeout: 1s
grpc.netty.max_msg_size: 10mb

이 설정들은 HTTP 네트워크 설정과 비슷하지만 gRPC 통신에 구체적으로 적용돼요.

gRPC 성능 이점 (gRPC performance benefits)

gRPC API를 사용하면 HTTP API 대비 여러 이점이 있어요.

  • 지연 시간 감소: 이진 프로토콜 버퍼가 JSON 파싱 오버헤드를 제거해요.
  • 더 높은 처리량: 고빈도 쿼리에서 네트워크 사용률이 더 효율적이에요.
  • 더 낮은 CPU 사용률: 직렬화·역직렬화 비용이 줄어요.
  • 타입 안전성: 프로토콜 버퍼 스키마가 컴파일 타임 검증을 제공해요.
  • 더 작은 페이로드 크기: 이진 인코딩이 네트워크 트래픽을 줄여요.

추가 성능 팁 (Additional performance tip)

문서를 SMILE 같은 지원되는 이진 형식으로 인덱싱하면 JSON으로 인덱싱·검색하는 것보다 보통 지연 시간이 낮아요. 인덱싱과 검색 지연 시간 모두 줄어들어야 해요.

더 알아보기 (Learn more)