README.md

metadata

title: open-webui-rag-system
sdk: docker

Open WebUI RAG System

Open WebUI와 연동 가능한 한국어 문서 기반 RAG(Retrieval-Augmented Generation) 시스템입니다. PDF와 HWPX 파일을 지원하며, 페이지별 정확한 정보 추출과 출처 추적이 가능합니다.

주요 기능

1. 문서 처리

• PDF 문서: PyMuPDF 기반 텍스트, 표, 이미지 OCR 추출
• HWPX 문서: XML 파싱을 통한 섹션별 텍스트, 표, 이미지 추출
• 페이지별 처리: 각 문서를 페이지/섹션 단위로 정확하게 분리
• 다중 콘텐츠 타입: 본문, 표, OCR 텍스트를 각각 식별하여 처리

2. 벡터 검색

• E5-Large 임베딩: 다국어 지원 고성능 임베딩 모델
• FAISS 벡터스토어: 빠른 유사도 검색
• 배치 처리: 대용량 문서 처리 최적화
• 청크 분할: 문맥 유지를 위한 겹침 처리

3. RAG 시스템

• Refine 체인: 다중 문서 참조를 통한 정확한 답변 생성
• 출처 추적: 페이지 번호와 문서명을 포함한 정확한 인용
• Hallucination 방지: 문서에 명시된 정보만 사용하는 엄격한 프롬프트

4. API 서버

• FastAPI 기반: 비동기 처리 지원
• OpenAI 호환: /v1/chat/completions 엔드포인트 제공
• 스트리밍 지원: 실시간 답변 생성
• Open WebUI 연동: 플러그인 없이 바로 연결 가능

시스템 요구사항

하드웨어

• GPU: CUDA 지원 (임베딩 및 LLM 추론용)
• RAM: 최소 16GB (대용량 문서 처리 시 더 필요)
• 저장공간: 모델 및 벡터스토어용 10GB+

소프트웨어

• Python 3.8+
• CUDA 11.7+ (GPU 사용 시)
• Tesseract OCR

설치 방법

1. 저장소 클론

git clone <repository-url>
cd open-webui-rag-system

2. 의존성 설치

pip install -r requirements.txt

3. Tesseract OCR 설치

Ubuntu/Debian:

sudo apt-get install tesseract-ocr tesseract-ocr-kor

Windows:

• Tesseract 공식 페이지에서 설치

4. LLM 서버 설정

llm_loader.py에서 사용할 LLM 서버 설정:

# EXAONE 모델 사용 예시
base_url="http://vllm:8000/v1"
model="LGAI-EXAONE/EXAONE-3.5-7.8B-Instruct"
openai_api_key="token-abc123"

실행 방법

1. 문서 준비

처리할 문서들을 dataset_test 폴더에 저장:

dataset_test/
├── document1.pdf
├── document2.hwpx
└── document3.pdf

2. 문서 처리 및 벡터스토어 생성

python document_processor_image_test.py

또는 벡터스토어 빌드 스크립트 사용:

python vector_store_test.py --folder dataset_test --save_path faiss_index_pymupdf

3. RAG 서버 실행

python rag_server.py

서버는 기본적으로 8000번 포트에서 실행됩니다.

4. Open WebUI 연동

Open WebUI의 모델 설정에서 다음과 같이 설정:

• API Base URL: http://localhost:8000/v1
• API Key: token-abc123
• Model Name: rag

5. 개별 테스트

명령줄에서 직접 질문:

python rag_system.py --query "문서에서 찾고 싶은 내용"

대화형 모드:

python rag_system.py

프로젝트 구조

open-webui-rag-system/
├── document_processor_image_test.py    # 문서 처리 메인 모듈
├── vector_store_test.py                # 벡터스토어 생성 모듈
├── rag_system.py                       # RAG 체인 구성 및 질의응답
├── rag_server.py                       # FastAPI 서버
├── llm_loader.py                      # LLM 모델 로더
├── e5_embeddings.py                   # E5 임베딩 모듈
├── requirements.txt                   # 의존성 목록
├── dataset_test/                      # 문서 저장 폴더
└── faiss_index_pymupdf/              # 생성된 벡터스토어

핵심 모듈 설명

document_processor_image_test.py

• PDF와 HWPX 파일의 텍스트, 표, 이미지를 페이지별로 추출
• PyMuPDF, pdfplumber, pytesseract를 활용한 다층 처리
• 섹션별 메타데이터와 페이지 정보 유지

vector_store_test.py

• E5-Large 임베딩 모델을 사용한 벡터화
• FAISS를 이용한 효율적인 벡터스토어 구축
• 배치 처리를 통한 메모리 최적화

rag_system.py

• Refine 체인을 활용한 다단계 답변 생성
• 페이지 번호 hallucination 방지 프롬프트
• 출처 추적과 메타데이터 관리

rag_server.py

• OpenAI 호환 API 엔드포인트 제공
• 스트리밍 응답 지원
• Open WebUI와의 원활한 연동

설정 옵션

문서 처리 옵션

• 청크 크기: chunk_size=500 (기본값)
• 청크 겹침: chunk_overlap=100 (기본값)
• OCR 언어: lang='kor+eng' (한국어+영어)

검색 옵션

• 검색 문서 수: k=7 (기본값)
• 임베딩 모델: intfloat/multilingual-e5-large-instruct
• 디바이스: cuda 또는 cpu

LLM 설정

지원하는 모델들:

• LGAI-EXAONE/EXAONE-3.5-7.8B-Instruct
• meta-llama/Meta-Llama-3-8B-Instruct
• 기타 OpenAI 호환 모델

트러블슈팅

1. CUDA 메모리 부족

# CPU 모드로 실행
python vector_store_test.py --device cpu

2. 한글 폰트 문제

# 한글 폰트 설치 (Ubuntu)
sudo apt-get install fonts-nanum

3. Tesseract 경로 문제

# pytesseract 경로 수동 설정
pytesseract.pytesseract.tesseract_cmd = '/usr/bin/tesseract'

4. 모델 다운로드 실패

# Hugging Face 캐시 경로 확인
export HF_HOME=/path/to/huggingface/cache

API 사용 예시

직접 질의

curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{"question": "문서에서 예산 관련 내용을 찾아주세요"}'

OpenAI 호환 API

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rag",
    "messages": [{"role": "user", "content": "예산 현황이 어떻게 되나요?"}],
    "stream": false
  }'

성능 최적화

1. 배치 크기 조정

python vector_store_test.py --batch_size 32  # GPU 메모리에 따라 조정

2. 청크 크기 최적화

# 긴 문서의 경우 청크 크기 증가
chunks = split_documents(docs, chunk_size=800, chunk_overlap=150)

3. 검색 결과 수 조정

python rag_system.py --k 10  # 더 많은 문서 참조

라이선스

MIT License

기여 방법

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request