RAG 검색 시스템

Ollama, Qdrant, PostgreSQL을 Docker로 구동하는 RAG(Retrieval-Augmented Generation) 검색 시스템입니다.

주요 기능

• 📄 문서 업로드: PDF, DOCX, TXT 파일 지원
• 🔍 의미 기반 검색: Qdrant 벡터 DB를 활용한 유사도 검색
• 🤖 AI 답변 생성: Ollama를 통한 로컬 LLM 기반 답변
• 📊 문서 관리: 업로드된 문서 목록 및 삭제 기능
• 📈 검색 히스토리: 쿼리 기록 및 통계

기술 스택

백엔드

• FastAPI: Python 웹 프레임워크
• PostgreSQL: 문서 메타데이터 및 검색 히스토리 저장
• Qdrant: 벡터 임베딩 저장 및 유사도 검색
• Ollama: 로컬 LLM 실행 (임베딩 + 텍스트 생성)

프론트엔드

• Next.js 15: React 프레임워크
• React 19: 최신 React 버전
• TypeScript: 타입 안정성
• Tailwind CSS: 스타일링

시작하기

필수 요구사항

• Docker & Docker Compose
• 최소 8GB RAM (LLM 모델 실행 위해)
• (선택) NVIDIA GPU (더 빠른 추론을 위해)

설치 및 실행 (간단 버전)

# 1. 서비스 시작
./start.sh

# 2. 모델 다운로드 (처음 한 번만, 약 5-10분 소요)
./download-models.sh

# 3. 브라우저에서 http://localhost:3000 접속

기타 유용한 명령어

./stop.sh          # 서비스 중지
./logs.sh          # 로그 확인 (Ctrl+C로 종료)
docker-compose ps  # 서비스 상태 확인

서비스 접속 URL

• 프론트엔드: http://localhost:3000
• 백엔드 API: http://localhost:8000
• API 문서: http://localhost:8000/docs
• Qdrant 대시보드: http://localhost:6333/dashboard

상세 설치 방법

수동으로 설치하기 (클릭하여 펼치기)

1. 환경 변수 설정

cp .env.example .env

2. Docker 컨테이너 실행

docker-compose up -d

3. Ollama 모델 다운로드

# 임베딩 모델
docker exec rag-ollama ollama pull nomic-embed-text

# LLM 모델
docker exec rag-ollama ollama pull llama3.2

# 또는 더 작은 모델 (리소스가 부족한 경우)
docker exec rag-ollama ollama pull llama3.2:1b

4. 서비스 접속

• 프론트엔드: http://localhost:3000
• 백엔드 API: http://localhost:8000

사용 방법

1. 문서 업로드

1. 웹 UI에서 "Upload" 탭 선택
2. PDF, DOCX, 또는 TXT 파일 선택
3. "업로드" 버튼 클릭
4. 백그라운드에서 자동으로 처리됨:
   • 텍스트 추출
   • 청크 분할
   • 임베딩 생성
   • Qdrant에 저장

2. 문서 검색

1. "Search" 탭에서 질문 입력
2. AI가 업로드된 문서에서 관련 내용을 찾아 답변 생성
3. 참고된 문서 청크와 유사도 점수 확인

3. 문서 관리

1. "Documents" 탭에서 업로드된 문서 목록 확인
2. 처리 상태 확인
3. 불필요한 문서 삭제

프로젝트 구조

wordsearch/
├── docker-compose.yml          # Docker 서비스 정의
├── backend/                    # FastAPI 백엔드
│   ├── main.py                # FastAPI 앱 진입점
│   ├── config.py              # 설정
│   ├── database.py            # DB 연결
│   ├── models.py              # SQLAlchemy 모델
│   ├── services/              # 비즈니스 로직
│   │   ├── qdrant_service.py
│   │   ├── embedding_service.py
│   │   ├── ollama_service.py
│   │   └── document_service.py
│   └── routers/               # API 엔드포인트
│       ├── documents.py
│       └── search.py
├── frontend/                   # Next.js 프론트엔드
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx       # 메인 페이지
│   │   │   └── layout.tsx
│   │   └── components/        # React 컴포넌트
│   │       ├── SearchInterface.tsx
│   │       ├── DocumentUpload.tsx
│   │       └── DocumentList.tsx
│   └── package.json
└── documents/                  # 업로드된 파일 저장 (gitignore)

API 엔드포인트

문서 관리

• POST /documents/upload - 문서 업로드
• GET /documents/ - 문서 목록 조회
• GET /documents/{id} - 특정 문서 조회
• DELETE /documents/{id} - 문서 삭제

검색

• POST /search/query - RAG 검색 수행
• GET /search/history - 검색 히스토리 조회
• GET /search/stats - 검색 통계 조회

헬스체크

• GET /health - 시스템 상태 확인

설정 커스터마이징

다른 LLM 모델 사용

.env 파일에서 모델 변경:

# 더 작은 모델 (빠르지만 정확도 낮음)
LLM_MODEL=llama3.2:1b
EMBEDDING_MODEL=nomic-embed-text

# 더 큰 모델 (느리지만 정확도 높음)
LLM_MODEL=llama3.1:8b
EMBEDDING_MODEL=nomic-embed-text

청크 크기 조정

backend/services/document_service.py에서:

DocumentService(chunk_size=500, chunk_overlap=50)

검색 결과 개수 조정

프론트엔드에서 top_k 값 변경:

{
  query: query,
  top_k: 5,  // 원하는 개수로 변경
  use_rag: true
}

문제 해결

Ollama 모델이 로드되지 않음

# Ollama 컨테이너 로그 확인
docker logs rag-ollama

# 컨테이너 재시작
docker-compose restart ollama

Qdrant 연결 오류

# Qdrant 컨테이너 상태 확인
docker ps | grep qdrant

# 대시보드 접속 확인
curl http://localhost:6333/collections

백엔드 에러

# 백엔드 로그 확인
docker logs rag-backend

# 컨테이너 재시작
docker-compose restart backend

성능 최적화

GPU 사용 (NVIDIA)

docker-compose.yml에서 Ollama 서비스의 GPU 설정 주석 해제:

ollama:
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]

메모리 제한

리소스가 부족한 경우 더 작은 모델 사용:

• llama3.2:1b (약 1GB)
• phi3:mini (약 2GB)

라이센스

MIT

기여

이슈와 PR을 환영합니다!