콘텐츠로 이동

LLM 배포 가이드

이 튜토리얼에서 무엇을 배우나요?

이 튜토리얼은 vllm을 사용하여 LLM을 Kubernetes 클러스터에 서빙하는 실습입니다.

작업을 위해 ML Platform 클러스터의 적절한 Kubernetes 권한이 필요합니다.

튜토리얼을 마치면 아래 경험을 직접 해볼 수 있습니다:

  • PVC에 모델 weight 파일을 준비하는 방법
  • vllm 기반 Deployment YAML을 구성하는 방법
  • Service와 VirtualService로 외부 접근을 설정하는 방법
  • 모델별로 달라지는 실행 인자(args)를 조정하는 방법
시작 전 확인 — 이런 경험이 있어야 합니다
  • Kubernetes 기본 개념: Pod, Deployment, Service, Namespace의 역할을 이해하고 있어야 합니다.
  • kubectl 사용: kubectl apply, kubectl get, kubectl logs 명령을 직접 실행할 수 있어야 합니다.
  • YAML 작성: Kubernetes 리소스 정의 파일을 읽고 수정할 수 있어야 합니다.
  • kubeconfig: 클러스터 접근을 위한 kubeconfig 파일을 발급받고 설정할 수 있어야 합니다.
  • GPU/LLM 기초: 모델 weight, tensor parallelism, GPU 메모리 등의 개념을 기본적으로 알고 있어야 합니다.

위 항목이 낯설다면 Kubernetes 공식 튜토리얼 및 kubectl 기초 학습 후 진행하는 것을 권장합니다.

용어 알아보기
  • vllm: LLM 추론 서빙에 최적화된 오픈소스 라이브러리입니다. OpenAI 호환 API를 제공합니다.
  • PVC (Persistent Volume Claim): Kubernetes에서 영구 저장소를 요청하는 단위. 컨테이너가 재시작되어도 데이터가 유지됩니다. 모델 weight 파일을 저장하는 데 사용합니다.
  • Deployment: Kubernetes에서 Pod 실행을 선언하는 리소스. 몇 개의 Pod를 어떤 이미지로 실행할지, 어떤 자원을 사용할지 정의합니다.
  • Service: Kubernetes 내부에서 Pod에 접근할 수 있는 고정된 주소를 제공하는 리소스입니다.
  • VirtualService: Istio 기반 트래픽 라우팅 규칙. 외부에서 특정 호스트명으로 들어오는 요청을 내부 Service로 연결합니다.
  • tensor-parallel-size: 하나의 모델을 여러 GPU에 분산해서 실행할 때 사용하는 GPU 수를 지정하는 vllm 인자입니다.

이 튜토리얼에서 사용하는 도구

도구 사용자 접근 방식 이 튜토리얼에서의 역할
kubectl 터미널 Kubernetes 리소스 배포 및 상태 확인
vllm Deployment 컨테이너 이미지 LLM 추론 서버 실행
Istio VirtualService YAML 파일 작성 외부 URL로 모델 API 노출

Runway에서 LLM 서빙이 동작하는 방식

모델 파일을 PVC에 준비한 뒤, Deployment로 vllm 서버를 실행하고 Service와 VirtualService로 외부에 노출합니다.

flowchart LR
    subgraph storage["스토리지"]
        PVC["PVC\n모델 weight 파일"]
    end

    subgraph k8s["Kubernetes (llm 네임스페이스)"]
        DEP["Deployment\nvllm 서버 실행"]
        SVC["Service\n클러스터 내부 접근"]
        VS["VirtualService\n외부 URL 라우팅"]
    end

    PVC -->|"볼륨 마운트"| DEP
    DEP --> SVC
    SVC --> VS
    VS -->|"호스트명으로 접근"| USER["사용자"]

왜 3개의 리소스가 필요한가요?

Deployment — 모델을 실행한다

vllm 서버를 컨테이너로 실행합니다. 어떤 모델을 어떤 GPU 설정으로 실행할지, PVC에서 모델 파일을 어디서 읽을지 지정합니다.

Service — 클러스터 안에서 접근 가능하게 한다

Deployment의 Pod IP는 재시작마다 바뀝니다. Service가 고정된 내부 주소를 제공해서 다른 리소스가 안정적으로 접근할 수 있게 합니다.

VirtualService — 외부에서 접근 가능하게 한다

Istio 게이트웨이를 통해 외부 호스트명으로 들어오는 요청을 Service로 연결합니다. 모델마다 고유한 URL을 부여합니다.

리소스 이름 중복 주의

동일한 네임스페이스에 동일한 이름으로 kubectl apply하면 기존 리소스가 업데이트됩니다. 별도의 네임스페이스를 생성하거나 이름을 변경하여 배포하세요.

전체 흐름

flowchart TD
    A["시작 전 준비\nkubeconfig 확인 · kubectl 설치"]
    B["1단계. 사전 준비\nPVC 확인 · 모델 weight 파일 업로드"]
    C["2단계. 리소스 배포\nDeployment · Service · VirtualService 배포"]

    A --> B --> C