SageMaker AI agora aceita a API compatível com OpenAI nos endpoints de inferência

O que mudou no SageMaker AI

A AWS adicionou suporte à API compatível com OpenAI nos endpoints de inferência em tempo real do Amazon SageMaker AI. Na prática, qualquer aplicação que já se comunique com a API da OpenAI — seja usando o OpenAI SDK, LangChain ou Strands Agents — pode ser redirecionada para um endpoint do SageMaker com uma única mudança: a URL base. Nenhuma reescrita de lógica, nenhuma adaptação de chamadas, nenhum cliente customizado.

Os endpoints do SageMaker AI passam a expor o caminho /openai/v1, que aceita requisições no formato Chat Completions e retorna as respostas diretamente do container, incluindo streaming. O roteamento é feito pelo nome do endpoint na URL, tornando qualquer cliente compatível com OpenAI funcional sem configuração adicional.

Para um exemplo completo com deploy e invocação, a AWS disponibilizou um notebook no GitHub.

Principais cenários de uso

Workflows agênticos em infraestrutura própria

Equipes que desenvolvem agentes de IA com múltiplas etapas usando frameworks como Strands Agents ou LangChain podem agora executar esses workflows inteiramente em endpoints próprios do SageMaker AI. Os agentes continuam chamando modelos pela mesma interface compatível com OpenAI, mas a inferência roda em instâncias de GPU dedicadas dentro da própria conta AWS.

Múltiplos modelos em um único endpoint

Quem opera vários modelos simultaneamente — por exemplo, um Llama para tarefas gerais, um Mistral ajustado para um domínio específico e um modelo menor para classificação — pode hospedar todos em um único endpoint usando inference components. Cada modelo recebe sua própria alocação de recursos e todos ficam acessíveis pelo mesmo OpenAI SDK, sem clientes separados ou lógica de roteamento no código da aplicação.

Modelos fine-tuned sem alterações no código

Para quem realiza fine-tuning de modelos open source, o deploy no SageMaker AI permite que as aplicações existentes continuem funcionando sem alterações. A única mudança necessária é a URL do endpoint. O restante — chamadas ao SDK, lógica de streaming, formatação de prompts — permanece intacto.

Autenticação com bearer tokens

Os endpoints compatíveis com OpenAI no SageMaker AI utilizam autenticação via bearer token. O SDK Python do SageMaker inclui um gerador de tokens que cria tokens com tempo de vida limitado — válidos por até 12 horas — a partir das credenciais AWS já existentes no ambiente. Não são necessárias chaves de API adicionais ou segredos extras.

O token exige as permissões sagemaker:CallWithBearerToken e sagemaker:InvokeEndpoint no IAM da conta.

Gerando um token

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

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

O gerador usa as credenciais AWS disponíveis no ambiente: credenciais de usuário IAM, perfil de instância no Amazon EC2 ou sessão do AWS IAM Identity Center (SSO). Por padrão, os tokens têm validade de 12 horas, mas isso pode ser ajustado com o parâmetro expiry. Para a ordem completa de resolução de credenciais, consulte a documentação de credenciais do Boto3.

Auto-refresh para aplicações de longa duração

Para aplicações que rodam continuamente, é possível implementar um padrão de renovação automática usando httpx, gerando um token novo a cada requisiçã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 IAM necessárias

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

Como boa prática, recomenda-se restringir o campo Resource ao ARN específico do endpoint para a ação InvokeEndpoint, em vez de usar wildcard. Já o CallWithBearerToken exige wildcard — não suporta restrições por recurso.

Boas práticas de segurança com tokens: o bearer token carrega a mesma autorização das credenciais AWS usadas para gerá-lo. Trate-o com o mesmo cuidado que trataria as credenciais. Não gere tokens a partir de roles com permissões amplas como AdministratorAccess ou SageMakerFullAccess. Não armazene tokens em disco, variáveis de ambiente, arquivos de configuração, bancos de dados ou caches distribuídos. Não registre tokens em logs e transmita-os apenas por protocolos criptografados como HTTPS. Como a geração de token é uma operação local sem overhead de rede, a recomendação é gerar um token novo no momento do uso ou usar o padrão de auto-refresh com httpx.Auth.

Deploy de endpoint com modelo único

O exemplo abaixo realiza o deploy do modelo Qwen3-4B usando o container Deep Learning vLLM do SageMaker AI em uma instância ml.g6.2xlarge.

Atenção: endpoints do SageMaker AI geram custos enquanto estiverem ativos, independentemente do tráfego recebido. Consulte a página de preços do Amazon SageMaker AI para mais detalhes.

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

print(f"Region: {REGION}")
print(f"Account ID: {ACCOUNT_ID}")
print(f"Execution role: {EXECUTION_ROLE}")
print(f"Model HF ID: {MODEL_HF_ID}")

import time
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}"

print(f"Timestamp suffix: {TIMESTAMP}")
print(f"Model: {SME_MODEL_NAME}")
print(f"Endpoint config: {SME_ENDPOINT_CONFIG_NAME}")
print(f"Endpoint: {SME_ENDPOINT_NAME}")

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",
        },
    },
)
print(f"Model created: {SME_MODEL_NAME}")

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

sagemaker_client.create_endpoint(
    EndpointName=SME_ENDPOINT_NAME,
    EndpointConfigName=SME_ENDPOINT_CONFIG_NAME,
)
print(f"Endpoint creation initiated: {SME_ENDPOINT_NAME}")
print("Waiting for endpoint to reach InService status (this takes 5-10 minutes)...")

waiter = sagemaker_client.get_waiter("endpoint_in_service")
waiter.wait(
    EndpointName=SME_ENDPOINT_NAME,
    WaiterConfig={"Delay": 30, "MaxAttempts": 40},
)
print(f"Endpoint is InService: {SME_ENDPOINT_NAME}")

Quando o endpoint atingir o status InService, ele estará disponível tanto no caminho padrão /invocations do SageMaker AI quanto no caminho compatível com OpenAI em /openai/v1/chat/completions.

Invocando o endpoint com o OpenAI SDK

A URL base segue o 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/endpoints/{SME_ENDPOINT_NAME}/openai/v1"

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

print(f"Base URL: {sme_base_url}")

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 campo model é repassado diretamente ao container. Como o SageMaker AI faz o roteamento pelo nome do endpoint na URL, esse campo pode ficar vazio ou receber o nome que o container espera.

Deploy com inference components (múltiplos modelos)

Com inference components, é possível hospedar vários modelos em um único endpoint, cada um com alocação de recursos dedicada. Nesse modelo, o modelo é associado ao componente, não à configuração do endpoint:

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

print(f"Model: {IC_MODEL_NAME}")
print(f"Endpoint config: {IC_ENDPOINT_CONFIG_NAME}")
print(f"Endpoint: {IC_ENDPOINT_NAME}")
print(f"Inference comp: {IC_NAME}")

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",
        },
    },
)
print(f"Model created: {IC_MODEL_NAME}")

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

sagemaker_client.create_endpoint(
    EndpointName=IC_ENDPOINT_NAME,
    EndpointConfigName=IC_ENDPOINT_CONFIG_NAME,
)
print(f"Endpoint creation initiated: {IC_ENDPOINT_NAME}")
print("Waiting for endpoint to reach InService status (this takes 5-10 minutes)...")

waiter = sagemaker_client.get_waiter("endpoint_in_service")
waiter.wait(
    EndpointName=IC_ENDPOINT_NAME,
    WaiterConfig={"Delay": 30, "MaxAttempts": 40},
)
print(f"Endpoint is InService: {IC_ENDPOINT_NAME}")

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},
)
print(f"Inference component creation initiated: {IC_NAME}")
print("Waiting for inference component to reach InService status...")

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

É possível criar inference components adicionais no mesmo endpoint para hospedar múltiplos modelos com escalonamento e alocação de recursos independentes.

Invocando inference components

Para invocar um inference component específico, inclua o nome do componente no caminho da URL: https://runtime.sagemaker.<REGION>.amazonaws.com/endpoints/<ENDPOINT>/inference-components/<IC_NAME>/openai/v1

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(f"Response: {response.choices[0].message.content}")
print(f"Connection pool active: shared_http is reusable across multiple IC clients")

O httpx.Client compartilhado permite que múltiplas instâncias do cliente OpenAI reutilizem as mesmas sessões TLS e o mesmo pool de conexões.

Integração com Strands Agents

O Strands Agents é um SDK open source para construção de agentes de IA. Por suportar provedores de modelos compatíveis com OpenAI, agora é possível executar workflows multi-agente inteiramente na infraestrutura do SageMaker AI — com controle total sobre qual versão do modelo os agentes utilizam e sem que os dados saiam da conta AWS.

from openai import AsyncOpenAI
from strands import Agent, tool
from strands.models.openai import OpenAIModel
from sagemaker.core.token_generator import generate_token

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression))

strands_client = AsyncOpenAI(
    base_url=f"https://runtime.sagemaker.{REGION}.amazonaws.com/endpoints/{SME_ENDPOINT_NAME}/openai/v1",
    api_key=generate_token(region=REGION),
)

model = OpenAIModel(client=strands_client, model_id="", params={"temperature": 0.7})

coder = Agent(
    model=model,
    system_prompt=(
        "You are an expert Python developer. Write clean, well-documented "
        "Python code with type hints. Output ONLY the code, no explanation."
    ),
    tools=[calculator],
)

reviewer = Agent(
    model=model,
    system_prompt=(
        "You are a senior code reviewer. Review Python code for correctness, "
        "performance, and PEP 8 style. Give a concise review with specific suggestions."
    ),
    tools=[calculator],
)

Limpeza de recursos

Para evitar cobranças contínuas, é fundamental excluir os endpoints e recursos associados após o uso. Endpoints do SageMaker AI geram custos enquanto estiverem ativos, mesmo sem receber tráfego.

import boto3

sagemaker_client = boto3.client("sagemaker", region_name="us-west-2")

sagemaker_client.delete_inference_component(InferenceComponentName="")
sagemaker_client.delete_endpoint(EndpointName="")
sagemaker_client.delete_endpoint_config(EndpointConfigName="")
sagemaker_client.delete_model(ModelName="")

Conclusão

Com o suporte à API compatível com OpenAI, o Amazon SageMaker AI remove a principal barreira de integração entre as aplicações de IA já existentes — construídas sobre o padrão OpenAI — e a infraestrutura necessária para escalar com controle. É possível manter o código existente, usar qualquer framework compatível com OpenAI e executar inferência em endpoints dedicados com controle de GPU, escalonamento e residência de dados.

Para começar, basta fazer o deploy de um modelo em um endpoint de inferência em tempo real do SageMaker AI usando um container suportado, instalar o SDK Python do SageMaker e apontar o cliente OpenAI para a URL do endpoint. Para se aprofundar, consulte a documentação Use SageMaker AI with OpenAI-compatible APIs no guia do desenvolvedor, ou acesse o console do Amazon SageMaker AI para criar seu primeiro endpoint.

Fonte

Announcing OpenAI-compatible API support for Amazon SageMaker AI endpoints (https://aws.amazon.com/blogs/machine-learning/announcing-openai-compatible-api-support-for-amazon-sagemaker-ai-endpoints/)