Open WebUI 통합

Open WebUI는 로컬 AI 모델을 위한 ChatGPT 같은 경험을 제공하는 오픈소스 자체 호스팅 웹 인터페이스예요. Docker Model Runner에 연결해 모델을 위한 세련된 채팅 인터페이스를 만들 수 있어요.

출처: 문서

본문

사전 요구 사항

TCP 접근이 활성화된 Docker Model Runner
풀된 모델(예: docker model pull ai/llama3.2)

Docker Compose로 빠른 시작

Open WebUI를 Docker Model Runner와 함께 실행하는 가장 쉬운 방법은 Docker Compose를 사용하는 거예요.

compose.yaml 파일을 만들어요:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

서비스를 시작해요:

$ docker compose up -d

브라우저에서 http://localhost:3000을 엽니다.

구성 옵션

환경 변수

변수	설명	기본값
`OLLAMA_BASE_URL`	Docker Model Runner의 URL	필수
`WEBUI_AUTH`	인증 활성화	`true`
`OPENAI_API_BASE_URL`	OpenAI 호환 API 대신 사용	-
`OPENAI_API_KEY`	API 키(DMR에는 아무 값이나 사용)	-

OpenAI 호환 API 사용

Ollama API 대신 OpenAI 호환 API를 사용하려면:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:12434/engines/v1
      - OPENAI_API_KEY=not-needed
      - WEBUI_AUTH=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

네트워크 구성

Docker Desktop

Docker Desktop에서 host.docker.internal은 호스트 머신으로 자동으로 해석돼요. 앞선 예시는 수정 없이 동작해요.

Docker Engine(Linux)

Docker Engine에서는 네트워크를 다르게 구성해야 할 수 있어요:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    network_mode: host
    environment:
      - OLLAMA_BASE_URL=http://localhost:12434
      - WEBUI_AUTH=false
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

또는 호스트 게이트웨이를 사용해요:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://172.17.0.1:12434
      - WEBUI_AUTH=false
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

Open WebUI 사용

모델 선택

http://localhost:3000을 엽니다.
왼쪽 상단의 모델 드롭다운을 선택합니다.
풀한 모델 중에서 선택합니다(ai/ 접두사로 나타나요).

UI로 모델 풀

Open WebUI는 모델을 직접 풀할 수 있어요:

모델 드롭다운을 선택합니다.
모델 이름을 입력합니다: ai/llama3.2
다운로드 아이콘을 선택합니다.

채팅 기능

Open WebUI는 다음을 제공해요:

컨텍스트가 있는 다중 턴 대화
메시지 편집과 재생성
코드 구문 하이라이팅
마크다운 렌더링
대화 기록과 검색
대화 내보내기

여러 모델을 사용한 완전한 예시

이 예시는 Docker Model Runner로 Open WebUI를 설정하고 여러 모델을 미리 풀합니다:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=false
      - DEFAULT_MODELS=ai/llama3.2
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      model-setup:
        condition: service_completed_successfully
  model-setup:
    image: docker:cli
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: >
      sh -c "
      docker model pull ai/llama3.2 &&
      docker model pull ai/qwen2.5-coder &&
      docker model pull ai/smollm2
      "
volumes:
  open-webui:

인증 활성화

다중 사용자 설정이나 보안을 위해 인증을 활성화하세요:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=true
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

첫 방문 시 관리자 계정을 만들게 돼요.

문제 해결

모델이 드롭다운에 나타나지 않음

Docker Model Runner에 접근할 수 있는지 확인해요:

$ curl http://localhost:12434/api/tags

모델이 풀되었는지 확인해요:

$ docker model list

OLLAMA_BASE_URL이 올바르고 컨테이너에서 접근 가능한지 확인해요.

"Connection refused" 오류

Docker Model Runner에 TCP 접근이 활성화되어 있는지 확인해요.

Docker Desktop에서 host.docker.internal이 해석되는지 확인해요:

$ docker run --rm alpine ping -c 1 host.docker.internal

Docker Engine에서는 network_mode: host나 명시적 호스트 IP를 사용해 보세요.

느린 응답 시간

첫 요청은 모델을 메모리에 로드하기 때문에 시간이 걸려요. 이후 요청은 훨씬 빠릅니다.

계속 느리다면 다음을 고려해요:

더 작은 모델 사용
컨텍스트 크기 줄이기
GPU 가속이 동작하는지 확인

CORS 오류

다른 호스트에서 Open WebUI를 실행한다면:

Docker Desktop에서 Settings > AI로 이동
CORS Allowed Origins에 Open WebUI URL을 추가

맞춤화

커스텀 시스템 프롬프트

Open WebUI는 모델별 시스템 프롬프트 설정을 지원해요. UI의 Settings > Models에서 구성하세요.

모델 파라미터

채팅 인터페이스에서 모델 파라미터를 조정해요:

모델 이름 옆의 설정 아이콘을 선택합니다.
온도, top-p, 최대 토큰 등을 조정합니다.
이 설정들은 Docker Model Runner로 전달돼요.

다른 포트에서 실행

다른 포트에서 Open WebUI를 실행하려면:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "8080:8080" # Change first port number
    # ... rest of config

다음 단계

API 레퍼런스 — Open WebUI가 사용하는 API 알아보기
구성 옵션 — 모델 동작 조정
IDE 통합 — 다른 도구를 DMR에 연결

Open WebUI 통합