본문으로 건너뛰기

문제 해결

GPU 워크로드가 배치되지 않거나 모델 서빙 엔드포인트에 연결할 수 없을 때 확인할 항목을 안내합니다.

Workload가 SchedulingGated 상태에 머무름​

Kueue가 Workload를 아직 승인하지 않은 상태입니다.

  1. Workload의 Queue 이름과 우선순위를 확인합니다.

    kubectl get workload -n <사용자 namespace> --show-labels

  2. LocalQueue가 올바른 ClusterQueue를 참조하는지 확인합니다.

    kubectl get localqueue -n <사용자 namespace> -o yaml

  3. Workload의 Admission 상태와 메시지를 확인합니다.

    kubectl describe workload <Workload 이름> -n <사용자 namespace>

kueue.x-k8s.io/queue-name과 kueue.x-k8s.io/priority-class는 annotation이 아닌 metadata.labels에 지정해야 합니다.

Workload는 승인됐지만 Pod가 Pending 상태임​

Kueue가 자원을 승인했지만 Scheduler가 워크로드의 배치 조건을 충족하지 못한 상태일 수 있습니다.

kubectl describe pod <Pod 이름> -n <사용자 namespace>
kubectl get podgroup -n <사용자 namespace>

다음 항목을 확인합니다.

  • 요청한 GPU, CPU, 메모리를 제공할 수 있는 노드가 있는지 확인
  • Gang을 구성하는 모든 Pod를 동시에 배치할 수 있는지 확인
  • KAI Scheduler 사용 시 kai.scheduler/enabled: "true"와 schedulerName: kai-scheduler가 모두 지정되었는지 확인
  • Volcano 사용 시 schedulerName: volcano-scheduler가 지정되었는지 확인
  • Network Topology의 hard 조건이 지나치게 제한적이지 않은지 확인

Dynamo Worker가 모델을 로드하지 못함​

kubectl get pod -n <사용자 namespace>
kubectl logs <Worker Pod 이름> -n <사용자 namespace> -c main
kubectl describe pod <Worker Pod 이름> -n <사용자 namespace>

다음 항목을 확인합니다.

  • models PVC가 정상적으로 Bound 상태인지 확인
  • /mnt/models/<모델 경로>가 실제 PVC 디렉터리와 일치하는지 확인
  • --tensor-parallel-size와 nvidia.com/gpu 요청값이 같은지 확인
  • Dynamo 런타임 이미지 태그와 runtimeVersionOverride가 일치하는지 확인
  • 노드가 요청한 CPU, 메모리, GPU를 제공할 수 있는지 확인

KServe InferencePoolReady가 WaitingForGateway 상태임​

LLMInferenceService의 HTTPRoute가 InferencePool을 참조하는지 확인합니다.

kubectl get httproute <서비스명>-kserve-route -n <사용자 namespace> -o yaml
kubectl get inferencepool <서비스명>-inference-pool -n <사용자 namespace>

spec.router.route.http.spec.rules[].backendRefs에 다음 값이 지정되어 있어야 합니다.

backendRefs:
  - group: inference.networking.k8s.io
    kind: InferencePool
    name: <서비스명>-inference-pool
    port: 8000

KServe Worker Pod가 생성되지 않음​

spec.worker에 initContainers가 추가되었는지 확인합니다. llm-d 라우팅 사이드카는 Decode Leader에만 필요하며 Worker에는 추가하지 않습니다.

Worker Pod가 생성되지 않으면 Volcano Gang이 충족되지 않아 Leader Pod도 Pending 상태에 머물 수 있습니다.

Prefill Deployment 수정 시 field is immutable 오류 발생​

배포 후 LLMInferenceService의 metadata.labels 또는 spec.prefill.labels를 변경하면 Prefill Deployment의 selector 변경으로 오류가 발생할 수 있습니다.

현재 Prefill Deployment 이름을 확인한 후 삭제합니다. KServe 컨트롤러가 새 설정으로 Deployment를 다시 생성합니다.

kubectl get deployment -n <사용자 namespace>
kubectl delete deployment <Prefill Deployment 이름> -n <사용자 namespace>
주의

Deployment를 삭제하면 Prefill 요청 처리가 일시적으로 중단됩니다. 트래픽 영향을 확인한 후 수행하세요.

Gateway 요청이 401 Unauthorized로 거부됨​

  1. 요청의 authorization 헤더를 확인합니다.

  2. API 키 앞에 Bearer 접두어가 포함되어 있는지 확인합니다.

  3. Secret의 key가 클라이언트 식별자이고 value가 실제 API 키인지 확인합니다.

    kubectl get secret <Secret 이름> -n <사용자 namespace>
    kubectl describe securitypolicy <SecurityPolicy 이름> -n <사용자 namespace>

  4. SecurityPolicy의 targetRefs[].name이 사용자 네임스페이스와 같은 Gateway 이름인지 확인합니다.

Gateway 요청이 404 또는 503으로 실패함​

kubectl get gateway,httproute -n <사용자 namespace>
kubectl get backend,aiservicebackend,aigatewayroute -n <사용자 namespace>
kubectl describe httproute <HTTPRoute 이름> -n <사용자 namespace>

다음 항목을 확인합니다.

  • HTTPRoute의 Accepted와 ResolvedRefs 조건이 True인지 확인
  • 호스트명이 Gateway 리스너의 호스트명 패턴에 포함되는지 확인
  • Backend의 FQDN과 포트가 실제 Service와 일치하는지 확인
  • 요청 본문의 model 값이 AIGatewayRoute의 x-ai-eg-model 매칭 값과 일치하는지 확인
  • 서빙 Pod와 Service Endpoint가 준비되었는지 확인

LLM 응답이 중간에 종료됨​

LLM 요청 시간이 Gateway의 기본 타임아웃보다 길 수 있습니다. BackendTrafficPolicy의 타임아웃을 확인합니다.

kubectl get backendtrafficpolicy <BackendTrafficPolicy 이름> -n <사용자 namespace> -o yaml

requestTimeout, streamIdleTimeout, maxStreamDuration이 모델의 최대 응답 시간에 맞게 설정되어 있는지 확인합니다.

추가 지원이 필요한 경우​

문제가 해결되지 않으면 다음 정보를 포함하여 담당 CS 채널로 문의해 주세요.

  • 사용자 네임스페이스
  • 문제가 발생한 리소스 종류와 이름
  • 발생 시각
  • kubectl describe의 Events
  • 관련 Pod 로그
  • Workload, PodGroup, HTTPRoute 또는 LLMInferenceService 상태
주의

문의 내용에 API 키, Secret 원문, 인증 토큰 또는 기타 민감한 정보를 포함하지 마세요.