기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Amazon SageMaker HyperPod 추론을 위한 추론 게이트웨이

Amazon SageMaker HyperPod Inference Gateway는 Amazon EKS의 HyperPod 클러스터를 위한 Kubernetes 네이티브 대규모 언어 모델(LLM) 인식 라우팅 및 오케스트레이션 계층입니다. 추론 요청을 검사하고, 각 요청에서 모델 이름을 읽고, GPU 부하를 기반으로 모델 서비스 포드를 선택하여 여러 모델의 트래픽이 단일 게이트웨이 엔드포인트를 통해 효율적으로 라우팅되도록 합니다.

게이트웨이는 각 요청을 세 계층을 통해 라우팅합니다. 공유 구성 요소인 Body-Based Router(BBR)는 요청 본문에서 model 필드를 읽고 LoRA 어댑터 이름을 기본 모델로 확인하며 X-Gateway-Model-Name 및 X-Gateway-Base-Model-Name 헤더를 설정합니다. 그런 다음 게이트웨이는 해당 헤더를 HTTPRoute와 일치시키고 요청된 모델의 InferencePool에 요청을 전달합니다. 이 풀 내에서 엔드포인트 선택기(EPP/스케줄러)는 접두사 캐시 및 LoRA 어댑터 선호도와 함께 대기열 깊이 및 KV 캐시 사용률과 같은 모델-서버 지표에 대한 후보 점수를 매겨 모델-서빙 포드를 선택합니다. 아래에서 정의하는 각 항목은 자체 엔드포인트 선택기를 spec.schedulers 실행하므로이 주제에서는 엔드포인트 선택기, EPP 및 스케줄러라는 용어를 상호 교환적으로 사용합니다.

추론 게이트웨이는 교체하는 대신 HyperPod 추론 연산자를 기반으로 합니다. 운영자가 모델 배포를 계속 오케스트레이션하는 동안 게이트웨이는 모델 서비스 포드 앞에 LLM 인식 라우팅 계층을 도입합니다. 게이트웨이는 특정 모델 서버 또는 오케스트레이션 계층에 의존하지 않으며 HyperPod 추론 Amazon EKS 추가 기능을 통해 전달됩니다.

사용자 InferenceGatewayConfig 지정 리소스를 사용하여 게이트웨이를 정의합니다. 단일는 하나의 게이트웨이, 즉 공유 바디 기반 라우터, TLS 종료, 요청 인증, 게이트웨이가 제공하는 각 모델에 대한 하나의 스케줄러를 InferenceGatewayConfig 설명합니다. 전체 스키마는 섹션을 참조하세요InferenceGatewayConfig CRD 참조.

사전 조건 및 배포

추론 게이트웨이는 HyperPod 추론 Amazon EKS 추가 기능의 일부로 제공됩니다. 추가 기능을 설치하면 게이트웨이를 사용할 수 있으므로 별도의 설치가 필요하지 않습니다. 그런 다음 모델 InferenceEndpointConfig 리소스의 spec.inferenceGateway.enabled 필드를 통해 모델의 게이트웨이 라우팅을 켭니다. 기능이 도입된 버전은 섹션을 참조하세요Amazon SageMaker HyperPod 추론 릴리스 정보.

게이트웨이를 통해 트래픽을 라우팅하기 전에 다음을 확인합니다.

인증서 발급자 IAM 역할 설정

게이트웨이가 TLS 인증서를 자동 발급하면 cert-manager는 클러스터에서 인증서를 생성하고 게이트웨이 컨트롤러는 이를 ACM으로 가져옵니다. 가져오기는 AWS API 직접 호출이므로 컨트롤러에 AWS 자격 증명이 필요합니다. hyperpod-inference-system 네임스페이스의 inference-gateway-controller 서비스 계정이 서비스 계정에 대한 IAM 역할(IRSA)을 통해 수임하는 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 추론 추가 기능은 추론 연산자와 추론 게이트웨이를 모두 설치합니다. 다음 명령을 사용하여 설치합니다. 의 경우 이전 섹션에서 생성한 인증서 발급자 역할을 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 추론 연산자와 통합

HyperPod 추론 연산자와 추론 게이트웨이에는 고유한 책임이 있습니다. 운영자는 모델 배포, 오케스트레이션 및 모델을 게이트웨이에 연결하는 와이어링을 소유합니다. 게이트웨이는 요청 라우팅을 소유하고 각 스케줄러에 대한 라우팅 리소스를 생성합니다. 연산자를 사용하여 모델을 배포하는 방법에 대한 자세한 내용은 섹션을 참조하세요Amazon SageMaker HyperPod에 모델 배포.

다음 spec.inferenceGateway 필드를 사용하여 모델의 InferenceEndpointConfig (또는 JumpStartModel) 리소스에서 연산자를 통해 게이트웨이에 모델을 연결합니다.

다음 코드 조각은 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>.

연산자는 , Ready또는의 status.inferenceGateway와 연결된 State의 Pending를 보고하는 아래의 모델 리소스FailedName에서 연결 상태를 미러링합니다InferenceGatewayConfig. 동일한 모델에서 intelligentRoutingSpec.enabled를와 inferenceGateway.enabled 함께 설정할 수 없습니다. 이러한 필드는 상호 배타적입니다.

게이트웨이가 모델에 대해 활성화되면 연산자는 단일 InferenceGatewayConfig 리소스를 생성 또는 업데이트하고 모델의 항목을 spec.schedulers 목록에 병합합니다. 연산자는 스케줄러 name, modelSelector, modelName targetPort및를 설정하고 항목을 처음 생성할 llm-d 때 기본값을 scheduler로 설정합니다. 이후 조정 시 연산자는 , scheduler weights및와 같이 고객이 제공한 값을 보존합니다loraAdapters. 둘 이상의 스케줄러가 있으면 본문 기반 라우터가 자동으로 활성화됩니다.

연산자는 InferenceGatewayConfig 리소스 또는 다운스트림 라우팅 리소스를 삭제하지 않습니다. 모델의 게이트웨이를 비활성화하거나 모델을 삭제하면 연산자는 해당 모델의 스케줄러 항목만 제거합니다. 게이트웨이 컨트롤러는 라우팅 리소스의 정리를 소유합니다.

두 InferenceGatewayConfig 가지 방법으로를 작성할 수 있으며 두 경로는 동일한 리소스에 공존합니다.

게이트웨이가 활성화된 모델 리소스를 조정하려면 먼저 HyperPod 추론 Amazon EKS 추가 기능을 통해 게이트웨이 구성 요소와 InferenceGatewayConfig CRD를 설치해야 합니다. 운영자 추가 기능 설치는 섹션을 참조하세요EKS 추가 기능을 사용하여 추론 연산자 설치. 스케줄러가 라우팅하는 모델 서비스 포드를 배포하려면 섹션을 참조하세요파운데이션 모델 및 사용자 지정 미세 조정 모델 배포.

InferenceGatewayConfig CRD 참조

단일 InferenceGatewayConfig 사용자 지정 리소스로 Inference Gateway를 구성합니다. 리소스는 지정된 게이트웨이의 단일 톤으로, 공유 바디 기반 라우터 구성과 모델별 스케줄러 목록을 보유합니다. 컨트롤러는 각 스케줄러에 대한 기본 InferencePool, 엔드포인트 선택기, HTTPRoute 및 EnvoyExtensionPolicy 리소스를 생성합니다. InferenceGatewayConfig 리소스만 작성합니다.

사양 필드

InferenceGatewayConfig 리소스의 spec 필드에는 공유 바디 기반 라우터 구성, TLS 설정, 필요한 스케줄러 목록, 선택적 관찰성 및 포드 기본 설정이 포함됩니다.

SchedulerSpec 필드

의 각 항목은 모델 하나에 대한 라우팅 및 엔드포인트 선택을 spec.schedulers 구성합니다. 스케줄러는 생성된 InferencePool, 엔드포인트 선택기, HTTPRoute 및 EnvoyExtensionPolicy 리소스의 이름을 지정합니다.

검증 규칙

InferenceGatewayConfig 리소스는 다음과 같은 검증 규칙을 적용합니다. 이러한 규칙을 위반하는 리소스는 거부됩니다.

상태 필드

컨트롤러는 status 하위 리소스에서 게이트웨이의 관찰된 상태를 보고합니다.

Kubernetes RBAC 권한

추론 게이트웨이는 hyperpod-inference-system 네임스페이스의 Kubernetes 서비스 계정inference-gateway-controller에서 단일 컨트롤러로 실행됩니다. 본문 기반 라우터, 스케줄러별 엔드포인트 선택기, 게이트웨이 컨트롤러 및 InferenceGatewayConfig 조정자는 모두이 단일 컨트롤러에서 실행됩니다. 클러스터 범위 권한은 ClusterRole명명된 sagemaker-inference-gateway-controller-supplement 및 일치하는에 의해 부여됩니다ClusterRoleBinding. 번들 게이트웨이 차트에서 이미 제공하는 서비스 계정과 권한을 함께 보완합니다. 이러한 권한은 범위가 지정되고 최소 권한이며 컨트롤러는 클러스터 관리자로 실행되지 않습니다.

다음 표에는 용도별로 그룹화된 컨트롤러의 클러스터 범위 권한이 나열되어 있습니다. 이 표에서 전체 액세스는 create, , get, list, watchupdatepatch, delete 및 동사를 의미합니다.

또한 컨트롤러는 게이트웨이 구성에 따라 런타임에 다음과 같은 네임스페이스 역할을 생성합니다.

이러한 권한 중 일부는 해당 기능이 활성화된 경우에만 적용됩니다.

관찰성

Inference Gateway는 모든 게이트웨이 구성 요소에서 Prometheus 지표를 내보냅니다. 본문 기반 라우터와 각 엔드포인트 선택기 모두 포드에 표준 Prometheus /metrics 엔드포인트를 노출합니다. 본문 기반 라우터 포드는 hyperpod-inference-system 네임스페이스에서 실행되고 엔드포인트 선택기 포드는와 동일한 네임스페이스에서 실행됩니다InferenceGatewayConfig. 지표에는 모델별 요청 카운터 및 기간, 엔드포인트 선택기 내의 예약 지연 시간 및 플러그인별 실행 시간, 평균 KV 캐시 사용률 및 대기열 깊이와 같은 집계된 풀 지표가 포함됩니다. 모델 서버 포드 지표(예: vLLM 또는 SGLang)는 모델 서버 자체에서 내보내집니다. 엔드포인트 선택기는 이를 스크레이핑하여 후보 포드를 채점합니다.

이 true (기본값)spec.observability.metrics.enabled인 경우 게이트웨이 컨트롤러는 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 스케줄러

이 예제에서는 epp 스케줄러 유형을 sglang 엔진과 함께 사용하고 명시적 엔드포인트 선택기 점수 가중치를 설정합니다.

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 작업은 아닙니다. modelName 대상 스케줄러의 로 설정된 model 필드를 사용하여 게이트웨이 엔드포인트로 요청을 전송합니다. 본문 기반 라우터는이 필드를 읽어 요청을 라우팅합니다.

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"}
    ]
  }'