TorchServe 추론 API

TorchServe 추론 API (Inference API)

TorchServe는 서빙된 모델로부터 예측을 받아오기 위한 추론 API를 제공해요. 기본적으로 포트 8080에서 수신 대기하고, 기본 설정에서는 localhost에서만 접근할 수 있어요. 기본 설정을 바꾸려면 TorchServe 설정을 참고하면 돼요.

출처: TorchServe Inference API (공식)

지원하는 API

TorchServe 서버는 여러 추론 API를 지원해요.

API 설명 — 사용 가능한 API와 옵션 목록 가져오기
헬스 체크 API — 실행 중인 서버의 상태 확인
예측 API — 서빙된 모델의 예측 가져오기
설명 API — 서빙된 모델의 설명 가져오기
KServe 추론 API — KServe로부터 서빙된 모델의 예측 가져오기
KServe 설명 API — KServe로부터 서빙된 모델의 설명 가져오기

API 설명

사용 가능한 추론 API 전체 목록을 보려면 이 커맨드를 써요. OpenAPI 3.0.1 JSON 형식으로 출력돼요.

curl -X OPTIONS http://localhost:8080

출력된 스펙으로 클라이언트 코드를 생성할 수도 있어요.

헬스 체크 API

서버가 잘 실행 중인지 확인하려면 ping API를 호출해요.

curl http://localhost:8080/ping

서버가 실행 중이면 응답은 이렇게 와요.

{ "status": "Healthy" }

ping은 모델별 액티브 워커 수가 설정된 minWorkers 이상이면 200 + "healthy", 미만이면 500 + "unhealthy"를 반환해요.

예측 API

로드된 모델의 기본 버전에서 예측을 받아오려면 /predictions/{model_name}에 REST 호출을 해요.

curl http://localhost:8080/predictions/resnet-18 -T kitten_small.jpg

또는 -F 옵션으로 파일을 보낼 수도 있어요.

curl http://localhost:8080/predictions/resnet-18 -F "data=@kitten_small.jpg"

특정 버전의 모델에서 예측을 받으려면 /predictions/{model_name}/{version}을 호출해요.

curl http://localhost:8080/predictions/resnet-18/2.0 -T kitten_small.jpg

응답은 이미지가 고양이일 가능성이 높다는 것을 알려주는 JSON이에요.

{ "class": "n02123045 tabby, tabby cat", "probability": 0.42514491081237793 }

스트리밍 응답

TorchServe는 HTTP/1.1 chunked encoding으로 스트리밍 응답을 지원해요. 전체 응답의 지연이 높고 중간 결과를 클라이언트에 보내는 게 유용한 경우(예: LLM 생성)에 권장돼요. 백엔드 핸들러가 send_intermediate_predict_response를 호출해 중간 결과를 하나씩 frontend에 보내고, 마지막 결과를 기존 방식으로 반환해요.

from ts.handler_utils.utils import send_intermediate_predict_response

def handle(data, context):
    if type(data) is list:
        for i in range(3):
            send_intermediate_predict_response(
                ["intermediate_response"], context.request_ids,
                "Intermediate Prediction success", 200, context)
    return ["hello world"]

클라이언트는 청크된 데이터를 받아요.

설명 API

TorchServe는 Captum 기능을 사용해 서빙된 모델의 설명을 반환해요. /explanations/{model_name}에 REST 호출을 하면 됩니다.

curl http://127.0.0.1:8080/explanations/mnist -T examples/image_classifier/mnist/test_data/0.png

KServe API

KServe Inference API를 통해서도 예측을 받아올 수 있어요. /v1/models/{model_name}:predict에 JSON POST를 보내요.

curl -H "Content-Type: application/json" \
  --data @kubernetes/kserve/kf_request_json/v1/mnist.json \
  http://127.0.0.1:8080/v1/models/mnist:predict

응답은 예측을 담은 JSON이에요.

{ "predictions": [2] }

TorchServe 추론 API