스튜디오 클래식을 사용하여 호출 Python용 SDK(Boto3)를 사용하여 호출 AWS CLI를 사용하여 호출

실시간 추론을 위한 모델 호출

SageMaker 호스팅 서비스를 사용하여 모델을 배포한 후에는 테스트 데이터를 전송하여 해당 엔드포인트에서 모델을 테스트할 수 있습니다. Amazon SageMaker Studio Classic, AWS SDK 또는 를 사용하여 엔드포인트를 테스트할 수 있습니다. AWS CLI

Amazon SageMaker 스튜디오 클래식을 사용하여 엔드포인트 호출

엔드포인트에 모델을 배포한 후 Amazon SageMaker Studio Classic에서 해당 엔드포인트를 확인할 수 있습니다.

참고

참고: 실시간 엔드포인트에 대해 Amazon SageMaker Studio Classic을 사용한 엔드포인트 SageMaker 테스트만 지원합니다.

엔드포인트에 테스트 추론 요청을 보내려면

Amazon SageMaker 스튜디오 클래식을 시작하세요.
왼쪽 탐색 패널의 홈 섹션에서 배포를 선택합니다.
드롭다운에서 엔드포인트를 선택합니다.
이름으로 엔드포인트를 찾고 표에서 이름을 선택합니다. 엔드포인트 패널에 나열된 엔드포인트 이름은 모델을 배포할 때 정의됩니다. Studio 작업 영역에서 엔드포인트 페이지가 새 탭에서 열립니다.
테스트 추론 탭에서 샘플 데이터를 JSON 형식으로 제공하여 엔드포인트에 요청을 보냅니다. JSON 에디터를 사용하여 엔드포인트에 요청을 제출하십시오.
(선택 사항) 요청을 보낼 사용자 지정 URL을 제공할 수 있습니다. 엔드포인트 URL 및 헤더 구성 섹션의 사용자 지정 URL 필드에 모델이 호스팅되는 곳의 URL을 입력합니다. SageMaker 엔드포인트를 사용하는 경우 이 필드를 비워 두십시오. 헤더 아래에서 사용자는 선택적으로 키-값 헤더를 추가하여 추론 요청과 함께 추가 정보를 전달할 수도 있습니다.
요청 전송을 선택합니다. Studio는 JSON 에디터 오른쪽에 있는 카드에 추론 출력을 표시합니다.

카드 상단에는 엔드포인트로 전송된 요청 유형이 표시됩니다 (JSON만 허용). 카드에는 다음 필드가 표시됩니다.

상태 - 다음 상태 유형 중 하나를 표시합니다.
- Complete – 요청이 성공했습니다.
- Failed – 요청이 실패했습니다. 실패 사유 아래에 응답이 표시됩니다.
- Pending - 추론 요청이 보류 중인 동안에는 상태에 회전하는 원형 아이콘이 표시됩니다.
실행 길이 - 호출에 걸린 시간(종료 시간에서 시작 시간을 뺀 값)을 밀리초 단위로 나타냅니다.
요청 시간 - 요청이 전송된 후 몇 분이 경과했는지입니다.
결과 시간 - 결과가 반환된 후 몇 분이 경과했는지를 나타냅니다.

AWS SDK for Python (Boto3)를 사용하여 엔드포인트 호출

엔드포인트에 모델을 배포한 후 다음을 포함한 AWS SDK 중 하나를 사용하여 엔드포인트를 확인할 수 있습니다. AWS SDK for Python (Boto3) 이 SDK로 엔드포인트를 테스트하려면 다음 방법 중 하나를 사용합니다.

invoke_endpoint - 모델 엔드포인트에 추론 요청을 보내고 모델이 생성한 응답을 반환합니다. 이 메서드는 모델이 추론 페이로드를 생성한 후 하나의 응답으로 추론 페이로드를 반환합니다. 자세한 내용은 Python용 AWSSDK(Boto3) API 참조의 invoke_endpoint 항목을 참조하세요.
invoke_endpoint_with_response_stream - 모델 엔드포인트에 추론 요청을 보내고 모델이 추론을 생성하는 동안 응답을 증분식으로 스트리밍합니다. 이 방법을 사용하면 부품을 사용할 수 있게 되면 클라이언트 애플리케이션이 응답의 일부를 즉시 수신하기 시작합니다. 클라이언트는 모델이 전체 응답 페이로드를 생성할 때까지 기다릴 필요가 없습니다. 사용자는 스트리밍을 구현하여 챗봇, 가상 어시스턴트, 음악 생성기와 같은 빠른 대화형 환경을 지원할 수 있습니다.

이 메서드는 추론 스트리밍을 지원하는 모델을 호출할 때만 사용하십시오.

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

클라이언트 코드에서 이러한 메서드를 사용하려면 먼저 SageMaker Runtime 클라이언트를 만들고 엔드포인트의 이름을 지정해야 합니다. 다음 예제는 이어지는 나머지 예제를 위해 클라이언트와 엔드포인트를 설정합니다.


import boto3

# Create a low-level client representing Amazon SageMaker Runtime
sagemaker_runtime = boto3.client(
    "sagemaker-runtime", region_name='aws_region')

# The endpoint name must be unique within 
# an AWS Region in your AWS account. 
endpoint_name='endpoint-name'

호출하여 추론 응답 가져오기

다음 예시에서는 invoke_endpoint 메서드를 사용하여 AWS SDK for Python (Boto3)을 포함하는 엔드포인트를 호출합니다.


# Gets inference from the model hosted at the specified endpoint:
response = sagemaker_runtime.invoke_endpoint(
    EndpointName=endpoint_name, 
    Body=bytes('{"features": ["This is great!"]}', 'utf-8')
    )

# Decodes and prints the response body:
print(response['Body'].read().decode('utf-8'))

이 예제는 모델에 SageMaker 전달할 Body 필드에 입력 데이터를 제공합니다. 이 데이터는 학습에 사용한 것과 동일한 형식이어야 합니다. 이 예제에서는 response 변수에 응답을 저장합니다.

response 변수는 HTTP 상태, 배포된 모델 이름 및 기타 필드에 대한 액세스를 제공합니다. 다음 스니펫은 HTTPStatusCode를 인쇄합니다.


print(response["HTTPStatusCode"])

호출하여 추론 응답을 스트리밍합니다.

추론 스트리밍을 지원하는 모델을 배포한 경우 사용자는 모델을 호출하여 추론 페이로드를 파트 스트림으로 수신할 수 있습니다. 모델은 모델이 이러한 부분을 생성할 때 이러한 부분을 점진적으로 제공합니다. 애플리케이션이 추론 스트림을 수신하면 애플리케이션이 모델이 전체 응답 페이로드를 생성할 때까지 기다릴 필요가 없습니다. 대신 애플리케이션은 응답이 제공되는 즉시 일부 응답을 받기 시작합니다.

애플리케이션에서 추론 스트림을 사용하면 사용자가 첫 번째 부분을 즉시 받기 때문에 추론이 빠르다고 인식할 수 있는 상호 작용을 만들 수 있습니다. 예를 들어 대규모 언어 모델(LLM)에서 생성된 텍스트를 점진적으로 표시하는 챗봇을 만들 수 있습니다.

추론 스트림을 가져오려면 사용자는 SDK for Python(Boto3)의 invoke_endpoint_with_response_stream 메서드를 사용할 수 있습니다. 응답 본문에서 SDK는 EventStream 객체를 제공하며, 이 객체는 추론을 일련의 PayloadPart 객체로 제공합니다.

예 추론 스트림

다음 예제는 PayloadPart JSON 객체의 스트림입니다.


{'PayloadPart': {'Bytes': b'{"outputs": [" a"]}\n'}}
{'PayloadPart': {'Bytes': b'{"outputs": [" challenging"]}\n'}}
{'PayloadPart': {'Bytes': b'{"outputs": [" problem"]}\n'}}
. . .

각 페이로드 부분에서 Bytes 필드는 모델의 추론 응답의 일부를 제공합니다. 이 부분은 텍스트, 이미지, 오디오 데이터 등 모델이 생성하는 모든 콘텐츠 유형일 수 있습니다. 이 예제에서 부분은 LLM에서 생성된 텍스트를 포함하는 JSON 객체입니다.

일반적으로 페이로드 부분에는 모델의 개별 데이터 청크가 포함됩니다. 이 예제에서는 불연속형 청크가 전체 JSON 객체입니다. 스트리밍 응답이 청크를 여러 페이로드 부분으로 분할하거나 여러 청크를 하나의 페이로드 부분으로 결합하는 경우가 있습니다. 다음 예제는 두 페이로드 부분으로 분할된 JSON 형식의 데이터 청크를 보여줍니다.


{'PayloadPart': {'Bytes': b'{"outputs": '}}
{'PayloadPart': {'Bytes': b'[" problem"]}\n'}}

추론 스트림을 처리하는 애플리케이션 코드를 작성할 때는 이러한 가끔 발생하는 데이터 분할 및 조합을 처리하는 로직을 포함하세요. 한 가지 전략으로는 애플리케이션이 페이로드 부분을 수신하는 동안 Bytes의 내용을 연결하는 코드를 작성할 수 있습니다. 여기에 있는 예제 JSON 데이터를 연결하면 데이터를 줄바꿈으로 구분된 JSON 본문으로 결합할 수 있습니다. 그러면 코드가 각 줄의 전체 JSON 객체를 파싱하여 스트림을 처리할 수 있습니다.

다음 예제는 Bytes의 예제 내용을 연결할 때 생성되는 줄바꿈으로 구분된 JSON을 보여줍니다.


{"outputs": [" a"]}
{"outputs": [" challenging"]}
{"outputs": [" problem"]}
. . .

예 추론 스트림을 처리하는 코드

다음 예제 Python 클래스 SmrInferenceStream는 사용자가 텍스트 데이터를 JSON 형식으로 보내는 추론 스트림을 처리하는 방법을 보여줍니다.


import io
import json

# Example class that processes an inference stream:
class SmrInferenceStream:
    
    def __init__(self, sagemaker_runtime, endpoint_name):
        self.sagemaker_runtime = sagemaker_runtime
        self.endpoint_name = endpoint_name
        # A buffered I/O stream to combine the payload parts:
        self.buff = io.BytesIO() 
        self.read_pos = 0
        
    def stream_inference(self, request_body):
        # Gets a streaming inference response 
        # from the specified model endpoint:
        response = self.sagemaker_runtime\
            .invoke_endpoint_with_response_stream(
                EndpointName=self.endpoint_name, 
                Body=json.dumps(request_body), 
                ContentType="application/json"
        )
        # Gets the EventStream object returned by the SDK:
        event_stream = response['Body']
        for event in event_stream:
            # Passes the contents of each payload part
            # to be concatenated:
            self._write(event['PayloadPart']['Bytes'])
            # Iterates over lines to parse whole JSON objects:
            for line in self._readlines():
                resp = json.loads(line)
                part = resp.get("outputs")[0]
                # Returns parts incrementally:
                yield part
    
    # Writes to the buffer to concatenate the contents of the parts:
    def _write(self, content):
        self.buff.seek(0, io.SEEK_END)
        self.buff.write(content)

    # The JSON objects in buffer end with '\n'.
    # This method reads lines to yield a series of JSON objects:
    def _readlines(self):
        self.buff.seek(self.read_pos)
        for line in self.buff.readlines():
            self.read_pos += len(line)
            yield line[:-1]

이 예제에서는 다음을 수행하여 추론 스트림을 처리합니다.

SageMaker 런타임 클라이언트와 모델 엔드포인트의 이름을 사용하여 초기화됩니다. 사용자가 인퍼런스 스트림을 가져오려면 엔드포인트가 호스트하는 모델이 인퍼런스 스트리밍을 지원해야 합니다.
예제 stream_inference 메서드에서는 요청 본문을 수신하여 SDK의 invoke_endpoint_with_response_stream 메서드에 전달합니다.
SDK가 반환하는 EventStream 객체의 각 이벤트를 반복합니다.
각 이벤트에서 PayloadPart 객체에 있는 Bytes 객체의 내용을 가져옵니다.
예제 _write 메서드에서는 버퍼에 기록하여 Bytes 객체의 내용을 연결합니다. 결합된 내용은 줄바꿈으로 구분된 JSON 본문을 형성합니다.
예제 _readlines 메서드를 사용하여 반복 가능한 일련의 JSON 객체를 가져옵니다.
각 JSON 객체에서 추론의 일부를 가져옵니다.
yield 표현식을 사용하면 조각들을 점진적으로 반환합니다.

다음 예제에서는 SmrInferenceStream 객체를 만들고 사용합니다.


request_body = {"inputs": ["Large model inference is"],
                "parameters": {"max_new_tokens": 100,
                               "enable_sampling": "true"}}
smr_inference_stream = SmrInferenceStream(
    sagemaker_runtime, endpoint_name)
stream = smr_inference_stream.stream_inference(request_body)
for part in stream:
    print(part, end='')

이 예제는 요청 본문을 stream_inference 메서드에 전달합니다. 응답을 반복하여 추론 스트림이 반환하는 각 부분을 인쇄합니다.

이 예제에서는 지정된 엔드포인트의 모델이 텍스트를 생성하는 LLM이라고 가정합니다. 이 예제의 출력은 점진적으로 인쇄되는 생성된 텍스트 본문입니다.


a challenging problem in machine learning. The goal is to . . .

AWS CLI를 사용하여 엔드포인트 호출

사용자는 AWS Command Line Interface(AWS CLI)로 명령을 실행하여 엔드포인트를 테스트할 수 있습니다. AWS CLI는 invoke-endpoint 명령을 통한 표준 추론 요청을 지원하고 invoke-endpoint-async 명령을 통한 비동기 추론 요청을 지원합니다.

참고

AWS CLI는 스트리밍 추론 요청을 지원하지 않습니다.

다음 예시에서는 invoke-endpoint 명령을 사용하여 모델 엔드포인트에 추론 요청을 보냅니다.


aws sagemaker-runtime invoke-endpoint \
    --endpoint-name endpoint_name \
    --body fileb://$file_name \
    output_file.txt

--endpoint-name 파라미터에는 CreateEndpoint로 엔드포인트를 생성할 때 EndpointName에 사용한 이름을 입력합니다. --body파라미터에 대해 모델에 SageMaker 전달할 입력 데이터를 제공하십시오. 데이터는 학습에 사용한 것과 동일한 형식이어야 합니다. 이 예제는 엔드포인트로 이진 데이터를 보내는 방법을 보여줍니다.

파일 내용을 AWS CLI의 파라미터에 전달할 때 fileb:// 대신 file://을 사용해야 하는 경우에 대한 자세한 내용은 로컬 파일 파라미터 모범 사례를 참조하세요.

자세한 내용과 전달할 수 있는 추가 파라미터를 보려면 사용자는 AWS CLI 명령 참조서의 invoke-endpoint 단원을 참조하세요.

invoke-endpoint 명령이 성공하면 다음과 같은 응답이 반환됩니다.


{
    "ContentType": "<content_type>; charset=utf-8",
    "InvokedProductionVariant": "<Variant>"
}

명령이 성공하지 못하면 입력 페이로드가 올바른 형식인지 확인합니다.

파일 출력 파일(이 예제에서는 output_file.txt)을 확인하여 호출 결과를 확인합니다.


more output_file.txt

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

모델 배포

엔드포인트 관리