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

OpenAI 호환 APIs 사용하여 엔드포인트 간접 호출

Amazon SageMaker AI 실시간 추론 엔드포인트는 OpenAI 호환 API 경로를 지원합니다. OpenAI SDK, LangChain 또는 Strands 에이전트를 사용하는 고객은 사용자 지정 클라이언트, SigV4 래퍼 또는 코드 재작성 없이 엔드포인트 URL만 변경하여 SageMaker AI에서 모델을 호출할 수 있습니다. SigV4

이 기능을 사용하면 SageMaker AI 엔드포인트는 Chat Completions 요청을 수락하고 스트리밍을 포함하여 컨테이너에서 직접 응답을 반환하는 /openai/v1/chat/completions 경로를 노출합니다. OpenAI 호환 엔드포인트는 표준 SageMaker AI APIs 및 SDKs.

SageMaker AI는 URL의 엔드포인트 이름을 기반으로 요청을 라우팅합니다. OpenAI 호환 클라이언트는 추가 구성 없이 작동합니다. 엔드포인트에 대한 수명이 짧은 보유자 토큰을 생성하고 OpenAI 클라이언트와 함께 사용할 수 있습니다.

사전 조건

시작하기 전에 다음 항목이 준비되었는지 확인합니다.

보유자 토큰을 사용한 인증

SageMaker AI OpenAI 호환 엔드포인트는 보유자 토큰 인증을 사용합니다. SageMaker AI Python SDK에는 기존 AWS 자격 증명에서 수명이 짧은 토큰(최대 12시간 유효)을 생성하는 토큰 생성기가 포함되어 있습니다. 추가 보안 암호나 API 키는 필요하지 않습니다.

토큰에는 역할 또는 사용자 자격 증명이 포함되며 sagemaker:CallWithBearerToken 및 sagemaker:InvokeEndpoint 작업 권한이 필요합니다.

토큰 생성

SageMaker AI Python SDK의 generate_token 함수를 사용하여 보유자 토큰을 생성합니다.

from sagemaker.core.token_generator import generate_token
from datetime import timedelta

token = generate_token(region="us-west-2", expiry=timedelta(minutes=5))

generate_token 함수는 SageMaker AI APIs로 인증하기 위한 수명이 짧은 보유자 토큰을 생성합니다. 기본적으로 토큰은 12시간 동안 유효합니다. 1초에서 12시간 사이의 timedelta 값을 사용하여 expiry 파라미터로 이를 재정의할 수 있습니다.

함수는 region, 선택적 aws_credentials_provider및 expiry 기간을 허용합니다. 리전이 제공되지 않으면 AWS_REGION 환경 변수로 돌아갑니다. 자격 증명 공급자가 제공되지 않은 경우 환경 변수, , , ~/.aws/credentials ~/.aws/config컨테이너 자격 증명 및 인스턴스 프로파일을 포함한 여러 소스를 검색하는 기본 AWS 자격 증명 체인을 사용하여 자격 증명을 확인합니다. 전체 해결 순서는 boto3 자격 증명 설명서를 참조하세요.

장기 실행 애플리케이션을 위한 토큰 자동 새로 고침

지속적으로 실행되는 애플리케이션의 경우 각 요청에서 새 토큰이 생성httpx되도록를 사용하여 자동 새로 고침 패턴을 구현할 수 있습니다.

import httpx
from sagemaker.core.token_generator import generate_token

class SageMakerAuth(httpx.Auth):
    def __init__(self, region: str):
        self.region = region

    def auth_flow(self, request):
        request.headers["Authorization"] = f"Bearer {generate_token(region=self.region)}"
        yield request

http_client = httpx.Client(auth=SageMakerAuth(region="us-west-2"))

IAM 권한

엔드포인트를 호출하는 IAM 역할 또는 사용자에게는 다음 권한이 필요합니다.

{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sagemaker:InvokeEndpoint",
            "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint/ENDPOINT_NAME"
        },
        {
            "Effect": "Allow",
            "Action": "sagemaker:CallWithBearerToken",
            "Resource": "*"
        }
    ]
}

토큰 작동 방식

보유자 토큰은 base64로 인코딩된 SigV4 미리 서명된 URL입니다. generate_token를 호출하면 SageMaker AI SDK는 CallWithBearerToken 작업에 대한 SageMaker AI 서비스에 대한 요청을 구성하고, 자격 AWS 증명을 사용하여 로컬로 서명하고, 서명된 결과 URL을 휴대용 토큰 문자열로 인코딩합니다. 토큰 생성 중에는 네트워크 호출이 이루어지지 않습니다. 서명은 전적으로 클라이언트 측에서 이루어집니다.

이 토큰을 SageMaker AI 엔드포인트에 제시하면 서비스가 토큰을 디코딩하고, SigV4 서명을 검증하고, 토큰이 만료되지 않았는지 확인하고, 원래 IAM 자격 증명에 필요한 권한이 있는지 확인합니다. 토큰의 유효 수명은 expiry 값 중 더 작은 값과 토큰에 서명하는 데 사용된 AWS 자격 증명의 나머지 유효 기간입니다.

보안 모범 사례

보유자 토큰은 이를 생성하는 데 사용되는 기본 AWS 자격 증명과 동일한 권한을 가집니다. 자격 증명과 동일한 주의를 기울여 토큰을 처리합니다. 다음 모범 사례를 따르세요.

단일 모델 엔드포인트 호출

단일 모델 엔드포인트는 하나의 모델을 호스팅하고 요청을 직접 제공합니다. 다음 예시에서는 ml.g6.2xlarge 인스턴스에서 SageMaker AI vLLM 딥 러닝 컨테이너를 사용하여 Qwen3-4B를 배포합니다.

엔드포인트 배포

import boto3
import sagemaker
import time
from sagemaker.core.helper.session_helper import Session
from sagemaker.core.helper.session_helper import get_execution_role

# AWS configuration
REGION = "us-west-2"

# Automatically resolve account ID and default SageMaker execution role
session = Session(boto_session=boto3.Session(region_name=REGION))
ACCOUNT_ID = boto3.client("sts", region_name=REGION).get_caller_identity()["Account"]
EXECUTION_ROLE = get_execution_role(sagemaker_session=session)

# HF Model ID
MODEL_HF_ID = "Qwen/Qwen3-4B"

# SageMaker vLLM Deep Learning Container
VLLM_IMAGE = (
    f"763104351884.dkr.ecr.{REGION}.amazonaws.com/"
    f"vllm:0.20.2-gpu-py312-cu130-ubuntu22.04-sagemaker"
)

# Instance type (1x NVIDIA L4 GPU)
INSTANCE_TYPE = "ml.g6.2xlarge"

sagemaker_client = boto3.client("sagemaker", region_name=REGION)

모델, 엔드포인트 구성 및 엔드포인트를 생성합니다.

TIMESTAMP = str(int(time.time()))

SME_MODEL_NAME = f"openai-compat-sme-model-{TIMESTAMP}"
SME_ENDPOINT_CONFIG_NAME = f"openai-compat-sme-epc-{TIMESTAMP}"
SME_ENDPOINT_NAME = f"openai-compat-sme-ep-{TIMESTAMP}"

sagemaker_client.create_model(
    ModelName=SME_MODEL_NAME,
    ExecutionRoleArn=EXECUTION_ROLE,
    PrimaryContainer={
        "Image": VLLM_IMAGE,
        "Environment": {
            "HF_MODEL_ID": MODEL_HF_ID,
            "SM_VLLM_TENSOR_PARALLEL_SIZE": "1",
            "SM_VLLM_MAX_NUM_SEQS": "4",
            "SM_VLLM_ENABLE_AUTO_TOOL_CHOICE": "true",
            "SM_VLLM_TOOL_CALL_PARSER": "hermes",
            "SAGEMAKER_ENABLE_LOAD_AWARE": "1",
        },
    },
)

sagemaker_client.create_endpoint_config(
    EndpointConfigName=SME_ENDPOINT_CONFIG_NAME,
    ProductionVariants=[
        {
            "VariantName": "variant1",
            "ModelName": SME_MODEL_NAME,
            "InstanceType": INSTANCE_TYPE,
            "InitialInstanceCount": 1,
        }
    ],
)

sagemaker_client.create_endpoint(
    EndpointName=SME_ENDPOINT_NAME,
    EndpointConfigName=SME_ENDPOINT_CONFIG_NAME,
)

# Wait for endpoint to reach InService status (5-10 minutes)
waiter = sagemaker_client.get_waiter("endpoint_in_service")
waiter.wait(
    EndpointName=SME_ENDPOINT_NAME,
    WaiterConfig={"Delay": 30, "MaxAttempts": 40},
)

엔드포인트는 몇 분 내에 InService 상태로 전환됩니다. 준비가 되면에서 표준 SageMaker AI /invocations 경로와 OpenAI 호환 경로를 모두 제공합니다/openai/v1/chat/completions.

API 엔드포인트 호출

서비스 중인 엔드포인트에서 OpenAI Python SDK를 사용하여 엔드포인트를 호출합니다. 기본 URL은 다음 형식을 따릅니다.

https://runtime.sagemaker.REGION.amazonaws.com/endpoints/ENDPOINT_NAME/openai/v1

from openai import OpenAI
from sagemaker.core.token_generator import generate_token

REGION = "us-west-2"
sme_base_url = (
    f"https://runtime.sagemaker.{REGION}.amazonaws.com"
    f"/endpoints/{SME_ENDPOINT_NAME}/openai/v1"
)

client = OpenAI(
    base_url=sme_base_url,
    api_key=generate_token(region=REGION),
)

stream = client.chat.completions.create(
    model="",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain how transformers work in machine learning, in three sentences."},
    ],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
print()

model 필드는 컨테이너로 전달됩니다. SageMaker AI는 URL의 엔드포인트 이름을 기반으로 요청을 라우팅하므로이 필드를 비워 두거나 컨테이너가 예상하는 모델 이름과 일치하도록 설정할 수 있습니다.

추론 구성 요소 호출

추론 구성 요소를 사용하면 각각 전용 컴퓨팅 리소스 할당이 있는 단일 엔드포인트에서 여러 모델을 호스팅할 수 있습니다. 추론 구성 요소를 사용하면 모델이 엔드포인트 구성이 아닌 구성 요소와 연결됩니다.

추론 구성 요소 엔드포인트 배포

IC_MODEL_NAME = f"openai-compat-ic-model-{TIMESTAMP}"
IC_ENDPOINT_CONFIG_NAME = f"openai-compat-ic-epc-{TIMESTAMP}"
IC_ENDPOINT_NAME = f"openai-compat-ic-ep-{TIMESTAMP}"
IC_NAME = f"openai-compat-ic-qwen3-4b-{TIMESTAMP}"

sagemaker_client.create_model(
    ModelName=IC_MODEL_NAME,
    ExecutionRoleArn=EXECUTION_ROLE,
    PrimaryContainer={
        "Image": VLLM_IMAGE,
        "Environment": {
            "HF_MODEL_ID": MODEL_HF_ID,
            "SM_VLLM_TENSOR_PARALLEL_SIZE": "1",
            "SM_VLLM_MAX_NUM_SEQS": "4",
            "SM_VLLM_ENABLE_AUTO_TOOL_CHOICE": "true",
            "SM_VLLM_TOOL_CALL_PARSER": "hermes",
            "SAGEMAKER_ENABLE_LOAD_AWARE": "1",
        },
    },
)

sagemaker_client.create_endpoint_config(
    EndpointConfigName=IC_ENDPOINT_CONFIG_NAME,
    ExecutionRoleArn=EXECUTION_ROLE,
    ProductionVariants=[
        {
            "VariantName": "variant1",
            "InstanceType": INSTANCE_TYPE,
            "InitialInstanceCount": 1,
        }
    ],
)

sagemaker_client.create_endpoint(
    EndpointName=IC_ENDPOINT_NAME,
    EndpointConfigName=IC_ENDPOINT_CONFIG_NAME,
)

# Wait for endpoint
waiter = sagemaker_client.get_waiter("endpoint_in_service")
waiter.wait(
    EndpointName=IC_ENDPOINT_NAME,
    WaiterConfig={"Delay": 30, "MaxAttempts": 40},
)

# Create the inference component
sagemaker_client.create_inference_component(
    InferenceComponentName=IC_NAME,
    EndpointName=IC_ENDPOINT_NAME,
    VariantName="variant1",
    Specification={
        "ModelName": IC_MODEL_NAME,
        "ComputeResourceRequirements": {
            "MinMemoryRequiredInMb": 1024,
            "NumberOfCpuCoresRequired": 2,
            "NumberOfAcceleratorDevicesRequired": 1,
        },
    },
    RuntimeConfig={"CopyCount": 1},
)

# Wait for inference component
while True:
    desc = sagemaker_client.describe_inference_component(InferenceComponentName=IC_NAME)
    status = desc["InferenceComponentStatus"]
    if status == "InService":
        break
    elif status == "Failed":
        raise RuntimeError(f"Inference component failed: {desc.get('FailureReason', 'unknown')}")
    time.sleep(30)

동일한 엔드포인트에 추가 추론 구성 요소를 생성하여 독립적인 조정 및 리소스 할당으로 여러 모델을 호스팅할 수 있습니다.

추론 구성 요소 호출

특정 추론 구성 요소를 호출하려면 URL 경로에 해당 이름을 포함합니다.

https://runtime.sagemaker.REGION.amazonaws.com/endpoints/ENDPOINT_NAME/inference-components/IC_NAME/openai/v1

다음 예제에서는 공유 연결 풀과 함께 OpenAI SDK를 사용하여 추론 구성 요소를 호출하는 방법을 보여줍니다.

import httpx
from openai import OpenAI
from sagemaker.core.token_generator import generate_token

shared_http = httpx.Client()

client_a = OpenAI(
    base_url=(
        f"https://runtime.sagemaker.{REGION}.amazonaws.com"
        f"/endpoints/{IC_ENDPOINT_NAME}/inference-components/{IC_NAME}/openai/v1"
    ),
    api_key=generate_token(region=REGION),
    http_client=shared_http,
)

response = client_a.chat.completions.create(
    model="",
    messages=[{"role": "user", "content": "What is 42 * 3? Reply with the number."}],
)
print(response.choices[0].message.content)

공유를 httpx.Client 사용하면 여러 OpenAI 클라이언트 인스턴스가 동일한 엔드포인트에서 서로 다른 추론 구성 요소를 대상으로 할 때 동일한 TLS 세션 및 연결 풀을 재사용할 수 있습니다.

지원되는 컨테이너

다음 컨테이너는 SageMaker AI에서 OpenAI 호환 APIs 지원합니다. 컨테이너는 /v1/chat/completions 경로를 구현하고 스트리밍 응답을 SSE 형식으로 반환해야 합니다.