hgzero/rag/TESTING.md

# Vector DB 통합 시스템 테스트 가이드

## 목차
1. [사전 준비](#사전-준비)
2. [환경 설정](#환경-설정)
3. [데이터베이스 설정](#데이터베이스-설정)
4. [데이터 로딩 테스트](#데이터-로딩-테스트)
5. [API 서버 실행](#api-서버-실행)
6. [API 엔드포인트 테스트](#api-엔드포인트-테스트)
7. [자동화 테스트](#자동화-테스트)
8. [문제 해결](#문제-해결)

---

## 사전 준비

### 필수 소프트웨어
- Python 3.9 이상
- PostgreSQL 14 이상 (pgvector 확장 지원)
- Redis (선택사항, 캐싱용)

### Azure 서비스
- Azure OpenAI Service (임베딩 생성용)
- Azure AI Search (관련 문서 검색용)

---

## 환경 설정

### 1. 가상환경 생성 및 활성화

```bash
cd vector
python -m venv venv

# Linux/Mac
source venv/bin/activate

# Windows
venv\Scripts\activate
```

### 2. 의존성 설치

```bash
pip install -r requirements.txt
```

### 3. 환경 변수 설정

`.env.example` 파일을 `.env`로 복사하고 실제 값으로 수정:

```bash
cp .env.example .env
```

`.env` 파일 수정 예시:

```bash
# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=meeting_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_actual_password

# Azure OpenAI
AZURE_OPENAI_API_KEY=your_actual_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com

# Azure AI Search
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_API_KEY=your_actual_api_key

# Claude AI
CLAUDE_API_KEY=your_actual_claude_api_key

# Redis
REDIS_PASSWORD=your_redis_password
```

---

## 데이터베이스 설정

### 1. PostgreSQL 데이터베이스 생성

```sql
CREATE DATABASE meeting_db;
```

### 2. pgvector 확장 설치

PostgreSQL에 연결 후:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

### 3. 데이터베이스 초기화

용어 데이터 로딩 스크립트를 실행하면 자동으로 테이블이 생성됩니다:

```bash
python scripts/load_terms.py
```

---

## 데이터 로딩 테스트

### 1. 데이터 로딩 검증 테스트

환경 설정 없이도 데이터 파일 로드를 검증할 수 있습니다:

```bash
python tests/test_data_loading.py
```

**예상 출력:**
```
============================================================
Vector DB 데이터 로딩 테스트
============================================================

============================================================
설정 로드 테스트
============================================================
✓ 설정 로드 성공
  - PostgreSQL 호스트: localhost
  - Azure OpenAI 모델: text-embedding-ada-002
  ...

============================================================
용어 데이터 로드 테스트
============================================================
✓ terms-01.json 로드 완료: XX개 용어
✓ terms-02.json 로드 완료: XX개 용어
...

총 XXX개 용어 로드 완료
```

### 2. 용어집 데이터 로딩

```bash
python scripts/load_terms.py
```

**예상 출력:**
```
============================================================
용어집 데이터 로딩 시작
============================================================
✓ 설정 로드 완료
✓ PostgreSQL 연결 완료
✓ 데이터베이스 초기화 완료
✓ 임베딩 생성기 초기화 완료
✓ 총 XXX개 용어 로드 완료
✓ 임베딩 생성 완료
✓ 삽입 완료: 성공 XXX, 실패 0

============================================================
용어집 통계
============================================================
전체 용어: XXX개
평균 신뢰도: X.XX

카테고리별 통계:
  - 기술용어: XX개
  - 비즈니스용어: XX개
  ...
```

### 3. 관련자료 데이터 로딩

```bash
python scripts/load_documents.py
```

**예상 출력:**
```
============================================================
관련자료 데이터 로딩 시작
============================================================
✓ 설정 로드 완료
✓ Azure AI Search 연결 완료
✓ 인덱스 생성 완료
✓ 임베딩 생성기 초기화 완료
✓ 총 XX개 문서 로드 완료
✓ 총 XXX개 청크 생성 완료
✓ XXX개 청크 업로드 완료

============================================================
관련자료 통계
============================================================
전체 문서: XX개
전체 청크: XXX개

문서 타입별 통계:
  - 회의록: XX개
  - 참고자료: XX개
  ...
```

---

## API 서버 실행

### 1. 개발 모드로 실행

```bash
python -m src.api.main
```

또는:

```bash
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
```

### 2. 서버 확인

브라우저에서 접속:
- API 문서: http://localhost:8000/docs
- 대체 API 문서: http://localhost:8000/redoc
- 루트 엔드포인트: http://localhost:8000/

---

## API 엔드포인트 테스트

### 1. 루트 엔드포인트 테스트

```bash
curl http://localhost:8000/
```

**예상 응답:**
```json
{
  "service": "Vector DB 통합 시스템",
  "version": "1.0.0",
  "endpoints": {
    "용어집": "/api/terms/*",
    "관련자료": "/api/documents/*"
  }
}
```

### 2. 용어 검색 테스트

#### 키워드 검색
```bash
curl -X POST http://localhost:8000/api/terms/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "API",
    "search_type": "keyword",
    "top_k": 5,
    "confidence_threshold": 0.7
  }'
```

#### 벡터 검색
```bash
curl -X POST http://localhost:8000/api/terms/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "회의 일정 관리",
    "search_type": "vector",
    "top_k": 3,
    "confidence_threshold": 0.6
  }'
```

#### 하이브리드 검색
```bash
curl -X POST http://localhost:8000/api/terms/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "마이크로서비스",
    "search_type": "hybrid",
    "top_k": 5,
    "confidence_threshold": 0.5
  }'
```

### 3. 용어 상세 조회

먼저 검색으로 용어 ID를 찾은 후:

```bash
curl http://localhost:8000/api/terms/{term_id}
```

### 4. 용어 설명 생성 (Claude AI)

```bash
curl -X POST http://localhost:8000/api/terms/{term_id}/explain \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_context": "백엔드 개발 회의에서 REST API 설계 논의"
  }'
```

### 5. 용어 통계 조회

```bash
curl http://localhost:8000/api/terms/stats
```

### 6. 관련 문서 검색

```bash
curl -X POST http://localhost:8000/api/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "프로젝트 계획",
    "top_k": 3,
    "relevance_threshold": 0.3,
    "semantic_ranking": true
  }'
```

#### 필터링된 검색
```bash
curl -X POST http://localhost:8000/api/documents/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "회의록",
    "top_k": 5,
    "relevance_threshold": 0.3,
    "document_type": "회의록",
    "folder": "프로젝트A",
    "semantic_ranking": true
  }'
```

### 7. 문서 통계 조회

```bash
curl http://localhost:8000/api/documents/stats
```

---

## 자동화 테스트

### 1. pytest 설치 확인

pytest가 requirements.txt에 포함되어 있어야 합니다.

### 2. API 테스트 실행

서버가 실행 중인 상태에서:

```bash
pytest tests/test_api.py -v
```

**예상 출력:**
```
tests/test_api.py::test_root PASSED
tests/test_api.py::test_search_terms_keyword PASSED
tests/test_api.py::test_search_terms_vector PASSED
tests/test_api.py::test_search_terms_hybrid PASSED
tests/test_api.py::test_get_term_stats PASSED
tests/test_api.py::test_search_documents PASSED
tests/test_api.py::test_search_documents_with_filters PASSED
tests/test_api.py::test_get_document_stats PASSED
tests/test_api.py::test_get_nonexistent_term PASSED
tests/test_api.py::test_explain_term PASSED
```

### 3. 개별 테스트 실행

```bash
# 특정 테스트만 실행
pytest tests/test_api.py::test_search_terms_keyword -v

# 테스트 상세 출력
pytest tests/test_api.py -v -s
```

---

## 문제 해결

### 1. PostgreSQL 연결 실패

**증상:**
```
psycopg2.OperationalError: could not connect to server
```

**해결:**
- PostgreSQL이 실행 중인지 확인
- .env 파일의 데이터베이스 접속 정보 확인
- 방화벽 설정 확인

### 2. pgvector 확장 오류

**증상:**
```
psycopg2.errors.UndefinedObject: type "vector" does not exist
```

**해결:**
```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

### 3. Azure OpenAI API 오류

**증상:**
```
openai.error.AuthenticationError: Incorrect API key provided
```

**해결:**
- .env 파일의 AZURE_OPENAI_API_KEY 확인
- Azure Portal에서 API 키 재확인
- API 엔드포인트 URL 확인

### 4. Azure AI Search 인덱스 생성 실패

**증상:**
```
azure.core.exceptions.HttpResponseError: (Unauthorized) Access denied
```

**해결:**
- .env 파일의 AZURE_SEARCH_API_KEY 확인
- Azure Portal에서 API 키 및 권한 확인
- 인덱스 이름 중복 여부 확인

### 5. 임베딩 생성 실패

**증상:**
```
RateLimitError: Rate limit exceeded
```

**해결:**
- Azure OpenAI의 Rate Limit 확인
- 배치 크기를 줄여서 재시도
- 재시도 로직이 자동으로 작동하므로 대기

### 6. Claude API 오류

**증상:**
```
anthropic.APIError: Invalid API Key
```

**해결:**
- .env 파일의 CLAUDE_API_KEY 확인
- API 키 유효성 확인
- 호출 빈도 제한 확인

---

## 성능 테스트

### 1. 검색 응답 시간 측정

```bash
time curl -X POST http://localhost:8000/api/terms/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "API",
    "search_type": "hybrid",
    "top_k": 10
  }'
```

### 2. 동시 요청 테스트

Apache Bench를 사용한 부하 테스트:

```bash
ab -n 100 -c 10 http://localhost:8000/
```

---

## 다음 단계

1. **프로덕션 배포 준비**
   - 환경별 설정 분리 (dev/staging/prod)
   - 로깅 및 모니터링 설정
   - 보안 강화 (API 키 관리, HTTPS)

2. **성능 최적화**
   - Redis 캐싱 활성화
   - 인덱스 튜닝
   - 쿼리 최적화

3. **기능 확장**
   - 사용자 인증/인가
   - 용어 버전 관리
   - 문서 업데이트 자동화

4. **통합 테스트**
   - E2E 테스트 작성
   - CI/CD 파이프라인 구축
   - 자동화된 성능 테스트