추론 프로토콜과 API

추론 프로토콜과 API

클라이언트는 Triton과 HTTP/REST 프로토콜, gRPC 프로토콜, 또는 인프로세스 C API나 그 C++ 래퍼로 통신할 수 있어요.

출처: 공식문서

HTTP/REST와 gRPC 프로토콜

Triton은 KServe 프로젝트가 제안한 표준 추론 프로토콜에 기반한 HTTP/REST·gRPC 엔드포인트를 노출해요. 모든 기능을 켜기 위해 Triton은 KServe 추론 프로토콜에 HTTP/REST·gRPC 확장도 구현해요. gRPC 프로토콜은 추론 RPC의 양방향 스트리밍 버전도 제공해서, 추론 요청/응답의 연속을 gRPC 스트림 위에서 보낼 수 있어요. 보통은 unary(단일) 버전을 추천하고, 스트리밍 버전은 상황이 요구할 때만 쓰는 게 좋아요. 몇 가지 사례는 다음과 같아요.

  • 로드 밸런서 뒤에 여러 Triton 인스턴스가 있는 시스템에서, 일련의 추론 요청이 같은 Triton 인스턴스에 도달해야 한다면 — gRPC 스트림이 수명 동안 단일 연결을 유지하므로 요청이 같은 인스턴스로 전달되게 보장해요.
  • 네트워크 위에서 요청/응답의 순서가 보존되어야 한다면 — gRPC 스트림은 클라이언트가 보낸 순서대로 서버가 요청을 받도록 보장해요.

HTTP/REST·gRPC 프로토콜은 또한 서버·모델 헬스, 메타데이터, 통계를 확인하는 엔드포인트도 제공해요. 추가 엔드포인트로 모델 로드/언로드와 추론도 가능하고, 자세한 내용은 KServe·확장 문서를 참고하세요.

HTTP 옵션

Triton은 HTTP 프로토콜로 서버-클라이언트 네트워크 트랜잭션을 위한 구성 옵션을 제공해요.

압축 (Compression)

Triton은 클라이언트를 통해 HTTP 상의 요청/응답을 와이어에서 압축할 수 있게 해줘요. 자세한 내용은 HTTP Compression을 참고하세요.

Triton 서버 에러 코드를 HTTP 상태 코드로 매핑

다음 표는 다양한 Triton 서버 에러 코드가 대응하는 HTTP 상태 코드로 어떻게 매핑되는지 보여줘요. HTTP 응답에서 Triton 서버 에러가 어떻게 처리되는지 이해하는 참고 자료로 쓰면 돼요.

Triton Server Error Code HTTP Status Code Description
TRITONSERVER_ERROR_INTERNAL 500 Internal Server Error
TRITONSERVER_ERROR_NOT_FOUND 404 Not Found
TRITONSERVER_ERROR_UNAVAILABLE 503 Service Unavailable
TRITONSERVER_ERROR_UNSUPPORTED 501 Not Implemented
TRITONSERVER_ERROR_UNKNOWN, TRITONSERVER_ERROR_INVALID_ARG, TRITONSERVER_ERROR_ALREADY_EXISTS, TRITONSERVER_ERROR_CANCELLED 400 Bad Request (default for other errors)

gRPC 옵션

Triton은 서버-클라이언트 네트워크 트랜잭션을 구성하는 다양한 gRPC 파라미터를 노출해요. 이 옵션들의 사용법은 tritonserver --help 출력을 참고하세요.

SSL/TLS

보안 채널 구성을 위한 옵션으로, 서버 쪽 옵션은 다음과 같아요.

  • --grpc-use-ssl
  • --grpc-use-ssl-mutual
  • --grpc-server-cert
  • --grpc-server-key
  • --grpc-root-cert

클라이언트 쪽 문서는 Client-Side GRPC SSL/TLS를 참고하세요. gRPC 인증 개요는 여기에서 더 자세히 볼 수 있어요.

압축 (Compression)

Triton은 서버 쪽에서 다음 옵션을 노출해 요청/응답 메시지의 와이어 압축을 허용해요.

  • --grpc-infer-response-compression-level

클라이언트 쪽 문서는 Client-Side GRPC Compression을 참고하세요. 압축은 서버-클라이언트 통신에서 사용되는 대역폭을 줄이는 데 유용해요. 자세한 내용은 gRPC Compression을 참고하세요.

GRPC KeepAlive

Triton은 클라이언트와 서버 양쪽의 기본값을 여기에 설명된 대로 두고 GRPC KeepAlive 파라미터를 노출해요. KeepAlive 설정을 구성하는 옵션은 다음과 같아요.

  • --grpc-keepalive-time
  • --grpc-keepalive-timeout
  • --grpc-keepalive-permit-without-calls
  • --grpc-http2-max-pings-without-data
  • --grpc-http2-min-recv-ping-interval-without-data
  • --grpc-http2-max-ping-strikes

클라이언트 쪽 문서는 Client-Side GRPC KeepAlive를 참고하세요.

GRPC 상태 코드

Triton은 특정 플래그가 헤더를 통해 활성화될 때 스트리밍 요청에 대한 GRPC 에러 처리를 구현해요. 에러를 만나면 Triton은 적절한 GRPC 에러 코드를 반환하고 이어서 스트림을 닫아요.

  • triton_grpc_error: 스트림을 시작할 때 헤더 값을 true로 설정해야 해요.

GRPC 상태 코드는 가시성·모니터링에 유용하니 gRPC Status Codes를 참고하세요. 클라이언트 쪽 문서는 Client-Side GRPC Status Codes를 참고하세요.

GRPC 추론 핸들러 스레드

일반적으로 completion queue마다 스레드 2개가 가장 좋은 성능을 내는 것 같아요. gRPC Performance Best Practices를 참고하세요. 다만 요청 처리 단계가 병목인 경우(예: ensemble 모델)에는 gRPC 추론 핸들러 스레드 수를 늘리면 처리량이 높아질 수 있어요.

  • --grpc-infer-thread-count: 기본값은 2예요.

참고: 스레드가 많다고 항상 성능이 좋은 건 아니에요.

엔드포인트 접근 제한 (Limit Endpoint Access, BETA)

Triton 사용자는 서버의 GRPC·HTTP 엔드포인트가 제공하는 프로토콜 또는 API에 대한 접근을 제한하고 싶을 때가 있어요. 예를 들어 추론 API에는 한 인증 자격 증명 집합을, 모델 로드/언로드 같은 모델 제어 API에는 다른 자격 증명을 제공할 수 있어요.

제한된 프로토콜 그룹(GRPC) 또는 제한된 API 그룹(HTTP)을 선언하려면 다음 옵션을 지정할 수 있어요.

--grpc-restricted-protocol=<protocol_1>,<protocol_2>,...:<restricted-key>=<restricted-value>
--http-restricted-api=<API_1>,API_2>,...:<restricted-key>=<restricted-value>

Vertex AI 엔드포인트 지원이 활성화되면 --http-restricted-api는 리다이렉트된 Vertex AI 요청에도 적용돼요. Triton이 TRITON_ENABLE_HTTP 없이 빌드되면 Vertex AI는 기본값인 제한 없는 API 설정으로 폴백돼요.

이 옵션을 여러 번 지정해 제한 설정이 다른 여러 프로토콜/API 그룹을 만들 수 있어요.

예제

관리자용 프로토콜/API 집합을 제한하고 나머지는 제한 없이 두고 서버를 시작하려면 다음 커맨드라인 인자를 사용해요.

tritonserver --grpc-restricted-protocol=shared-memory,model-config,model-repository,statistics,trace:<admin-key>=<admin-value> \
             --http-restricted-api=shared-memory,model-config,model-repository,statistics,trace:<admin-key>=<admin-value> ...

관리자 프로토콜에 대한 GRPC 요청은 값이 <admin-value>인 추가 헤더 triton-grpc-protocol-<admin-key>를 제공해야 하고, 관리자 API에 대한 HTTP 요청은 값이 <admin-value>인 추가 헤더 <admin-key>를 제공해야 해요.

더 알아보기 (Learn more)