As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Invoque endpoints com APIs OpenAI-compatible

Os endpoints de inferência em tempo real da Amazon SageMaker AI oferecem suporte a um caminho de OpenAI-compatible API. Os clientes que usam o OpenAI SDK ou o Strands Agents podem invocar modelos na SageMaker IA alterando somente o URL do endpoint, sem exigir clientes personalizados, wrappers SigV4 ou regravações de código. LangChain

Com esse recurso, os endpoints de SageMaker IA expõem um /openai/v1/chat/completions caminho que aceita solicitações de conclusão de bate-papo e retorna respostas diretamente do contêiner, incluindo streaming. OpenAI-compatible os endpoints estão disponíveis em todos os endpoints e componentes de inferência usando APIs e SDKs de SageMaker IA padrão.

SageMaker A IA encaminha as solicitações com base no nome do endpoint na URL. Qualquer OpenAI-compatible cliente funciona sem configuração adicional. Você pode criar tokens portadores de curta duração para seus endpoints e usá-los com seus clientes OpenAI.

Pré-requisitos

Antes de começar, você deve ter o seguinte:

Autenticação com tokens de portador

SageMaker OpenAI-compatible Os endpoints de IA usam autenticação de token do portador. O SDK SageMaker AI Python inclui um gerador de tokens que cria tokens de curta duração (válidos por até 12 horas) a partir de suas credenciais existentes. AWS Não são necessários segredos ou chaves de API adicionais.

O token contém sua função ou credenciais de usuário e requer as permissões sagemaker:CallWithBearerToken e de sagemaker:InvokeEndpoint ação.

Gere um token

Use a generate_token função do SDK SageMaker AI Python para criar um token portador:

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

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

A generate_token função gera um token de portador de curta duração para autenticação com SageMaker APIs de IA. Por padrão, os tokens são válidos por 12 horas. Você pode substituir isso pelo expiry parâmetro usando um timedelta valor entre 1 segundo e 12 horas.

A função aceita umregion, um opcional aws_credentials_provider e a expiry duração. Se nenhuma região for fornecida, ela retornará à variável de AWS_REGION ambiente. Se nenhum provedor de credenciais for fornecido, ele resolverá as credenciais usando a cadeia de AWS credenciais padrão, que pesquisa várias fontes, incluindo variáveis de ambiente,, ~/.aws/credentials~/.aws/config, credenciais de contêiner e perfis de instância. Para ver a ordem de resolução completa, consulte a documentação de credenciais do boto3.

Auto-refresh tokens para aplicativos de longa duração

Para aplicativos que são executados continuamente, você pode implementar um padrão de atualização automática usando httpx para que um novo token seja gerado em cada solicitação:

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"))

Permissões do IAM

A função do IAM ou o usuário que invoca o endpoint precisa das seguintes permissões:

{
    "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": "*"
        }
    ]
}

Como o token funciona

O token portador é um URL SigV4 pré-assinado codificado em base64. Quando você ligagenerate_token, o SDK de SageMaker IA cria uma solicitação para o serviço de SageMaker IA para a CallWithBearerToken ação, a assina localmente usando suas AWS credenciais e codifica a URL assinada resultante como uma string de token portátil. Nenhuma chamada de rede é feita durante a geração do token — a assinatura acontece inteiramente no lado do cliente.

Quando você apresenta esse token a um endpoint de SageMaker IA, o serviço o decodifica, valida a assinatura SigV4, verifica se o token não expirou e confirma se a identidade IAM de origem tem as permissões necessárias. A vida útil efetiva do token é o menor expiry valor e a validade restante das AWS credenciais usadas para assiná-lo.

Práticas recomendadas de segurança

O token portador carrega a mesma autorização que as AWS credenciais subjacentes usadas para gerá-lo. Trate os tokens com o mesmo cuidado que as credenciais. Siga estas práticas recomendadas:

Invocar um endpoint de modelo único

Um endpoint de modelo único hospeda um modelo e atende às solicitações diretamente. O exemplo a seguir é implantado Qwen3-4B usando o SageMaker AI vLLM Deep Learning Container em uma instância. ml.g6.2xlarge

Implementar o endpoint

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)

Crie o modelo, a configuração do endpoint e o endpoint:

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},
)

O endpoint muda para o InService status em alguns minutos. Uma vez pronto, ele serve tanto o /invocations caminho padrão da SageMaker IA quanto o OpenAI-compatible caminho em/openai/v1/chat/completions.

Invocar o endpoint

Com o endpoint em serviço, invoque-o usando o SDK OpenAI Python. O URL base segue esse formato:

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()

O model campo é passado para o contêiner. Como a SageMaker IA encaminha as solicitações com base no nome do endpoint na URL, você pode deixar esse campo vazio ou configurá-lo para corresponder ao nome do modelo que seu contêiner espera.

Invocar componentes de inferência

Os componentes de inferência permitem que você hospede vários modelos em um único endpoint, cada um com alocações dedicadas de recursos computacionais. Com componentes de inferência, o modelo é associado ao componente e não à configuração do endpoint.

Implemente um endpoint de componente de inferência

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)

Você pode criar componentes de inferência adicionais no mesmo endpoint para hospedar vários modelos com escalabilidade e alocação de recursos independentes.

Invocar um componente de inferência

Para invocar um componente de inferência específico, inclua seu nome no caminho do URL:

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

O exemplo a seguir mostra como invocar um componente de inferência usando o SDK do OpenAI com um pool de conexões compartilhado:

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)

O compartilhado httpx.Client permite que várias instâncias do cliente OpenAI reutilizem as mesmas sessões TLS e o mesmo pool de conexões ao direcionar diferentes componentes de inferência no mesmo endpoint.

Contêineres compatíveis

Os contêineres a seguir oferecem suporte a OpenAI-compatible APIs em SageMaker IA. O contêiner deve implementar o /v1/chat/completions caminho e retornar as respostas de streaming no formato SSE.