翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon SageMaker HyperPod 推論用の推論ゲートウェイ

Amazon SageMaker HyperPod Inference Gateway は、Amazon EKS 上の HyperPod クラスター用の Kubernetes ネイティブの大規模言語モデル (LLM) 対応ルーティングおよびオーケストレーションレイヤーです。推論リクエストを検査し、各リクエストからモデル名を読み取り、GPU 負荷に基づいてモデル提供ポッドを選択すると、複数のモデルのトラフィックが単一のゲートウェイエンドポイントを介して効率的にルーティングされます。

ゲートウェイは、各リクエストを 3 つのレイヤーにルーティングします。共有コンポーネントである本文ベースのルーター (BBR) は、リクエスト本文から modelフィールドを読み取り、LoRA アダプター名をベースモデルに解決し、 X-Gateway-Model-Name ヘッダーと X-Gateway-Base-Model-Nameヘッダーを設定します。次に、ゲートウェイはこれらのヘッダーを HTTPRoute に照合し、リクエストされたモデルの InferencePool にリクエストを転送します。このプール内で、Endpoint Picker (EPP/スケジューラ) は、キューの深さや KV キャッシュ使用率などのモデルサーバーメトリクスの候補をプレフィックスキャッシュや LoRA アダプターのアフィニティとともにスコアリングすることで、モデルサービスを提供するポッドを選択します。で定義する各エントリは独自の Endpoint Picker spec.schedulersを実行するため、このトピックでは Endpoint Picker、EPP、スケジューラという用語を同じ意味で使用します。

Inference Gateway は、置き換える代わりに HyperPod Inference Operator 上に構築されます。オペレーターがモデルのデプロイをオーケストレーションし続ける間、ゲートウェイはモデル提供ポッドの前に LLM 対応ルーティングレイヤーを導入します。ゲートウェイは、特定のモデルサーバーまたはオーケストレーションレイヤーに依存しず、HyperPod Inference Amazon EKS アドオンを介して配信されます。

InferenceGatewayConfig カスタムリソースを使用してゲートウェイを定義します。単一の は、共有ボディベースルーター、TLS 終了、リクエスト認証、ゲートウェイが機能するモデルごとに 1 つのスケジューラという 1 つのゲートウェイをInferenceGatewayConfig記述します。スキーマの詳細については、「」を参照してくださいInferenceGatewayConfig CRD リファレンス。

前提条件とデプロイ

Inference Gateway は、HyperPod Inference Amazon EKS アドオンの一部として配信されます。アドオンをインストールするとゲートウェイが使用可能になるため、別途インストールする必要はありません。次に、モデルのInferenceEndpointConfigリソースの spec.inferenceGateway.enabledフィールドを通じてモデルのゲートウェイルーティングを有効にします。機能が導入されたバージョンについては、「」を参照してくださいAmazon SageMaker HyperPod Inference リリースノート。

ゲートウェイ経由でトラフィックをルーティングする前に、以下を確認してください。

証明書発行者の IAM ロールを設定する

ゲートウェイが TLS 証明書を自動発行すると、cert-manager はクラスターに証明書を生成し、ゲートウェイコントローラーはそれを ACM にインポートします。インポートは AWS API コールであるため、コントローラーには AWS 認証情報が必要です。これらを提供するには、hyperpod-inference-system名前空間inference-gateway-controllerのサービスアカウントがサービスアカウント (IRSA) の IAM ロールを通じて引き受ける IAM ロールを作成します。

次の環境変数を設定し、クラスターの OIDC 発行者を取得します。

export CLUSTER=EKS_CLUSTER_NAME
export REGION=REGION
export ACCOUNT=AWS_ACCOUNT_ID
export ROLE_NAME=CERT_ISSUER_ROLE_NAME

export OIDC_ID=$(aws eks describe-cluster --name $CLUSTER --region $REGION \
  --query 'cluster.identity.oidc.issuer' --output text | sed 's|https://||')

ゲートウェイコントローラーサービスアカウントがロールを引き受けることを許可する信頼ポリシーを作成します。

cat > trust-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::${ACCOUNT}:oidc-provider/${OIDC_ID}"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "${OIDC_ID}:sub": "system:serviceaccount:hyperpod-inference-system:inference-gateway-controller",
        "${OIDC_ID}:aud": "sts.amazonaws.com"
      }
    }
  }]
}
EOF

ロールを作成し、 AmazonSageMakerHyperPodInferenceGatewayAccess 管理ポリシーをアタッチします。このポリシーは、コントローラーが作成する証明書をインポート、タグ付け、記述、削除するために必要な ACM アクセス許可を付与します。

aws iam create-role --role-name $ROLE_NAME --assume-role-policy-document file://trust-policy.json
aws iam attach-role-policy --role-name $ROLE_NAME --policy-arn arn:aws:iam::aws:policy/AmazonSageMakerHyperPodInferenceGatewayAccess

アドオンをインストールするinferenceGateway.serviceAccount.roleArnときに、このロール ARN を として指定します。

アドオンをインストールする

HyperPod Inference アドオンは、Inference Operator と Inference Gateway の両方をインストールします。次のコマンドを使用してインストールします。にはinferenceGateway.serviceAccount.roleArn、前のセクションで作成した証明書発行者ロールを使用します。残りのプレースホルダー値を、アカウントのロールとバケットに置き換えます。

aws eks create-addon \
  --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --addon-version v2.0.0-eksbuild.2 \
  --configuration-values '{
    "executionRoleArn": "arn:aws:iam::<ACCOUNT>:role/<EXEC_ROLE>",
    "tlsCertificateS3Bucket": "<TLS_BUCKET>",
    "inferenceOperator": { "enabled": true },
    "inferenceGateway": {
      "enabled": true,
      "serviceAccount": { "roleArn": "arn:aws:iam::<ACCOUNT>:role/<CERT_ISSUER_ROLE_NAME>" }
    },
    "keda": { "enabled": true, "auth": { "aws": { "irsa": { "enabled": true, "roleArn": "arn:aws:iam::<ACCOUNT>:role/<KEDA_IRSA_ROLE>" } } } },
    "alb": { "enabled": true, "serviceAccount": { "create": true, "roleArn": "arn:aws:iam::<ACCOUNT>:role/<ALB_IRSA_ROLE>" } },
    "jumpstartGatedModelDownloadRoleArn": "arn:aws:iam::<ACCOUNT>:role/<JUMPSTART_ROLE>"
  }'

アドオンがクラスターに既にインストールされている場合は、 create-addonを に置き換えupdate-addonて を追加します--resolve-conflicts OVERWRITE。コマンドの残りの部分は変更されません。 はコマンドの設定値を既存のアドオン設定OVERWRITEに適用します。

ゲートウェイコントローラーが実行されていること、およびゲートウェイリソースが登録されていることを確認します。

kubectl rollout status deploy/inference-gateway-controller \
  -n hyperpod-inference-system --timeout=150s

kubectl get crd inferencegatewayconfigs.inference.sagemaker.aws.amazon.com

kubectl get gatewayclass inference-gateway

アドオン自体がアクティブであり、ヘルスの問題がないことを確認します。

aws eks describe-addon \
  --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --query 'addon.{version:addonVersion,status:status,health:health.issues}'

HyperPod Inference Operator との統合

HyperPod Inference Operator と Inference Gateway には個別の責任があります。オペレーターは、モデルのデプロイ、オーケストレーション、およびモデルをゲートウェイにアタッチするワイヤリングを所有します。ゲートウェイはリクエストルーティングを所有し、各スケジューラのルーティングリソースを生成します。演算子を使用したモデルのデプロイの詳細については、「」を参照してくださいAmazon SageMaker HyperPod にモデルをデプロイする。

演算子、モデルの InferenceEndpointConfig (または JumpStartModel) リソース、 spec.inferenceGatewayフィールドを使用して、モデルをゲートウェイにアタッチします。

次のスニペットは、 InferenceEndpointConfigリソースのオinferenceGatewayプトインを示しています。

apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: my-model
spec:
  # ... model deployment fields ...
  inferenceGateway:
    enabled: true
    name: my-gateway        # Optional. When empty, the operator generates inf-igw-<uuid>.

演算子は、、Pending、Readyまたは Stateの Failedとstatus.inferenceGateway、アタッチされた Nameの をレポートする のモデルリソースのアタッチ状態をミラーリングしますInferenceGatewayConfig。同じモデルintelligentRoutingSpec.enabledで をinferenceGateway.enabled一緒に設定することはできません。これらのフィールドは相互に排他的です。

モデルに対してゲートウェイを有効にすると、オペレータは単一のInferenceGatewayConfigリソースを作成または更新し、モデルのエントリをそのspec.schedulersリストにマージします。演算子は、スケジューラ name、modelName、targetPort、および を設定しmodelSelector、エントリを最初に作成llm-dするときにデフォルトを schedulerに設定します。後の照合では、演算子は scheduler、、 weightsなどのお客様が指定した値を保持しますloraAdapters。複数のスケジューラが存在する場合、本文ベースのルーターは自動的に有効になります。

オペレーターは、InferenceGatewayConfigリソースまたはダウンストリームルーティングリソースを削除しません。モデルのゲートウェイを無効にするか、モデルを削除すると、オペレーターはそのモデルのスケジューラエントリのみを削除します。ゲートウェイコントローラーは、ルーティングリソースのクリーンアップを所有しています。

は 2 つのInferenceGatewayConfig方法で作成でき、2 つのパスは同じリソースに共存します。

ゲートウェイコンポーネントと InferenceGatewayConfig CRD は、ゲートウェイが有効になっているモデルリソースを照合する前に、HyperPod Inference Amazon EKS アドオンを介してインストールする必要があります。オペレータアドオンのインストールについては、「」を参照してくださいEKS アドオンを使用した推論演算子のインストール。スケジューラがルーティングするモデル提供ポッドのデプロイについては、「」を参照してください基盤モデルとカスタムファインチューニングされたモデルをデプロイする。

InferenceGatewayConfig CRD リファレンス

Inference Gateway は 1 つのInferenceGatewayConfigカスタムリソースで設定します。リソースは、特定のゲートウェイのシングルトンです。共有ボディベースのルーター設定とモデルごとのスケジューラのリストを保持します。コントローラーはInferencePool、各スケジューラの基盤となる 、エンドポイントピッカー、HTTPRoute、およびEnvoyExtensionPolicyリソースを生成します。リソースのみを作成しますInferenceGatewayConfig。

仕様フィールド

InferenceGatewayConfig リソースの specフィールドには、共有ボディベースのルーター設定、TLS 設定、スケジューラの必須リスト、オプションのオブザーバビリティとポッドのデフォルト設定が含まれます。

SchedulerSpec フィールド

の各エントリは、1 つのモデルに対してルーティングとエンドポイントの選択spec.schedulersを設定します。スケジューラは、生成された InferencePool、エンドポイントピッカー、HTTPRoute、およびEnvoyExtensionPolicyリソースに名前を付けます。

検証ルール

InferenceGatewayConfig リソースは、次の検証ルールを適用します。これらのルールのいずれかに違反するリソースは拒否されます。

ステータスフィールド

コントローラーは、statusサブリソース内のゲートウェイの観測状態を報告します。

Kubernetes RBAC アクセス許可

Inference Gateway は、hyperpod-inference-system名前空間の Kubernetes サービスアカウントinference-gateway-controllerで単一のコントローラーとして実行されます。本文ベースのルーター、スケジューラごとのエンドポイントピッカー、ゲートウェイコントローラー、InferenceGatewayConfigおよびリコンシラーはすべて、この 1 つのコントローラーで実行されます。クラスタースコープのアクセス許可は、 ClusterRoleという名前の sagemaker-inference-gateway-controller-supplementと一致する によって付与されますClusterRoleBinding。これらは、バンドルされた Gateway チャートが既に提供しているサービスアカウントとアクセス許可を補完します。これらのアクセス許可はスコープと最小特権であり、コントローラーはクラスター管理者として実行されません。

次の表は、コントローラーのクラスタースコープのアクセス許可を目的別にグループ化したものです。この表では、フルアクセスとは、create、、get、list、watch、updatepatch、およびdelete動詞を意味します。

また、コントローラーは、ゲートウェイの設定に応じて、実行時に次の名前空間ロールを作成します。

これらのアクセス許可の一部は、対応する機能が有効になっている場合にのみ適用されます。

オブザーバビリティ

Inference Gateway は、すべてのゲートウェイコンポーネントから Prometheus メトリクスを出力します。Body-Based Router と各 Endpoint Picker の両方が、ポッド上の標準の Prometheus /metricsエンドポイントを公開します。本文ベースのルーターポッドは hyperpod-inference-system名前空間で実行され、Endpoint Picker ポッドは と同じ名前空間で実行されますInferenceGatewayConfig。メトリクスは、モデルごとのリクエストカウンターと期間、Endpoint Picker 内のスケジューリングレイテンシーとプラグインごとの実行時間、平均 KV キャッシュ使用率やキュー深度などの集計プールメトリクスを対象としています。Model-server ポッドメトリクス (vLLM や SGLang など) は、モデルサーバー自体によって出力されます。Endpoint Picker はそれらをスクレイプして候補ポッドをスコアリングします。

spec.observability.metrics.enabled が true (デフォルト) の場合、ゲートウェイコントローラーは OpenTelemetry Collector サイドカーをすべての本文ベースのルーターおよびエンドポイントピッカーポッドに挿入します。サイドカーは、これらのメトリクスを HyperPod 推論オブザーバビリティスタックに転送します。このスタックでは、組み込みの Grafana ダッシュボードがモデルサーバーとクラスターのメトリクスとともに表示します。セットアップとダッシュボードの詳細については、「」を参照してくださいHyperPod クラスターでの推論オブザーバビリティの実装。サイドカーインジェクションをスキップfalseするには、 フィールドを に設定します。フィールドリファレンスについては、「」のobservability「」を参照してください仕様フィールド。

Amazon Managed Grafana でゲートウェイメトリクスを表示するには、推論ダッシュボードフォルダを開き、推論ゲートウェイダッシュボードを選択します。ダッシュボードには、各モデルのゲートウェイ全体の可用性、リクエストレート、end-to-endのレイテンシー、スケジューラごとのスループット、レイテンシー、エラー、およびボディベースルーターがリクエスト本文からモデル名を解決するレートがレポートされます。

例

次の例は、一般的なInferenceGatewayConfig設定とゲートウェイを呼び出す方法を示しています。

最小限のマルチモデル設定

この例では、TLS が自動発行された llm-d スケジューラにルーティングします。tls は空のオブジェクトに設定されているため、ゲートウェイは証明書を自動的に発行し、ACM にインポートします。

apiVersion: inference.sagemaker.aws.amazon.com/v1alpha1
kind: InferenceGatewayConfig
metadata:
  name: inference-gateway-demo
  namespace: inference-gateway
spec:
  bbr:
    enabled: true
  tls: {}                       # Auto-issue a certificate via cert-manager and import to ACM.
  schedulers:
    - name: llama
      modelName: "meta-llama/Llama-3.2-1B-Instruct"
      modelSelector:
        matchLabels:
          app: vllm-llama
      targetPort: 8000
      scheduler: llm-d

明示的な重みを持つ SGLang スケジューラ

この例では、sglangエンジンで スeppケジューラタイプを使用し、明示的な Endpoint Picker スコアリングの重みを設定します。

spec:
  bbr:
    enabled: true
  schedulers:
    - name: qwen7b
      modelName: "Qwen/Qwen2.5-7B-Instruct"
      modelSelector:
        matchLabels:
          app: sglang-qwen7b
      targetPort: 8000
      scheduler: epp
      engineType: sglang
      logLevel: 4
      weights:
        kvCache: 2
        prefix: 3
        runningRequests: 2

LoRA アダプター ConfigMap

本文ベースのルーターは、BBR 管理用にラベル付けされた ConfigMap から LoRA アダプターとそのベースモデルを検出します。ルーターはこのマッピングを使用して、リクエスト本文のアダプター名をベースモデルに解決します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: deepseek-adapters
  labels:
    inference.networking.k8s.io/bbr-managed: "true"
data:
  baseModel: deepseek/vllm-deepseek-r1
  adapters: |
    - ski-resorts
    - movie-critique

ゲートウェイを呼び出す

ゲートウェイは OpenAI 互換の推論エンドポイントを提供します。これは、ゲートウェイを介して推論リクエストを送信するためのランタイム呼び出し契約であり、 AWS API オペレーションではありません。model フィールドをターゲットスケジューラmodelNameの に設定して、ゲートウェイエンドポイントにリクエストを送信します。本文ベースのルーターは、このフィールドを読み取り、リクエストをルーティングします。

curl https://your-gateway-endpoint/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'