Docker로 Gemma 3 모델 구축하기: 개발자를 위한 실용적 가이드 (2025)

Docker로 Gemma 3 모델 구축하기: 개발자를 위한 실용적 가이드 (2025)

Google의 Gemma 3 AI 모델을 Docker와 Compose로 설정하는 방법을 배워보세요. 이 가이드는 실제 프로덕션 환경에서 사용할 수 있는 코드와 설정으로 구성되어 있습니다.

⚡ 핵심 요약

• Ollama와 Docker를 통해 로컬 환경에서 강력한 Gemma 3 모델 실행
• 다양한 모델 사이즈(1B~27B) 지원으로 하드웨어에 맞춘 유연한 배포
• 코드 중심의 실행 가이드로 간편한 복사-붙여넣기 지원

📋 모델 크기별 시스템 요구사항

모델 크기 스토리지 요구량 최소 메모리 GPU 필요성 주요 사용 사례

gemma3:1b	815MB	4GB+	선택적	경량 텍스트 생성, 초기 프로토타입
gemma3:4b	3.3GB	8GB+	권장	중간 복잡도 작업, 일반 질의응답
gemma3:12b	8.1GB	16GB+	필수	고급 추론, 전문 영역 분석
gemma3:27b	17GB	32GB+	필수	연구 및 최고 품질 생성 작업

🔧 필수 설치 항목

# Docker 설치 (Ubuntu)
sudo apt-get update
sudo apt-get install docker.io docker-compose -y

# NVIDIA Container Toolkit 설치 (GPU 사용시)
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

📄 Docker Compose 설정 파일

version: '3'
services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_volume:/root/.ollama
    command: serve
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1

  setup:
    image: ollama/ollama
    depends_on:
      - ollama
    entrypoint: [ "sh", "-c" ]
    command: |
      sleep 10
      ollama --host http://ollama:11434 pull gemma3:4b
      ollama --host http://ollama:11434 run gemma3:4b
    volumes:
      - ollama_volume:/root/.ollama

volumes:
  ollama_volume:

위 코드를 docker-compose.yml 파일로 저장하세요. 필요에 따라 gemma3:4b를 다른 모델 크기로 변경할 수 있습니다.

🚀 실행 명령어

# Docker Compose 서비스 시작
docker compose up -d

# 상태 확인
docker ps

# CLI를 통한 모델과 대화
docker exec -it ollama ollama chat gemma3:4b

# API 요청 보내기
curl -X POST -H "Content-Type: application/json" \
     -d '{ "model": "gemma3:4b", "prompt": "안녕하세요, 어떻게 지내세요?" }' \
     http://localhost:11434/completions

🔄 빠른 맞춤 설정

GPU 없이 사용하기

GPU 없이 CPU로만 Gemma 3를 실행하려면, Docker Compose 파일에서 다음 부분을 제거하세요:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1

다른 모델 크기 사용하기

# 1B 모델로 변경 (저사양 시스템용)
sed -i 's/gemma3:4b/gemma3:1b/g' docker-compose.yml

# 더 강력한 12B 모델로 변경 (고성능 시스템용)
sed -i 's/gemma3:4b/gemma3:12b/g' docker-compose.yml

🛠️ 문제 해결 명령어

# 로그 확인
docker compose logs -f

# 모델 다운로드 상태 확인
docker exec -it ollama ollama list

# 리소스 사용량 모니터링
docker stats

# 컨테이너 재시작
docker compose restart

# 완전 초기화 (모든 데이터 삭제)
docker compose down -v

📊 성능 최적화 참고 사항

• GPU 메모리 부족 시 작은 모델 크기로 전환하세요
• 긴 컨텍스트 처리 시 메모리 요구량이 증가합니다
• 모델 첫 실행 시 다운로드에 상당한 시간이 소요될 수 있습니다

📋 API 참조

# 텍스트 생성 요청
curl -X POST -H "Content-Type: application/json" \
     -d '{
       "model": "gemma3:4b",
       "prompt": "Docker란 무엇인가요?",
       "stream": false,
       "max_tokens": 500
     }' http://localhost:11434/completions

# 모델 목록 가져오기
curl http://localhost:11434/models

# 채팅 완성 요청
curl -X POST -H "Content-Type: application/json" \
     -d '{
       "model": "gemma3:4b",
       "messages": [
         {"role": "user", "content": "Docker와 VM의 차이점은?"}
       ]
     }' http://localhost:11434/chat/completions

🔒 보안 강화 설정

# 11434 포트를 로컬에서만 접근 가능하도록 설정
sed -i 's/"11434:11434"/"127.0.0.1:11434:11434"/g' docker-compose.yml

# API 보안 헤더 설정 (프록시 서버 구성 시)
server {
    listen 443 ssl;
    server_name ollama.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:11434;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # API 키 확인 (실제 프로덕션에서는 더 강력한 인증 필요)
        if ($http_x_api_key != "YOUR_SECRET_KEY") {
            return 403;
        }
    }
}

🔍 고급 사용 사례

다중 모델 설정

setup:
  image: ollama/ollama
  depends_on:
    - ollama
  entrypoint: [ "sh", "-c" ]
  command: |
    sleep 10
    ollama --host http://ollama:11434 pull gemma3:4b
    ollama --host http://ollama:11434 pull gemma3:1b
    echo "모든 모델 다운로드 완료"
  volumes:
    - ollama_volume:/root/.ollama

자동화된 프롬프트 처리

#!/bin/bash
# prompt_processor.sh

INPUT_FILE="prompts.txt"
OUTPUT_FILE="responses.json"

echo "[" > $OUTPUT_FILE

while read -r prompt; do
  response=$(curl -s -X POST -H "Content-Type: application/json" \
       -d "{ \"model\": \"gemma3:4b\", \"prompt\": \"$prompt\" }" \
       http://localhost:11434/completions)
  
  echo "  {\"prompt\": \"$prompt\", \"response\": $response}," >> $OUTPUT_FILE
done < "$INPUT_FILE"

# 마지막 쉼표 제거 및 JSON 배열 닫기
sed -i '$ s/,$//' $OUTPUT_FILE
echo "]" >> $OUTPUT_FILE

echo "처리 완료: $OUTPUT_FILE"