본문 바로가기 메뉴 바로가기

Kakao i Machine Learning::구성::엔드포인트/배포

페이지 이동경로

엔드포인트

공공 클라우드 환경 미지원 안내
카카오 i 머신러닝 운영 환경(퍼블릭/공공)에 따라 제공하는 기능이 다를 수 있습니다. 엔드포인트 생성 및 설정 기능은 퍼블릭 환경에서만 제공합니다. 공공 클라우드 환경에서 지원 가능한 시점에 카카오 i 클라우드 (공공 리전2) 공지사항으로 안내할 예정입니다.

기계학습 모델을 추론(Inference)하기 위해서는 모델을 배포해야 합니다. Kakao i Machine Learning에서 엔드포인트를 생성하여 모델을 배포할 수 있습니다.

엔드포인트(Endpoint)는 모델의 추론 및 추론 결과를 전송하기 위해 클라이언트가 호출할 수 있는 HTTP 엔드포인트입니다. 엔드포인트에 인스턴스 리소스를 이용하여 모델을 배포하기 때문에 빠르게 추론할 수 있습니다.

엔드포인트 제공 기능

엔드포인트에서 제공하는 기능은 다음과 같습니다.

  • 전용 환경(컨테이너 이미지) 제공
  • 다중 모델 배포
  • 트래픽 할당, 트래픽 미러링
  • ‘토큰 기반' 인증
  • 리퀘스트, 리소스 모니터링
안내
KiML CLI를 이용할 경우, 엔드포인트와 배포를 각각 생성하거나 배포 생성 시 엔드포인트를 만들 수 있습니다. 콘솔에서는 엔드포인트와 배포를 동시에 생성합니다.

엔드포인트 요청 방식

엔드포인트에 모델을 배포하기 위해서는 아래 항목으로 구성된 URL에 추론 요청과 API Header에 Authorization: Bearer 를 이용하여 엔드포인트를 요청할 수 있습니다. 엔드포인트 기본 설정값은 아래와 같습니다.

  • Proxy body size: 20MB
  • Client body buffer size: 10MB
표엔드포인트 요청 입력값
항목 입력값
요청 주소 {엔드포인트 URL}
- Kakao i Machine Learning 환경별로 상이
요청 Header Authorization: Bearer {API Key}

코드예제엔드포인트 요청 Sample Code (Testbed 환경) 

curl -X 'GET' 'http:{엔드포인트 URL}' -H 'Authorization: Bearer ef1ff0ee8de7c487245397c4bc4f242ab42330e920784634064204aa8b72271fe2c'

엔드포인트 API 키 재발급

KiML CLI 명령어를 이용하여 엔드포인트 API 키를 재발급할 수 있습니다.

안내
콘솔에서 API 키를 재발급하는 기능은 추후 지원할 예정입니다.

엔드포인트 모니터링

엔드포인트 상세 정보에서 엔드포인트 및 배포 단위로 네트워크 요청 정보와 컴퓨팅 자원 사용량을 실시간으로 조회할 수 있습니다. 수정 또는 삭제된 배포 모니터링도 조회할 수 있습니다.

  • HTTP Request
  • Request Latency
  • GPU, GPU Memory Utilization
  • vCPU, vCPU Memory Utilization
  • Power Consumption
  • Network I/O Bandwith

엔드포인트 알림

엔드포인트 상태를 모니터링 할 수 있는 알림 기능을 제공합니다.
Kakao i Machine Learning 콘솔의 ‘엔드포인트’ 메뉴 > 엔드포인트 상세 > [알림] 탭에서 설정할 수 있습니다.

엔드포인트 및 배포 알림 조건

분류 조건 상세 조건
모니터링 로그 오류 발생 준비 중인 기능(제공 이후 안내 예정)
QPS(Query per seconds) 설정한 임계치 이상으로 QPS가 발생한 경우, 알림 발송
상태 알림 HTTP Status Code에서 400번대, 500번대 오류가 발생한 경우, 알림 발송
- 4XX: Client error responses
- 5XX: Server error responses
배포 상태 변경 Progressing 엔드포인트의 배포 중 상태값이 Available에서 Progressing으로 변경된 경우, 알림 발송
Available 엔드포인트의 배포 중 상태값이 Progressing에서 Available으로 변경된 경우, 알림 발송
컴퓨팅 자원 사용량(Usage) 상한 CPU 가장 높은 CPU 사용량 기준으로 설정한 임계치 이상인 경우, 즉시 알림 발송 해당 조건이 지속될 경우, 12시간 간격으로 알림 발송
CPU 메모리 가장 높은 CPU 메모리 사용량 기준으로 설정한 임계치 이상인 경우, 즉시 알림 발송
GPU 사용량 가장 높은 GPU 사용량 기준으로 설정한 임계치 이상인 경우, 즉시 알림 발송
컴퓨팅 자원 사용량(Usage) 하한 CPU 가장 낮은 CPU 사용량 기준으로 설정한 임계치 이하인 경우, 즉시 알림 발송
CPU 메모리 가장 낮은 CPU 메모리 사용량 기준으로설정한 임계치 이하인 경우, 즉시 알림 발송
GPU 사용량 가장 낮은 GPU 사용량 기준으로 설정한 임계치 이하인 경우, 즉시 알림 발송

엔드포인트 알림 조건 설정 그림엔드포인트 알림 조건 설정

엔드포인트 알림 수단

엔드포인트 알림 수단은 카카오워크 Incoming Webhook(beta)를 지원합니다.

  • 일부 카카오워크 워크스페이스에서만 Incoming Webhook(beta) 기능을 사용할 수 있습니다.
  • 카카오워크 인커밍 웹훅 대화방에 참여한 사용자만 알림을 수신합니다.

엔드포인트 알림 채널을 설정하는 방법은 다음과 같습니다.

  1. 카카오워크 확장 탭 > 확장 서비스 메뉴에서 Incoming Webhook를 클릭한 후, [Bot 만들기] 버튼을 클릭합니다.
  2. 1:1 채팅 또는 그룹 채팅을 선택 후, [봇 만들기] 버튼을 클릭합니다.
  3. 발급된 ‘Incoming Webhook URL’을 클립보드에 복사 및 백업을 위해 ‘나와의 채팅방’에 발송합니다.
  4. Kakao i Machine Learning 콘솔에서 엔드포인트 메뉴 > 엔드포인트 상세 정보 > [알림] 탭을 클릭합니다.
  5. 알림 채널 토글 버튼을 활성한 후, 엔드포인트 알림 채널 설정 팝업창에서 복사한 웹훅 URL을 입력하고 [저장] 버튼을 클릭합니다.

배포

배포(Deployment)는 추론할 모델을 호스팅하는 데 필요한 리소스 묶음입니다. 하나의 엔드포인트에 최대 2개의 모델을 배포할 수 있으며, 하나의 모델을 여러 엔드포인트에 배포할 수 있습니다.

주의

  • 엔드포인트 생성 시, 워크스페이스 컴퓨팅 자원 쿼터 내에서 인스턴스 구성을 선택할 수 있습니다. 잔여 워크스페이스 쿼터가 있는 경우에만 신규 배포를 생성할 수 있습니다.
  • 엔드포인트 생성 후, 인스턴스 구성(타입과 개수)을 변경할 수 없습니다.
  • 엔드포인트에 포함된 배포는 생성 시점부터 컴퓨팅 자원을 점유하며 쿼터를 소진합니다.

배포 타입

표배포 타입
상태 설명
TensorFlow Serving TensorFlow으로 모델을 서빙
- TensorFlow로 학습한 모델만 서빙 가능
- 자세한 내용은 TensorFlow Serving 문서 참고
Triton NVIDIA Trition으로 모델을 서빙
- TensorFlow 또는 PyTorch로 학습한 모델을 서빙 가능
- 자세한 내용은 NVIDA Trition Inference Server 문서와 Serving a Torch-TensorRT model with Triton 문서 참고
Custom Image 컨테이너 이미지를 커스텀 이미지로 등록하여 모델 서빙
- 커스텀 이미지만 선택 가능
- 커스텀 이미지에 모델 정보를 포함하여, 별도 모델 등록 절차 없이 배포 가능
- Port 번호 입력 필수 (미입력 시, 8080으로 처리)
Cosmos Serving 스크립트를 GitHub URL 또는 직접 입력하여, 전후 비즈니스 로직 등을 자유롭게 추가하여 배포 가능

배포 이름

표배포 이름
항목 설명
배포 이름 - 배포를 생성할 엔드포인트에서 고유해야 함
- 공백 없이, 영어 소문자(a-z), 숫자(0-9), 하이픈(-)만 입력 가능
- 영어 소문자(a-z)로 시작하며, 소문자(a-z) 또는 숫자(0-9)로 끝나야 됨
- 2~63자 입력 가능
배포 설명(선택) 배포 설명이 필요할 경우 입력
- 최대 1,024자 이내로 작성

배포 상태값

표배포 상태값
상태 설명
Progressing 배포를 생성 중인 상태
- 컴퓨팅 자원이 부족하거나 설정값이 잘못되어 서비스 제공이 어려운 경우, Progressing 상태가 유지될 수 있음
- 인스턴스(파드)가 0개인 상태에도 Progressing 상태로 유지됨
Available 인스턴스가 정상적으로 운영 중인 상태

배포 인스턴스(파드) 상태값

배포 정보를 조회하여 인스턴스(파드) 상태값을 확인할 수 있습니다. 인스턴트(파드) 상태별 발생 원인은 다음과 같습니다.

표배포 인스턴스(파드) 상태 원인
상태 설명
Running 인스턴스(파드)가 정상적으로 운영 가능한 상태

값을 입력을 잘못하여 인스턴스(파드) 생성과 종료를 반복하며 Running 상태인 경우
- Back-off restarting failed container
- Unknown
Pending 정상적으로 Pending 상태인 경우
- 새롭게 생성한 배포
- 배포 또는 배포 내 특정 인스턴스(파드)를 재시작하는 경우
- 배포가 업데이트 중인 경우

오류가 발생하여 Pending 상태인 경우
- Initializing
- ContainersReady
- PodScheduled
- Ready
- 기타 오류

값을 잘못 입력하여 인스턴스(파드) 생성과 종료가 반복하며 Pending 또는 Waiting 상태인 경우
- ImagePullBackOff
- ErrImagePull
- CrashLoopBackOff
- 기타 오류
Terminating 인스턴스(파드)가 정상적으로 종료 중인 상태
새로 띄운 상태의 배포, 배포 전체 혹은 특정 인스턴스(파드) 재시작, 배포 업데이트 중인 경우
Terminated 오류가 발생하여 Terminated 상태인 경우
- Unschedulable
Failed 모든 인스턴스(파드) 또는 한 개 이상의 인스턴스(파드)에서 작업 실패하여 종료된 경우
- Exited
- Terminated
Unknown 인스턴스(파드) 상태를 알 수 없는 경우
- 인스턴스(파드)가 실행되어야 하는데 노드와 통신 오류가 발생한 경우

배포 프로토콜 설정

배포를 통신할 프로토콜을 설정할 수 있습니다. 프로토콜은 HTTP와 gRPC를 지원합니다.

  • HTTP(Hyptertext Transfer Protocol)은 웹에서 사용하는 통신 프로토콜입니다. 인터페이스 정의 언어(IDL)은 JSON으로, 텍스트로 전송됩니다.
  • gRPC(Google Remote Procedure Call)는 HTTP 2.0 기반의 고성능 RPC(원격 프로시저 호출) 프레임워크입니다. 인터페이스 정의 언어(IDL)는 Protocol Buffers입니다. 브라우저에서 gRPC를 직접 호출할 수 없습니다. 자세한 내용은 gRPC 공식 가이드를 참고하시기 바랍니다.

환경변수 설정

key=value 형태로 배포 환경변수를 설정할 수 있습니다.

  • 배포당 최대 50개 추가 가능합니다.
  • proxy 또는 no_proxy 구성이 필요할 경우, 환경변수로 설정합니다. (예. no_proxy=“127.0.0.1,localhost”)
표배포 이름 설정
항목 설명
키 - 필수값
- 영어 대소문자(A-Z, a-z), 숫자(0-9), 밑줄(_)만 입력 가능
- 숫자로 시작할 수 없음
- 2~63자 입력 가능
값 (선택) - 선택값
- 최대 1,024자 입력 가능

배포 트래픽 설정

엔드포인트에 모델을 배포할 때, 배포별 트래픽 비율을 설정할 수 있습니다. 엔드포인트별 트래픽 비율은 항상 전체의 합이 100%가 되어야 합니다. 예를 들어, 2개의 모델 배포의 트래픽 비율을 10:90, 50:50, 65:35 등으로 설정할 수 있습니다. 설정한 트래픽 비율은 엔드포인트 생성 이후에도 변경할 수 있습니다.

  • CLI에서는 배포별 트래픽을 비율로 할당할 수 있습니다. (예. 1:2)
  • 웹 콘솔에서 배포별 트래픽 할당은 5의 배수로 설정 가능하며, 전체 합이 100%가 되어야 합니다. (예. 5, 10, 15, 20, …100)

트래픽 미러링

트래픽 미러링은 배포된 여러 모델에 100% 트래픽을 동일하게 전송합니다. 트래픽 미러링을 활성화한 경우, 하나의 배포에서만 API 호출 응답 결과를 받을 수 있습니다.

배포 헬스체크

배포 타입이 ‘커스텀 이미지’일 경우, 모델을 서빙한 배포 인스턴스의 활성 상태(Liveness)와 준비 상태(Readiness)를 진단할 수 있는 헬스체크 기능을 제공합니다. 그 외 배포 타입은 Kakao i Machine Learning에서 자동으로 배포 인스턴스 헬스체크를 관리합니다.

준비 상태 (Readiness)

배포의 인스턴스가 요청을 처리할 준비가 되었는지 확인합니다.

  • 설정한 호출 간격 주기로 체크합니다. 허용된 실패 횟수만큼 연속적으로 호출에 실패할 경우, 해당 인스턴스는 Not Ready 상태로 변경되며 호출 대상에서 제외됩니다.
  • HTTP Probe 또는 TCP Probe 중 한 가지 방법만 선택할 수 있습니다.
  • 인스턴스가 준비 상태가 일시적으로 불가능할 수 있습니다. 아래와 같은 경우 해당 파드는 사용할 수 없는 상태(Unhealthy Pod)로 표시되며 서비스에서 제외됩니다.
    • 배포를 만들거나 재시작하는 경우에 상태값은 Running이지만 Configuration을 로딩 중일 경우
    • 외부 서비스를 호출하는 경우
    • 많은 양의 데이터를 불러오는 경우

활성 상태 (Liveness)

배포의 인스턴스가 정상적으로 동작 중인지 확인합니다.

  • 배포의 인스턴스 상태를 주기적으로 체크하며, 실패 허용 횟수만큼 연속적으로 응답이 없을 경우 인스턴스를 자동으로 재시작합니다.
  • HTTP Probe 또는 TCP Probe 중 한 가지 방법만 선택 가능합니다.

안내
활성 상태(Liveness)는 준비 상태(Readiness) 보다 보수적으로 설정하여, 오류가 발생한 파드에 트래픽 유입되는 것을 먼저 차단되도록 설정하는 것을 권장합니다.

  • 서비스가 안정적인 경우에는 활성 상태(Liveness)를 설정하지 않는 것이 효율적일 수 있습니다.

배포 인스턴스 상태

표배포 인스턴스 상태별 Probe 유형
항목 Probe 유형 설명
배포 인스턴스
준비 상태 (Readiness)		 HTTP Probe - HTTP Get을 이용하여 배포 상태를 체크함
- 200, 300번대 이외의 HTTP 응답 코드는 비정상으로 판단하고 호출 대상에서 제외함
TCP Probe - TCP Socket의 지정된 포트로 연결을 시도함
- 연결에 성공할 경우 파드가 정상으로 판단함
- 실패 허용 횟수만큼 연결 실패 시, 비정상으로 간주하며 호출 대상에서 제외함
배포 인스턴스
활성 상태 (Liveness)		 HTTP Probe - HTTP Get을 이용하여 배포 상태를 체크함
- 실패 허용 횟수만큼 200, 300번대 이외의 HTTP 응답 코드를 연속으로 받을 경우, 비정상으로 판단하고 인스턴스를 재시작함
TCP Probe - TCP Socket의 지정된 포트로 연결을 시도함
- 연결에 성공할 경우 파드가 정상으로 판단함
- 실패 허용 횟수만큼 연속으로 연결 실패 시, 비정상으로 간주하고 인스턴스를 재시작함

배포 수정

엔드포인트 상세 화면에서 기존에 생성한 배포 구성을 수정하거나 신규 배포를 추가할 수 있습니다.
배포 수정을 지원하지 않는 항목은 다음과 같습니다.

  • 배포 이름
  • 클러스터 구성
안내
기존에 배포를 구성한 모델이나 이미지를 삭제한 경우, 배포를 수정할 수 없습니다. 추론 또는 서빙할 모델이나 이미지를 다시 등록 후 신규 배포를 만드시기 바랍니다.
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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