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:
+ Un AWS account con le autorizzazioni per creare endpoint AI. SageMaker
+ L'SDK SageMaker AI Python installato (). `pip install sagemaker`
+ L'SDK Python OpenAI installato (). `pip install openai`
+ Un modello archiviato in Amazon S3 (ad esempio, Qwen3-4B scaricato da Hugging Face).
+ Un ruolo di esecuzione IAM con la `AmazonSageMakerFullAccess` policy per la creazione degli endpoint.
+ Un ruolo o un utente IAM con i permessi `sagemaker:CallWithBearerToken` e le `sagemaker:InvokeEndpoint` autorizzazioni per richiamare l'endpoint.
## 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 a`region`, 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.](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)
### 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": "*"
}
]
}
```
**Importante**
Limita sempre il `Resource` for `sagemaker:InvokeEndpoint` a ARN endpoint specifici anziché utilizzare un carattere jolly. Il token bearer generato da questo ruolo ha lo stesso livello di accesso, quindi una policy ad ambito ristretto limita il raggio di esplosione se un token viene esposto inavvertitamente.
**Nota**
`sagemaker:CallWithBearerToken`richiede un carattere jolly () per il campo. `"*"` `Resource` Non supporta restrizioni a livello di risorsa.
### Come funziona il token
Il token bearer è un URL SigV4 prefirmato con codifica Base64. Quando effettui una chiamata`generate_token`, l'SDK SageMaker AI crea una richiesta al servizio SageMaker AI per l'`CallWithBearerToken`azione, 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:
+ Limita il ruolo IAM utilizzato per la generazione di token alle autorizzazioni minime richieste, in particolare `sagemaker:InvokeEndpoint` e solo `sagemaker:CallWithBearerToken` sugli ARN degli endpoint a cui il chiamante deve accedere.
+ Non generare token da ruoli con autorizzazioni estese, come quelle concesse o gestite da policy. `AdministratorAccess` `AmazonSageMakerFullAccess`
+ Non archiviate i token su disco, nelle variabili di ambiente, nei file di configurazione, nei database o nelle cache distribuite. Non registrate i token e trasmetteteli solo tramite protocolli di comunicazione crittografati come HTTPS.
+ La generazione di token è un'operazione locale senza sovraccarico di rete. Genera un nuovo token nel punto di utilizzo o utilizza lo `httpx.Auth` schema di aggiornamento automatico mostrato sopra.
+ Imposta la scadenza del token sulla durata più breve richiesta dal carico di lavoro.
## 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`
**Nota**
SageMaker Gli endpoint AI comportano costi durante il servizio, indipendentemente dal traffico. Consulta la [pagina dei prezzi dell'SageMaker IA](https://aws.amazon.com/sagemaker/pricing/) per i dettagli.
### 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.
| Contenitore | Stato del supporto |
| --- | --- |
| SageMaker Contenitore di deep learning AI VLLm | Supportata |
| SageMaker Contenitore di deep learning AI SGlang | Supportata |
| Contenitori personalizzati che implementano percorsi API OpenAI e `/ping` | Supportata |