📋 FAQ

Sponsored by n8n

Does your interface have a backend yet? Try n8n

💡 왜 Docker를 선택해야 하나요?

Docker가 모든 사용자에게 적합하지 않을 수 있다는 점은 이해하지만, 이 접근법은 프로젝트 설계와 운영 효율성의 중심입니다. 저희는 프로젝트가 Docker에 대한 헌신을 기본적인 면으로 보고 있으며, 다른 배포 방법을 찾고 계신 경우 커뮤니티 주도적인 대안을 탐구하시길 권장합니다.

Q: 로고 및 브랜딩을 어떻게 맞춤 설정하나요?

A: **기업 라이선스**를 이용하면 테마, 로고, 브랜딩을 맞춤 설정할 수 있으며, 이는 독점적인 기업 기능을 활성화합니다.

기업 솔루션 및 브랜딩 맞춤 설정에 대한 자세한 내용은 저희 영업팀에 문의하십시오: 📧 [email protected]

Q: 왜 가입을 해야 합니까? 제 데이터는 어디로 전달되나요?

A: 가입을 통해 관리자 사용자로 설정되어 보안을 강화합니다. 이를 통해 Open WebUI가 외부에 노출되더라도 데이터 보안을 유지할 수 있습니다. 모든 것이 로컬에 유지되며, 저희는 귀하의 데이터를 수집하지 않습니다. 가입 시 모든 정보는 서버 내에서 유지되며, 귀하의 기기 밖으로 나가지 않습니다. 귀하의 개인정보와 보안은 저희의 최우선 사항이며, 항상 데이터가 귀하의 통제 하에 있어야 한다고 생각합니다.

Q: 왜 Docker 컨테이너가 localhost를 사용하여 호스트의 서비스에 연결할 수 없나요?

A: Docker 컨테이너 내부에서 localhost는 컨테이너 자체를 의미하며, 호스트 머신을 의미하지 않습니다. 이러한 차이는 네트워킹에서 매우 중요합니다. 컨테이너에서 호스트에서 실행 중인 서비스로 연결하려면 localhost 대신 host.docker.internal이라는 DNS 이름을 사용해야 합니다. 이 DNS 이름은 Docker에서 특별히 인식되어 이러한 연결을 용이하게 하며, 컨테이너 내에서 호스트를 도달 가능한 엔티티로 처리하여 일반적인 localhost 범위 제한을 우회합니다.

Q: 호스트의 서비스를 Docker 컨테이너에서 접근 가능하게 만들려면 어떻게 해야 하나요?

A: 호스트에서 실행 중인 서비스를 Docker 컨테이너에서 접근 가능하게 만들려면, 이러한 서비스를 모든 네트워크 인터페이스에서 수신하도록 0.0.0.0 IP 주소를 사용하여 설정해야 하며, 이는 localhost로 제한되는 127.0.0.1과는 다릅니다. 이 설정은 Docker 컨테이너를 포함한 모든 IP 주소에서 연결을 허용합니다. 잠재적인 외부 접근이 있는 환경에서 이와 같은 설정을 사용할 때는 보안상의 고려사항을 인지해야 합니다. 방화벽이나 인증과 같은 적절한 보안 조치를 구현함으로써 위험을 완화할 수 있습니다.

Q: 왜 제 Open WebUI가 업데이트되지 않나요? 새 이미지를 다시 가져오고 컨테이너를 재시작했는데, 변경이 없습니다.

A: Open WebUI를 업데이트하려면 새로운 Docker 이미지를 가져오는 것 이상의 작업이 필요합니다. 다음은 업데이트가 표시되지 않는 이유와 이를 해결하는 방법입니다:

1. Docker 이미지 업데이트: docker pull ghcr.io/open-webui/open-webui:main 명령어는 Docker 이미지를 업데이트하지만, 실행 중인 컨테이너나 데이터는 업데이트되지 않습니다.
2. Docker 볼륨의 지속적인 데이터: Docker 볼륨은 컨테이너 라이프사이클과 독립적으로 데이터를 저장하며, 업데이트가 이루어질 때 데이터(예: 채팅 기록)를 보존합니다.
3. 업데이트 적용: 기존 컨테이너를 제거하고(볼륨은 삭제되지 않음), 업데이트된 이미지와 기존 볼륨을 함께 사용하여 새 컨테이너를 생성해야 업데이트가 적용됩니다.

이 프로세스는 데이터를 안전하게 유지하면서 앱을 업데이트합니다.

Q: 컨테이너를 삭제하면 데이터를 잃게 되나요?

A: 일반적인 우려지만, Docker 볼륨을 제대로 사용하는 경우 컨테이너를 삭제해도 데이터를 잃지 않습니다. 이유는 다음과 같습니다:

• 볼륨은 데이터를 보존합니다: Docker 볼륨은 컨테이너 라이프사이클 외부에 데이터를 유지하도록 설계되었습니다. 데이터가 볼륨에 저장된 경우, 컨테이너에 어떤 일이 있어도 데이터는 그대로 유지됩니다.
• 안전한 업데이트 프로세스: Open WebUI를 업데이트할 때, 기존 컨테이너를 삭제하고 업데이트된 이미지로 새로운 컨테이너를 생성해도 볼륨에 저장된 데이터는 영향을 받지 않습니다. 단, docker volume rm과 같은 명령으로 볼륨을 삭제하지 않는 것이 중요합니다.

올바른 업데이트 단계를 따라가면 - 새 이미지를 가져오고, 볼륨을 삭제하지 않고 기존 컨테이너를 제거한 다음, 업데이트된 이미지와 기존 볼륨으로 새로운 컨테이너를 생성하면, 애플리케이션 코드는 업데이트되고 데이터는 안전하게 유지됩니다.

Q: 배포판에 포함된 Docker를 사용할까요, 아니면 공식 Docker 패키지를 사용할까요?

A: Open WebUI를 실행하기 위해 공식 Docker 패키지를 사용하는 것을 추천합니다. 공식 Docker 패키지는 최신 기능, 버그 수정 및 보안 패치를 포함하여 주기적으로 업데이트되므로 최적의 성능과 보안을 제공합니다. 또한, host.docker.internal과 같은 중요 기능을 지원하는데, 이는 배포판 패키지 버전에서는 제공되지 않을 수 있습니다. 이 기능은 Docker 컨테이너 내의 적절한 네트워크 설정 및 연결을 위해 필수적입니다.

공식 Docker 패키지를 선택함으로써 다양한 환경에서 일관된 동작, 더 신뢰할 수 있는 문제 해결 지원 및 최신 Docker 개발 기능을 활용하는 이점을 누릴 수 있습니다. 또한, 폭넓은 Docker 커뮤니티와 자원이 공식 패키지와 더 잘 맞아떨어져 발생할 수 있는 문제에 대해 풍부한 정보와 지원을 제공합니다.

Open WebUI를 실행하는 데 필요한 모든 것, 즉 데이터는 사용자의 서버 환경 내에서 관리되며 이는 사용자의 개인 정보 및 보안에 대한 당사의 약속을 강조합니다. 공식 Docker 패키지를 설치하는 방법은 Docker의 공식 문서 사이트 Install Docker Engine 가이드를 참조하십시오.

Q: Docker에서 GPU 지원이 가능한가요?

A: Docker에서 GPU 지원은 플랫폼에 따라 다릅니다. 공식적으로 Windows용 Docker와 Linux에서의 Docker Engine에서 GPU 지원이 제공됩니다. 반면, Linux와 MacOS용 Docker Desktop에서는 현재 GPU 지원이 제공되지 않습니다. 이러한 제한 사항은 GPU 가속이 필요한 애플리케이션을 사용할 때 중요한 요소입니다. GPU 기능을 활용하기 위해서는 GPU 통합을 공식적으로 지원하는 플랫폼에서 Docker를 사용하는 것을 권장합니다.

Q: Open WebUI가 Docker 사용을 강조하는 이유는 무엇인가요?

A: Docker를 사용하는 결정은 일관성을 보장하고, 독립성을 유지하며, 다양한 환경에서 배포를 간소화할 수 있는 Docker의 능력에 기인합니다. Docker는 호환성 문제를 최소화하고, 기본 시스템과 상관없이 WebUI를 간단히 실행할 수 있도록 합니다. 이는 프로젝트 유지 관리자가 이러한 이점을 활용하기 위해 선택한 전략적 결정이며, Docker를 사용하는 데는 학습 곡선이 있다는 점을 인정하지만, 배포 및 유지 관리의 이점은 상당합니다. Docker가 모든 사람의 선호도에 맞지 않을 수 있다는 점을 이해하지만, 이 접근 방식은 본 프로젝트의 설계 및 운영 효율성과 밀접하게 관련되어 있습니다. 우리는 Docker에 대한 프로젝트의 헌신을 근본적인 요소로 보고 있으며, 다른 배포 방법을 탐색하려는 사용자들에게 커뮤니티 주도 대안을 살펴보기를 권장합니다.

Q: Speech-to-Text(STT) 및 Text-to-Speech(TTS)가 내 배포 환경에서 작동하지 않는 이유는 무엇인가요?

A: 배포 환경에서 Speech-to-Text(STT) 및 Text-to-Speech(TTS) 서비스의 기능은 올바르게 작동하려면 HTTPS가 필요할 수 있습니다. 현대 브라우저는 STT와 TTS와 같은 특정 기능이 보안 HTTPS 연결에서만 작동할 수 있도록 제한하는 보안 조치를 시행합니다. 배포 환경이 HTTPS를 사용하도록 구성되지 않은 경우 이러한 서비스가 예상대로 작동하지 않을 수 있습니다. HTTPS를 통해 배포 환경에 액세스할 수 있도록 설정하면 이러한 문제를 해결하여 STT/TTS 기능을 완전히 활용할 수 있습니다.

Q: Open WebUI가 내장된 HTTPS 지원을 포함하지 않는 이유는 무엇인가요?

A: 모든 사용자의 요구를 적절히 충족하지 못할 수 있기 때문에, HTTPS 지원을 포함하는 전체 솔루션을 구현하지 않아야 합니다. 프로젝트에 HTTPS를 직접 구현하면 유연성이 제한되고 모든 사용자에게 특정 요구 사항이나 환경에 맞지 않을 수 있습니다. 모든 사용자가 자신의 환경에 맞게 구성을 조정할 수 있도록 HTTPS 종료의 구현은 생산 배포를 위해 사용자에게 맡깁니다. 이 결정은 더 폭넓은 적응성과 맞춤화를 제공합니다. 공식 문서에서는 HTTPS 설정에 대한 안내를 제공하지 않지만 커뮤니티 구성원이 요청 시 경험에 기반한 통찰력과 제안을 공유할 수 있습니다.

Q: 일부 새로운 소프트웨어를 업데이트/재시작/설치한 후 Open WebUI가 더 이상 작동하지 않습니다!

A: 업데이트 또는 새 소프트웨어 설치 후 Open WebUI가 실행되지 않는 경우, 백엔드 종속성에 대해 가상 환경을 사용하지 않은 경우와 같은 직접 설치 접근 방식과 관련되어 있을 수 있습니다. 직접 설치는 업데이트 또는 기존 종속성을 변경하는 새 설치와 같은 시스템 환경의 변경에 민감할 수 있습니다. 충돌을 방지하고 안정성을 유지하기 위해 백엔드의 requirements.txt 종속성을 관리하기 위해 가상 환경을 사용하는 것을 권장합니다. 이렇게 하면 Open WebUI 종속성이 다른 시스템 패키지와 격리되어 이러한 문제의 위험을 최소화할 수 있습니다.

Q: 업데이트/재시작 후 내 로그인이 더 이상 작동하지 않으며, 새 계정을 만들어야 하고 내 모든 채팅이 사라졌습니다.

A: 이 문제는 일반적으로 /app/backend/data에 대한 볼륨을 마운트하지 않고 Docker 컨테이너를 생성하거나 지정된 Open WebUI 볼륨(예: open-webui)이 실수로 삭제된 경우에 발생합니다. Docker 볼륨은 컨테이너의 라이프사이클 동안 데이터를 지속적으로 유지하는 데 중요합니다. 재시작 후 새 계정을 생성해야 한다면 기존 데이터를 포함한 볼륨을 연결하지 않고 새 컨테이너를 시작했을 가능성이 높습니다. 데이터 손실을 방지하기 위해 Docker 실행 명령에 올바른 데이터 위치를 지정하는 볼륨 마운트를 포함해야 합니다.

Q: 로그인하려 했는데 실패했습니다. 새 계정을 만들었더니 제 계정은 관리자가 활성화해야 한다는 메시지가 나옵니다.

A: 초기 세팅 중 생성된 첫 번째 관리자 계정의 비밀번호를 잊어버릴 경우 이러한 상황이 발생합니다. 첫 번째 계정은 자동으로 관리자 계정으로 지정됩니다. 관리자 계정에 액세스하지 못하는 상태에서 새 계정을 생성하면 관리자 활성화가 필요하게 됩니다. 첫 번째 관리자 계정 자격 증명을 잃지 않는 것이 Open WebUI에 원활히 액세스하고 관리하는 데 중요합니다. 관리자 비밀번호 재설정 가이드를 참조하여 관리자 계정을 복구하는 방법을 확인하세요.

Q: Open WebUI가 SSL 오류로 인해 시작되지 않습니다. 왜 그런가요?

A: Open WebUI를 시작하려고 할 때 SSL 오류가 발생하는 이유는 SSL 인증서가 없거나 huggingface.co 설정이 잘못되었기 때문일 가능성이 큽니다. 이 문제를 해결하려면 HuggingFace의 미러를 설정하세요. 예를 들어 hf-mirror.com 같은 미러를 설정하고 Docker 컨테이너 시작 시 이를 엔드포인트로 지정할 수 있습니다. Docker 실행 명령에서 -e HF_ENDPOINT=https://hf-mirror.com/ 매개변수를 사용하여 HuggingFace 미러 주소를 정의할 수 있습니다. 예시는 다음과 같습니다:

docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --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

Q: Open WebUI에서 RAG(정보 검색 증강 생성)가 잘 작동하지 않거나 성능이 매우 좋지 않습니다. 왜 그런가요?

A: Ollama를 사용하는 경우, Ollama가 기본적으로 문맥 길이를 2048 토큰으로 설정한다는 점을 참고하세요. 이로 인해 검색된 데이터가 사용되지 않을 수 있습니다. 이는 검색된 데이터가 사용 가능한 컨텍스트 창에 맞지 않을 때 발생합니다.

Open WebUI에서 정보 검색 증강 생성(RAG)의 성능을 개선하려면 문맥 길이를 훨씬 더 큰 값(8192+ 토큰)으로 늘려 검색된 문서들이 모델 응답에 효과적으로 사용될 수 있도록 해야 합니다.

이를 위해 Ollama 모델의 매개변수를 구성하여 더 큰 컨텍스트 창을 허용하세요. 채팅에서 직접 또는 모델 편집기 페이지에서 이 설정을 확인하고 수정하여 RAG 경험을 크게 향상시킬 수 있습니다.

Q: MCP(Model Context Protocol)를 Open WebUI에서 지원하나요?

A: 네, Open WebUI에서는 MCP Tool Servers를 공식적으로 지원합니다. 단, OpenAPI 호환 프록시를 통해서만 지원됩니다 (openapi-servers). 이를 통해 최적의 호환성, 보안, 유지 관리가 가능합니다.

MCP(및 기타 백엔드 프로토콜)를 연결하기 위해, 우리는 다음 링크에서 사용할 수 있는 맞춤 프록시 구현을 제공합니다: 👉 https://github.com/open-webui/mcpo

이 설계 선택은 다음과 같은 핵심 원칙에 따라 이루어졌습니다:

• 📘 표준 우선 접근: OpenAPI는 RESTful 서비스 정의 및 계약 기반 서비스 상호 운용성을 위한 사실상의 표준입니다. OpenAPI를 통한 통합을 통해 업그레이드 및 배포 시 재현 가능한 스키마 기반 동작을 가능하게 합니다.
• 🔒 보안 모델 격리: 프록시를 통한 MCP 통합은 백엔드 프로토콜 동작을 샌드박스로 격리하여 공격 표면을 줄이고 경계 수준 감사, 인증 및 가시성을 가능하게 합니다.
• ⚙️ 프로토콜 추상화: Open WebUI가 백엔드에 구애받지 않으면서도 예측 가능한 런타임 동작을 유지할 수 있도록 이기종 백엔드(MCP 등)를 단일 OpenAPI 스키마를 통해 지원합니다.
• ⛓️ 분리된 배포 토폴로지: 프록시 기반 아키텍처는 MCP와 같은 툴 서버가 프론트엔드 표현과 독립적으로 발전할 수 있도록 하여 매우 모듈화된 프로덕션 환경 또는 분산 워크로드를 촉진합니다.

요약하면: MCP는 OpenAPI 호환 프록시를 통해 MCP Tool Server가 제공되는 경우에만 지원됩니다. 이 아키텍처 결정은 Open WebUI가 확장 가능하고, 안전하며, 유지 관리가 용이하도록 설계되었습니다.

추가적인 도움이 필요하신가요?

추가적인 질문이나 문제가 있으시면, GitHub Issues 페이지 또는 Discord 채널에서 도움과 추가 정보를 요청하세요.