View a markdown version of this page

Inference Gateway 문제 해결 가이드 - Amazon SageMaker AI
게이트웨이 상태 진단추가 기능 설치 문제InferenceGatewayConfig가 준비되지 않음스케줄러별 실패스케줄러 rolloutState 성능 저하됨모델 포드 재시작 후 오래된 엔드포인트JWT 인증에서 401 또는 403 반환대시보드에서 누락된 지표요청 실패엔드포인트 선택 디버깅수명 주기 및 정리로그 수집

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

Inference Gateway 문제 해결 가이드

개요: HyperPod 추론 게이트웨이는 본문 기반 라우터(BBR),를 사용하는 게이트웨이HTTPRoute, 엔드포인트 선택기(EPP)의 세 계층을 통해 트래픽을 라우팅합니다. 계층을 잘못 구성하면 요청 실패, 트래픽이 잘못된 모델에 도달 또는 모델 서비스 포드 간에 고르지 않은 로드가 발생할 수 있습니다. 이 섹션에서는 게이트웨이, BBR, 게이트웨이 및 HTTPRoute, InferencePool, EPP 관련 문제와 이로 인해 발생하는 모든 문제를 다룹니다.

게이트웨이 상태 진단

다음 명령을 사용하여 게이트웨이와 게이트웨이가 관리하는 리소스를 검사합니다.

네임스페이스의 모든 InferenceGatewayConfig 리소스를 나열합니다.

kubectl get inferencegatewayconfig -A

특정 게이트웨이에 대한 세부 상태, 스케줄러별 롤아웃 상태 및 조건 메시지를 표시합니다.

kubectl describe inferencegatewayconfig <name> -n <namespace>

게이트웨이 컨트롤러와 본문 기반 라우터 포드를 확인합니다.

kubectl get pods -n hyperpod-inference-system

컨트롤러에서 생성된 다운스트림 라우팅 리소스를 확인합니다.

kubectl get httproute,inferencepool,securitypolicy -A

status.conditions 및 각 스케줄러의 rolloutState (Pending, Available, 또는 Degraded)Progressing를 검사합니다. 실행 가능한 실패 이유는 해당 조건 메시지에 있습니다.

추가 기능 설치 문제

문제: 게이트웨이 리소스가 누락되었거나 HyperPod 추론 Amazon EKS 추가 기능을 설치한 후가 수락GatewayClass되지 않습니다.

증상 및 해결 방법:가를 kubectl get gatewayclass inference-gateway 반환NotFound하거나 리소스에가 표시됩니다ACCEPTED=False. 이는 추가 기능이 설치되지 않았거나 설치가 완료되지 않았음을 나타냅니다. 추가 기능을 다시 설치하거나 업데이트합니다.

aws eks update-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --resolve-conflicts OVERWRITE

그런 다음 게이트웨이 컨트롤러가 실행 중인지 확인합니다.

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

InferenceGatewayConfig가 준비되지 않음

문제: InferenceGatewayConfig가 생성되었지만 Accepted=False 또는가 status.conditions 표시Ready=False되거나 검증에 의해 kubectl apply가 완전히 거부됩니다.

증상 및 해결 방법:

  • kubectl apply는에서 실패합니다bbr must be enabled when more than one scheduler is defined. 둘 이상의 스케줄러가 정의될 때마다 본문 기반 라우터가 필요합니다. spec.bbr.enabled를 true으로 설정합니다.

  • kubectl apply 에서는가 실패합니다modelName must be unique across schedulers. 두 스케줄러가 동일한를 선언합니다modelName. 모든 스케줄러에 고유한이 있도록 이름을 바꿉니다modelName.

  • Accepted=False, Reason=InvalidLoraAdapters. 아래에 선언된 LoRA 어댑터 이름은 스케줄러 간에 spec.schedulers[].loraAdapters 중복되거나 스케줄러의와 충돌합니다modelName. 조건 메시지에 문제가 되는 이름이 있는지 검사합니다.

    kubectl describe inferencegatewayconfig <name> -n <namespace>

  • Accepted=False, Reason=ResourceNamingViolation. 연결된 이름이 Kubernetes 63자 레이블 제한을 <config-name>-<scheduler-name> 초과합니다. 구성 또는 스케줄러 이름을 줄입니다.

  • Ready=False, Reason=GatewayNotProgrammed. 게이트웨이가 아직 로드 밸런서를 프로비저닝하지 않았습니다. 상위 게이트웨이를 검사합니다.

    kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway <name> -n hyperpod-inference-system

  • AdmissionBlocked=True, Reason=WebhookDenied. 클러스터 승인 웹후크가 게이트웨이 포드를 거부하고 있습니다. 조건 메시지는 불쾌한 웹후크의 이름을 지정합니다. 웹후크를 제거하거나 수정한 다음 포드가 즉시 다시 생성되도록 게이트웨이 배포를 다시 시작합니다. 배포 이름이 생성되므로 먼저 조회합니다.

    kubectl -n hyperpod-inference-system get deploy \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>

    그런 다음 다시 시작합니다.

    kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>

스케줄러별 실패

문제: 특정 스케줄러의 조건(BackendsReady, LoraSupported또는 PoolReady)은 스케줄러가 완전히 준비되지 않았음을 나타냅니다.

증상 및 해결 방법:

  • BackendsReady=False, Reason=NoModelPods 또는 Reason=NoReadyModelPods. 일치하는 포드가 없거나 spec.schedulers[].modelSelector일치하는 포드가 아직 준비되지 않았습니다. 모델 서비스 포드의 레이블을 스케줄러의 선택기와 비교합니다.

    kubectl get pods -n <namespace> --show-labels

    모델 서비스 포드를 배포하고를 적용하기 전에 준비 상태가 될 때까지 기다립니다InferenceGatewayConfig.

  • BackendsReady=False, Reason=InvalidModelSelector. matchLabels matchExpressions 이하의 형식modelSelector이 잘못되었습니다. 구성에서 선택기를 수정합니다.

  • LoraSupported=False, Reason=ModelServerLoraDisabled. 이 스케줄러를 지원하는 모델 서버가 LoRA 지원이 활성화된 상태로 시작되지 않았습니다. 모델 서버에서 동일한 플래그(예: vLLM--enable-lora의 경우)를 활성화하고 모델 포드를 다시 시작합니다.

  • PoolReady=False, Reason=NotFound 또는 Reason=NotAccepted. 게이트웨이에서 InferencePool 또는를 아직 조정하거나 수락HTTPRoute하지 않았습니다. 다음 두 가지를 모두 검사합니다.

    kubectl get inferencepool,httproute -n <namespace>

    구성이 적용된 후 몇 분 후에도 둘 중 하나가 여전히 누락된 경우 상위 게이트웨이를 설명하여 승인 오류를 확인합니다.

    kubectl describe gateway -n hyperpod-inference-system

스케줄러 rolloutState 성능 저하됨

문제: 스케줄러에 대한 엔드포인트 선택기 배포가 중단되어 사용 가능 상태가 되지 않습니다.

증상 및 해결 방법: 스케줄러의 EPPReady 조건에는 실행 가능한 이유가 포함됩니다. 일반적인 사용 사례는 다음과 같습니다.

  • 컨테이너 이미지는 가져올 수 없습니다.

  • 포드가 충돌 루프 상태입니다.

  • 컨테이너에 잘못된 환경 변수, 볼륨 마운트 또는 보안 암호 참조와 같은 구성 오류가 있습니다.

  • 배포가 진행 기한을 초과했습니다.

다음 명령을 사용하여 실패한 스케줄러를 식별하고 배포를 검사합니다.

# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{range .status.schedulers[?(@.rolloutState=="Degraded")]}{.name}{"\n"}{end}'

# Describe the scheduler's Endpoint Picker Deployment for pod events and container errors
kubectl describe deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

모델 포드 재시작 후 오래된 엔드포인트

문제: 모델 포드가 삭제되고 대체 포드가 준비 상태가 되면 엔드포인트 선택기는 삭제된 포드의 IP 주소로 계속 라우팅됩니다. 요청은 HTTP 503을 반환하거나 연결이 거부되고 조건은 자체적으로 복구되지 않습니다.

해결 방법: 풀에서 IP가 제거되기 전에 Kubernetes가 포드 NotReady를 표시하고 트래픽이 완전히 제공되면 교체 포드만 알리도록 모델 포드에 준비 프로브를 추가합니다. port를 스케줄러의 로 targetPort 설정하고 path를 모델 서버의 상태 엔드포인트로 설정합니다.

readinessProbe:
  httpGet:
    path: /health
    port: 8000

해결 방법: 모델 포드를 즉시 재배포할 수 없는 경우 스케줄러의 엔드포인트 선택기를 다시 시작하여 현재 포드 세트에서 엔드포인트 목록을 강제로 다시 빌드합니다.

kubectl rollout restart deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

JWT 인증에서 401 또는 403 반환

문제: 모델에 도달하기 전에 spec.auth.jwt가 구성되고 요청이 거부되거나 JWT 인증이 활성화된 후 게이트웨이가 준비 상태가 되지 않습니다.

증상 및 해결 방법:

  • HTTP 401. 토큰이 누락되었거나, 만료되었거나, 형식이 잘못되었거나, iss 클레임이 구성된 공급자와 일치하지 않습니다. 클라이언트가 Authorization: Bearer <token> 헤더를 전송하는지 확인하고 JWT를 디코딩하여 iss 클레임을와 비교합니다spec.auth.jwt.provider.issuer.

  • HTTP 403. 서명 검증에 실패했거나 토큰의 aud 또는 requiredClaims가 공급자 구성과 일치하지 않습니다. 공급자 구성을 검사하고 토큰aud과 requiredClaims 일치하는 모든 항목을 확인합니다.

    kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.auth.jwt.provider}'

  • JWT가 활성화된 상태에서는 게이트웨이가 준비 상태가 되지 않습니다. 생성된 SecurityPolicy는 게이트웨이에서 수락되지 않습니다. SecurityPolicy 리소스에서 실패 이유를 검사합니다.

    kubectl get securitypolicy -A
kubectl describe securitypolicy <name> -n <namespace>

    게이트웨이에서 연결할 수 spec.auth.jwt.provider.remoteJWKS.uri 없는 것이 일반적인 원인입니다. URI가 유효한 JWKS 문서를 확인하고 반환하는지 확인합니다.

대시보드에서 누락된 지표

문제: 엔드포인트 선택기 또는 본문 기반 라우터 지표가 모니터링 대시보드에 표시되지 않습니다.

증상 및 해결 방법: 지표 수집은 기본적으로 활성화되어 있으므로 일반적으로 OpenTelemetry Collector 사이드카가 있습니다. 사이드카가 두 포드 유형 모두에서 실행 중인지, 지표가 명시적으로 비활성화되었는지 확인합니다.

바디 기반 라우터 포드에서 사이드카를 확인합니다.

kubectl -n hyperpod-inference-system get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

엔드포인트 선택기 포드에서 사이드카를 확인합니다.

kubectl -n <namespace> get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

지표가 명시적으로 비활성화되었는지 확인합니다.

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.observability.metrics.enabled}'

마지막 명령의 빈 출력은 필드가 설정되지 않았고 지표가 활성화되었음을 의미합니다. 명시적 만 사이드카를 false 비활성화합니다. 값이 인 경우 필드를 로 false설정true하거나 제거하면 컨트롤러가 다음 조정 시 사이드카를 주입합니다.

요청 실패

문제: 게이트웨이가 준비되었지만 추론 요청이 실패합니다.

증상 및 해결 방법:

  • 알려진 모델에 대한 HTTP 404입니다. 요청 본문의 model 값이 스케줄러의와 정확히 일치하지 않거나 modelName요청된 모델이에서 선언되지 않은 LoRA 어댑터를 통해 제공됩니다spec.schedulers[].loraAdapters. 요청된 모델과 일치하는 스케줄러가 없고 설정되지 않은 경우 게이트웨이spec.bbr.defaultBackend는 404를 반환합니다. 구성된 모델 이름과 어댑터 이름을 확인합니다.

    kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].loraAdapters}'

  • 요청이 중단된 다음 시간 초과됩니다. 모델 서비스 포드가 아직 모델 가중치를 로드하고 있거나에 준비된 엔드포인트InferencePool가 없습니다. 게이트웨이 엔드포인트를 호출하기 전에 모델 포드가 준비 상태가 될 때까지 기다립니다. 의 스케줄러 modelSelector 레이블을 선택기InferenceGatewayConfig로 사용합니다.

    kubectl get pods -n <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>

엔드포인트 선택 디버깅

문제: 소수의 모델 포드에 대한 트래픽 스큐 또는 어댑터를 호스팅하지 않는 포드로 LoRA 요청이 라우팅됩니다.

해결 방법: 엔드포인트 선택기의 로그 세부 정보를 일시적으로 높여 점수 결정 사항을 검사합니다. 스케줄러logLevel에서를 설정합니다.

spec:
  schedulers:
    - name: <scheduler-name>
      logLevel: 4

로그 수준 의미:

  • 1 - 수명 주기 이벤트를 요청합니다.

  • 2 - 기본값입니다. 경고 및 승인 거부.

  • 3 - 선택한 엔드포인트 및 점수별 요약.

  • 4 - 엔드포인트별, 점수별 점수 및 가중치 기반 합계.

  • 5 - 프로토콜 수준 추적(구체적).

엔드포인트 선택기 로그를 검사합니다.

kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp --tail=200 -f

초과 로그 볼륨logLevel을 방지하기 위해 조사가 완료되면 기본값으로 돌아갑니다.

수명 주기 및 정리

문제: HyperPod Inference Amazon EKS 추가 기능을 제거 또는 업그레이드하면 분리된 리소스가 클러스터에 남거나 후속 설치가 차단됩니다.

해결 방법: 추가 기능을 제거하거나 업그레이드하기 전에 항상 모든 InferenceGatewayConfig 리소스를 삭제합니다. InferenceGatewayConfig가 있는 동안 추가 기능을 제거하면 리소스의 최종 사용자를 소유한 컨트롤러가 제거되어 해당 리소스가에 멈춰 있습니다Terminating.

kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A

추가 기능 작업을 계속하기 전에 두 번째 명령이 행을 반환하지 않는지 확인합니다.

추가 기능을 다시 설치한 후 게이트웨이 네임스페이스에 리소스를 나열하고 더 이상 라이브에 매핑되지 않는 모든 항목을 제거합니다InferenceGatewayConfig.

kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
  -n hyperpod-inference-system

컨트롤러에서 발급한 ACM 인증서는 추가 기능 제거로 삭제되지 않습니다. 이를 제거하려면 AWS Resource Groups Tagging API에서 태그를 기준으로 ACM 인증서를 필터링CreatedBy=HyperPodInference하고 더 이상 필요하지 않은 인증서를 삭제합니다.

로그 수집

다음 명령을 사용하여 각 게이트웨이 구성 요소에서 로그를 검색합니다.

# Gateway controller
kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller

# Body-Based Router (deployment name is <gateway-name>-bbr)
kubectl logs -n hyperpod-inference-system deploy/<gateway-name>-bbr -c bbr

# Endpoint Picker for a specific scheduler
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp