Docker Compose로 OpenWebUI에서 Gemma 3 모델 구축하기: 단계별 완벽 가이드

Docker Compose로 OpenWebUI에서 Gemma 3 모델 구축하기: 단계별 완벽 가이드

안녕하세요! 오늘은 Docker Compose를 활용하여 OpenWebUI에서 Ollama로 Gemma 3 모델을 설정하고 사용하는 방법에 대해 알아보겠습니다. Google DeepMind의 Gemma 3 모델을 로컬 환경에서 쉽게 실행할 수 있는 방법을 단계별로 안내해 드리겠습니다.

Gemma 3와 OpenWebUI란?

Gemma 3는 Google DeepMind에서 개발한 경량 멀티모달 모델로, 텍스트와 이미지를 모두 처리할 수 있습니다. 128K 컨텍스트 윈도우를 지원하며 140개 이상의 언어를 처리할 수 있는 강력한 AI 모델입니다.

OpenWebUI는 오프라인에서 작동하는 사용자 친화적인 AI 플랫폼으로, Ollama와 같은 다양한 LLM 러너를 지원합니다. 직관적인 인터페이스를 제공하여 AI 모델과 쉽게 상호작용할 수 있습니다.

Ollama는 로컬 환경에서 대형 언어 모델(LLM)을 실행할 수 있게 해주는 오픈소스 도구로, Gemma 3와 같은 다양한 모델을 지원합니다.

준비 사항

시작하기 전에 필요한 것들은 다음과 같습니다:

1. Docker와 Docker Compose 설치
   • Docker 공식 문서
   • Docker Compose 공식 문서
2. 하드웨어 요구 사항
   • Gemma 3 모델 크기에 따라 다름 (아래 표 참조)
   • 충분한 디스크 공간 (모델 크기에 따라 수 GB 필요)

Gemma 3 모델 종류

다음은 Gemma 3의 다양한 모델 크기와 특징에 대한 표입니다:

모델 유형 파라미터 크기 컨텍스트 윈도우 태그

텍스트	1B	32k	gemma3:1b
멀티모달(비전)	4B	128k	gemma3:4b
멀티모달(비전)	12B	128k	gemma3:12b
멀티모달(비전)	27B	128k	gemma3:27b

단계별 설치 가이드

1. 프로젝트 디렉토리 설정

먼저 새 디렉토리를 만들고 해당 디렉토리로 이동합니다:

mkdir openwebui-ollama
cd openwebui-ollama

2. docker-compose.yaml 파일 생성

프로젝트 디렉토리 안에 docker-compose.yaml 파일을 생성하고 다음 내용을 복사하세요:

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama_data:/root/.ollama
    restart: unless-stopped
  
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    volumes:
      - openwebui_data:/app/backend/data
    ports:
      - 3000:8080
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama
    restart: unless-stopped

volumes:
  ollama_data:
  openwebui_data:

이 구성에서:

• ollama 서비스는 Ollama의 최신 이미지를 사용하고, 모델 데이터를 영구적으로 저장하기 위한 볼륨을 설정합니다.
• open-webui 서비스는 OpenWebUI의 메인 이미지를 사용하고, 포트 3000을 통해 접근할 수 있도록 설정합니다.
• 두 서비스 모두 컨테이너가 재시작되어도 데이터가 유지되도록 볼륨을 사용합니다.

3. 컨테이너 시작

프로젝트 디렉토리에서 다음 명령어를 실행하여 컨테이너를 시작합니다:

docker compose up -d

-d 옵션은 컨테이너를 백그라운드에서 실행합니다. 로그를 확인하고 싶다면 docker compose logs -f 명령어를 사용하세요.

4. Gemma 3 모델 다운로드

시스템 자원에 맞는 Gemma 3 모델을 선택합니다. 예를 들어, 4B 모델을 다운로드하려면:

docker exec -it ollama ollama pull gemma3:4b

다운로드 시간은 모델 크기와 인터넷 속도에 따라 달라질 수 있습니다. 작은 모델(1B)은 더 빠르게 다운로드되지만 성능이 제한적일 수 있고, 큰 모델(27B)은 더 좋은 성능을 제공하지만 강력한 하드웨어가 필요합니다.

5. OpenWebUI 접근하기

브라우저에서 http://localhost:3000으로 이동하여 OpenWebUI에 접속합니다.

첫 접속 시 계정을 생성해야 합니다. 최초 생성한 계정은 자동으로 관리자 권한을 가집니다.

6. 모델 선택 및 사용 시작

로그인 후 채팅 인터페이스에서 모델 선택 드롭다운 메뉴를 클릭하고 다운로드한 Gemma 3 모델(예: gemma3:4b)을 선택합니다.

이제 채팅 창에 메시지를 입력하여 Gemma 3 모델과 상호작용할 수 있습니다!

시스템 구성 다이어그램

추가 관리 및 팁

컨테이너 관리

• 컨테이너 중지하기:
• docker compose down
• 로그 확인하기:
• docker compose logs -f
• 최신 이미지로 업데이트하기:
• docker compose pull docker compose up -d

모델 선택 팁

1. 하드웨어에 맞는 모델 선택:
   • 1B 모델: 최소 8GB RAM, CPU에서도 실행 가능
   • 4B 모델: 최소 16GB RAM 권장
   • 12B 모델: 최소 24GB RAM과 GPU 권장
   • 27B 모델: 32GB 이상 RAM과 강력한 GPU 필요
2. 다른 모델 탐색: OpenWebUI에서 다른 모델도 쉽게 다운로드하고 사용할 수 있습니다.

문제 해결

• 컨테이너가 시작되지 않는 경우: Docker 로그를 확인하여 오류 메시지를 확인하세요.
• 모델이 로드되지 않는 경우: 시스템 사양이 모델 요구 사항을 충족하는지 확인하세요.
• OpenWebUI에 모델이 표시되지 않는 경우: Ollama 컨테이너가 정상적으로 실행 중인지 확인하세요.

정리

Docker Compose를 사용하여 OpenWebUI와 Ollama로 Gemma 3 모델을 설정하는 방법을 알아보았습니다. 이 방법을 통해 로컬 환경에서 강력한 AI 모델을 쉽게 실행하고 사용할 수 있습니다. 시스템 사양에 맞는 모델 크기를 선택하여 최적의 경험을 누리세요!

이 설정은 개인 프로젝트, 연구, 또는 AI 기능을 탐색하는데 유용하게 활용할 수 있습니다. Docker를 사용하기 때문에 환경 설정이 간편하고, 다른 시스템으로 쉽게 이전할 수 있습니다.

질문이나 문제가 있으시면 언제든지 댓글로 남겨주세요. 행복한 AI 여정이 되길 바랍니다!

참고 자료

• OpenWebUI 공식 문서
• Ollama 공식 블로그
• Gemma 3 모델 라이브러리
• Docker 공식 문서
• Docker Compose 공식 문서