많은 기업과 팀이 Open WebUI를 사내 프라이빗 LLM 포털로 도입하는 가장 결정적인 이유는 바로 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 기능 때문입니다. “사내 규정집, API 명세서, 소스코드, 고객 매뉴얼 PDF를 업로드하고 사내 전용 AI 챗봇을 만든다”는 시나리오는 매우 매력적입니다.

AI

5 분 소요

SERIES Open WebUI 실무 완벽 가이드 3 / 4 시리즈 전체 보기 →

많은 기업과 팀이 Open WebUI를 사내 프라이빗 LLM 포털로 도입하는 가장 결정적인 이유는 바로 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 기능 때문입니다. “사내 규정집, API 명세서, 소스코드, 고객 매뉴얼 PDF를 업로드하고 사내 전용 AI 챗봇을 만든다”는 시나리오는 매우 매력적입니다.

하지만 실무에서 기본 설정 그대로 수십 권의 문서를 올리고 여러 사용자가 동시 질문을 던지기 시작하면 곧바로 한계에 부딪힙니다.

  • “PDF 몇 개 올렸더니 컨테이너 메모리가 수 GB씩 치솟고 다운된다.”
  • “문서에 분명히 있는 내용인데 엉뚱한 답변(Hallucination)을 내놓는다.”
  • “동시에 여러 명이 문서를 올렸더니 벡터 DB가 락에 걸린다.”

이번 3편에서는 대규모 문서 환경에서도 안정적으로 동작하는 엔터프라이즈급 RAG 파이프라인 최적화(PGVector, Tika/Docling, Reranking)와 모델에게 가상 터미널 탐색 권한을 주어 검색 정확도를 극대화하는 ENABLE_KB_EXEC, 그리고 실시간 웹 검색(SearXNG) 연동까지 완벽하게 파헤칩니다.

1. Open WebUI RAG 파이프라인의 기본 구조

Open WebUI의 RAG는 크게 두 가지 방식으로 사용됩니다.

  1. 임시 대화 첨부 (One-off Attachments):
    • 채팅창에 파일을 드래그 앤 드롭하여 질문하는 방식입니다.
    • 해당 파일은 오직 그 대화방의 컨텍스트 내에서만 청킹 및 임베딩되어 사용됩니다.
  2. 영구 지식베이스 (Workspace > Knowledge Base):
    • 사내 매뉴얼, 위키, 기술 문서처럼 여러 대화에서 반복해서 참조해야 하는 문서를 모아두는 영구 저장소입니다.
    • 채팅창에서 # 단축키를 입력해 원하는 지식베이스를 즉시 소환하거나, 특정 커스텀 모델에 기본 지식으로 영구 바인딩할 수 있습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13

[ 원본 문서 (PDF/MD/TXT/DOCX) ]
              │
              ▼ (1. Content Extraction: Tika / Docling)
[ 텍스트 추출 및 정제 ]
              │
              ▼ (2. Chunking: Token/Character Split)
[ 청크 분할 (예: 1500자 단위, Overlap 150자) ]
              │
              ▼ (3. Embedding Engine: nomic-embed-text / OpenAI)
[ 벡터 임베딩 생성 ]
              │
              ▼ (4. Vector Database: PGVector)
[ 벡터 인덱스 저장 ] ──(5. Similarity Search + Reranker)──> [ 모델 답변 생성 ]

2. 대규모 RAG를 위한 3대 병목 해결

2.1 임베딩 엔진 오프로딩 (RAG_EMBEDDING_ENGINE)

  • 기본값: 내장 SentenceTransformers (all-MiniLM-L6-v2) 모델이 컨테이너 내부 CPU에서 직접 임베딩을 계산합니다. 워커당 약 500MB의 메모리를 상시 점유하며, 대용량 파일 인제스트 시 CPU 사용량이 100%로 치솟습니다.
  • 해결책: 임베딩 연산을 외부 API나 전용 인스턴스로 분리합니다. 
    1
2
3
4
5
6
7
8
9

    # Ollama의 전용 임베딩 모델로 오프로딩 (추천: nomic-embed-text 또는 bge-m3)
RAG_EMBEDDING_ENGINE=ollama
RAG_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://host.docker.internal:11434

# 또는 상용 API 활용
# RAG_EMBEDDING_ENGINE=openai
# RAG_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_API_KEY=your-key

2.2 문서 추출 파서 교체 (CONTENT_EXTRACTION_ENGINE)

  • 기본값: pypdf 라이브러리를 사용합니다. 복잡한 다단 레이아웃이나 표(Table) 추출 성능이 떨어지고, 대용량 문서를 반복 파싱할 때 메모리 누수(Memory Leak)가 발생하는 고질적인 문제가 있습니다.
  • 해결책: 전문 파서 엔진으로 교체합니다.
    • Tika (tika): Apache Tika 서버를 별도 컨테이너로 띄워 수백 가지 파일 형식을 안정적으로 파싱
    • Docling (docling): IBM의 최신 문서 파서로 복잡한 표, 수식, 레이아웃 보존에 탁월 
      1
2

      CONTENT_EXTRACTION_ENGINE=tika
TIKA_SERVER_URL=http://tika:9998

2.3 벡터 데이터베이스 교체 (VECTOR_DB=pgvector)

  • 기본값: 내장 SQLite 백엔드의 ChromaDB를 사용합니다. 단일 파일 기반이라 멀티 유저 환경에서 동시 업로드 시 쓰기 락이 발생합니다.
  • 해결책: 1편에서 구축한 PostgreSQL에 pgvector 확장을 활성화하여 프로덕션급 벡터 DB로 통합합니다. 
    1
2

    VECTOR_DB=pgvector
PGVECTOR_DB_URL=postgresql://webui_user:webui_password@postgres:5432/webui_db

3. 실무 권장 RAG 하이퍼파라미터 세팅

Settings > Admin > Documents에서 설정하는 파라미터는 검색 정확도에 지대한 영향을 미칩니다.

파라미터 권장값 설명
Chunk Splitter token 또는 character 텍스트 분할 기준 단위
Chunk Size 1500 (토큰 기준: 500~800) 한 청크에 담길 문맥의 크기 (너무 작으면 문맥 누락, 너무 크면 집중도 저하)
Chunk Overlap 150 청크 간 경계 단절을 막기 위한 중복 구간 (보통 Chunk Size의 10%)
Top K (Top Results) 5 모델에게 넘겨줄 상위 검색 결과 수
Relevance Threshold 0.3 ~ 0.4 유사도 하한선 (터무니없는 오검색 청크 차단)
Reranking Engine bge-reranker-large 등 1차 검색된 청크들을 교차 검증하여 최종 순위를 재배열 (정확도 대폭 향상)

4. 차세대 에이전트 RAG: ENABLE_KB_EXEC=True

일반적인 RAG는 질문이 들어오면 사용자가 작성한 문장을 벡터 유사도(Cosine Similarity)로만 검색해서 상위 3~5개 조각을 모델 프롬프트에 욱여넣습니다. 이 방식은 “문서 전체의 목차 구조”나 “특정 함수/키워드가 몇 페이지에 걸쳐 나오는지”를 파악하기 어렵습니다.

Open WebUI는 이를 극복하기 위해 가상 파일시스템 기반 탐색 기능(KB_EXEC)을 제공합니다.

1

ENABLE_KB_EXEC=True

동작 원리

이 옵션을 활성화하면 지식베이스가 모델에게 가상의 디렉터리/파일시스템 구조로 노출되며, 모델은 다음과 같은 도구를 자율적으로 호출합니다:

  • ls: 지식베이스 내 문서 목록 확인
  • tree: 문서의 목차 및 섹션 계층 구조 탐색
  • grep: 특정 에러 코드, 키워드, 함수명의 위치 검색
  • cat / read_by_line: 필요한 섹션만 핀포인트로 읽어오기
1
2
3
4
5

User: "우리 프로젝트의 결제 타임아웃 재시도 정책이 어떻게 돼?"
Agent:
1. `tree` 명령으로 결제 모듈 문서 구조 파악
2. `grep "timeout"` 실행 -> payment_policy.md 의 42번째 라인 발견
3. `cat payment_policy.md 40-50` 호출로 정확한 정책 문단만 읽고 답변

이 방식을 사용하면 불필요한 청크 낭비 없이 정확한 팩트 기반 답변을 유도할 수 있어 환각(Hallucination)이 극적으로 줄어듭니다.

5. 외부 소스 자동 동기화: oikb 데몬

사내 문서는 계속 수정되고 업데이트됩니다. 관리자가 매번 Open WebUI에 접속해 새 문서를 수동 업로드하는 것은 지속 불가능합니다. Open WebUI 팀은 이를 위해 공식 동기화 도구인 oikb (Knowledge Base Sync)를 제공합니다.

  • 동작 방식: 로컬 폴더, Git 저장소, S3 버킷, Confluence, Notion 등 40개 이상의 소스를 감시(Watch)하다가 문서가 변경되면 백그라운드에서 Open WebUI API를 호출해 자동으로 지식베이스를 갱신합니다.
  • 실행 예시: 
    1
2

    # 사내 매뉴얼 폴더를 지식베이스와 지속 동기화
oikb sync --source /var/docs/company-handbook --kb-id "company-handbook-id" --watch

6. 실시간 웹 검색 (Web Search) 연동

모델의 학습 컷오프 이후 정보나 실시간 뉴스, 주가, 날씨 등을 보완하기 위해 웹 검색을 통합합니다.

1
2
3
4
5
6
7
8
9
10

                   ┌──────────────────────────────────┐
                   │    Open WebUI Agentic Engine     │
                   └────────────────┬─────────────────┘
                                    │ Search Query
                                    ▼
       ┌────────────────────────────┴────────────────────────────┐
       ▼                                                         ▼
[ Self-Hosted: SearXNG ]                                [ Commercial: Tavily / Brave ]
- 전송 데이터 완전 비공개                               - 고품질 AI 요약 결과 반환
- 별도 API 비용 없음                                    - 복합 쿼리 지원
  1. 자체 호스팅 검색 엔진: SearXNG (추천):
    • 외부 상용 검색 API에 검색어를 노출하지 않고 사내 프라이빗하게 운영할 때 최적입니다.
    • Settings > Admin > Web Search에서 SearXNG 선택 후 엔드포인트 지정: 
      1

      http://searxng:8080/search?q=<query>&format=json
  2. AI 최적화 상용 API: Tavily / Firecrawl / Brave:
    • 웹페이지 본문 마크다운 추출 및 AI 요약에 최적화된 엔진입니다. API Key만 입력하면 즉시 활성화됩니다.
  3. 검색 결과 지식베이스 즉시 저장 (Save to Knowledge):
    • 웹 검색으로 찾은 최신 조사 결과를 클릭 한 번으로 영구 Knowledge Base에 아카이빙할 수 있어 팀 지식 자산화에 유용합니다.

요약

  • RAG를 프로덕션 규모로 운영하려면 PGVector(벡터 DB), Tika/Docling(추출기), nomic-embed-text(전용 임베딩)로 3대 병목을 외주화해야 합니다.
  • 단순 벡터 검색을 넘어 ENABLE_KB_EXEC=True를 켜면 모델이 문서를 파일시스템처럼 탐색하여 환각을 비약적으로 낮춥니다.
  • oikb 데몬을 연동하면 Git이나 사내 저장소의 최신 문서를 사람의 개입 없이 상시 자동 동기화할 수 있습니다.

다음 완결편인 4편에서는 단순한 대화형 챗봇을 넘어 실제 컴퓨터 환경을 다루는 차세대 에이전트 구축(Open Terminal, MCP 연동, Open WebUI Computer)을 다룹니다.

// reading compass

이 글과 이어지는 경로

시리즈, 카테고리, 태그 겹침, 최신도를 점수화해 가까운 글일수록 중심에 배치합니다.

hover nodes or cards · click a node to pin
Next reads 0

    댓글남기기

    참고

    AI

    Open WebUI 실무 완벽 가이드 4편 - 차세대 에이전트 구축(Open Terminal, MCP 연동, Open WebUI Computer)

    우리가 AI와 상호작용하는 방식은 빠르게 변하고 있습니다. 지금까지의 1~3편이 “질문을 던지면 똑똑하게 글과 문서를 찾아 답해주는 대화형 AI(Chatbot)”에 초점을 맞췄다면, 이번 4편은 “목표를 주면 스스로 판단해 코드를 실행하고, 브라우저를 띄우며, 내 컴퓨터의 프로젝트...

    5 분 소요

    Wiki

    멱등성(Idempotency), 재시도해도 안전한 API 만들기

    같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 똑같이 유지되는 성질을 멱등성(idempotency)이라고 한다. 말로만 들으면 당연한 얘기 같은데, 막상 네트워크가 불안정한 환경에서 API를 설계하다 보면 은근히 신경 써야 하는 부분이다. 클라이언트가 응답을 못 받아서 같은...

    1 분 소요