기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 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 추론 연](sagemaker-hyperpod-model-deployment.md)산자를 기반으로 합니다. 운영자가 모델 배포를 계속 오케스트레이션하는 동안 게이트웨이는 모델 서비스 포드 앞에 LLM 인식 라우팅 계층을 도입합니다. 게이트웨이는 특정 모델 서버 또는 오케스트레이션 계층에 의존하지 않으며 HyperPod 추론 Amazon EKS 추가 기능을 통해 전달됩니다. 사용자 `InferenceGatewayConfig` 지정 리소스를 사용하여 게이트웨이를 정의합니다. 단일는 하나의 게이트웨이, 즉 공유 바디 기반 라우터, TLS 종료, 요청 인증, 게이트웨이가 제공하는 각 모델에 대한 하나의 스케줄러를 `InferenceGatewayConfig` 설명합니다. 전체 스키마는 섹션을 참조하세요[InferenceGatewayConfig CRD 참조](#sagemaker-hyperpod-model-deployment-inference-gateway-crd). **중요** Inference Gateway에서 생성한 엔드포인트에는 기본적으로 요청 수준 인증 또는 권한 부여가 없습니다. `spec.auth.jwt`에서를 구성하지 않는 한 `InferenceGatewayConfig`게이트웨이는에 도달하는 모든 요청을 수락합니다. 액세스는 VPC 및 네트워크 제어에 의해서만 제한됩니다. 모든 게이트웨이에서 JWT 인증을 활성화하는 것이 좋습니다. 인증을 구성하려면 아래의 [사전 조건 및 배포](#sagemaker-hyperpod-model-deployment-inference-gateway-prereqs) 및 섹션을 참조`spec.auth`하세요[사양 필드](#sagemaker-hyperpod-model-deployment-inference-gateway-spec). ## 사전 조건 및 배포 추론 게이트웨이는 HyperPod 추론 Amazon EKS 추가 기능의 일부로 제공됩니다. 추가 기능을 설치하면 게이트웨이를 사용할 수 있으므로 별도의 설치가 필요하지 않습니다. 그런 다음 모델 `InferenceEndpointConfig` 리소스의 `spec.inferenceGateway.enabled` 필드를 통해 모델의 게이트웨이 라우팅을 켭니다. 기능이 도입된 버전은 섹션을 참조하세요[Amazon SageMaker HyperPod 추론 릴리스 정보](sagemaker-hyperpod-inference-release-notes.md). 게이트웨이를 통해 트래픽을 라우팅하기 전에 다음을 확인합니다. 배포된 모델 서비스 포드 각 스케줄러는 레이블 선택기에서 선택한 모델 서비스 포드로 라우팅됩니다. HyperPod 추론 연산자를 사용하여 모델을 배포하고 게이트웨이 구성에서 참조할 수 있도록 포드에 적용된 레이블을 기록해 둡니다. 모델 포드의 레이블을 나열하려면 다음 명령을 실행합니다. ``` kubectl get pods -n NAMESPACE --show-labels ``` 모델 서버 버전 추론 게이트웨이에는 vLLM v0.9.2 이상과 SGLang v0.3.5.post1 이상이 필요합니다. 이전 vLLM 버전에서는 KV 캐시 지표가 게이트웨이가 읽는 것과 다른 이름으로 게시됩니다. 요청은 여전히 나머지 신호를 사용하여 라우팅되지만 KV 캐시 사용률은 무시되고 오류는 보고되지 않습니다. 이전 SGLang 버전은 `--enable-metrics` 플래그를 지원하지 않으며 컨테이너가 시작되지 않습니다. 게이트웨이가 라우팅 결정에 필요한 지표를 읽을 수 있도록이 플래그로 SGLang을 시작합니다. 추가 기능 버전 추론 게이트웨이는 Amazon SageMaker HyperPod 추론 추가 기능 버전부터 사용할 `v2.0.0-eksbuild.2` 수 있습니다. 사용 가능한 최신 버전의 추가 기능을 설치하거나 업데이트합니다. 클러스터가 `InferenceGatewayConfig` 리소스를 인식하지 못하면 추가 기능이 게이트웨이를 포함하지 않는 이전 버전을 실행하고 있는 것입니다. 클러스터 종속성 + cert-manager는가 없이 `spec.tls` 설정된 경우 게이트웨이가 사용하는 자동 발급 TLS 경로의 클러스터에 설치해야 합니다`acmArn`. + Application Load AWS Load Balancer 엔드포인트 유형에 대해 로드 밸런서 컨트롤러를 설치해야 합니다. Application Load Balancer + 게이트웨이는 `hyperpod-inference-system` 네임스페이스를 사용합니다. TLS 인증서 게이트웨이에서 HTTPS를 종료하려면 기존 ACM 인증서 ARN을 제공하거나 게이트웨이가 인증서를 자동 발급하도록 합니다. 자동 발급은 cert-manager를 사용하고 인증서를 ACM으로 가져옵니다. 이 흐름을 수행하려면 운영자 실행 역할에 IRSA를 통한 `acm:ImportCertificate`, `acm:AddTagsToCertificate``acm:DescribeCertificate`, 및 `acm:DeleteCertificate` 권한이 있어야 합니다. 인증 요청(권장) 에서를 설정하여 모든 게이트웨이`spec.auth.jwt`에서 JWT 인증을 활성화하는 것이 좋습니다`InferenceGatewayConfig`. `spec.auth`이 생략되면 게이트웨이에는 요청 수준 인증이 없으며 VPC 및 네트워크 제어에 의해서만 액세스가 제한됩니다. JWT 인증을 활성화하려면를 작성하기 전에 `InferenceGatewayConfig`OIDC 발급자 URL, 발급자의 서명 키를 게시하는 HTTPS JWKS 엔드포인트,이 게이트웨이에 대한 토큰에 포함해야 하는 대상 값(또는 필수 클레임)을 준비합니다. 전체 스키마는 `spec.auth` 아래의 섹션을 참조[사양 필드](#sagemaker-hyperpod-model-deployment-inference-gateway-spec)하세요. ### 인증서 발급자 IAM 역할 설정 게이트웨이가 TLS 인증서를 자동 발급하면 cert-manager는 클러스터에서 인증서를 생성하고 게이트웨이 컨트롤러는 이를 ACM으로 가져옵니다. 가져오기는 AWS API 직접 호출이므로 컨트롤러에 AWS 자격 증명이 필요합니다. `hyperpod-inference-system` 네임스페이스의 `inference-gateway-controller` 서비스 계정이 서비스 계정에 대한 IAM 역할(IRSA)을 통해 수임하는 IAM 역할을 생성하여 제공합니다. **중요** TLS 자동 발급은 기본적으로 활성화되어 있으며 게이트웨이 컨트롤러는 시작 시이 역할을 읽습니다. 추가 기능을 설치하기 전에 역할을 생성합니다. 다음 환경 변수를 설정하고 클러스터의 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 < 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:::role/", "tlsCertificateS3Bucket": "", "inferenceOperator": { "enabled": true }, "inferenceGateway": { "enabled": true, "serviceAccount": { "roleArn": "arn:aws:iam:::role/" } }, "keda": { "enabled": true, "auth": { "aws": { "irsa": { "enabled": true, "roleArn": "arn:aws:iam:::role/" } } } }, "alb": { "enabled": true, "serviceAccount": { "create": true, "roleArn": "arn:aws:iam:::role/" } }, "jumpstartGatedModelDownloadRoleArn": "arn:aws:iam:::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에 모델 배포](sagemaker-hyperpod-model-deployment.md). HyperPod 추론 연산자 모델 사용자 지정 리소스 `InferenceEndpointConfig` 및 `JumpStartModel` (그룹 `inference.sagemaker.aws.amazon.com`, 버전 `v1`)를 조정합니다. 연산자는 모델 배포 및 서비스, Application Load Balancer, KEDA Auto Scaling, cert-manager 인증서 및 SageMaker AI 엔드포인트 등록을 생성합니다. 모델에 대해 게이트웨이가 활성화되면 연산자도 해당 모델을 게이트웨이에 연결합니다. 추론 게이트웨이 본문 기반 라우터에서 게이트웨이 및 HTTPRoute를 통해 엔드포인트 선택기로 요청 라우팅을 소유하고 , `InferencePool`엔드포인트 선택기 구성, HTTPRoute 및 등 각 스케줄러에 대한 다운스트림 라우팅 리소스를 생성합니다`EnvoyExtensionPolicy`. **참고** 운영자의 모델 사용자 지정 리소스는 버전를 사용하는 `v1`반면 게이트웨이의 `InferenceGatewayConfig` 리소스는 버전를 사용합니다`v1alpha1`. 둘 다 `inference.sagemaker.aws.amazon.com` 그룹에 속합니다. 다음 `spec.inferenceGateway` 필드를 사용하여 모델의 `InferenceEndpointConfig` (또는 `JumpStartModel`) 리소스에서 연산자를 통해 게이트웨이에 모델을 연결합니다. `spec.inferenceGateway.enabled` (선택 사항, 부울) 이 모델이 게이트웨이에 연결되어 있는지 여부입니다. 기본값: `false`. `spec.inferenceGateway.name` (선택 사항, 문자열) 연결할 `InferenceGatewayConfig` 리소스의 이름입니다. 이름과 네임스페이스를 공유하는 모델은 하나의 게이트웨이를 공유합니다. 이 필드가 비어 있으면 연산자가 양식의 이름을 생성합니다`inf-igw-`. 다음 코드 조각은 `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-. ``` 연산자는 , `Ready`또는의 `status.inferenceGateway`와 연결된 `State`의 `Pending`를 보고하는 아래의 모델 리소스`Failed``Name`에서 연결 상태를 미러링합니다`InferenceGatewayConfig`. 동일한 모델에서 `intelligentRoutingSpec.enabled`를와 `inferenceGateway.enabled` 함께 설정할 수 없습니다. 이러한 필드는 상호 배타적입니다. 게이트웨이가 모델에 대해 활성화되면 연산자는 단일 `InferenceGatewayConfig` 리소스를 생성 또는 업데이트하고 모델의 항목을 `spec.schedulers` 목록에 병합합니다. 연산자는 스케줄러 `name`, `modelSelector`, `modelName` `targetPort`및를 설정하고 항목을 처음 생성할 `llm-d` 때 기본값을 `scheduler`로 설정합니다. 이후 조정 시 연산자는 , `scheduler` `weights`및와 같이 고객이 제공한 값을 보존합니다`loraAdapters`. 둘 이상의 스케줄러가 있으면 본문 기반 라우터가 자동으로 활성화됩니다. 연산자는 `InferenceGatewayConfig` 리소스 또는 다운스트림 라우팅 리소스를 삭제하지 않습니다. 모델의 게이트웨이를 비활성화하거나 모델을 삭제하면 연산자는 해당 모델의 스케줄러 항목만 제거합니다. 게이트웨이 컨트롤러는 라우팅 리소스의 정리를 소유합니다. 두 `InferenceGatewayConfig` 가지 방법으로를 작성할 수 있으며 두 경로는 동일한 리소스에 공존합니다. + 모델의 `spec.inferenceGateway.enabled`에서를 설정하여 연산자를 통해 모델당 게이트웨이를 활성화합니다`InferenceEndpointConfig`. 연산자는 모델의 스케줄러 항목을 작성하고 유지 관리합니다. + 에 표시된 대로 `InferenceGatewayConfig` 리소스를 직접 작성합니다[예제](#sagemaker-hyperpod-model-deployment-inference-gateway-examples). 게이트웨이가 활성화된 모델 리소스를 조정하려면 먼저 HyperPod 추론 Amazon EKS 추가 기능을 통해 게이트웨이 구성 요소와 `InferenceGatewayConfig` CRD를 설치해야 합니다. 운영자 추가 기능 설치는 섹션을 참조하세요[EKS 추가 기능을 사용하여 추론 연산자 설치](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-install-inference-operator-addon). 스케줄러가 라우팅하는 모델 서비스 포드를 배포하려면 섹션을 참조하세요[파운데이션 모델 및 사용자 지정 미세 조정 모델 배포](sagemaker-hyperpod-model-deployment-deploy.md). **참고** SageMaker HyperPod 추론 연산자의 상태를 유지하는 것은 AWS 와 고객 간의 공동 책임입니다. AWS 는 SageMaker HyperPod 추론 연산자를 제공하고 유지 관리할 책임이 있습니다. 설치 후 고객은 클러스터 내 운영자의 운영 상태를 모니터링할 책임이 있습니다. ## InferenceGatewayConfig CRD 참조 단일 `InferenceGatewayConfig` 사용자 지정 리소스로 Inference Gateway를 구성합니다. 리소스는 지정된 게이트웨이의 단일 톤으로, 공유 바디 기반 라우터 구성과 모델별 스케줄러 목록을 보유합니다. 컨트롤러는 각 스케줄러에 대한 기본 `InferencePool`, 엔드포인트 선택기, HTTPRoute 및 `EnvoyExtensionPolicy` 리소스를 생성합니다. `InferenceGatewayConfig` 리소스만 작성합니다. **InferenceGatewayConfig 리소스 메타데이터** | 속성 | 값 | | --- | --- | | 종류 | InferenceGatewayConfig | | Group | inference.sagemaker.aws.amazon.com | | 버전 | v1alpha1 | | 복수형 | inferencegatewayconfigs | | 짧은 이름 | igwc | | Scope | 네임스페이스 | | 상태 하위 리소스 | /status | ### 사양 필드 `InferenceGatewayConfig` 리소스의 `spec` 필드에는 공유 바디 기반 라우터 구성, TLS 설정, 필요한 스케줄러 목록, 선택적 관찰성 및 포드 기본 설정이 포함됩니다. `bbr`(필수) 공유 본문 기반 라우터에 대한 구성입니다. 다음 필드가 포함됩니다. `bbr.enabled` (필수, 부울) 본문 기반 라우터의 활성화 여부입니다. 스케줄러가 두 개 이상 구성된 경우 라우터를 활성화해야 합니다. `bbr.replicas`(선택 사항, 정수) 본문 기반 라우터 복제본 수입니다. 최소: `1`. 기본값: `2`. `bbr.defaultBackend` (선택 사항) 라우터가 스케줄러와 일치시킬 수 없는 요청을 수신하는 백엔드입니다. `name` 문자열과 `port` 정수를 포함합니다(기본값: `8000`). `bbr.maxRequestBodyBytes`(선택 사항, 정수) 라우터가 `model` 필드를 읽기 위해 버퍼링하는 바이트 단위의 최대 요청 본문 크기입니다. 기본값 및 최대값: `268435456` (256MiB). `tls` 게이트웨이에 대한 HTTPS 종료 구성입니다. 기존 ACM 인증서를 참조하는 `acmArn` 필드를 포함합니다. `tls`가 빈 로 설정된 경우 `acmArn`게이트웨이는 cert-manager로 인증서를 자동 발급하고 ACM으로 가져옵니다. `auth`(선택 사항, 권장됨) 인증 구성을 요청합니다. 모든 게이트웨이에서 JWT 보유자 토큰 인증을 활성화하는 것이 좋습니다. 생략하면 게이트웨이에 요청 수준 인증이 없습니다. 로드 밸런서 상태 확인 경로는 인증되지 않은 상태로 유지되므로 토큰 없이 상태 프로브가 성공할 수 있습니다. 다음 필드가 `auth.jwt.provider` 포함된를 포함합니다. `name` (필수, 문자열) 공급자의 고유 이름입니다. `issuer` (필수, 문자열) OIDC 발급자 URL(`https://...`). 게이트웨이는이 값에 대해 토큰의 `iss` 클레임을 검증합니다. `remoteJWKS.uri` (필수, 문자열) JWT 서명을 확인하는 데 사용되는 HTTPS JWKS 엔드포인트입니다. `audiences` (선택 사항, 목록) 허용되는 `aud` 클레임 값(최대 8개). `audiences` 또는 중 하나 이상을 설정해야 `requiredClaims` 합니다. `requiredClaims` (선택 사항, 목록) 클레임 기반 권한 부여(최대 16개 항목). 각 항목에는 `name`, `valueType` (`String` 또는 `StringArray`) 및 `values` (1\~128개 항목, 각각 1\~1024자)가 있습니다. 설정하면 게이트웨이는 기본적으로 요청을 거부하고 클레임 값이 일치하는 토큰만 허용합니다. `observability` (선택 사항) 관찰성 구성. OpenTelemetry 지표 사이드카를 `metrics.enabled`제어하는를 포함합니다. 지표는 기본적으로 활성화됩니다. `podDefaults` (선택 사항) 본문 기반 라우터 및 엔드포인트 선택기 포드 모두에 적용되는 기본 포드 설정입니다. `resources`, , `nodeSelector`, `tolerations`, `affinity`, `labels``annotations`, 및 `env`를 지원합니다`envFrom`. `schedulers` (필수, 목록) 로 키가 지정된 모델별 스케줄러 구성의 목록입니다`name`. 하나 이상의 스케줄러가 필요하며 최대 100개까지 정의할 수 있습니다. 각 항목은에 `SchedulerSpec`설명된 입니다[SchedulerSpec 필드](#sagemaker-hyperpod-model-deployment-inference-gateway-scheduler). ### SchedulerSpec 필드 의 각 항목은 모델 하나에 대한 라우팅 및 엔드포인트 선택을 `spec.schedulers` 구성합니다. 스케줄러는 생성된 `InferencePool`, 엔드포인트 선택기, HTTPRoute 및 `EnvoyExtensionPolicy` 리소스의 이름을 지정합니다. `name` (필수, 문자열) 스케줄러 이름입니다. 생성된 `InferencePool`, 엔드포인트 선택기, HTTPRoute 및 `EnvoyExtensionPolicy` 리소스의 이름을 지정하는 데 사용됩니다. 최대 길이: 63자. `modelSelector`(필수) 이 스케줄러가 라우팅하는 모델 서비스 포드를 선택하는 Kubernetes 레이블 선택기입니다. `modelName` (필수, 문자열) 요청 본문의 `model` 필드와 일치하고 HTTPRoute 헤더 일치로 사용되는 모델 이름입니다. 스케줄러 간에 고유해야 합니다. 최대 길이: 253자. `targetPort`(선택 사항, 정수) 전달된 트래픽을 수신하는 모델 서비스 포드의 포트입니다. 범위: 1\~65535. 기본값: `8000`. `appProtocol` (선택 사항, 문자열) 모델 서비스 포드에 도달하는 데 사용되는 애플리케이션 프로토콜입니다. 유효한 값: `http`, `kubernetes.io/h2c`. 기본값: `http`. `scheduler` (선택 사항, 문자열) 엔드포인트 선택기 이미지를 선택하는 스케줄러 유형입니다. 유효한 값: `llm-d`, `epp`. 기본값: `llm-d`. `engineType` (선택 사항, 문자열) 모델 서비스 포드에서 실행되는 추론 엔진입니다. 이 값은 엔드포인트 선택기가 스크레이핑하는 Prometheus 지표 이름 집합을 선택합니다. 유효한 값: `vllm`, `sglang`. 기본값: `vllm`. `weights` (선택 사항) 엔드포인트 선택기가 후보 포드의 순위를 매기는 데 사용하는 점수 가중치입니다. 모든 가중치는 음수가 아닌 정수입니다. `configMapRef`와는 함께 사용할 수 없습니다. 지원되는 가중치: `queue` 보류 중인 요청 대기열 깊이의 가중치입니다. 기본값: `2`. `kvCache` KV 캐시 사용률에 대한 가중치입니다. 기본값: `2`. `prefix` 접두사 캐시 선호도에 대한 가중치입니다. 기본값: `3`. `lru` least-recently-used 점수에 대한 가중치입니다. `scheduler`이 `llm-d`인 경우에만 유효합니다. `loraAffinity` LoRA 어댑터 선호도에 대한 가중치입니다. `runningRequests` 포드에서 실행 중인 요청 수의 가중치입니다. `predictedLatency` 예측된 요청 지연 시간의 가중치입니다. `configMapRef` (선택 사항) 대신 사용자 지정 엔드포인트 선택기 구성을 제공하는 ConfigMap에 대한 참조입니다`weights`. 필수 `name` 및를 포함합니다`key`(기본값: `default-plugins.yaml`). `weights`와는 함께 사용할 수 없습니다. `replicas`(선택 사항, 정수) 이 스케줄러에 대한 엔드포인트 선택기 복제본 수입니다. 최소: `1`. 기본값: `2`. `replicas`가 1보다 크면 엔드포인트 선택기는 리더 선택과 함께 고가용성으로 실행됩니다. `env` 및 `envFrom` (선택 사항) 이 스케줄러의 엔드포인트 선택기 컨테이너에 추가된 환경 변수입니다. `loraAdapters` (선택 사항, 목록) 이 스케줄러의 모델 뒤에 제공되는 LoRA 어댑터 이름입니다. 최대: 항목 50개, 각각 최대 253자. `routeTimeout` (선택 사항, 문자열) HTTPRoute 요청 제한 시간은 게이트웨이 API 기간(예: `30s` 또는 `5m`)입니다. 제한 시간을 비활성화하려면 `0s`으로 설정합니다. `logLevel`(선택 사항, 정수) 엔드포인트 선택기 로그 세부 정보입니다. 범위: 0\~5. ### 검증 규칙 `InferenceGatewayConfig` 리소스는 다음과 같은 검증 규칙을 적용합니다. 이러한 규칙을 위반하는 리소스는 거부됩니다. + 둘 이상의 스케줄러가 구성된 경우 본문 기반 라우터를 활성화(`bbr.enabled: true`)해야 합니다. + `modelName`는 모든 스케줄러에서 고유해야 합니다. + 스케줄러 내에서 `weights` 및 `configMapRef`는 상호 배타적입니다. + `weights.lru` 가중치는 스케줄러의 `scheduler` 유형이 인 경우에만 유효합니다`llm-d`. ### 상태 필드 컨트롤러는 `status` 하위 리소스에서 게이트웨이의 관찰된 상태를 보고합니다. `conditions` 게이트웨이 구성의 전체 상태를 설명하는 표준 Kubernetes 조건입니다. `schedulers` 스케줄러별 상태입니다. 각 항목에는 다음이 포함됩니다. `name` 스케줄러 이름입니다. `conditions` 이 스케줄러의 상태를 설명하는 조건입니다. `currentScheduler` 이 항목에 현재 적용 중인 스케줄러 유형입니다. `rolloutState` 스케줄러의 롤아웃 상태입니다. `Pending`, `Progressing`, `Available` 또는 `Degraded` 중 하나 `observedGeneration` 컨트롤러가 가장 최근에 조정한 리소스의 생성입니다. `tls` TLS 상태, 자동 발급 모드에서만 보고됨. `acmArn`, `issuedAt`및를 포함합니다`dnsNames`. ## Kubernetes RBAC 권한 추론 게이트웨이는 `hyperpod-inference-system` 네임스페이스의 Kubernetes 서비스 계정`inference-gateway-controller`에서 단일 컨트롤러로 실행됩니다. 본문 기반 라우터, 스케줄러별 엔드포인트 선택기, 게이트웨이 컨트롤러 및 `InferenceGatewayConfig` 조정자는 모두이 단일 컨트롤러에서 실행됩니다. 클러스터 범위 권한은 `ClusterRole`명명된 `sagemaker-inference-gateway-controller-supplement` 및 일치하는에 의해 부여됩니다`ClusterRoleBinding`. 번들 게이트웨이 차트에서 이미 제공하는 서비스 계정과 권한을 함께 보완합니다. 이러한 권한은 범위가 지정되고 최소 권한이며 컨트롤러는 클러스터 관리자로 실행되지 않습니다. 다음 표에는 용도별로 그룹화된 컨트롤러의 클러스터 범위 권한이 나열되어 있습니다. 이 표에서 *전체 액세스*는 `create`, , `get`, `list`, `watch``update``patch`, `delete` 및 동사를 의미합니다. **Inference Gateway 컨트롤러 권한** | API 그룹 | 리소스 | 동사 | 용도 | | --- | --- | --- | --- | | inference.sagemaker.aws.amazon.com | inferencegatewayconfigs, status 및 finalizers 하위 리소스 포함 | get의 patch 경우 list, update, , 및 watch, inferencegatewayconfigsget의 patch 경우 update, , status,의 update 경우 finalizers | InferenceGatewayConfig 리소스를 조정하고, 상태를 작성하고, 최종 사용자를 관리합니다. | | gateway.networking.k8s.io | httproutes, gateways, gatewayclasses | httproutes 및에 대한 전체 액세스 gateways권한, get, list, create, watch및에 patch 대한 gatewayclasses | Gateway API를 통한 프로그램 요청 라우팅. | | inference.networking.k8s.io | inferencepools | 모든 액세스 | 각 스케줄러에 대한 라우팅 백엔드를 생성합니다. | | inference.networking.x-k8s.io | inferencepools, inferenceobjectives, inferencemodelrewrites | get, list, watch | 엔드포인트 선택을 위한 읽기 라우팅 의도입니다. | | gateway.envoyproxy.io | envoyextensionpolicies, envoyproxies, httproutefilters, clienttrafficpolicies, securitypolicies | 모든 액세스 | 게이트웨이 데이터 영역 및 원격 측정을 구성합니다. | | 코어("") | configmaps, services, serviceaccounts, events, secrets, pods | configmaps, 및 services에 대한 전체 액세스 serviceaccounts권한, create patch에 대한 전체 액세스 권한list, secrets 및에 watch 대한 events get전체 액세스 권한 pods | 생성된 워크로드와 읽기 라우팅 및 서비스 상태를 관리합니다. | | apps | deployments | 모든 액세스 | 본문 기반 라우터 및 엔드포인트 선택기 배포를 관리합니다. | | rbac.authorization.k8s.io | roles, rolebindings | 모든 액세스 | 스케줄러별 엔드포인트 선택기를 생성합니다Role. | | discovery.k8s.io, coordination.k8s.io | endpointslices; leases | get의 경우 list, watch 및 , endpointslicesget의 patch 경우 list, watch, create, update, 및 leases | 엔드포인트 검색 및 엔드포인트 선택기 리더 선택. | | networking.k8s.io | ingresses, networkpolicies | 모든 액세스 | 로드 Application Load Balancer AWS Load Balancer 경로를 프로비저닝합니다. | | cert-manager.io | issuers, certificates (코어 watch의 getlist, 및 secrets) | 모든 액세스 | 이 없이 spec.tls 설정된 경우 TLS 인증서를 자동 발급합니다acmArn. | | apiextensions.k8s.io | customresourcedefinitions | create, 및 get, patch, update및 리소스 이름에 따라 게이트웨이가 관리하는 특정 게이트웨이 API CRDs로 delete 제한됨 | 게이트웨이가 의존하는 사용자 지정 리소스 정의를 설치합니다. | **참고** 의 `create` 동사는 특정 리소스 이름으로 제한되지 `customresourcedefinitions` 않습니다. 컨트롤러는 시작 시 자체 컨테이너 이미지에서 이를 적용하여 의존하는 Gateway API 사용자 지정 리소스 정의를 설치합니다. 결합 크기가 Amazon EKS 추가 기능 페이로드 제한을 초과하기 때문입니다. Kubernetes는 동`create`사를 명명된 리소스로 제한하도록 허용하지 않으므로이 권한은 반드시 광범위합니다. 사용자 지정 리소스 정의, `get`, `patch`및 `update`에 대한 다른 모든 작업은 게이트웨이가 관리하는 특정 사용자 지정 리소스 정의로 `delete`제한됩니다. 이 권한은 이러한 CRD 유형만 정의할 수 있으며 사용자 지정 리소스의 데이터에 대한 액세스 권한을 부여하지 않습니다. 또한 컨트롤러는 게이트웨이 구성에 따라 런타임에 다음과 같은 네임스페이스 역할을 생성합니다. + *본문 기반 라우터 -* 라우터`Role`가 LoRA 어댑터를 해결하기 위해 읽는 `list`, 및 `get``configmaps`를 `watch`에 부여하는 네임스페이스입니다. 라우터가 여러 네임스페이스에서 실행되는 경우 `ClusterRole` 대신 입니다. + *엔드포인트 선택기* -에 대한 읽기 액세스 권한을 `Role` 부여하는 네임스페이스입니다`pods`. 엔드포인트 선택기가 둘 이상의 복제본으로 실행되는 경우 컨트롤러는 `leases` 및에 `Role` 대한 리더-선택도 생성합니다`events`. Prometheus 지표가 활성화되면 컨트롤러는 `/metrics` 엔드포인트`create`에 `tokenreviews` 대한 `subjectaccessreviews` 및 읽기 액세스 권한을 `ClusterRole` 부여하는 선택적를 생성합니다. **참고** HyperPod 추론 연산자를 통해 게이트웨이를 활성화하면 연산자의 자체 컨트롤러는 `InferenceGatewayConfig` 리소스를 생성하고 업데이트할 수 있는 권한을 보유합니다. 연산자가 모델을 게이트웨이에 연결하는 방법은 단원을 참조하십시오[HyperPod 추론 연산자와 통합](#sagemaker-hyperpod-model-deployment-inference-gateway-operator-integration). 이러한 권한 중 일부는 해당 기능이 활성화된 경우에만 적용됩니다. ## 관찰성 Inference Gateway는 모든 게이트웨이 구성 요소에서 Prometheus 지표를 내보냅니다. 본문 기반 라우터와 각 엔드포인트 선택기 모두 포드에 표준 Prometheus `/metrics` 엔드포인트를 노출합니다. 본문 기반 라우터 포드는 `hyperpod-inference-system` 네임스페이스에서 실행되고 엔드포인트 선택기 포드는와 동일한 네임스페이스에서 실행됩니다`InferenceGatewayConfig`. 지표에는 모델별 요청 카운터 및 기간, 엔드포인트 선택기 내의 예약 지연 시간 및 플러그인별 실행 시간, 평균 KV 캐시 사용률 및 대기열 깊이와 같은 집계된 풀 지표가 포함됩니다. 모델 서버 포드 지표(예: vLLM 또는 SGLang)는 모델 서버 자체에서 내보내집니다. 엔드포인트 선택기는 이를 스크레이핑하여 후보 포드를 채점합니다. 이 `true` (기본값)`spec.observability.metrics.enabled`인 경우 게이트웨이 컨트롤러는 OpenTelemetry Collector 사이드카를 모든 본문 기반 라우터 및 엔드포인트 선택기 포드에 주입합니다. 사이드카는 이러한 지표를 HyperPod 추론 관찰성 스택으로 전달합니다. 여기서 기본 제공 Grafana 대시보드는 이러한 지표를 모델 서버 및 클러스터 지표와 함께 표시합니다. 설정 및 대시보드 세부 정보는 섹션을 참조하세요[HyperPod 클러스터에서 추론 관찰성 구현](sagemaker-hyperpod-model-deployment-observability.md). 사이드카 주입을 건너뛰`false`려면 필드를 로 설정합니다. 필드 참조는 `observability` 아래의 섹션을 참조하세요[사양 필드](#sagemaker-hyperpod-model-deployment-inference-gateway-spec). 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"} ] }' ```