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:

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 aregion, 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.

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

Wie funktioniert das Token

Das Bearer-Token ist eine Base64-kodierte, vorsignierte SigV4-URL. Wenn Sie aufrufengenerate_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:

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

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.