hgzero/rag/docs/README.md

Vector DB 통합 시스템

개요

회의록 작성 시스템을 위한 Vector DB 기반 용어집 및 관련자료 검색 시스템

주요 기능

1. 용어집 (Term Glossary)

   • PostgreSQL + pgvector 기반
   • 맥락 기반 용어 설명 제공
   • Claude AI 연동

2. 관련자료 (Related Documents)

   • Azure AI Search 기반 (별도 인덱스)
   • Hybrid Search + Semantic Ranking
   • 회의록 유사도 검색

기술 스택

• Python 3.11+
• FastAPI (REST API)
• PostgreSQL + pgvector (용어집)
• Azure AI Search (관련자료)
• Azure OpenAI (Embedding)
• Claude 3.5 Sonnet (LLM)
• Redis (캐싱)

프로젝트 구조

vector/
├── src/
│   ├── models/        # 데이터 모델
│   ├── db/            # DB 연동 (PostgreSQL, Azure Search)
│   ├── services/      # 비즈니스 로직
│   ├── api/           # REST API
│   └── utils/         # 유틸리티 (임베딩, 설정 등)
├── scripts/           # 초기화 및 데이터 로딩 스크립트
└── tests/             # 테스트

설치 및 실행

1. 환경 설정

# .env 파일 생성
cp .env.example .env

# .env 파일을 열어 실제 API 키 및 데이터베이스 정보 입력
# - POSTGRES_* (PostgreSQL 접속 정보)
# - AZURE_OPENAI_* (Azure OpenAI API 키 및 엔드포인트)
# - AZURE_SEARCH_* (Azure AI Search API 키 및 엔드포인트)
# - CLAUDE_API_KEY (Claude API 키)

2. 의존성 설치

# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 패키지 설치
pip install -r requirements.txt

3. 설정 검증

# 모든 설정이 올바른지 확인
python scripts/validate_setup.py

4. 데이터 로딩

# 용어집 데이터 로딩 (PostgreSQL 테이블 자동 생성 및 데이터 삽입)
python scripts/load_terms.py

# 관련자료 데이터 로딩 (Azure AI Search 인덱스 생성 및 데이터 업로드)
python scripts/load_documents.py

5. API 서버 실행

# 방법 1: 직접 실행
python -m src.api.main

# 방법 2: uvicorn 사용 (개발 모드)
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

6. API 문서 확인

브라우저에서 다음 주소로 접속:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API 엔드포인트

용어집 API

• POST /api/terms/search - 용어 검색
• GET /api/terms/{term_id} - 용어 상세 조회
• POST /api/terms/{term_id}/explain - 맥락 기반 용어 설명 (Claude AI)

관련자료 API

• POST /api/documents/search - 관련 문서 검색 (Hybrid Search)
• GET /api/documents/related/{meeting_id} - 관련 회의록 추천
• POST /api/documents/{doc_id}/summarize - 유사 내용 요약 (Claude AI)

테스트

설정 검증 테스트

# 환경 설정 및 의존성 확인
python scripts/validate_setup.py

데이터 로딩 테스트

# 데이터 파일 로드 및 임베딩 생성 검증
python tests/test_data_loading.py

API 테스트

# API 서버가 실행 중인 상태에서:
pytest tests/test_api.py -v

자세한 테스트 가이드는 TESTING.md 참조

문서

• TESTING.md - 상세한 테스트 가이드 및 문제 해결
• IMPLEMENTATION_SUMMARY.md - 구현 완료 보고서
• 용어집 구현방안
• 관련자료 구현방안
• 아키텍처 최적안 결정