shared-dg05-coffeeQuokka/hgzero

Fork 0

mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 13:46:24 +00:00

djeon 5d897cb845 feat: init rag service

2025-10-29 05:54:08 +09:00

10 KiB

Raw Blame History

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

사전 준비

필수 소프트웨어

Python 3.9 이상
PostgreSQL 14 이상 (pgvector 확장 지원)
Redis (선택사항, 캐싱용)

Azure 서비스

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

환경 설정

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

cd vector
python -m venv venv

# Linux/Mac
source venv/bin/activate

# Windows
venv\Scripts\activate

2. 의존성 설치

pip install -r requirements.txt

3. 환경 변수 설정

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

cp .env.example .env

.env 파일 수정 예시:

# 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 데이터베이스 생성

CREATE DATABASE meeting_db;

2. pgvector 확장 설치

PostgreSQL에 연결 후:

CREATE EXTENSION IF NOT EXISTS vector;

3. 데이터베이스 초기화

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

python scripts/load_terms.py

데이터 로딩 테스트

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

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

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. 용어집 데이터 로딩

python scripts/load_terms.py

예상 출력:

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

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

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

3. 관련자료 데이터 로딩

python scripts/load_documents.py

예상 출력:

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

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

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

API 서버 실행

1. 개발 모드로 실행

python -m src.api.main

또는:

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. 루트 엔드포인트 테스트

curl http://localhost:8000/

예상 응답:

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

2. 용어 검색 테스트

키워드 검색

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
  }'

벡터 검색

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
  }'

하이브리드 검색

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를 찾은 후:

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

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

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

5. 용어 통계 조회

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

6. 관련 문서 검색

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
  }'

필터링된 검색

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. 문서 통계 조회

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

자동화 테스트

1. pytest 설치 확인

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

2. API 테스트 실행

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

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. 개별 테스트 실행

# 특정 테스트만 실행
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

해결:

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. 검색 응답 시간 측정

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를 사용한 부하 테스트:

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

다음 단계

프로덕션 배포 준비
- 환경별 설정 분리 (dev/staging/prod)
- 로깅 및 모니터링 설정
- 보안 강화 (API 키 관리, HTTPS)
성능 최적화
- Redis 캐싱 활성화
- 인덱스 튜닝
- 쿼리 최적화
기능 확장
- 사용자 인증/인가
- 용어 버전 관리
- 문서 업데이트 자동화
통합 테스트
- E2E 테스트 작성
- CI/CD 파이프라인 구축
- 자동화된 성능 테스트

10 KiB Raw Blame History

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

목차

사전 준비

필수 소프트웨어

Azure 서비스

환경 설정

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

2. 의존성 설치

3. 환경 변수 설정

데이터베이스 설정

1. PostgreSQL 데이터베이스 생성

2. pgvector 확장 설치

3. 데이터베이스 초기화

데이터 로딩 테스트

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

2. 용어집 데이터 로딩

3. 관련자료 데이터 로딩

API 서버 실행

1. 개발 모드로 실행

2. 서버 확인

API 엔드포인트 테스트

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

2. 용어 검색 테스트

키워드 검색

벡터 검색

하이브리드 검색

3. 용어 상세 조회

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

5. 용어 통계 조회

6. 관련 문서 검색

필터링된 검색

7. 문서 통계 조회

자동화 테스트

1. pytest 설치 확인

2. API 테스트 실행

3. 개별 테스트 실행

문제 해결

1. PostgreSQL 연결 실패

2. pgvector 확장 오류

3. Azure OpenAI API 오류

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

5. 임베딩 생성 실패

6. Claude API 오류

성능 테스트

1. 검색 응답 시간 측정

2. 동시 요청 테스트

다음 단계

10 KiB

Raw Blame History