drama-studio/.claude/skills/gpu-local-models.md

GPU 로컬 모델 인프라 (GPU Local Models)

로컬 LLM/ML 모델 서빙을 위한 GPU 인프라 가이드입니다.

GPU 인벤토리

GPU	VRAM	수량	용도
NVIDIA V100	16GB	8	중형 모델, 병렬 추론
NVIDIA V100	32GB	4	대형 모델, 파인튜닝
NVIDIA RTX 3090	24GB	2	개발/테스트, 중형 모델

총 VRAM: 16×8 + 32×4 + 24×2 = 128 + 128 + 48 = 304GB

VRAM별 모델 가이드

16GB (V100 16GB, 단일)

• Llama 3.1 8B (Q4 양자화)
• Mistral 7B
• Phi-3 Medium
• Gemma 2 9B

24GB (RTX 3090)

• Llama 3.1 8B (FP16)
• Qwen2.5 14B (Q4)
• CodeLlama 13B

32GB (V100 32GB, 단일)

• Llama 3.1 70B (Q4 양자화)
• Qwen2.5 32B
• DeepSeek Coder 33B

멀티 GPU (텐서 병렬)

• V100 32GB × 2 (64GB): Llama 3.1 70B (FP16)
• V100 32GB × 4 (128GB): Llama 3.1 70B + 여유 / 대형 모델
• V100 16GB × 8 (128GB): 대규모 배치 추론

모델 서빙 프레임워크

vLLM (권장)

# Docker 실행
docker run --gpus all -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --tensor-parallel-size 1

Text Generation Inference (TGI)

docker run --gpus all -p 8080:80 \
  -v ~/.cache/huggingface:/data \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id meta-llama/Llama-3.1-8B-Instruct

Ollama (개발/테스트용)

# 설치
curl -fsSL https://ollama.com/install.sh | sh

# 모델 실행
ollama run llama3.1:8b

Docker Compose GPU 패턴

단일 GPU 서비스

services:
  llm-server:
    image: vllm/vllm-openai:latest
    container_name: {프로젝트}-llm
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    command: >
      --model meta-llama/Llama-3.1-8B-Instruct
      --max-model-len 8192
    networks:
      - {프로젝트}-network

멀티 GPU 텐서 병렬

services:
  llm-large:
    image: vllm/vllm-openai:latest
    container_name: {프로젝트}-llm-large
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 4
              capabilities: [gpu]
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
      - CUDA_VISIBLE_DEVICES=0,1,2,3
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8001:8000"
    command: >
      --model meta-llama/Llama-3.1-70B-Instruct
      --tensor-parallel-size 4
      --max-model-len 4096
    networks:
      - {프로젝트}-network

특정 GPU 지정

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          device_ids: ['0', '1']  # GPU 0, 1 지정
          capabilities: [gpu]

API 통합 패턴

OpenAI 호환 클라이언트 (vLLM)

from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="http://llm-server:8000/v1",
    api_key="not-needed"  # 로컬은 API 키 불필요
)

response = await client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": prompt}],
    max_tokens=2048,
    temperature=0.7
)

로컬/원격 전환 패턴

import os
from openai import AsyncOpenAI

def get_llm_client():
    """환경에 따라 로컬 또는 원격 LLM 클라이언트 반환"""
    if os.getenv("USE_LOCAL_LLM", "false").lower() == "true":
        return AsyncOpenAI(
            base_url=os.getenv("LOCAL_LLM_URL", "http://llm-server:8000/v1"),
            api_key="not-needed"
        )
    else:
        return AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))

환경 변수

# .env 추가 항목
HF_TOKEN=hf_...                          # Hugging Face 토큰
USE_LOCAL_LLM=true                       # 로컬 LLM 사용 여부
LOCAL_LLM_URL=http://llm-server:8000/v1  # 로컬 LLM 엔드포인트
LOCAL_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct

GPU 모니터링

nvidia-smi

# 실시간 모니터링
watch -n 1 nvidia-smi

# 특정 정보만
nvidia-smi --query-gpu=index,name,memory.used,memory.total,utilization.gpu --format=csv

Docker 내부에서

docker exec {컨테이너명} nvidia-smi

헬스체크

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 30s
  retries: 3
  start_period: 120s  # 모델 로딩 시간 고려

주의사항

• 모델 첫 로딩 시 시간 소요 (수 분)
• VRAM 부족 시 OOM 에러 → 양자화 또는 GPU 추가
• Hugging Face 게이트 모델은 토큰 및 동의 필요
• 멀티 GPU 사용 시 NVLink 유무에 따라 성능 차이