Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# 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 un`region`, 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](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).
### 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:CallWithBearerToken`requiere 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 llamas`generate_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 concedidas`AdministratorAccess`. `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](https://aws.amazon.com/sagemaker/pricing/) 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 |