MOMIN09Platform & DevOps

로컬 GPU 기반 AI Platform 구축

1 item

4 min read

프로젝트 개요

이 프로젝트는 WSL2와 NVIDIA GeForce RTX 4090을 기반으로 로컬 AI inference 환경을 구축하고, 단일 Docker container에서 시작한 Gemma 4 serving을 Kubernetes 기반 AI Platform으로 확장하는 과정이다.

단순히 model API를 실행하는 데서 끝내지 않고 GPU scheduling, model cache 영속화, Service 접근, OpenAI-compatible API 검증, metrics 수집까지 단계적으로 확인한다. 각 단계에서 발생한 실패 원인과 복구 과정을 함께 기록해 같은 환경을 다시 구성할 수 있는 실행 근거를 남기는 것이 목적이다.

시작 배경

GPU container 하나를 실행하는 것과 여러 AI workload를 안정적으로 운영하는 platform을 만드는 것은 다른 문제다. model architecture와 serving argument, GPU runtime, container port, Kubernetes resource, storage, network 경계를 각각 이해해야 이후 model 교체, 관측, benchmark, 운영 자동화로 확장할 수 있다.

따라서 다음 순서로 범위를 넓혔다.

WSL2 GPU 환경
  → Docker에서 Gemma 4와 vLLM 검증
  → k3s cluster 구성과 GPU resource 노출
  → Kubernetes Deployment·PVC·Service 구성
  → OpenAI-compatible API와 vLLM metrics 검증
  → 관측과 benchmark 환경으로 확장

구축 목표

영역목표
model servingGemma 4 12B Q4 checkpoint를 vLLM으로 실행
GPU runtimeRTX 4090을 Docker와 Kubernetes workload에 할당
orchestrationk3s에서 Pod, PVC, Service lifecycle 관리
persistencemodel cache를 40Gi PVC에 유지
API/v1/models, /v1/chat/completions 검증
observabilityvLLM metrics를 확인하고 Prometheus·Grafana·DCGM Exporter로 확장

실행 환경

구성 요소사용 환경
hostWindows + WSL2
GPUNVIDIA GeForce RTX 4090 24GB
containerDocker 29.6.1 + NVIDIA runtime
Kubernetessingle-node k3s
serving enginevLLM 0.24.0
modelgoogle/gemma-4-12B-it-qat-w4a16-ct
served modelgemma-4-12b-q4

문서 구성

순서문서내용
1Docker Gemma 4 12B 트러블슈팅Docker에서 Gemma 4와 vLLM serving 기반 검증
2k3s 설치 트러블슈팅WSL2에서 k3s cluster 구축과 운영 기반 구성
2-1Kind GPU 검토대안 Kubernetes 환경의 GPU 실험 범위를 검토한 선택 단계
3Kubernetes Gemma 4 GPU 서빙Kubernetes GPU workload와 AI inference API serving 검증
4관측과 기준 벤치마크Prometheus, Grafana, DCGM Exporter 기반 metrics 수집과 기준 성능 검증

현재 프로젝트 구성

현재 문서는 Docker 단일 container serving 검증, k3s cluster 구성, 선택적인 Kind GPU 경로 검토, Kubernetes GPU serving, 관측과 benchmark의 다섯 단계 문서로 구성된다. 세부 트러블슈팅과 검증 결과는 각 단계 문서에서 관리한다.

향후 프로젝트 구조에 새로운 platform 확장 단계가 추가되면 이 소개글의 전체 흐름과 문서 구성도 함께 갱신한다.

그래프 뷰