From 2481fa907bd3982ec4a5c9c3702f94cb97a2027f Mon Sep 17 00:00:00 2001
From: djeon <daewoong.jeon@kt.com>
Date: Thu, 30 Oct 2025 11:26:23 +0900
Subject: [PATCH] feat: rag md file

---
 rag/docs/README.md | 132 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 rag/docs/README.md

diff --git a/rag/docs/README.md b/rag/docs/README.md
new file mode 100644
index 0000000..3c35e6e
--- /dev/null
+++ b/rag/docs/README.md
@@ -0,0 +1,132 @@
+# 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. 환경 설정
+```bash
+# .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. 의존성 설치
+```bash
+# 가상환경 생성 (권장)
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# venv\Scripts\activate   # Windows
+
+# 패키지 설치
+pip install -r requirements.txt
+```
+
+### 3. 설정 검증
+```bash
+# 모든 설정이 올바른지 확인
+python scripts/validate_setup.py
+```
+
+### 4. 데이터 로딩
+```bash
+# 용어집 데이터 로딩 (PostgreSQL 테이블 자동 생성 및 데이터 삽입)
+python scripts/load_terms.py
+
+# 관련자료 데이터 로딩 (Azure AI Search 인덱스 생성 및 데이터 업로드)
+python scripts/load_documents.py
+```
+
+### 5. API 서버 실행
+```bash
+# 방법 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)
+
+## 테스트
+
+### 설정 검증 테스트
+```bash
+# 환경 설정 및 의존성 확인
+python scripts/validate_setup.py
+```
+
+### 데이터 로딩 테스트
+```bash
+# 데이터 파일 로드 및 임베딩 생성 검증
+python tests/test_data_loading.py
+```
+
+### API 테스트
+```bash
+# API 서버가 실행 중인 상태에서:
+pytest tests/test_api.py -v
+```
+
+자세한 테스트 가이드는 [TESTING.md](TESTING.md) 참조
+
+## 문서
+- [TESTING.md](TESTING.md) - 상세한 테스트 가이드 및 문제 해결
+- [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - 구현 완료 보고서
+- [용어집 구현방안](../design/구현방안-용어집.md)
+- [관련자료 구현방안](../design/구현방안-관련자료.md)
+- [아키텍처 최적안 결정](../design/아키텍처_최적안_결정.md)