폐쇄 루프 에이전트(Closed-Loop Agents)를 활용한 고급 검색 증강 생성 (RAG)

취약한 파이프라인에서 프로덕션 준비 완료된 시스템으로

특징 • 아키텍처 • 설치 • 사용법 • 기술 심층 분석

이 프로젝트는 전통적인 검색 증강 생성 (RAG)을 넘어선 프로덕션 준비 완료된 자가 치유 RAG (Self-Healing RAG) 시스템을 구현합니다. 표준 RAG의 취약한 개방 루프 (open-loop) 아키텍처와 달리, 이 시스템은 모든 단계에서 폐쇄 루프 (closed-loop) 피드백을 구현하여 오류를 자율적으로 탐지하고 수정합니다.

표준 RAG 시스템이 프로덕션 환경에서 실패하는 이유는 다음과 같습니다:

모달리티 불일치 (Modality Mismatch): 짧은 질의(query)가 긴 문서와 잘 맞지 않음
맹목적 신뢰 (Blind Trust): 검색된 문서의 관련성에 대한 검증 부재
오류 전파 (Error Propagation): 검색(retrieval) → 생성(generation) 단계로 실수가 연쇄적으로 발생
정적 프롬프트 (Static Prompts): 성공적인 상호작용으로부터의 학습 부재

다음 기능을 갖춘 자가 치유 시스템:

• ✅ HyDE: 더 나은 검색을 위해 가설 문서(hypothetical documents) 생성
• ✅ 질의 분해 (Query Decomposition): 복잡한 질의를 원자적 하위 질문(atomic sub-questions)으로 분해
• ✅ CRAG: 문서를 검증하고 폴백(fallback) 전략 트리거
• ✅ 교차 인코더 재순위화 (Cross-Encoder Reranking): 정밀한 문서 점수 산정
• ✅ 동적 학습 (Dynamic Learning): 성공적인 질의-답변 쌍으로부터 학습

HyDE (Hypothetical Document Embeddings): 재현율(recall)을 15-30% 향상
질의 분해 (Query Decomposition): 다중 부분 비교 질문 처리
자동 질의 재작성 (Automatic Query Rewriting): 검색 엔진에 최적화

CRAG (Corrective RAG): 3단계 문서 검증 (정확/모호/부정확)
웹 검색 폴백 (Web Search Fallback): 필요 시 자동 외부 검색 수행
관련성 등급 산정 (Relevance Grading): LLM 기반 문서 품질 평가

2단계 검색 (Two-Stage Retrieval): Bi-encoder 재현율 + Cross-encoder 재순위화
하이브리드 아키텍처 (Hybrid Architecture): 속도 (O(n))와 정확도의 균형
설정 가능한 Top-K (Configurable Top-K): 유연한 결과 집합 크기

동적 퓨샷 (Dynamic Few-Shot): 사용자 피드백으로부터 학습
예시 라이브러리 (Example Library): 성공적인 질의-답변 패턴 저장
피드백 루프 (Feedback Loop): 품질 향상을 위한 👍/👎 통합

실시간 플레이그라운드 (Real-Time Playground): 실시간 결과로 질의 테스트
아키텍처 다이어그램 (Architecture Diagrams): 대화형 Mermaid 시각화
통계 대시보드 (Statistics Dashboard): 시스템 성능 지표
기술 문서 (Technical Documentation): 포괄적인 가이드

┌─────────────────────────────────────────────────────────────┐
│ User Query Input │
└─────────────────────┬───────────────────────────────────────┘
...

• Python 3.10+
• Node.js 18+
• OpenAI API Key

# 저장소 복제 (Clone the repository)
git clone <your-repo>
cd self-healing-RAG
...

# 프론트엔드 디렉토리로 이동 (Navigate to frontend directory)
cd frontend
# Node 의존성 설치 (Install Node dependencies)
...

옵션 1: 시작 스크립트 사용 (권장) (Option 1: Use the startup script (Recommended))

chmod +x start.sh
./start.sh

옵션 2: 수동 시작 (Option 2: Manual startup)

터미널 1 (백엔드) (Terminal 1 (Backend)):

source .venv/bin/activate
cd backend
python api_server.py

터미널 2 (프론트엔드) (Terminal 2 (Frontend)):

cd frontend
npm run dev

프론트엔드 (Frontend): http://localhost:3000
API 문서 (API Docs): http://localhost:8000/docs
API 상태 (API Health): http://localhost:8000/api/health

플레이그라운드 탭 (Playground Tab): 질의를 입력하고 실시간 결과 확인
아키텍처 탭 (Architecture Tab): 대화형 시스템 다이어그램 탐색
문서 탭 (Documentation Tab): 각 기술에 대해 학습
통계 탭 (Statistics Tab): 시스템 성능 모니터링

단순 예시 (Simple):
- "RAG란 무엇이며 어떻게 작동하나요?"
- "HyDE 기술을 설명해주세요"
...

backend/api_server.py 수정:

# 웹 검색 활성화 (Tavily API 키 필요) (Enable web search (requires Tavily API key))
rag_system = SelfHealingRAGSystem(
openai_api_key=openai_api_key,
...

포트 변경을 위해 frontend/vite.config.js 수정:

export default defineConfig({
server: {
port: 3000, // 프론트엔드 포트 변경 (Change frontend port)
...

모든 기술은 Playground UI에서 토글할 수 있습니다:

HyDE: 가설적 문서 생성 (Hypothetical Document Generation) 토글
Decomposition: 쿼리 분할 (Query Splitting) 활성화/비활성화
CRAG: 검증 (Validation) 켜기/끄기
Reranking: 교차 인코더 (Cross-encoder) 정밀도 사용
Learning: 동적 퓨샷 예시 (Dynamic Few-shot Examples) 적용

문제 (Problem): 쿼리는 짧고 문서는 길다 → 의미론적 매칭 (Semantic Match) 저하

해결책 (Solution): 가설적 답변을 생성한 후, 그와 유사한 문서를 검색

# 전통적 방식: "CRAG는 어떻게 작동하나요?" → 벡터 검색 (Vector Search)
# HyDE: "CRAG는 어떻게 작동하나요?" → LLM이 가설적 답변 생성 → 벡터 검색 (Vector Search)

장점 (Benefits):

• 모달리티 간극 (Modality Gap) 해소
• 재현율 (Recall) 15-30% 향상
• 임베딩 (Embeddings) 재학습 없이 작동

문제 (Problem): "X와 Y를 비교하라"와 같은 복잡한 쿼리는 비교 정보를 찾는 데 실패함

해결책 (Solution): 원자적 하위 쿼리 (Atomic Sub-queries)로 분해

입력: "코딩에 있어서 Llama-3와 GPT-4 중 어느 것이 더 나은가요?"
하위 쿼리 (Sub-Queries):
1. "Llama-3의 코딩 능력 및 벤치마크"
...

문제 (Problem): 표준 RAG는 검색된 문서를 맹목적으로 신뢰함

해결책 (Solution): 관련성을 등급화하고 폴백 (Fallback) 트리거

for document in retrieved_docs:
    grade = llm.grade(document, query)
    if grade == "correct":
        ...

세 가지 상태 (Three States):

• ✅ 정확함 (Correct): 그대로 사용 - ⚡
• ⚠️ 모호함 (Ambiguous): 지식 정제 (Knowledge Refinement) 적용 - ❌
• ❌ 부정확함 (Incorrect): 웹 검색 폴백 (Web Search Fallback)

2단계 전략 (Two-Stage Strategy):

1단계 (Stage 1): 바이 인코더 (Bi-Encoder)
├─ 쿼리와 문서를 각각 인코딩
├─ 빠른 코사인 유사도 (Cosine Similarity): O(n)
...

작동 원리 (Why This Works):

• 광범위한 재현율 (Recall)을 위한 바이 인코더 (Bi-encoder)의 속도
• 최종 순위 산정 (Ranking)을 위한 크로스 인코더 (Cross-encoder)의 정확도
• 두 아키텍처의 장점을 결합

워크플로우 (Workflow):

# 사용자가 좋은 답변에 👍를 누름
system.add_feedback(query, answer, is_positive=True)
# 시스템이 벡터 인덱스 (Vector Index)에 저장
...

장점 (Benefits):

• 재학습 없는 지속적인 개선
• 도메인 특화 지식 축적
• 환각 (Hallucinations) 감소

• 단순 쿼리 (Simple Query): ~1.5s

• 복합 쿼리 (Complex Query, 분해 포함): ~3.2s

• 웹 폴백 (Web Fallback) 포함: ~4.5s

• HyDE 생성 (HyDE Generation): ~500ms

• 벡터 검색 (Vector Retrieval): ~50ms

• CRAG 검증 (CRAG Validation): ~800ms

• 교차 인코더 재순위화 (Cross-Encoder Reranking): ~200ms

• 답변 생성 (Answer Generation): ~1.2s

POST /api/query
Content-Type: application/json
{
...

응답 (Response):

{
"query": "CRAG는 어떻게 작동하나요?",
"answer": "CRAG (Corrective RAG)는 자가 수정...",
...

POST /api/feedback
Content-Type: application/json
{
...

GET /api/statistics

응답 (Response):

{
"system_stats": {
"total_queries": 45,
...

# 개별 컴포넌트 테스트
pytest backend/tests/test_hyde.py
pytest backend/tests/test_crag.py
...

# 전체 파이프라인 테스트
pytest backend/tests/test_integration.py

cd frontend
npm run test

벡터 데이터베이스 (Vector Database): 인메모리 인덱스를 Pinecone/Weaviate로 교체
캐싱 (Caching): HyDE 가상 문서 (hypothetical documents) 캐싱
속도 제한 (Rate Limiting): API 속도 제한 구현
모니터링 (Monitoring): Prometheus/Grafana 메트릭 추가
확장성 (Scaling): 세션 관리를 위해 Redis 사용
보안 (Security): 인증/인가 (authentication/authorization) 추가

docker-compose up -d

기여(Contributions)를 환영합니다! 개선 분야:

• 더 많은 임베딩 모델 (embedding models) 지원 추가
• DSPy 자동 최적화 구현
• 스트리밍 응답 (streaming responses) 추가
• 다국어 지원 (Multi-language support)
• 도메인 데이터 기반 교차 인코더 (cross-encoders) 미세 조정 (Fine-tuning)

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요

질문이나 이슈가 있는 경우:

• GitHub에 이슈(issue) 생성
• 앱 내 문서(documentation) 확인
• 대화형 아키텍처 다이어그램 검토

프로덕션 수준의 RAG 시스템을 요구하는 기술 전문가들을 위해 구축되었습니다

⭐ 유용하다고 생각되면 이 저장소(repo)에 별(Star)을 눌러주세요!