Requisitos previos Autenticación mediante token portador Single-model endpoint Componentes de inferencias Contenedores admitidos

Invoque puntos finales con API OpenAI-compatible

Los puntos de enlace de inferencia en tiempo real de Amazon SageMaker AI admiten una ruta de OpenAI-compatible API. Los clientes que utilizan el SDK de OpenAI o los agentes de Strands pueden invocar modelos en SageMaker IA cambiando solo la URL de su punto final, sin necesidad de clientes personalizados, envoltorios SigV4 ni reescrituras de código. LangChain

Con esta funcionalidad, los terminales de SageMaker IA muestran una /openai/v1/chat/completions ruta que acepta las solicitudes de finalización de chat y devuelve las respuestas directamente desde el contenedor, incluida la transmisión. OpenAI-compatible Los puntos finales están disponibles en todos los puntos finales y componentes de inferencia mediante API y SDK de IA estándar SageMaker .

SageMaker La IA enruta las solicitudes en función del nombre del punto final que figura en la URL. Todos los OpenAI-compatible clientes funcionan sin necesidad de configuración adicional. Puede crear tokens portadores de corta duración para sus puntos finales y utilizarlos con sus clientes de OpenAI.

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

Una AWS cuenta con permisos para crear puntos de conexión de IA. SageMaker
El SDK de Python para SageMaker IA instalado (pip install sagemaker).
El SDK de Python para OpenAI instalado ()pip install openai.
Un modelo almacenado en Amazon S3 (por ejemplo, Qwen3-4B descargado de Hugging Face).
Una función de ejecución de IAM con la AmazonSageMakerFullAccess política de crear los puntos de enlace.
Un rol o usuario de IAM con los sagemaker:InvokeEndpoint permisos sagemaker:CallWithBearerToken y para invocar el punto final.

Autenticación con fichas portadoras

SageMaker OpenAI-compatible Los puntos finales de IA utilizan la autenticación por token portador. El SDK para Python de SageMaker IA incluye un generador de fichas que crea fichas de corta duración (válidas hasta 12 horas) a partir de tus AWS credenciales existentes. No se requieren secretos ni claves de API adicionales.

El token contiene tu rol o tus credenciales de usuario y requiere los permisos sagemaker:CallWithBearerToken y la sagemaker:InvokeEndpoint acción.

Genera un token

Usa la generate_token función del SDK de Python para SageMaker IA para crear un 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))

La generate_token función genera un token portador de corta duración para autenticarse con las API de IA. SageMaker De forma predeterminada, los tokens son válidos durante 12 horas. Puede anular esto con el expiry parámetro utilizando un timedelta valor comprendido entre 1 segundo y 12 horas.

La función acepta unregion, un elemento opcional aws_credentials_provider y la expiry duración. Si no se proporciona ninguna región, recurre a la variable de AWS_REGION entorno. Si no se proporciona ningún proveedor de credenciales, las resuelve mediante la cadena de AWS credenciales predeterminada, que busca en varias fuentes, incluidas las variables de entorno ~/.aws/credentials~/.aws/config, las credenciales de contenedor y los perfiles de instancia. Para ver el orden de resolución completo, consulta la documentación sobre las credenciales de boto3.

Auto-refresh identificadores para aplicaciones de larga duración

Para las aplicaciones que se ejecutan de forma continua, puedes implementar un patrón de actualización automática httpx para que se genere un token nuevo en cada solicitud:


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

Permisos de IAM

El rol o usuario de IAM que invoca el punto final necesita los siguientes permisos:


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

Limite siempre el formulario sagemaker:InvokeEndpoint a Resource los ARN de punto final específicos en lugar de utilizar un comodín. El token portador generado a partir de esta función tiene el mismo nivel de acceso, por lo que una política de alcance limitado limita el radio de emisión en caso de que un token quede expuesto de forma inadvertida.

nota

sagemaker:CallWithBearerTokenrequiere un comodín () para el campo. "*" Resource No admite restricciones a nivel de recursos.

Cómo funciona el token

El token portador es una URL prefirmada de SiGv4 codificada en base64. Cuando llamasgenerate_token, el SDK de SageMaker IA crea una solicitud de CallWithBearerToken acción dirigida al servicio de SageMaker IA, la firma localmente con tus AWS credenciales y codifica la URL firmada resultante como una cadena de token portátil. No se realiza ninguna llamada de red durante la generación del token; la firma se realiza íntegramente por parte del cliente.

Cuando presentas este token a un punto final de SageMaker IA, el servicio lo decodifica, valida la firma SigV4, verifica que el token no haya caducado y confirma que la identidad de IAM de origen tiene los permisos necesarios. La vida útil efectiva del token es el menor entre el expiry valor y la validez restante de las AWS credenciales utilizadas para firmarlo.

Prácticas recomendadas de seguridad

El token portador lleva la misma autorización que las AWS credenciales subyacentes utilizadas para generarlo. Trate los tokens con el mismo cuidado que las credenciales. Siga estas prácticas recomendadas:

Limite la función de IAM utilizada para la generación de los tokens a los permisos mínimos requeridos, específicamente sagemaker:InvokeEndpoint y solo sagemaker:CallWithBearerToken en los ARN de los puntos finales a los que la persona que llama necesita acceder.
No generes fichas a partir de funciones con permisos ampliados, como los otorgados por políticas gestionadas o concedidasAdministratorAccess. AmazonSageMakerFullAccess
No almacene los tokens en el disco, en las variables de entorno, en los archivos de configuración, en las bases de datos o en las cachés distribuidas. No registre los tokens y solo los transmita a través de protocolos de comunicación cifrados, como HTTPS.
La generación de tokens es una operación local sin sobrecarga de red. Genera un token nuevo en el punto de uso o usa el httpx.Auth patrón de actualización automática que se muestra arriba.
Establezca la caducidad del token en la duración más corta que requiera su carga de trabajo.

Invoque un punto final de modelo único

Un punto final de un solo modelo aloja un modelo y atiende las solicitudes directamente. En el siguiente ejemplo, se implementa Qwen3-4B con el contenedor de aprendizaje profundo SageMaker AI vLLM en una instancia. ml.g6.2xlarge

nota

SageMaker Los puntos finales de IA incurren en cargos mientras estén en servicio, independientemente del tráfico. Consulte la página de precios de la SageMaker IA para obtener más información.

Implemente el punto de conexión


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)

Cree el modelo, la configuración del punto final y el punto final:


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

El punto final pasa al InService estado en unos minutos. Una vez listo, sirve tanto para la /invocations ruta de SageMaker IA estándar como para la OpenAI-compatible ruta de/openai/v1/chat/completions.

Invocar al punto de conexión

Con el punto final en servicio, invoquelo mediante el SDK de Python para OpenAI. La URL base sigue este 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()

El model campo se pasa al contenedor. Como la SageMaker IA enruta las solicitudes en función del nombre del punto final que figura en la URL, puedes dejar este campo vacío o configurarlo para que coincida con el nombre de modelo que espera tu contenedor.

Invoca los componentes de inferencia

Los componentes de inferencia le permiten alojar varios modelos en un único punto final, cada uno con asignaciones de recursos informáticos dedicadas. Con los componentes de inferencia, el modelo se asocia al componente y no a la configuración del punto final.

Implemente un punto final de componente de inferencia


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)

Puede crear componentes de inferencia adicionales en el mismo punto final para alojar varios modelos con un escalado y una asignación de recursos independientes.

Invoque un componente de inferencia

Para invocar un componente de inferencia específico, incluya su nombre en la ruta URL:


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

El siguiente ejemplo muestra cómo invocar un componente de inferencia mediante el SDK de OpenAI con un grupo de conexiones compartido:


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)

Lo compartido httpx.Client permite que varias instancias de clientes de OpenAI reutilicen las mismas sesiones de TLS y el mismo grupo de conexiones cuando se dirigen a diferentes componentes de inferencia en el mismo punto final.

Contenedores admitidos

Los siguientes contenedores admiten las OpenAI-compatible API de IA. SageMaker El contenedor debe implementar la /v1/chat/completions ruta y devolver las respuestas de streaming en formato SSE.

Container	Estado de Support
SageMaker Contenedor de aprendizaje profundo AI vLLM	compatible
SageMaker Contenedor de aprendizaje profundo AI SGLang	compatible
Contenedores personalizados que implementan rutas de API OpenAI y `/ping`	compatible

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Invocación de modelos

Puntos de conexión