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:
+ Uma AWS conta com permissões para criar endpoints de SageMaker IA.
+ O SDK SageMaker AI Python instalado (). `pip install sagemaker`
+ O SDK do OpenAI Python instalado (). `pip install openai`
+ Um modelo armazenado no Amazon S3 (por exemplo, Qwen3-4B baixado do Hugging Face).
+ Uma função de execução do IAM com a `AmazonSageMakerFullAccess` política para criar os endpoints.
+ Uma função ou usuário do IAM com as `sagemaker:InvokeEndpoint` permissões `sagemaker:CallWithBearerToken` e para invocar o endpoint.
## 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 um`region`, 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](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).
### 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": "*"
}
]
}
```
**Importante**
Sempre restrinja o `Resource` for `sagemaker:InvokeEndpoint` a ARNs de endpoint específicos em vez de usar um caractere curinga. O token portador gerado por essa função tem o mesmo nível de acesso, portanto, uma política de escopo restrito limita o raio de explosão se um token for exposto inadvertidamente.
**nota**
`sagemaker:CallWithBearerToken`requer um curinga (`"*"`) para o `Resource` campo. Ele não oferece suporte a restrições em nível de recursos.
### Como o token funciona
O token portador é um URL SigV4 pré-assinado codificado em base64. Quando você liga`generate_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:
+ Defina o escopo da função do IAM usada para geração de tokens de acordo com as permissões mínimas necessárias, especificamente `sagemaker:InvokeEndpoint` e somente `sagemaker:CallWithBearerToken` nos ARNs do endpoint que o chamador precisa acessar.
+ Não gere tokens de funções com permissões amplas, como aquelas concedidas `AdministratorAccess` ou `AmazonSageMakerFullAccess` gerenciadas por políticas.
+ Não armazene tokens em disco, em variáveis de ambiente, em arquivos de configuração, em bancos de dados ou em caches distribuídos. Não registre tokens e apenas os transmita por meio de protocolos de comunicação criptografados, como HTTPS.
+ A geração de tokens é uma operação local sem sobrecarga de rede. Gere um novo token no ponto de uso ou use o `httpx.Auth` padrão de atualização automática mostrado acima.
+ Defina a expiração do token para a duração mais curta que sua carga de trabalho exige.
## 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`
**nota**
SageMaker Os endpoints de IA incorrem em cobranças enquanto estão em serviço, independentemente do tráfego. Consulte a [página de preços da SageMaker IA](https://aws.amazon.com/sagemaker/pricing/) para obter detalhes.
### 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.
| Contêiner | Status do suporte |
| --- | --- |
| SageMaker Contêiner de aprendizado profundo AI vLLM | Compatível |
| SageMaker Contêiner de aprendizado profundo AI SGlang | Compatível |
| Contêineres personalizados que implementam caminhos de API OpenAI e `/ping` | Compatível |