Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Endpunkte mit APIs aufrufen OpenAI-compatible
Amazon SageMaker AI-Inferenzendpunkte in Echtzeit unterstützen einen OpenAI-compatible API-Pfad. Kunden, die das OpenAI SDK oder Strands Agents verwenden LangChain, können Modelle auf SageMaker KI aufrufen, indem sie nur ihre Endpunkt-URL ändern, ohne dass benutzerdefinierte Clients, SigV4-Wrapper oder Code-Umschreibungen erforderlich sind.
Mit dieser Funktion stellen SageMaker KI-Endpunkte einen `/openai/v1/chat/completions` Pfad zur Verfügung, der Anfragen zum Abschluss von Chats akzeptiert und Antworten direkt aus dem Container zurückgibt, einschließlich Streaming. OpenAI-compatible Endpunkte sind auf allen Endpunkten und Inferenzkomponenten mithilfe von SageMaker Standard-KI-APIs und -SDKs verfügbar.
SageMaker KI leitet Anfragen auf der Grundlage des Endpunktnamens in der URL weiter. Jeder OpenAI-compatible Client funktioniert ohne zusätzliche Konfiguration. Sie können kurzlebige Bearer-Token für Ihre Endgeräte erstellen und diese mit Ihren OpenAI-Clients verwenden.
## Voraussetzungen
Stellen Sie vor dem Beginn sicher, dass Sie über das Folgende verfügen:
+ Ein AWS Konto mit Berechtigungen zum Erstellen von KI-Endpunkten. SageMaker
+ Das SageMaker AI Python SDK ist installiert (`pip install sagemaker`).
+ Das OpenAI Python SDK ist installiert (`pip install openai`).
+ Ein in Amazon S3 gespeichertes Modell (z. B. von Hugging Face Qwen3-4B heruntergeladen).
+ Eine IAM-Ausführungsrolle mit der `AmazonSageMakerFullAccess` Richtlinie zur Erstellung der Endgeräte.
+ Eine IAM-Rolle oder ein IAM-Benutzer mit den `sagemaker:InvokeEndpoint` Berechtigungen `sagemaker:CallWithBearerToken` und zum Aufrufen des Endpunkts.
## Authentifizierung mit Inhaber-Tokens
SageMaker OpenAI-compatible KI-Endpunkte verwenden die Bearer-Token-Authentifizierung. Das SageMaker AI Python SDK enthält einen Token-Generator, der kurzlebige Token (gültig bis zu 12 Stunden) aus Ihren vorhandenen AWS Anmeldeinformationen erstellt. Es sind keine zusätzlichen Geheimnisse oder API-Schlüssel erforderlich.
Das Token enthält Ihre Rollen- oder Benutzeranmeldedaten und erfordert die entsprechenden `sagemaker:CallWithBearerToken` und `sagemaker:InvokeEndpoint` Aktionsberechtigungen.
### Generieren Sie ein Token
Verwenden Sie die `generate_token` Funktion aus dem SageMaker AI Python SDK, um ein Bearer-Token zu erstellen:
```
from sagemaker.core.token_generator import generate_token
from datetime import timedelta
token = generate_token(region="us-west-2", expiry=timedelta(minutes=5))
```
Die `generate_token` Funktion generiert ein kurzlebiges Bearer-Token für die Authentifizierung mit KI-APIs. SageMaker Standardmäßig sind Token 12 Stunden gültig. Sie können dies mit dem `expiry` Parameter überschreiben, indem Sie einen `timedelta` Wert zwischen 1 Sekunde und 12 Stunden verwenden.
Die Funktion akzeptiert a`region`, ein optionales `aws_credentials_provider` und die `expiry` Dauer. Wenn keine Region angegeben wird, wird auf die `AWS_REGION` Umgebungsvariable zurückgegriffen. Wenn kein Anbieter für Anmeldeinformationen angegeben wird, werden Anmeldeinformationen mithilfe der standardmäßigen AWS Anmeldeinformationskette aufgelöst, die mehrere Quellen durchsucht, darunter Umgebungsvariablen,, `~/.aws/credentials``~/.aws/config`, Container-Anmeldeinformationen und Instanzprofile. Die vollständige Reihenfolge der Auflösung finden Sie in der Dokumentation zu den [boto3-Anmeldeinformationen](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).
### Auto-refresh Token für Anwendungen mit langer Laufzeit
Für Anwendungen, die kontinuierlich ausgeführt werden, können Sie ein automatisches Aktualisierungsmuster implementieren, `httpx` sodass bei jeder Anfrage ein neues Token generiert wird:
```
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"))
```
### IAM-Berechtigungen
Die IAM-Rolle oder der Benutzer, der den Endpunkt aufruft, benötigt die folgenden Berechtigungen:
```
{
"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": "*"
}
]
}
```
**Wichtig**
Beschränken Sie das `Resource` für immer `sagemaker:InvokeEndpoint` auf bestimmte Endpunkt-ARNs, anstatt einen Platzhalter zu verwenden. Das von dieser Rolle generierte Bearer-Token hat dieselbe Zugriffsebene, sodass eine eng begrenzte Richtlinie den Explosionsradius begrenzt, falls ein Token versehentlich offengelegt wird.
**Anmerkung**
`sagemaker:CallWithBearerToken`erfordert einen Platzhalter () für das Feld. `"*"` `Resource` Einschränkungen auf Ressourcenebene werden nicht unterstützt.
### Wie funktioniert das Token
Das Bearer-Token ist eine Base64-kodierte, vorsignierte SigV4-URL. Wenn Sie aufrufen`generate_token`, erstellt das SageMaker AI-SDK eine Anfrage an den SageMaker AI-Service für die `CallWithBearerToken` Aktion, signiert sie lokal mit Ihren AWS Anmeldeinformationen und codiert die resultierende signierte URL als tragbare Tokenzeichenfolge. Während der Token-Generierung erfolgt kein Netzwerkaufruf — die Signierung erfolgt ausschließlich auf der Clientseite.
Wenn Sie dieses Token einem SageMaker KI-Endpunkt vorlegen, dekodiert der Dienst es, validiert die SigV4-Signatur, überprüft, ob das Token nicht abgelaufen ist, und bestätigt, dass die ursprüngliche IAM-Identität über die erforderlichen Berechtigungen verfügt. Die tatsächliche Lebensdauer des Tokens entspricht dem `expiry` Wert und der verbleibenden Gültigkeit der zum Signieren verwendeten AWS Anmeldeinformationen, je nachdem, welcher Wert niedriger ist.
### Bewährte Methoden für die Gewährleistung der Sicherheit
Das Inhaber-Token hat dieselbe Autorisierung wie die zugrunde liegenden AWS Anmeldeinformationen, mit denen es generiert wurde. Behandeln Sie Tokens mit derselben Sorgfalt wie Anmeldeinformationen. Folgen Sie diesen bewährten Methoden:
+ Beschränken Sie die für die Token-Generierung verwendete IAM-Rolle auf die erforderlichen Mindestberechtigungen — `sagemaker:InvokeEndpoint` und zwar ausschließlich `sagemaker:CallWithBearerToken` auf die Endpunkt-ARNs, auf die der Anrufer zugreifen muss.
+ Generieren Sie keine Token aus Rollen mit umfangreichen Berechtigungen, wie z. B. solche, die durch `AdministratorAccess` Richtlinien gewährt oder verwaltet werden. `AmazonSageMakerFullAccess`
+ Speichern Sie Token nicht auf der Festplatte, in Umgebungsvariablen, in Konfigurationsdateien, in Datenbanken oder in verteilten Caches. Protokollieren Sie keine Token und übertragen Sie sie nur über verschlüsselte Kommunikationsprotokolle wie HTTPS.
+ Die Token-Generierung ist ein lokaler Vorgang ohne Netzwerk-Overhead. Generieren Sie am Einsatzort ein neues Token oder verwenden Sie das oben gezeigte automatische `httpx.Auth` Aktualisierungsmuster.
+ Stellen Sie den Ablauf des Tokens auf die kürzeste Dauer ein, die Ihr Workload benötigt.
## Rufen Sie einen Endpunkt mit einem einzigen Modell auf
Ein Endpunkt mit einem einzigen Modell hostet ein Modell und bearbeitet Anfragen direkt. Das folgende Beispiel wird Qwen3-4B mithilfe des SageMaker AI vLLM Deep Learning Containers auf einer Instanz bereitgestellt. `ml.g6.2xlarge`
**Anmerkung**
SageMaker Bei KI-Endpunkten fallen während des Betriebs Gebühren an, unabhängig vom Datenverkehr. Einzelheiten finden Sie auf der [Seite mit den SageMaker KI-Preisen](https://aws.amazon.com/sagemaker/pricing/).
### Stellen Sie den Endpunkt bereit
```
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)
```
Erstellen Sie das Modell, die Endpunktkonfiguration und den Endpunkt:
```
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},
)
```
Der Endpunkt wechselt innerhalb weniger Minuten in `InService` den Status. Sobald er bereit ist, bedient er sowohl den SageMaker `/invocations` Standard-KI-Pfad als auch den OpenAI-compatible Pfad unter`/openai/v1/chat/completions`.
### Rufen Sie den Endpunkt auf
Wenn der Endpunkt in Betrieb ist, rufen Sie ihn mit dem OpenAI Python SDK auf. Die Basis-URL folgt diesem Format:
```
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()
```
Das `model` Feld wird an den Container weitergegeben. Da SageMaker KI Anfragen auf der Grundlage des Endpunktnamens in der URL weiterleitet, können Sie dieses Feld leer lassen oder es so einstellen, dass es dem Modellnamen entspricht, den Ihr Container erwartet.
## Rufen Sie Inferenzkomponenten auf
Mit Inferenzkomponenten können Sie mehrere Modelle auf einem einzigen Endpunkt hosten, von denen jedes über eigene Rechenressourcenzuweisungen verfügt. Bei Inferenzkomponenten ist das Modell der Komponente und nicht der Endpunktkonfiguration zugeordnet.
### Stellen Sie einen Endpunkt für eine Inferenzkomponente bereit
```
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)
```
Sie können zusätzliche Inferenzkomponenten auf demselben Endpunkt erstellen, um mehrere Modelle mit unabhängiger Skalierung und Ressourcenzuweisung zu hosten.
### Rufen Sie eine Inferenzkomponente auf
Um eine bestimmte Inferenzkomponente aufzurufen, geben Sie ihren Namen in den URL-Pfad ein:
```
https://runtime.sagemaker.{{REGION}}.amazonaws.com/endpoints/{{ENDPOINT_NAME}}/inference-components/{{IC_NAME}}/openai/v1
```
Das folgende Beispiel zeigt, wie eine Inferenzkomponente mithilfe des OpenAI SDK mit einem gemeinsamen Verbindungspool aufgerufen wird:
```
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)
```
Die gemeinsame Nutzung `httpx.Client` ermöglicht es mehreren OpenAI-Client-Instanzen, dieselben TLS-Sitzungen und denselben Verbindungspool wiederzuverwenden, wenn sie auf verschiedene Inferenzkomponenten auf demselben Endpunkt abzielen.
## Unterstützte Container
Die folgenden Container unterstützen OpenAI-compatible APIs auf SageMaker KI. Der Container muss den `/v1/chat/completions` Pfad implementieren und Streaming-Antworten im SSE-Format zurückgeben.
| Behälter | Status der Support |
| --- | --- |
| SageMaker AI vLLM Deep-Learning-Container | Unterstützt |
| SageMaker KI-SGLang Deep-Learning-Container | Unterstützt |
| Benutzerdefinierte Container, die OpenAI-API-Pfade implementieren und `/ping` | Unterstützt |