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
<a name="realtime-endpoints-openai-compatible"></a>

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
<a name="realtime-endpoints-openai-compatible-prerequisites"></a>

Sebelum Anda mulai, pastikan Anda memiliki yang berikut:
+  AWS Akun dengan izin untuk membuat titik akhir SageMaker AI.
+  SageMaker AI Python SDK diinstal (). `pip install sagemaker`
+ SDK Python OpenAI diinstal (). `pip install openai`
+ Model yang disimpan di Amazon S3 (misalnya, Qwen3-4B diunduh dari Hugging Face).
+ Peran eksekusi IAM dengan `AmazonSageMakerFullAccess` kebijakan untuk membuat titik akhir.
+ Peran IAM atau pengguna dengan `sagemaker:InvokeEndpoint` izin `sagemaker:CallWithBearerToken` dan untuk memanggil titik akhir.

## Otentikasi dengan token pembawa
<a name="realtime-endpoints-openai-compatible-auth"></a>

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
<a name="realtime-endpoints-openai-compatible-auth-generate"></a>

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_token`Fungsi 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 a`region`, opsional`aws_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](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html).

### Auto-refresh token untuk aplikasi yang berjalan lama
<a name="realtime-endpoints-openai-compatible-auth-refresh"></a>

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
<a name="realtime-endpoints-openai-compatible-auth-iam"></a>

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

**penting**  
Selalu batasi `Resource` for `sagemaker:InvokeEndpoint` ke ARN titik akhir tertentu daripada menggunakan wildcard. Token pembawa yang dihasilkan dari peran ini memiliki tingkat akses yang sama, sehingga kebijakan dengan cakupan sempit membatasi radius ledakan jika token diekspos secara tidak sengaja.

**catatan**  
`sagemaker:CallWithBearerToken`membutuhkan wildcard (`"*"`) untuk `Resource` bidang tersebut. Itu tidak mendukung pembatasan tingkat sumber daya.

### Cara kerja token
<a name="realtime-endpoints-openai-compatible-auth-how-it-works"></a>

Token pembawa adalah URL pra-ditandatangani SigV4 yang dikodekan base64. Saat Anda menelepon`generate_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
<a name="realtime-endpoints-openai-compatible-auth-security"></a>

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:
+ Cakupan peran IAM yang digunakan untuk pembuatan token hingga izin minimum yang diperlukan — khususnya `sagemaker:InvokeEndpoint` dan hanya `sagemaker:CallWithBearerToken` pada ARN titik akhir yang perlu diakses oleh pemanggil.
+ Jangan membuat token dari peran dengan izin ekspansif, seperti yang diberikan oleh `AdministratorAccess` atau kebijakan `AmazonSageMakerFullAccess` terkelola.
+ Jangan menyimpan token pada disk, dalam variabel lingkungan, dalam file konfigurasi, dalam database, atau dalam cache terdistribusi. Jangan mencatat token, dan hanya mengirimkannya melalui protokol komunikasi terenkripsi seperti HTTPS.
+ Pembuatan Token adalah operasi lokal tanpa overhead jaringan. Hasilkan token baru pada titik penggunaan atau gunakan `httpx.Auth` pola penyegaran otomatis yang ditunjukkan di atas.
+ Setel kedaluwarsa token ke durasi terpendek yang dibutuhkan beban kerja Anda.

## Memanggil titik akhir model tunggal
<a name="realtime-endpoints-openai-compatible-single-model"></a>

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`

**catatan**  
SageMaker Titik akhir AI dikenakan biaya saat dalam layanan, terlepas dari lalu lintas. Lihat [halaman harga SageMaker AI](https://aws.amazon.com/sagemaker/pricing/) untuk detailnya.

### Terapkan titik akhir
<a name="realtime-endpoints-openai-compatible-single-model-deploy"></a>

```
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
<a name="realtime-endpoints-openai-compatible-single-model-invoke"></a>

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

`model`Bidang 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
<a name="realtime-endpoints-openai-compatible-inference-components"></a>

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
<a name="realtime-endpoints-openai-compatible-ic-deploy"></a>

```
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
<a name="realtime-endpoints-openai-compatible-ic-invoke"></a>

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
<a name="realtime-endpoints-openai-compatible-containers"></a>

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


|  Kontainer  |  Status Support  | 
| --- | --- | 
| SageMaker Wadah Pembelajaran Mendalam AI Vllm | Didukung | 
| SageMaker Wadah Pembelajaran Mendalam AI SGlang | Didukung | 
| Wadah khusus yang mengimplementasikan jalur API OpenAI dan `/ping` | Didukung |