AI 튜토리얼

셀프 호스팅 AI용 Open WebUI 설치 및 사용

pip 또는 Docker로 Open WebUI를 설치하고, Ollama 또는 OpenAI 호환 API를 연결해 모델과 대화를 시작하는 방법을 알아보세요. 이 튜토리얼에서는 문서 검색, 웹 콘텐츠, 다중 모델 대화, 오프라인 작동, GPU 가속, 문제 해결 및 프로덕션 지향 기능도 소개합니다.

2026년 8월 20일약 14분 소요

Open WebUI란?

Open WebUI는 로컬 리소스로 구성하면 완전히 오프라인에서 작동하도록 설계된 확장 가능하고 자체 호스팅되는 AI 플랫폼입니다. 브라우저 기반 인터페이스를 통해 로컬 Ollama 모델과 OpenAI 호환 API를 사용할 수 있으며, 일반적으로 RAG라고 하는 검색 증강 생성(retrieval-augmented generation)을 위한 내장 추론 엔진도 제공합니다.

개인용 AI 작업 공간으로 사용하거나 팀을 위해 배포할 수 있습니다. 대화 기능 외에도 메모, 공유 채널, 영구 메모리, 캘린더, 예약 자동화, 이미지 생성 통합, 음성 및 영상 통화, 분석, 모델 평가, 세분화된 액세스 제어 기능을 제공합니다.

주요 기능

유연한 모델 연결: LMStudio, GroqCloud, Mistral, OpenRouter, vLLM과 같은 OpenAI 호환 서비스와 로컬 Ollama 모델을 함께 사용할 수 있습니다.
로컬 RAG: 채팅에 문서를 추가하거나 # 명령으로 지식 라이브러리에서 파일을 검색할 수 있습니다. 하이브리드 검색, 재순위화, 여러 추출 엔진, 9개의 벡터 데이터베이스를 지원합니다.
모델 및 에이전트: 사용자 지정 지침, 지식, 도구, 동적 변수, 사용자 또는 그룹 액세스 규칙으로 기본 모델을 확장할 수 있습니다.
확장성: Filters, Actions, Pipes, Tools, Skills를 추가하거나 MCP, MCPO, OpenAPI 도구 서버에 연결할 수 있습니다.
협업: 메모, 실시간 채널, 스레드, 반응, 고정, 공유 캘린더, AI 지원 일정 관리를 사용할 수 있습니다.
다중 모달: 음성-텍스트 변환, 텍스트-음성 변환, 음성 및 영상 통화, 이미지 생성 또는 편집 엔진을 구성할 수 있습니다.
관리: 역할, 그룹, 권한, 인증, 사용량 분석, 모델 평가, 저장소, 관측 가능성을 관리할 수 있습니다.
유연한 배포: pip, uv, Docker, Docker Compose, Kubernetes, Kustomize 또는 Helm을 통해 설치할 수 있습니다.
반응형 인터페이스: 데스크톱과 모바일에서 Open WebUI를 사용하거나 프로그레시브 웹 앱으로 설치할 수 있습니다.

설치 방법 선택

빠르게 로컬에서 테스트하려면 pip 또는 Docker를 사용하세요. Pip은 Python에서 직접 Open WebUI를 제공하고, Docker는 격리된 배포 환경을 제공하며 표준 이미지, CUDA 지원 이미지 또는 Ollama가 포함된 이미지를 쉽게 선택할 수 있게 해줍니다.

중요: 모든 Docker 명령은 open-webui:/app/backend/data를 마운트해야 합니다. 이 영구 볼륨은 컨테이너를 교체하거나 제거할 때 데이터베이스와 기타 애플리케이션 데이터를 보호합니다.

옵션 1: Python pip로 설치

프로젝트에서 설명하는 pip 설치에는 Python 3.11이 필요합니다. 진행하기 전에 환경에서 올바른 Python 버전을 사용하는지 확인하세요.

패키지를 설치합니다.
```
pip install open-webui
```
서버를 시작합니다.
```
open-webui serve
```
브라우저에서 http://localhost:8080을 엽니다.

옵션 2: Docker로 Open WebUI 실행

호스트 컴퓨터의 Ollama에 연결

Docker와 같은 컴퓨터에서 Ollama가 이미 실행 중이라면 표준 Open WebUI 이미지를 시작하고 호스트 매핑을 추가하여 컨테이너가 호스트에 연결할 수 있도록 하세요.

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

컨테이너가 시작되면 http://localhost:3000을 방문하세요.

다른 서버의 Ollama에 연결

OLLAMA_BASE_URL을 원격 Ollama 서비스의 주소로 설정합니다.

docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

https://example.com을 실제 Ollama 서버 URL로 바꾸세요.

Nvidia GPU 지원 활성화

Open WebUI는 CUDA 태그가 지정된 이미지를 제공합니다. 실행하기 전에 Linux 또는 WSL에 Nvidia CUDA 컨테이너 툴킷을 설치하세요.

docker run -d -p 3000:8080 --gpus all --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda

OpenAI API만 사용

Ollama가 필요하지 않다면 OpenAI API 키를 표준 이미지에 전달하세요.

docker run -d -p 3000:8080 -e OPENAI_API_KEY=your_secret_key -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

your_secret_key를 적절한 인증 정보로 바꾸세요. Open WebUI는 다른 OpenAI 호환 API에도 연결할 수 있으며, 제공업체별 구성은 프로젝트 문서에 설명되어 있습니다.

하나의 컨테이너에서 Open WebUI와 Ollama 실행

:ollama 이미지는 Open WebUI와 Ollama를 함께 제공합니다. Ollama 모델용 볼륨 하나와 Open WebUI 애플리케이션 데이터용 볼륨 하나를 사용합니다.

GPU와 함께 번들로 제공되는 Ollama

docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

CPU만 사용하는 번들 Ollama

docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

컨테이너가 시작된 후 http://localhost:3000을 엽니다.

기본 사용법

인터페이스 열기: pip 설정에는 포트 8080을 사용하고, 위의 표준 Docker 명령에는 포트 3000을 사용하세요.
사용 가능한 모델 사용: 구성된 Ollama 또는 OpenAI 호환 연결에서 제공하는 모델로 대화를 시작하세요.
더 풍부한 프롬프트 작성: 응답은 Markdown과 LaTeX를 지원하므로 구조화된 설명, 코드, 표, 수학 표기법에 적합한 인터페이스입니다.
여러 기기에서 계속 사용: 반응형 인터페이스는 데스크톱과 모바일에서 작동하며, Progressive Web App 지원으로 앱과 유사한 환경을 제공합니다.

RAG로 문서 사용

문서를 대화에 직접 추가하거나 # 명령으로 라이브러리에서 가져오세요. Open WebUI는 콘텐츠를 추출하고 색인화한 뒤, 관련 구절을 검색하여 모델 컨텍스트에 삽입할 수 있습니다. RAG 스택은 BM25 및 벡터 하이브리드 검색, 재순위 지정, 전체 컨텍스트 모드를 지원합니다.

대규모 배포에서 지원되는 벡터 데이터베이스 옵션으로는 ChromaDB, PGVector, Qdrant, Milvus, Elasticsearch, OpenSearch, Pinecone, S3Vector, Oracle 23ai가 있습니다.

웹사이트를 채팅으로 가져오기

# 명령 뒤에 URL을 입력하여 웹사이트 콘텐츠를 대화로 가져오세요. 필요할 때 모델이 웹 콘텐츠를 가져오도록 Open WebUI를 구성할 수도 있습니다.

여러 모델 비교

다중 모델 대화를 사용하면 여러 모델과 동시에 상호작용할 수 있습니다. 추론 방식, 문체 또는 제공업체의 동작을 비교할 때 유용합니다. 관리자는 내장 아레나, A/B 테스트 및 ELO 기반 리더보드를 사용하여 모델을 평가할 수도 있습니다.

고급 구성 팁

전문 모델 및 에이전트 만들기

기본 모델에 사용자 지정 지침, 도구 및 지식을 결합하여 전문 에이전트를 만드세요. 동적 변수와 사용자별 또는 그룹별 액세스 제어를 사용하면 다양한 팀에 맞게 에이전트를 조정할 수 있습니다. Open WebUI Community에서 커뮤니티 프리셋을 가져올 수도 있습니다.

플랫폼 확장

Open WebUI는 Filters, Actions, Pipes, Tools 및 Skills를 지원합니다. MCP, MCPO 및 OpenAPI 도구 서버를 통해 외부 서비스를 연결할 수 있습니다. 이러한 확장 지점은 사용자 지정 통합, 승인 흐름, 속도 제한 및 추가 데이터 연결을 지원할 수 있습니다.

팀 및 엔터프라이즈 배포 계획

다중 사용자 환경에서는 역할, 그룹 및 권한을 사용하여 액세스를 제어하세요. Open WebUI는 LDAP 및 Active Directory 통합, 신뢰할 수 있는 헤더 및 OAuth 기반 싱글 사인온, Okta, Azure AD 및 Google Workspace와 같은 ID 제공업체를 위한 SCIM 2.0 프로비저닝을 지원합니다.

스토리지에는 SQLite를 사용할 수 있으며, 선택적으로 암호화를 적용할 수 있고 PostgreSQL도 사용할 수 있습니다. 파일은 로컬 또는 S3, Google Cloud Storage, Azure Blob Storage에 저장할 수 있습니다. Redis 기반 세션과 WebSocket 지원을 사용하면 로드 밸런서 뒤에서 다중 워커 및 다중 노드 배포를 구성할 수 있으며, OpenTelemetry는 트레이스, 메트릭 및 로그를 제공합니다.

완전한 오프라인 운영

오프라인 환경에서 Open WebUI를 실행할 때는 HF_HUB_OFFLINE을 1로 설정하여 인터넷에서 모델을 다운로드하려는 시도를 차단하세요.

export HF_HUB_OFFLINE=1

오프라인 배포에서도 환경에 필요한 모든 모델, 종속성 및 로컬 서비스를 사용할 수 있어야 합니다.

개발 이미지는 신중하게 사용

:dev 이미지에는 불안정한 최신 변경 사항이 포함되어 있어 버그나 미완성 기능이 있을 수 있습니다. 이러한 위험을 감수할 수 있을 때만 사용하세요.

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --add-host=host.docker.internal:host-gateway --restart always ghcr.io/open-webui/open-webui:dev

Ollama 연결 오류 문제 해결

일반적인 Docker 문제는 컨테이너 내부에서 Open WebUI가 127.0.0.1:11434 또는 host.docker.internal:11434의 Ollama에 연결하지 못하는 경우 발생합니다. 지원되는 시스템에서 문서화된 해결 방법 중 하나는 호스트 네트워킹을 사용하는 것입니다.

docker run -d --network=host -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://127.0.0.1:11434 --name open-webui --restart always ghcr.io/open-webui/open-webui:main

이 명령을 사용하면 포트 3000이 아닌 http://localhost:8080에서 Open WebUI에 액세스하세요.

그래도 연결에 실패하면 Ollama가 실행 중인지 확인하고 주소를 검증한 다음, Open WebUI 문제 해결 문서를 참조하세요. Docker 환경에서는 추가 네트워킹 구성이 필요할 수 있습니다.

유지 관리 및 보안

배포를 교체하거나 업그레이드할 때는 공식 업데이트 가이드를 따르세요.
애플리케이션 데이터 손실을 방지하려면 업그레이드 중에도 영구 Docker 볼륨을 연결된 상태로 유지하세요.
코드베이스에 여러 라이선스가 적용된 구성 요소가 포함되어 있으므로 프로젝트 라이선스와 라이선스 이력을 검토하세요. 여기에는 현재 Open WebUI 라이선스 코드에 대한 브랜딩 요구 사항도 포함됩니다.
취약점이 의심되면 공개 커뮤니티 채널이 아니라 프로젝트의 GitHub 책임 있는 취약점 공개 프로그램을 통해 기밀로 신고하세요.

결론

Open WebUI는 사용자가 제어하는 인프라를 통해 로컬 및 호스팅된 AI 모델을 실행할 수 있는 유연한 인터페이스를 제공합니다. Python 3.11 또는 영구 Docker 배포로 시작하고, Ollama나 OpenAI 호환 API를 연결한 다음 RAG, 에이전트, 플러그인, 협업, 분석 및 확장 가능한 프로덕션 서비스로 기능을 확장할 수 있습니다. 더 많은 배포 옵션은 공식 시작하기 문서를 참조하세요.