Kubernetes에서 구축하는 첫 번째 LLM API
Kubernetes에서 LLM을 실행하는 것은 일반적인 웹 앱을 실행하는 것과는 다릅니다. 단순히 요청 수에 따라 스케일링하는 것이 아니라, GPU 용량과 모델 가중치(weights)를 기준으로 스케일링해야 합니다.
이 가이드에서는 모델을 GPU 노드에 배포하고, 이를 API로 노출한 뒤, curl 요청을 통해 호출하는 과정을 다룹니다.
다음 도구들을 사용합니다:
- 모델: Qwen/Qwen2.5-1.5B-Instruct
- 엔진: vLLM
- 인프라: NVIDIA GPU 지원 기능이 포함된 Kubernetes
1단계: GPU 용량 확인
시작하기 전에 Kubernetes가 하드웨어를 인식하고 있는지 확인하세요. 다음 명령어를 실행합니다:
kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\.com/gpu
만약 GPU 컬럼이 비어 있다면 중단하세요. 먼저 NVIDIA device plugin을 해결해야 합니다.
2단계: 모델 액세스 보안 설정
공개 모델이라 하더라도 Hugging Face 토큰을 사용하세요. 이렇게 하면 나중에 프라이빗 모델로 교체하기가 더 쉬워집니다.
- 네임스페이스 생성:
kubectl create namespace llm-demo - 토큰을 위한 Secret 생성:
kubectl create secret generic hf-token -n llm-demo --from-literal=HF_TOKEN="your_token_here"
3단계: 모델 서버 배포
vLLM은 복잡한 작업을 대신 처리해주기 때문에 사용합니다. vLLM은 배칭(batching), 토큰화(tokenization), 그리고 OpenAI 호환 API를 관리합니다.
다음의 주요 요구 사항을 포함하여 deployment 파일을 생성합니다:
- GPU 1개 요청:
nvidia.com/gpu: 1 /dev/shm마운트: 모델 서버가 충돌하는 것을 방지하려면 공유 메모리(shared memory)가 필요합니다.- Secret 사용:
HF_TOKEN을 컨테이너로 전달합니다.
설정을 적용합니다:
kubectl apply -f qwen-vllm.yaml
4단계: API 검증
"Running" 상태만 믿지 마세요. Pod가 "Running" 상태이더라도 거대한 모델 파일을 다운로드 중일 수 있습니다. 로그를 확인하세요:
kubectl logs -n llm-demo -f deployment/qwen-vllm
서버가 8000번 포트에서 리스닝(listening) 상태가 될 때까지 기다립니다.
포트 포워딩으로 테스트합니다:
kubectl port-forward -n llm-demo svc/qwen-vllm 8000:8000
curl 요청을 실행합니다:
curl http://127.0.0.1:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [{"role": "user", "content": "Explain Kubernetes in two sentences."}],
"max_tokens": 120
}'
목표 달성:
이제 단순한 GPU 용량 확보를 넘어 실제로 작동하는 API를 구축했습니다. 다음 사항들을 증명한 것입니다:
- Kubernetes가 GPU 워크로드를 스케줄링함.
- 컨테이너가 하드웨어에 액세스할 수 있음.
- 모델 서버가 가중치를 메모리에 로드함.
- API가 표준 요청에 응답함.
만약 이 과정이 실패한다면, 스케일링이나 라우팅을 아무리 잘해도 소용이 없습니다. 먼저 기초를 다지세요.
선택 사항 학습 커뮤니티: https://t.me/GyaanSetuAi