🔗 Open WebUI 통합

개요

Open WebUI v0.6+는 OpenAPI 서버를 통해 외부 도구와의 원활한 통합을 지원합니다. 이를 통해 커뮤니티 기반 도구 서버 또는 맞춤형 도구 서버를 사용하여 LLM 워크플로를 쉽게 확장할 수 있습니다 🧰.

이 가이드에서는 OpenAPI 호환 도구 서버를 시작하고 직관적인 사용자 인터페이스를 통해 Open WebUI에 연결하는 방법을 배우게 될 것입니다. 자, 시작해봅시다! 🚀

---

단계 1: OpenAPI 도구 서버 시작

시작하려면 openapi-servers 저장소에 제공된 참조 도구 서버 중 하나를 시작해야 합니다. 빠른 테스트를 위해 시간 도구 서버를 예제로 사용합니다.

🛠️ 예제: 로컬에서 time 서버 시작하기

git clone https://github.com/open-webui/openapi-servers
cd openapi-servers

# 시간 도구 서버로 이동
cd servers/time

# 필요한 종속성 설치
pip install -r requirements.txt

# 서버 시작
uvicorn main:app --host 0.0.0.0 --reload

서버가 실행되면 이 서버는 http://localhost:8000에서 로컬 OpenAPI 서버를 호스팅합니다. 이를 Open WebUI에 연결할 수 있습니다.

---

단계 2: Open WebUI에 도구 서버 연결

다음으로 실행 중인 도구 서버를 Open WebUI에 연결합니다:

1. 브라우저에서 Open WebUI를 엽니다.
2. ⚙️ 설정을 엽니다.
3. ➕ 도구를 클릭하여 새로운 도구 서버를 추가합니다.
4. OpenAPI 도구 서버가 실행 중인 URL을 입력합니다(예: http://localhost:8000).
5. "저장"을 클릭합니다.

🧑‍💻 사용자 도구 서버 vs. 🛠️ 전역 도구 서버

Open WebUI에서 도구 서버를 등록하는 두 가지 방법이 있습니다:

1. 사용자 도구 서버(일반 설정을 통해 추가됨)

• 도구 서버를 등록한 사용자만 접근 가능합니다.
• 연결은 브라우저(클라이언트 측)에서 사용자가 직접 수행합니다.
• 맞춤형 또는 로컬 도구를 테스트하거나 개인 워크플로에 적합합니다.

2. 전역 도구 서버(관리자 설정을 통해 추가됨)

관리자는 배포 전체 또는 선택된 사용자에게 공유된 도구 서버를 관리할 수 있습니다:

• 🛠️ 관리자 설정 > 도구로 이동합니다.
• 사용자 설정에서 도구 서버 URL을 추가하는 것과 동일한 방식으로 추가합니다.
• 이러한 도구는 Open WebUI의 내장 도구와 유사하게 처리됩니다.

👉 선택 사항: mcpo와 함께 구성 파일 사용하기

구성 파일을 사용하여 mcpo를 통해 여러 도구를 실행하는 경우 주의할 사항:

🧩 각 도구는 고유 경로에 마운트됩니다!

예를 들어, mcpo를 사용하여 memory 및 time 도구를 동시에 실행하는 경우 각 도구는 고유 경로에서 접근 가능합니다:

• http://localhost:8000/time
• http://localhost:8000/memory

이 말은:

• Open WebUI에서 도구를 연결하려면 특정 도구에 해당하는 전체 경로를 입력해야 합니다 — 루트 URL(http://localhost:8000)을 입력해서는 안 됩니다.
• Open WebUI 설정에서 각 도구를 해당 서브 경로 URL을 사용하여 개별적으로 추가해야 합니다.

✅ 올바름:

http://localhost:8000/time
http://localhost:8000/memory

🚫 유효하지 않음:

http://localhost:8000

이를 통해 Open WebUI가 각 도구 서버를 올바르게 인식하고 통신할 수 있습니다.

---

단계 3: 도구 서버 연결 확인 ✅

도구 서버 연결이 성공적으로 이루어지면 Open WebUI 메시지 입력 영역에 도구 서버 표시기가 직접 표시됩니다 👇:

📍 이제 입력 상자 아래에 다음 아이콘이 표시됩니다:

이 아이콘을 클릭하면 팝업이 열리며:

• 연결된 도구 서버 정보를 볼 수 있습니다.
• 사용 가능한 도구와 해당 도구를 제공하는 서버를 확인할 수 있습니다.
• 필요 시 특정 도구를 디버그하거나 연결을 끊을 수 있습니다.

🔍 다음은 도구 정보 모달의 확장된 모습입니다:

🛠️ 전역 도구 서버는 다르게 표시됩니다 — 기본적으로 숨겨져 있습니다!

전역 도구 서버(관리자가 구성한 도구 서버)를 연결하면 사용자 도구 서버처럼 입력 영역에 자동으로 표시되지 않습니다.

대신:

• 전역 도구는 기본적으로 숨겨져 있으며 사용자가 명시적으로 활성화해야 합니다.
• 활성화하려면 메시지 입력 영역(채팅 상자 왼쪽 하단)의 ➕ 버튼을 클릭한 후 사용하려는 특정 전역 도구를 수동으로 켜야 합니다.

다음은 그 예입니다:

⚠️ 전역 도구 서버에 대한 중요 사항:

• ➕ 메뉴에서 활성화하기 전까지 도구 표시 팝업에 표시되지 않습니다.
• 각 전역 도구는 활성화하려면 개별적으로 켜야 합니다.
• 활성화되면 사용자 도구와 동일한 방식으로 작동합니다.
• 관리자는 역할 기반 권한을 통해 전역 도구에 대한 접근을 제어할 수 있습니다.

팀 환경 설정 또는 공유 환경에 이상적으로 적합하며, 문서 검색, 메모리 또는 웹 조회와 같은 자주 사용되는 도구가 여러 사용자가 중앙에서 접근할 수 있게 합니다.

---

(선택 사항) 4단계: "네이티브" 함수 호출 (ReACT 스타일) 도구 사용 🧠

정보

이 기능이 효과적으로 작동하려면 선택한 모델이 네이티브 도구 호출을 지원해야 합니다. 일부 로컬 모델은 지원을 주장하지만 결과가 좋지 않은 경우가 많습니다. 최상의 경험을 위해 GPT-4o 또는 함수 호출을 네이티브로 지원하는 다른 OpenAI 모델을 사용하는 것을 강력히 권장합니다.

대화 내에서 직접 ReACT 스타일(추론 + 행동) 네이티브 함수 호출을 활성화하고 싶으신가요? Open WebUI를 네이티브 함수 호출을 사용하도록 전환할 수 있습니다.

✳️ 네이티브 함수 호출 활성화 방법:

1. 채팅 창을 엽니다.
2. ⚙️ Chat Controls > Advanced Params로 이동합니다.
3. Function Calling 매개변수를 Default에서 Native로 변경합니다.

---

더 많은 도구가 필요하신가요? 탐색하고 확장하세요! 🧱

openapi-servers 리포에는 다양한 참고용 서버가 포함되어 있습니다:

• 📂 파일 시스템 접근
• 🧠 메모리 및 지식 그래프
• 🗃️ Git 리포지토리 브라우징
• 🌎 웹 검색 (진행 중)
• 🛢️ 데이터베이스 쿼리 (진행 중)

위 단계를 반복하여 이 도구들을 실행하고 Open WebUI에 연결할 수 있습니다.

---

문제 해결 및 팁 🧩

• ❌ 연결되지 않나요? URL이 올바르고 Open WebUI를 실행하는 브라우저에서 접근 가능한지 확인하세요.
• 🔒 원격 서버를 사용하는 경우, 방화벽 및 HTTPS 구성을 확인하세요!
• 📝 서버를 지속적으로 유지하려면 Docker나 시스템 서비스를 사용하여 배포하는 것을 고려하십시오.

도움이 필요하신가요? 👉 토론 페이지를 방문하거나 문제를 제기하세요.