호스팅 서비스를 사용한 사용자 지정 추론 코드 - Amazon SageMaker AI
SageMaker AI가 추론 이미지를 실행하는 방법SageMaker AI가 모델 아티팩트를 로드하는 방법컨테이너의 추론 요청 응답 방법컨테이너의 상태 확인(핑) 요청 응답 방법

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

호스팅 서비스를 사용한 사용자 지정 추론 코드

이 섹션에서는 Amazon SageMaker AI가 호스팅 서비스를 위해 자체 추론 코드를 실행하는 Docker 컨테이너와 상호 작용하는 방법을 설명합니다. 이 정보를 사용하여 추론 코드를 작성하고 Docker 이미지를 생성합니다.

주제

SageMaker AI가 추론 이미지를 실행하는 방법

컨테이너를 실행 파일로 실행하도록 구성하려면 Dockerfile에서 ENTRYPOINT 지침을 사용합니다. 다음 사항에 유의하세요.

  • 모델 추론의 경우 SageMaker AI는 컨테이너를 다음과 같이 실행합니다.

    docker run image serve

    SageMaker AI는 이미지 이름 뒤에 serve 인수를 지정하여 컨테이너의 기본 CMD 문을 재정의합니다. serve 인수는 또한 Dockerfile에서 CMD 명령을 사용하여 입력한 인수 또한 재정의합니다.

     

  • SageMaker AI는 모든 컨테이너가 루트 사용자와 함께 실행될 것으로 예상합니다. 루트 사용자만 사용하도록 컨테이너를 생성하세요. SageMaker AI가 컨테이너를 실행할 때 루트 수준 액세스 권한이 없는 사용자는 권한 문제를 일으킬 수 있습니다.

     

  • exec 지침의 ENTRYPOINT 양식을 사용하는 것이 좋습니다.

    ENTRYPOINT ["executable", "param1", "param2"]

    예시:

    ENTRYPOINT ["python", "k_means_inference.py"]

    exec 형식의 ENTRYPOINT 명령은, /bin/sh의 하위로서가 아니라, 실행 파일을 직접 시작합니다. 이를 통해 SageMaker API로부터 SIGTERM 및 SIGKILL과 같은 신호를 수신할 수 있으며, 이는 필수 사항입니다.

     

    예를 들어 CreateEndpoint API를 사용하여 엔드포인트를 생성할 때 SageMaker AI는 요청에 지정한 엔드포인트 구성에 필요한 ML 컴퓨팅 인스턴스 수를 프로비저닝합니다. SageMaker AI는 해당 인스턴스에서 Docker 컨테이너를 실행합니다.

     

    엔드포인트를 지원하는 인스턴스 수를 줄이면(UpdateEndpointWeightsAndCapacitiesAPI를 호출하여) SageMaker AI는 명령을 실행하여 종료되는 인스턴스에서 Docker 컨테이너를 중지합니다. 명령은 SIGTERM 신호를 전송한 다음 30초 후에 SIGKILL 신호를 전송합니다.

     

    엔드포인트를 업데이트하면(UpdateEndpointAPI를 호출하여) SageMaker AI는 다른 ML 컴퓨팅 인스턴스 세트를 시작하고 추론 코드가 포함된 Docker 컨테이너를 실행합니다. 그런 다음 명령을 실행하여 이전 Docker 컨테이너를 중지합니다. Docker 컨테이너를 중지하려면 명령은 SIGTERM 신호를 전송한 다음 30초 후에 SIGKILL 신호를 전송합니다.

     

  • SageMaker AI는 CreateModel 요청에 제공한 컨테이너 정의를 사용하여 다음과 같이 컨테이너의 환경 변수 및 DNS 호스트 이름을 설정합니다.

     

    • ContainerDefinition.Environment 문자열 간 맵을 사용하여 환경 변수를 설정합니다.

    • ContainerDefinition.ContainerHostname을 사용하여 DNS 호스트 이름을 설정합니다.

       

  • (CreateEndpointConfig 요청에 GPU 기반 ML 컴퓨팅 인스턴스를 지정하여) 모델 추론에 GPU 디바이스를 사용하려는 경우 컨테이너가 nvidia-docker와 호환 가능한지 확인해야 합니다. 이미지가 포함된 NVIDIA 드라이버를 번들화하지 마세요. nvidia-docker에 대한 자세한 정보는 NVIDIA/nvidia-docker를 참조하세요.

     

  • tini 초기화기는 train 및 serve 인수와 혼동되므로 SageMaker AI 컨테이너의 진입점으로 사용할 수 없습니다.

SageMaker AI가 모델 아티팩트를 로드하는 방법

CreateModel API 요청에서 사용자는 ModelDataUrl 또는 S3DataSource 파라미터를 사용하여 모델 아티팩트가 저장되는 S3 위치를 식별할 수 있습니다. SageMaker AI는 추론 코드에서 사용할 수 있도록 모델 아티팩트를 S3 위치에서 /opt/ml/model 디렉터리로 복사합니다. 컨테이너에 /opt/ml/model에 대한 읽기 전용 액세스 권한이 있습니다. 이 디렉터리에는 쓰지 마세요.

ModelDataUrl은 tar.gz 파일을 가리켜야 합니다. 그렇지 않으면 SageMaker AI가 파일을 다운로드하지 않습니다.

SageMaker AI에서 모델을 훈련한 경우 모델 아티팩트는 Amazon S3에 단일 압축 tar 파일로 저장됩니다. SageMaker AI 외부에서 모델을 훈련시킨 경우이 단일 압축 tar 파일을 생성하여 S3 위치에 저장해야 합니다. SageMaker AI는 컨테이너가 시작되기 전에이 tar 파일을 /opt/ml/model 디렉터리로 압축 해제합니다.

대형 모델을 배포하는 경우 압축되지 않은 모델 배포하기을 수행하는 것을 권장합니다.

컨테이너의 추론 요청 응답 방법

추론을 얻기 위해 클라이언트 애플리케이션은 SageMaker AI 엔드포인트에 POST 요청을 보냅니다. SageMaker AI는 요청을 컨테이너에 전달하고 컨테이너의 추론 결과를 클라이언트에 반환합니다.

컨테이너가 수신할 추론 요청에 대한 자세한 내용은 Amazon SageMaker AI API 참조의 다음 작업을 참조하세요.

추론 컨테이너 요구 사항

추론 요청에 응답하려면 컨테이너가 다음 요구 사항을 충족해야 합니다.

  • SageMaker AI는에서 지원하는 헤더를 제외한 모든 POST 헤더를 제거합니다InvokeEndpoint. SageMaker AI는 헤더를 추가할 수 있습니다. 추론 컨테이너는 이러한 추가 헤더를 안전하게 무시할 수 있어야 합니다.

  • 추론 요청을 수신하려면 컨테이너에 포트 8080에서 수신하는 웹 서버가 있어야 하고, /invocations 및 /ping 엔드포인트에 대한 POST 요청을 수락해야 합니다.

  • 고객의 모델 컨테이너는 250ms 이내에 소켓 연결 요청을 수락해야 합니다.

  • 고객의 모델 컨테이너는 60초 안에 요청에 응답해야 합니다. 모델 자체가 /invocations에 응답하는 데 최대 처리 시간이 60초까지 걸릴 수 있기 때문입니다. 모델에서 처리하는 데 50~60초가량 걸린다면 SDK 소켓 시간제한을 70초로 설정해야 합니다.

예 호출 함수

다음 예제에서는 컨테이너의 코드가 추론 요청을 처리하는 방법을 보여 줍니다. 이 예제는 InvokeEndpoint 작업을 사용하여 클라이언트 애플리케이션이 보내는 요청을 처리합니다.

FastAPI

FastAPI는 Python으로 API를 빌드하기 위한 웹 프레임워크입니다.

from fastapi import FastAPI, status, Request, Response
. . .
app = FastAPI()
. . .
@app.post('/invocations')
async def invocations(request: Request):
    # model() is a hypothetical function that gets the inference output:
    model_resp = await model(Request)

    response = Response(
        content=model_resp,
        status_code=status.HTTP_200_OK,
        media_type="text/plain",
    )
    return response
. . .

이 예제에서 invocations 함수는 SageMaker AI가 /invocations 엔드포인트로 보내는 추론 요청을 처리합니다.

Flask

Flask는 Python으로 웹 애플리케이션을 개발하기 위한 프레임워크입니다.

import flask
. . .
app = flask.Flask(__name__)
. . .
@app.route('/invocations', methods=["POST"])
def invoke(request):
    # model() is a hypothetical function that gets the inference output:
    resp_body = model(request)
    return flask.Response(resp_body, mimetype='text/plain')

이 예제에서 invoke 함수는 SageMaker AI가 /invocations 엔드포인트로 보내는 추론 요청을 처리합니다.

예 스트리밍 요청을 위한 호출 함수

다음 예제에서는 추론 컨테이너의 코드가 스트리밍 추론 요청을 처리하는 방법을 보여 줍니다. 이 예제는 InvokeEndpointWithResponseStream 작업을 사용하여 클라이언트 애플리케이션이 보내는 요청을 처리합니다.

컨테이너가 스트리밍 추론 요청을 처리할 때, 컨테이너는 모델의 추론을 모델이 생성함에 따라 점진적으로 일련의 부분으로 반환합니다. 클라이언트 애플리케이션은 응답이 제공되는 즉시 응답을 받기 시작합니다. 모델이 전체 응답을 생성할 때까지 기다릴 필요가 없습니다. 사용자는 스트리밍을 구현하여 챗봇, 가상 어시스턴트, 음악 생성기와 같은 빠른 대화형 환경을 지원할 수 있습니다.

FastAPI

FastAPI는 Python으로 API를 빌드하기 위한 웹 프레임워크입니다.

from starlette.responses import StreamingResponse
from fastapi import FastAPI, status, Request
. . .
app = FastAPI()
. . .
@app.post('/invocations')
async def invocations(request: Request):
    # Streams inference response using HTTP chunked encoding
    async def generate():
        # model() is a hypothetical function that gets the inference output:
        yield await model(Request)
        yield "\n"

    response = StreamingResponse(
        content=generate(),
        status_code=status.HTTP_200_OK,
        media_type="text/plain",
    )
    return response
. . .

이 예제에서 invocations 함수는 SageMaker AI가 /invocations 엔드포인트로 보내는 추론 요청을 처리합니다. 응답을 스트리밍하기 위해 예제에서는 Starlette 프레임워크의 StreamingResponse 클래스를 사용합니다.

Flask

Flask는 Python으로 웹 애플리케이션을 개발하기 위한 프레임워크입니다.

import flask
. . .
app = flask.Flask(__name__)
. . .
@app.route('/invocations', methods=["POST"])
def invocations(request):
    # Streams inference response using HTTP chunked encoding

    def generate():
        # model() is a hypothetical function that gets the inference output:
        yield model(request)
        yield "\n"
    return flask.Response(
        flask.stream_with_context(generate()), mimetype='text/plain')
. . .

이 예제에서 invocations 함수는 SageMaker AI가 /invocations 엔드포인트로 보내는 추론 요청을 처리합니다. 응답을 스트리밍하기 위해 예제에서는 Flask 프레임워크의 flask.stream_with_context 함수를 사용합니다.

컨테이너의 상태 확인(핑) 요청 응답 방법

SageMaker AI는 다음과 같은 상황에서 새 추론 컨테이너를 시작합니다.

  • CreateEndpoint, UpdateEndpoint, UpdateEndpointWeightsAndCapacities API 직접 호출에 대한 응답

  • 보안 패치

  • 비정상 인스턴스 대체

컨테이너 시작 직후 SageMaker AI는 /ping 엔드포인트에 주기적 GET 요청을 보내기 시작합니다.

컨테이너에 대한 가장 간단한 요구 사항은 HTTP 200 상태 코드 및 비어 있는 본문을 포함하여 응답하는 것입니다. 이는 SageMaker AI에 컨테이너가 /invocations 엔드포인트에서 추론 요청을 수락할 준비가 되었음을 나타냅니다.

시작 후 8분 동안 지속적으로 200초로 응답하여 컨테이너가 상태 확인을 통과하지 못하면 새 인스턴스 시작이 실패합니다. 이는 CreateEndpoint에 장애가 발생하여 엔드포인트가 실패 상태가 되는 원인이 됩니다. UpdateEndpoint에서 요청한 업데이트가 완료되지 않고, 보안 패치가 적용되지 않으며, 비정상 인스턴스가 교체되지 않게 됩니다.

최소 기준이 컨테이너가 정적 200을 반환하는 반면 컨테이너 개발자는 이 기능을 사용하여 더욱 자세한 확인을 수행할 수 있습니다. /ping 시도의 요청 제한 시간은 2초입니다.