Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Memanggil titik akhir dengan API OpenAI-compatible

Titik akhir inferensi real-time Amazon SageMaker AI mendukung jalur OpenAI-compatible API. Pelanggan yang menggunakan OpenAI SDK, LangChain, atau Strands Agents dapat memanggil model pada SageMaker AI dengan hanya mengubah URL titik akhir mereka, tanpa memerlukan klien khusus, pembungkus SigV4, atau penulisan ulang kode.

Dengan kemampuan ini, titik akhir SageMaker AI mengekspos /openai/v1/chat/completions jalur yang menerima permintaan Penyelesaian Obrolan dan mengembalikan respons langsung dari wadah, termasuk streaming. OpenAI-compatible titik akhir tersedia di semua titik akhir dan komponen inferensi menggunakan API dan SDK SageMaker AI standar.

SageMaker AI merutekan permintaan berdasarkan nama titik akhir di URL. Setiap OpenAI-compatible klien bekerja tanpa konfigurasi tambahan. Anda dapat membuat token pembawa berumur pendek untuk titik akhir Anda dan menggunakannya dengan klien OpenAI Anda.

Prasyarat

Sebelum Anda mulai, pastikan Anda memiliki yang berikut:

Otentikasi dengan token pembawa

SageMaker OpenAI-compatible Titik akhir AI menggunakan otentikasi token pembawa. SageMaker AI Python SDK menyertakan generator token yang membuat token berumur pendek (berlaku hingga 12 jam) dari kredensyal Anda yang ada. AWS Tidak ada rahasia tambahan atau kunci API yang diperlukan.

Token berisi peran atau kredensyal pengguna Anda dan memerlukan izin sagemaker:CallWithBearerToken dan sagemaker:InvokeEndpoint tindakan.

Menghasilkan token

Gunakan generate_token fungsi dari SageMaker AI Python SDK untuk membuat token pembawa:

from sagemaker.core.token_generator import generate_token
from datetime import timedelta

token = generate_token(region="us-west-2", expiry=timedelta(minutes=5))

generate_tokenFungsi ini menghasilkan token pembawa berumur pendek untuk mengautentikasi dengan SageMaker AI API. Secara default, token berlaku selama 12 jam. Anda dapat mengganti ini dengan expiry parameter menggunakan timedelta nilai di mana saja antara 1 detik dan 12 jam.

Fungsi menerima aregion, opsionalaws_credentials_provider, dan expiry durasi. Jika tidak ada wilayah yang disediakan, itu kembali ke variabel AWS_REGION lingkungan. Jika tidak ada penyedia kredensyal yang disediakan, ia menyelesaikan kredensyal menggunakan rantai kredensyal default, yang mencari beberapa sumber termasuk variabel lingkungan,,, AWS kredensyal kontainer~/.aws/credentials, ~/.aws/config dan profil instance. Untuk urutan resolusi penuh, lihat dokumentasi kredensil boto3.

Auto-refresh token untuk aplikasi yang berjalan lama

Untuk aplikasi yang berjalan terus menerus, Anda dapat menerapkan pola penyegaran otomatis menggunakan httpx sehingga token baru dihasilkan pada setiap permintaan:

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

Izin IAM

Peran IAM atau pengguna yang memanggil titik akhir memerlukan izin berikut:

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

Cara kerja token

Token pembawa adalah URL pra-ditandatangani SigV4 yang dikodekan base64. Saat Anda menelepongenerate_token, SageMaker AI SDK membuat permintaan ke layanan SageMaker AI untuk CallWithBearerToken tindakan tersebut, menandatanganinya secara lokal menggunakan AWS kredensyal Anda, dan mengkodekan URL yang ditandatangani yang dihasilkan sebagai string token portabel. Tidak ada panggilan jaringan yang dilakukan selama pembuatan token — penandatanganan terjadi sepenuhnya di sisi klien.

Saat Anda menyajikan token ini ke titik akhir SageMaker AI, layanan menerjemahkannya, memvalidasi tanda tangan SigV4, memverifikasi bahwa token belum kedaluwarsa, dan mengonfirmasi bahwa identitas IAM yang berasal memiliki izin yang diperlukan. Masa pakai token yang efektif adalah expiry nilai yang lebih rendah dan validitas yang tersisa dari AWS kredensi yang digunakan untuk menandatanganinya.

Praktik terbaik keamanan

Token pembawa membawa otorisasi yang sama dengan AWS kredensyal dasar yang digunakan untuk menghasilkannya. Perlakukan token dengan perawatan yang sama seperti kredensil. Ikuti praktik terbaik ini:

Memanggil titik akhir model tunggal

Titik akhir model tunggal menampung satu model dan melayani permintaan secara langsung. Contoh berikut diterapkan Qwen3-4B menggunakan SageMaker AI VllM Deep Learning Container pada sebuah instance. ml.g6.2xlarge

Terapkan titik akhir

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)

Buat model, konfigurasi titik akhir, dan titik akhir:

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},
)

Titik akhir beralih ke InService status dalam beberapa menit. Setelah siap, ia melayani /invocations jalur SageMaker AI standar dan OpenAI-compatible jalur di/openai/v1/chat/completions.

Memanggil titik akhir

Dengan titik akhir dalam layanan, panggil menggunakan OpenAI Python SDK. URL dasar mengikuti format ini:

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

modelBidang dilewatkan ke wadah. Karena SageMaker AI merutekan permintaan berdasarkan nama titik akhir di URL, Anda dapat membiarkan bidang ini kosong atau menyetelnya agar sesuai dengan nama model yang diharapkan penampung Anda.

Memanggil komponen inferensi

Komponen inferensi memungkinkan Anda meng-host beberapa model pada satu titik akhir, masing-masing dengan alokasi sumber daya komputasi khusus. Dengan komponen inferensi, model dikaitkan dengan komponen daripada konfigurasi titik akhir.

Menerapkan titik akhir komponen inferensi

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)

Anda dapat membuat komponen inferensi tambahan pada titik akhir yang sama untuk meng-host beberapa model dengan penskalaan independen dan alokasi sumber daya.

Memanggil komponen inferensi

Untuk memanggil komponen inferensi tertentu, sertakan namanya di jalur URL:

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

Contoh berikut menunjukkan cara memanggil komponen inferensi menggunakan OpenAI SDK dengan kumpulan koneksi bersama:

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)

Shared httpx.Client memungkinkan beberapa instance klien OpenAI untuk menggunakan kembali sesi TLS dan kumpulan koneksi yang sama saat menargetkan komponen inferensi yang berbeda pada titik akhir yang sama.

Kontainer yang didukung

Kontainer berikut mendukung OpenAI-compatible API di SageMaker AI. Wadah harus mengimplementasikan /v1/chat/completions jalur dan mengembalikan respons streaming dalam format SSE.