하이브리드 RAG 프로젝트

사용자가 제공하는 모든 문서에서 작동하는 하이브리드 검색 기능을 갖춘 범용 RAG(검색 증강 생성, Retrieval-Augmented Generation) 시스템입니다. 최적의 문서 검색을 위해 의미(밀집 벡터) 검색과 키워드(희소 BM25) 검색을 결합하며, 손쉬운 통합을 위한 MCP 서버 API를 제공합니다.

🎯 주요 기능: 다중 형식 지원 • 로컬 LLM • Claude Desktop 통합 • 구조적 데이터 쿼리 • 문서 유형 인식 검색

🚀 빠른 시작(MCP 불필요!)

이 프로젝트를 사용하는 데 Claude Desktop이나 MCP가 필요하지 않습니다! 그냥 실행만 하세요:

# 1. Make sure Ollama is running
ollama serve

# 2. Activate virtual environment
source .venv/bin/activate

# 3. Start conversational demo (recommended)
python scripts/demos/conversational.py

# Or use the shortcut
./scripts/bin/ask.sh

끝입니다! 샘플 데이터셋의 43,835개 문서 청크에 대해 질문할 수 있습니다.

📖 전체 사용 방법은 빠른 시작 가이드를 참조하세요. 📚 모든 문서는 docs/ 폴더에서 확인하거나 docs/README.md부터 시작하세요.

Related MCP server: Hybrid RAG Project MCP Server

개요

이 프로젝트는 다음을 결합하는 하이브리드 RAG 시스템을 구현합니다:

• 의미 기반 검색(Semantic Search): 의미와 맥락을 이해하기 위한 밀집 벡터 임베딩

• 키워드 검색(Keyword Search): 정확한 키워드 일치를 위한 BM25 희소 검색

• 하이브리드 융합(Hybrid Fusion): 두 방식의 결과를 결합하는 RRF(Reciprocal Rank Fusion)

• MCP 서버: Claude 통합을 위한 REST API 및 Model Context Protocol 서버

• 다중 형식 지원(Multi-format Support): 다양한 파일 형식의 문서를 자동으로 로드

하이브리드 접근 방식은 두 검색 방식의 장점을 모두 활용하여 더 나은 검색 정확도를 보장합니다.

기능

• Chroma 및 Ollama 임베딩을 사용한 벡터 기반 의미 검색

• 정확한 용어 일치를 위한 BM25 키워드 검색

• RRF(Reciprocal Rank Fusion)를 사용하는 앙상블 리트리버

• 답변 생성을 위한 로컬 Ollama LLM 통합

• 여러 문서 형식 지원(TXT, PDF, MD, DOCX, CSV)

• 데이터 디렉터리에서 문서 자동 로드

• /ingest 및 /query 엔드포인트를 갖춘 RESTful API 서버

• Claude Desktop/API 통합을 위한 MCP(Model Context Protocol) 서버

• 설정 기반 아키텍처(하드코딩된 값 없음)

• 이후 쿼리 속도 향상을 위한 영구 벡터 저장소

아키텍처

User Documents → data/ directory
                      ↓
            Document Loader
                      ↓
Query → Hybrid Retriever → [Vector Retriever + BM25 Retriever]
                         → RRF Fusion
                         → Retrieved Context
                         → LLM (Ollama)
                         → Final Answer

사전 요구 사항

1. Python 3.9+

2. Ollama가 로컬에 설치 및 실행 중이어야 합니다.

3. 필요한 Ollama 모델:

   • llama3.1:latest (또는 다른 LLM 모델)

   • nomic-embed-text (또는 다른 임베딩 모델)

Ollama 설치

ollama.ai를 방문하여 플랫폼에 맞는 Ollama를 다운로드하고 설치하세요.

설치 후 필요한 모델을 받으세요:

ollama pull llama3.1:latest
ollama pull nomic-embed-text

Ollama가 실행 중인지 확인하세요:

curl http://localhost:11434/api/tags

설치

1. 저장소를 클론하세요:

git clone <your-repo-url>
cd hybrid-rag-project

2. 가상 환경을 만드세요:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 의존성을 설치하세요:

pip install -r requirements.txt

프로젝트 구조

hybrid-rag-project/
├── src/
│   └── hybrid_rag/            # Core application package
│       ├── __init__.py        # Package initialization
│       ├── document_loader.py # Document loading utility
│       ├── structured_query.py# CSV query engine
│       └── utils.py           # Logging and utility functions
├── scripts/
│   ├── run_demo.py            # Main demonstration script
│   ├── mcp_server.py          # REST API server
│   └── mcp_server_claude.py   # MCP server for Claude integration
├── config/
│   ├── config.yaml            # Configuration file
│   └── claude_desktop_config.json # Sample Claude Desktop MCP config
├── docs/
│   ├── INSTALLATION.md        # Detailed installation guide
│   ├── STRUCTURED_QUERIES.md  # CSV query documentation
│   ├── ASYNC_INGESTION.md     # Async ingestion guide
│   └── SHUTDOWN.md            # Shutdown handling guide
├── data/                      # Sample data files (13 files included)
│   ├── *.csv                  # 7 CSV files (structured data)
│   ├── *.md                   # 5 Markdown files (unstructured)
│   └── *.txt                  # 1 Text file (technical specs)
├── chroma_db/                 # Vector store (auto-created)
├── tests/                     # Unit tests
│   └── extract_fields_tests.py
├── setup.py                   # Package setup file
├── requirements.txt           # Python dependencies
├── TESTING_RESULTS.md         # Comprehensive test results
├── CONTRIBUTING.md            # Contribution guidelines
├── CHANGELOG.md               # Version history
├── LICENSE                    # MIT License
└── README.md                  # This file

샘플 데이터(UCSC Extension 프로젝트)

이 저장소에는 데모 및 테스트 목적으로 13개의 샘플 데이터 파일이 포함되어 있습니다. 이 파일들은 TechVision Electronics의 현실적인 비즈니스 시나리오를 나타내며, 다양한 문서 유형에서 시스템의 역량을 보여주도록 설계되었습니다.

📊 포함된 샘플 데이터

정형 데이터(CSV) - 7개 파일:

• product_catalog.csv - 제품 사양이 포함된 제품 카탈로그(5,000행)

• inventory_levels.csv - 재고 수량 및 창고 데이터(10,000행)

• sales_orders_november.csv - 월간 판매 거래(8,000행)

• warranty_claims_q4.csv - 고객 보증 청구(3,000행)

• production_schedule_dec2024.csv - 제조 일정(4,000행)

• supplier_pricing.csv - 공급업체 가격 정보(6,000행)

• shipping_manifests.csv - 배송 및 물류 데이터(5,000행)

비정형 데이터(Markdown) - 5개 파일:

• customer_feedback_q4_2024.md - 고객 리뷰 및 피드백(600개 청크)

• market_analysis_2024.md - 시장 조사 및 동향(400개 청크)

• quality_control_report_nov2024.md - 품질 관리 결과 및 이슈(501개 청크)

• return_policy_procedures.md - 정책 문서(300개 청크)

• support_tickets_summary.md - 기술 지원 요약(700개 청크)

텍스트 데이터 - 1개 파일:

• product_specifications.txt - 기술 사양(334개 청크)

전체 데이터셋:

• 41,000개의 CSV 행(행당 10개씩 청크로 나뉘어 총 41,000개의 문서 생성)

• 2,835개의 텍스트/마크다운 청크(1000자 단위, 200자 오버랩으로 청킹)

• 총 43,835개의 검색 가능한 문서 청크

🎯 목적

이 샘플 파일들은 다음 용도로 포함되어 있습니다:

1. 시스템의 하이브리드 검색 기능 시연

2. 의미(벡터) 검색과 어휘(키워드) 검색 모두 테스트

3. 문서 유형 인식 검색 아키텍처 검증

4. 추가 설정 없이 바로 사용할 수 있는 작동 예제 제공

5. 문서 간 쿼리 종합 소개

📖 테스트 결과

포괄적인 테스트 결과는 TESTING_RESULTS.md에 문서화되어 있으며, 다음을 보여줍니다:

• ✅ 모든 문서 유형에서 100% 검색 성공률

• ✅ 상세 결과가 포함된 17개 테스트 쿼리

• ✅ 성능 지표 및 비교 분석

• ✅ 의미 기반 vs 키워드 vs 하이브리드 검색 비교

💡 샘플 데이터 사용법

빠른 시작:

# 1. Run setup
./setup.sh

# 2. The sample data is already in data/ - ready to use!

# 3. Run the demo
python scripts/run_demo.py

# 4. Or use Claude Desktop
# Configure MCP server and query: "What are the prices in the product catalog?"

프로덕션 사용 시: 자체 데이터를 대신 사용하려면:

1. data/에서 샘플 파일을 제거하거나 백업하세요.

2. 자체 문서를 추가하세요(TXT, PDF, MD, DOCX, CSV).

3. 문서 업로드를 다시 실행하세요.

4. 선택적으로 .gitignore의 데이터 제외 항목 주석을 해제하세요.

## Configuration

All settings are managed in `config/config.yaml`:

```yaml
# Ollama Configuration
ollama:
  base_url: "http://localhost:11434"
  embedding_model: "nomic-embed-text"
  llm_model: "llama3.1:latest"

# Data Configuration
data:
  directory: "./data"
  supported_formats:
    - "txt"
    - "pdf"
    - "md"
    - "docx"
    - "csv"

# Retrieval Configuration
retrieval:
  vector_search_k: 2
  keyword_search_k: 2

# MCP Server Configuration
mcp_server:
  host: "0.0.0.0"
  port: 8000

# Vector Store Configuration
vector_store:
  persist_directory: "./chroma_db"

이 파일을 수정하여 다음을 설정할 수 있습니다:

• 다른 Ollama 모델 사용

• 데이터 디렉터리 위치 변경

• 검색 파라미터(k 값) 조정

• 서버 호스트/포트 구성

• 벡터 저장소의 지속성 위치 변경

사용 방법

옵션 1: 명령줄 스크립트

1. 문서를 data/ 디렉터리에 추가하세요:

cp /path/to/your/documents/*.pdf data/
cp /path/to/your/documents/*.txt data/

2. 스크립트를 실행하세요:

python scripts/run_demo.py

스크립트는 다음 작업을 수행합니다:

• data/ 디렉터리에서 지원되는 모든 문서를 로드

• Ollama 임베딩 및 LLM 초기화

• 벡터 리트리버와 BM25 리트리버 생성

• 하이브리드 RAG 체인 구축

• 샘플 쿼리 실행 및 결과 표시

옵션 2: REST API 서버

1. REST API 서버를 시작하세요:

python scripts/mcp_server.py

서버는 http://localhost:8000에서 시작됩니다.

서버를 중지하려면: 정상 종료를 위해 Ctrl+C를 누르세요.

2. 문서를 업로드하세요(먼저 실행):

curl -X POST http://localhost:8000/ingest

응답:

{
  "status": "success",
  "message": "Documents ingested successfully",
  "documents_loaded": 15
}

3. 문서를 쿼리하세요:

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the main topic of these documents?"}'

응답:

{
  "answer": "Based on the documents...",
  "context": [
    {
      "content": "Document text...",
      "source": "example.pdf",
      "type": ".pdf"
    }
  ]
}

4. 서버 상태를 확인하세요:

curl http://localhost:8000/status

API 엔드포인트

옵션 3: MCP를 통한 Claude Desktop/API

MCP(Model Context Protocol) 서버를 사용하면 Claude가 로컬 RAG 시스템을 직접 쿼리할 수 있습니다.

Claude Desktop 설정

1. 먼저 데이터 디렉터리에 문서를 추가하세요:

cp /path/to/your/documents/*.pdf data/

2. config/claude_desktop_config.json 파일을 편집하여 올바른 절대 경로를 사용하세요:

{
  "mcpServers": {
    "hybrid-rag": {
      "command": "python",
      "args": [
        "/absolute/path/to/hybrid-rag-project/scripts/mcp_server_claude.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/hybrid-rag-project"
      }
    }
  }
}

3. 이 구성을 Claude Desktop에 추가하세요:

   macOS에서:

   # Copy the configuration
   mkdir -p ~/Library/Application\ Support/Claude
   # Edit the file and add your MCP server configuration
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

   Windows에서:

   %APPDATA%\Claude\claude_desktop_config.json

   Linux에서:

   ~/.config/Claude/claude_desktop_config.json

4. Claude Desktop을 다시 시작하세요

5. Claude Desktop에서 MCP 도구를 사용할 수 있습니다. Claude에게 다음과 같이 요청할 수 있습니다:

   • "ingest_documents 도구를 사용해 내 문서를 로드해 줘"

   • "[질문]에 대해 내 문서를 검색해 줘"

   • "RAG 시스템 상태를 확인해 줘"

사용 가능한 MCP 도구

Claude는 다음 도구에 접근할 수 있습니다:

문서 업로드 및 검색:

• ingest_documents: data/ 디렉터리에서 문서를 비동기적으로 로드하고 색인화합니다.

• get_ingestion_status: 문서 업로드 진행 상황(백분율, 현재 파일, 단계)을 모니터링합니다.

• query_documents: 색인된 문서를 하이브리드 검색(의미 + 키워드)으로 쿼리합니다.

• get_status: RAG 시스템 상태를 확인합니다.

구조화된 데이터 쿼리(CSV 파일용):

• list_datasets: 사용 가능한 모든 CSV 데이터셋을 열과 행 수와 함께 나열합니다.

• count_by_field: 필드가 특정 값과 일치하는 행 수를 계산합니다(예: "이름이 Michael인 사람 수").

• filter_dataset: 필드 조건과 일치하는 모든 행을 가져옵니다(예: "Company X의 모든 인원").

• get_dataset_stats: 데이터셋에 대한 통계(행, 열, 메모리 사용량)를 가져옵니다.

진행 상황 추적 기능을 갖춘 비동기 업로드

업로드 프로세스는 실시간 진행 상황 업데이트와 함께 비동기적으로 실행됩니다:

• 비차단(Non-blocking): 업로드가 백그라운드에서 실행됩니다.

• 진행률 추적: 완료 백분율(0~100%) 확인

• 파일 수준 업데이트: 현재 처리 중인 파일 확인

• 단계 정보: 파일 로드(080%) → 인덱스 구축(80100%) → 완료

• 상태 모니터링: get_ingestion_status로 언제든지 진행 상황 확인

Claude 사용 예시

You: "Please start ingesting my documents"
Claude: [Uses ingest_documents tool]
        "Ingestion started. Use get_ingestion_status to monitor progress."

You: "Check the ingestion status"
Claude: [Uses get_ingestion_status tool]
        "Ingestion Status: In Progress
         Progress: 45%
         Stage: loading_files
         Files Processed: 9/20
         Current File: document.pdf
         Documents Loaded: 15"

You: "Check status again"
Claude: [Uses get_ingestion_status tool]
        "Ingestion Status: Completed ✅
         Progress: 100%
         Total Files Processed: 20
         Total Documents Loaded: 35

         You can now use query_documents to search the documents."

You: "What are the main topics in my documents?"
Claude: [Uses query_documents tool with your question]
        "Based on the documents, the main topics are..."

구조적 데이터 쿼리

CSV 파일의 경우 정확한 개수와 필터링을 위해 구조화된 쿼리 도구를 사용하세요:

You: "List available datasets"
Claude: [Uses list_datasets tool]
        "Available Datasets:
         📊 contacts
            Rows: 24,697
            Columns (7): First Name, Last Name, URL, Email Address, Company, Position, Connected On"

You: "Count how many people are named Michael in the contacts dataset"
Claude: [Uses count_by_field tool with dataset="contacts", field="First Name", value="Michael"]
        "Count Result:
         Dataset: contacts
         Field: First Name
         Value: Michael
         Count: 226 out of 24,697 total rows (0.92%)"

You: "Show me all the Michaels"
Claude: [Uses filter_dataset tool]
        "Filter Results:
         Found: 226 rows
         Showing: 100 rows (truncated to 100)

         [1] First Name: Michael | Last Name: Randel | Company: Randel Consulting Associates ..."

각 접근 방식을 사용해야 하는 경우:

• 구조화된 쿼리(count_by_field, filter_dataset): 정확한 개수, 필터링, 정형 데이터가 필요한 경우

• 의미 기반 검색(query_documents): 개념 질문, 내용 이해, 요약이 필요한 경우

지원되는 파일 형식

시스템은 다음 형식의 파일을 자동으로 로드하고 처리합니다:

• .txt - 일반 텍스트 파일

• .pdf - PDF 문서

• .md - 마크다운 파일

• .docx - Microsoft Word 문서

• .csv - CSV 파일

data/ 디렉터리에 지원되는 파일을 넣기만 하면 됩니다!

동작 원리

문서 로드

DocumentLoaderUtility 클래스는:

1. data/ 디렉터리를 재귀적으로 스캔합니다.

2. 지원되는 파일 형식을 식별합니다.

3. 각 형식에 적합한 로더를 사용합니다.

4. 각 문서에 메타데이터(소스 파일, 파일 형식)를 추가합니다.

5. 인덱싱 준비가 된 Document 객체 목록을 반환합니다.

하이브리드 검색

EnsembleRetriever는 RRF(Reciprocal Rank Fusion)를 사용하여:

1. 벡터 검색(의미 기반)에서 상위 k개 결과를 검색합니다.

2. BM25 검색(키워드 기반)에서 상위 k개 결과를 검색합니다.

3. 각 결과에 역순위 점수를 할당합니다.

4. 점수를 결합하여 통합 순위를 생성합니다.

5. 전체적으로 가장 관련성이 높은 문서를 반환합니다.

이 방식은 다음을 처리합니다:

• 의미 기반 쿼리("휴가 신청은 어떻게 하나요?")

• 키워드 검색 쿼리("PTO 양식 HR-42")

• 두 방식 모두의 이점이 필요하는 복잡한 쿼리

사용자 지정

다른 모델 사용

config/config.yaml을 편집하여 모델을 변경하세요:

ollama:
  embedding_model: "your-embedding-model"
  llm_model: "your-llm-model"

검색 파라미터 조정

config/config.yaml의 k 값을 수정하세요:

retrieval:
  vector_search_k: 5   # Return top 5 from semantic search
  keyword_search_k: 5  # Return top 5 from keyword search

더 많은 파일 형식 지원 추가

src/hybrid_rag/document_loader.py를 편집하여 로더를 더 추가하세요:

self.supported_loaders = {
    '.txt': TextLoader,
    '.pdf': PyPDFLoader,
    '.json': JSONLoader,  # Add this
    # ... more formats
}

프롬프트 사용자 지정

scripts/run_demo.py 또는 scripts/mcp_server.py의 프롬프트 템플릿을 편집하세요:

prompt = ChatPromptTemplate.from_template("""
Your custom prompt here...

<context>
{context}
</context>

Question: {input}
""")

개발 워크플로우

1. data/ 디렉터리에 문서를 추가하세요

2. 필요에 따라 config/config.yaml에서 설정을 수정하세요

3. 명령줄로 테스트: python scripts/run_demo.py

4. MCP 서버 배포: python scripts/mcp_server.py

5. API를 통해 여러분의 애플리케이션에 통합하세요

문제 해결

"Error connecting to Ollama" 오류

• Ollama가 설치되어 실행 중인지 확인하세요.

• 구성된 URL에서 Ollama 서비스에 연결할 수 있는지 확인하세요.

• 모델이 다운로드되었는지 확인하세요: ollama list

"No documents found in data directory" 오류

• data/ 디렉터리에 파일을 추가하세요.

• 파일이 지원되는 확장자(.txt, .pdf, .md, .docx, .csv)인지 확인하세요.

• config/config.yaml의 데이터 디렉터리 경로가 올바른지 확인하세요.

"ModuleNotFoundError" 오류

• 가상 환경이 활성화되어 있는지 확인하세요: source .venv/bin/activate

• 의존성을 다시 설치하세요: pip install -r requirements.txt

검색 결과가 좋지 않을 때

• data/ 디렉터리에 관련 문서를 더 추가하세요.

• config/config.yaml의 k 값을 조정하세요.

• 다른 임베딩 모델을 사용해 보세요.

• 쿼리 용어가 문서 내용과 일치하는지 확인하세요.

API 오류

• /ingest를 /query보다 먼저 호출해야 합니다

• 자세한 오류 메시지는 서버 로그를 확인하세요

• Ollama가 실행 중이고 접근 가능한지 확인하세요

• 문서가 성공적으로 로드되었는지 확인하세요

예시: 전체 워크플로우

# 1. Activate environment
source .venv/bin/activate

# 2. Add your documents
cp ~/my-docs/*.pdf data/

# 3. Start MCP server
python scripts/mcp_server.py &

# 4. Ingest documents
curl -X POST http://localhost:8000/ingest

# 5. Query your documents
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Summarize the key points"}'

# 6. Check status
curl http://localhost:8000/status

의존성

핵심 라이브러리:

• langchain: LLM 애플리케이션용 프레임워크

• langchain-community: 커뮤니티 통합

• langchain-ollama: Ollama 통합

• chromadb: 임베딩용 벡터 데이터베이스

• rank-bm25: 키워드 검색용 BM25 구현

• fastapi: API용 웹 프레임워크

• uvicorn: ASGI 서버

• pyyaml: YAML 구성 파싱

문서 로더:

• pypdf: PDF 처리

• python-docx: Word 문서 처리

• unstructured: Markdown 및 기타 형식

성능 팁

1. 벡터 저장소 영구화: 벡터 저장소는 수집 후 디스크(chroma_db/)에 영구 저장되므로 이후 쿼리가 더 빨라집니다.

2. 배치 처리: 문서를 많이 추가할 때는 /ingest 엔드포인트를 여러 번 호출하지 말고 한 번만 호출하세요.

3. 검색 매개변수: k 값을 낮추면(예: 2-3) 더 빠르며 작은 문서 세트에는 종종 충분합니다.

4. 모델 선택: 더 작은 임베딩 모델은 더 빠르지만 정확도가 다소 떨어질 수 있습니다.

라이선스

이 프로젝트는 교육 및 데모 목적으로 있는 그대로 제공됩니다.

기여

개선 사항이 있으면 언제든지 이슈를 제출하고, 저장소를 포크하고, 풀 리퀘스트를 생성하세요.

리소스

• LangChain 문서

• Ollama 문서

• ChromaDB 문서

• FastAPI 문서

• BM25 알고리즘

• 상호 순위 융합

변경 로그

버전 2.0.0

• 모든 문서에서 작동하도록 시스템 일반화

• 문서 수집을 위한 data/ 디렉토리 추가

• 다중 형식 지원을 위한 DocumentLoaderUtility 생성

• Python 모범 사례를 따르도록 프로젝트 재구성(src 레이아웃)

• 모든 구성을 config/ 디렉토리로 이동

• 모든 문서를 docs/ 디렉토리로 이동

• setup.py로 적절한 Python 패키지 구조 생성

• 스크립트를 scripts/ 디렉토리로 정리

• 모든 import 경로 및 문서 업데이트

버전 1.0.0

• 샘플 HR 문서로 초기 구현

• 벡터 및 BM25 검색기를 사용한 기본 하이브리드 검색