Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Richiama gli endpoint con le API OpenAI-compatible

Gli endpoint di inferenza in tempo reale di Amazon SageMaker AI supportano un percorso OpenAI-compatible API. I clienti che utilizzano OpenAI SDK o Strands Agents possono richiamare modelli sull' SageMaker intelligenza artificiale modificando solo l'URL dell'endpoint, senza richiedere client personalizzati, wrapper SigV4 o riscritture del codice. LangChain

Grazie a questa funzionalità, gli endpoint SageMaker AI espongono un /openai/v1/chat/completions percorso che accetta le richieste di Chat Completions e restituisce le risposte direttamente dal contenitore, incluso lo streaming. OpenAI-compatible gli endpoint sono disponibili su tutti gli endpoint e i componenti di inferenza utilizzando API e SDK AI standard. SageMaker

SageMaker L'IA indirizza le richieste in base al nome dell'endpoint nell'URL. Qualsiasi OpenAI-compatible client funziona senza configurazioni aggiuntive. Puoi creare token portatori di breve durata per i tuoi endpoint e utilizzarli con i tuoi client OpenAI.

Prerequisiti

Prima di iniziare, assicurati di disporre di:

Autenticazione con token bearer

SageMaker OpenAI-compatible Gli endpoint AI utilizzano l'autenticazione con token portatore. L'SDK SageMaker AI Python include un generatore di token che crea token di breve durata (validi fino a 12 ore) a partire dalle credenziali esistenti. AWS Non sono richiesti segreti o chiavi API aggiuntivi.

Il token contiene le credenziali del ruolo o dell'utente e richiede le sagemaker:InvokeEndpoint autorizzazioni sagemaker:CallWithBearerToken e le azioni.

Genera un token

Usa la generate_token funzione dell'SDK SageMaker AI Python per creare un token bearer:

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 funzione genera un token bearer di breve durata per l'autenticazione con le API AI. SageMaker Per impostazione predefinita, i token sono validi per 12 ore. È possibile sovrascrivere questo valore con il expiry parametro utilizzando un timedelta valore compreso tra 1 secondo e 12 ore.

La funzione accetta aregion, un opzionale aws_credentials_provider e la expiry durata. Se non viene fornita alcuna regione, torna alla variabile di AWS_REGION ambiente. Se non viene fornito alcun provider di credenziali, risolve le credenziali utilizzando la catena di AWS credenziali predefinita, che cerca più fonti tra cui variabili di ambiente,~/.aws/credentials, credenziali del contenitore e profili di ~/.aws/config istanza. Per l'ordine di risoluzione completo, consulta la documentazione delle credenziali boto3.

Auto-refresh token per applicazioni a lunga durata

Per le applicazioni che funzionano continuamente, puoi implementare un pattern di aggiornamento automatico httpx in modo che venga generato un nuovo token per ogni richiesta:

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

autorizzazioni IAM

Il ruolo o l'utente IAM che richiama l'endpoint necessita delle seguenti autorizzazioni:

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

Come funziona il token

Il token bearer è un URL SigV4 prefirmato con codifica Base64. Quando effettui una chiamatagenerate_token, l'SDK SageMaker AI crea una richiesta al servizio SageMaker AI per l'CallWithBearerTokenazione, la firma localmente utilizzando le tue AWS credenziali e codifica l'URL firmato risultante come una stringa di token portatile. Non viene effettuata alcuna chiamata di rete durante la generazione del token: la firma avviene interamente sul lato client.

Quando presenti questo token a un endpoint SageMaker AI, il servizio lo decodifica, convalida la firma SigV4, verifica che il token non sia scaduto e conferma che l'identità IAM di origine disponga delle autorizzazioni richieste. La durata effettiva del token è pari al expiry valore e alla validità residua inferiori delle credenziali utilizzate per firmarlo. AWS

Best practice di sicurezza

Il token bearer ha la stessa autorizzazione delle AWS credenziali sottostanti utilizzate per generarlo. Tratta i token con la stessa cura delle credenziali. Segui queste best practice:

Richiama un endpoint a modello singolo

Un endpoint a modello singolo ospita un modello e gestisce direttamente le richieste. L'esempio seguente esegue la distribuzione Qwen3-4B utilizzando l' SageMaker AI VLLm Deep Learning Container su un'istanza. ml.g6.2xlarge

Implementa l'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)

Crea il modello, la configurazione dell'endpoint e l'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},
)

L'endpoint passa InService allo stato in pochi minuti. Una volta pronto, serve sia il percorso di SageMaker intelligenza artificiale standard che il /invocations OpenAI-compatible percorso successivo. /openai/v1/chat/completions

Richiamare l'endpoint

Con l'endpoint in servizio, richiamalo utilizzando l'SDK Python di OpenAI. L'URL di base segue questo 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()

Il model campo viene passato al contenitore. Poiché SageMaker AI indirizza le richieste in base al nome dell'endpoint nell'URL, puoi lasciare questo campo vuoto o impostarlo in modo che corrisponda al nome del modello previsto dal contenitore.

Invoca componenti di inferenza

I componenti di inferenza consentono di ospitare più modelli su un singolo endpoint, ciascuno con allocazioni di risorse di elaborazione dedicate. Con i componenti di inferenza, il modello è associato al componente anziché alla configurazione dell'endpoint.

Implementa un endpoint con componenti di inferenza

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)

È possibile creare componenti di inferenza aggiuntivi sullo stesso endpoint per ospitare più modelli con scalabilità e allocazione delle risorse indipendenti.

Invoca un componente di inferenza

Per richiamare un componente di inferenza specifico, includi il suo nome nel percorso dell'URL:

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

L'esempio seguente mostra come richiamare un componente di inferenza utilizzando l'SDK OpenAI con un pool di connessioni condiviso:

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)

La condivisione httpx.Client consente a più istanze client OpenAI di riutilizzare le stesse sessioni TLS e lo stesso pool di connessioni quando si indirizzano a diversi componenti di inferenza sullo stesso endpoint.

Contenitori supportati

I seguenti contenitori supportano le OpenAI-compatible API sull' SageMaker intelligenza artificiale. Il contenitore deve implementare il /v1/chat/completions percorso e restituire risposte in streaming in formato SSE.