서빙 스택 설치(Helm 차트)¶

목표: Helm으로 전체 스택(게이트웨이, llm-d 라우터의 Endpoint Picker(EPP), modelserver)을 레퍼런스 구성으로 설치하고 최초 추론 응답을 받습니다.

차트 준비 및 기본 구성¶

coding-assistant-stack 차트를 다운로드하고 --untar로 차트의 압축을 푸세요. 이 문서의 설치 명령은 압축을 푼 디렉터리를 사용합니다. 압축을 푼 디렉터리에는 차트의 values.yaml, 포함된 예제(examples/), 스크립트(scripts/)도 있습니다.

1
2
3
4

helm registry login repo.rebellions.ai    # 차트를 다운로드하려면 인증 정보가 필요합니다.
helm pull oci://repo.rebellions.ai/rebellions/coding-assistant-stack --version <CHART_VERSION> --untar

# 다운로드 위치: ./coding-assistant-stack/ (values.yaml, examples/, scripts/)

차트와 modelserver 이미지는 repo.rebellions.ai에 있으며, 둘 다 인증 정보가 필요합니다. 차트를 다운로드하려면 helm registry login으로 로그인하세요. 노드가 modelserver 이미지를 가져올 때 쓰는 Image Pull Secret을 생성하세요(Secret 및 모델 저장소 참고).

라우팅 사이드카 이미지와 EPP 이미지는 공개 레지스트리 ghcr.io/llm-d에 있으므로 인증 정보가 필요하지 않습니다. modelserver 이미지를 자체 레지스트리에서 가져오려면 modelserver.image.repository를 그 레지스트리의 repository로 설정하세요.

차트 기본값이 레퍼런스 구성입니다. 차트 기본값으로 설치하면 스택은 MiniMax-M2.7을 4P4D로 서빙합니다. 4P4D는 prefill Pod 4개와 decode Pod 4개이며, 각 Pod는 RCT npu-rdma가 요청하는 NPU 4개를 할당받습니다. 다른 모델을 서빙하려면 차트의 examples/models/README.md에 나열된 레시피 파일을 사용하세요(주요 구성 변경 참고).

다음 values를 values-env.yaml로 저장하세요. values-env.yaml의 각 값은 클러스터의 객체 이름을 가리키므로 차트 기본값에 들어 있지 않습니다.

1
2
3
4
5
6
7
8

storage:
  model:
    kind: existingClaim
    existingClaim: <pvc-name>          # 모델 가중치가 있는 PVC
  compileCache:
    storageClass: <storage-class>      # ReadWriteMany를 지원하는 StorageClass. 비워 두면 클러스터의 기본 StorageClass를 사용합니다.
imagePullSecrets:
  - <pull-secret-name>                 # modelserver 이미지용 Image Pull Secret

최초 설치 전에 다음 차트 기본값을 확인하세요.

• 차트는 컴파일 캐시 PVC를 accessModes: ["ReadWriteMany"]로 생성합니다. prefill Pod 4개가 PVC 하나를, decode Pod 4개가 다른 PVC 하나를 함께 마운트하기 때문입니다. ReadWriteMany를 지원하는 StorageClass를 선택하세요(PVC 구성, 용량 및 accessModes 참고).
• storage.compileCache.size의 기본값은 200Gi입니다. PVC는 축소할 수 없으므로 storage.compileCache.size는 최초 설치 전에 결정하세요.
• modelserver.resources는 Pod마다 CPU 40개와 메모리 630Gi를 요청합니다. 리소스 및 노드 예산에서 노드 용량이 modelserver.resources를 충족하는지 확인하세요.

EPP를 차트 외부에 설치했다면 eppServiceName을 그 EPP의 Service 이름으로 설정하세요.

사전 점검¶

설치 전에 다음 항목을 확인하세요.

설치 절차¶

Helm 릴리스 이름(<release-name>)은 사용자가 정합니다. Helm 릴리스 이름은 차트가 Istio Gateway를 생성할 때(기본값) 최대 39자이고, 그 밖의 경우 최대 40자입니다.

1
2
3
4
5
6
7
8
9

# 1) 최초 설치: 1P1D로 컴파일 캐시를 채웁니다.
helm install <release-name> ./coding-assistant-stack -n <ns> \
  --set modelserver.replicas.prefill=1 --set modelserver.replicas.decode=1 \
  -f values-env.yaml

# 2) Pod가 Ready 상태가 되면 values-env.yaml을 다시 전달해 4P4D로 확장합니다.
helm upgrade <release-name> ./coding-assistant-stack -n <ns> \
  --set modelserver.replicas.prefill=4 --set modelserver.replicas.decode=4 \
  -f values-env.yaml

최초 설치에서는 컴파일 때문에 Ready가 늦어집니다(최초 시작 시간 참고).

이후 helm upgrade를 실행할 때마다 설치 시 지정한 values를 다시 전달하세요. values를 다시 전달하는 규칙은 확장 및 업그레이드 › 업그레이드, 롤백 및 제거를 참고하세요.

특정 노드에 Pod를 배치하려면 modelserver.replicas 대신 modelserver.nodePlacement를 사용하세요(주요 차트 설정 참고).

최초 추론¶

modelserver Pod가 실행 중인지, Istio가 게이트웨이 Service를 생성했는지 확인합니다. 그다음 게이트웨이 Service로 최초 추론 요청을 보냅니다.

1
2

kubectl -n <ns> get pods -l 'llm-d.ai/role'             # Pod가 5분 이상 Pending이면 장애 대응 › 증상별 진단을 참고합니다.
kubectl -n <ns> get svc <release-name>-inference-gateway-istio   # Istio가 이 Service를 생성합니다.

1
2
3
4

# <gateway-address>: 게이트웨이 Service의 EXTERNAL-IP 또는 클러스터 내부에서 사용할 ClusterIP
# <model>: modelserver.model 값. 차트 기본값은 MiniMaxAI/MiniMax-M2.7입니다.
curl http://<gateway-address>/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"<model>","max_tokens":32,"messages":[{"role":"user","content":"Say hello."}]}'

응답에 choices 필드가 있으면 설치가 완료된 것입니다. Pod가 Pending 상태로 남거나 요청이 오류를 반환하면 장애 대응 › 증상별 진단을 참고하세요.

다음 단계¶

최초 추론이 성공하면 다음 문서를 참고하세요.

• 운영
• 장애 대응