LADR 지식그래프 시스템

Linear Algebra Done Right (LADR) 교재에서 수학적 엔티티를 추출하여 지식그래프를 구축하고 검색하는 시스템입니다.

🎯 주요 기능

• 스마트 PDF 엔티티 추출: 3페이지 슬라이딩 윈도우로 페이지 경계에서 누락되는 엔티티 방지
• 지능형 중복 제거: 벡터 유사도와 텍스트 분석을 통한 자동 중복 엔티티 정리
• Neo4j 지식그래프: 수학적 개념 간의 관계를 그래프로 구조화
• 웹 인터페이스: PDF 뷰어와 채팅을 결합한 학습 도구
• 하이브리드 검색: 텍스트, 벡터, 그래프 검색을 조합한 통합 검색
• 스마트 그래프 쿼리: Text-to-Cypher 실패시 자동 쿼리 수정 및 재시도
• 페이지 제약 기능: 교육적 맥락에서 특정 페이지 이전 내용만 참조

🏗️ 시스템 아키텍처

시스템은 다음과 같은 5단계 파이프라인으로 구성됩니다:

1. PDF 처리

• 3페이지 윈도우: 현재 페이지와 전후 페이지를 함께 분석하여 컨텍스트 유지
• 슬라이딩 추출: 페이지 경계에서 누락되는 엔티티 방지
• 경계 보완: 페이지 간 연결된 개념들을 자동으로 식별하고 병합

2. LLM 엔티티 추출

• GPT-4 분석: 수학적 엔티티의 정확한 식별과 분류
• 구조화된 응답: JSON 형태로 정의, 정리, 증명, 예제 등을 체계적으로 추출
• 신뢰도 평가: 각 엔티티의 추출 품질을 자동 평가

3. Neo4j 저장

• 노드 생성: 추출된 엔티티를 그래프 데이터베이스에 노드로 저장
• 관계 매핑: 엔티티 간의 의미적 관계를 자동으로 구축
• 벡터 임베딩: 텍스트 검색과 유사도 계산을 위한 임베딩 생성

4. 중복 제거

• 벡터 유사도: 임베딩 기반으로 유사한 엔티티 자동 탐지
• 텍스트 분석: 이름과 내용의 유사성을 다각도로 분석
• 자동 정리: 중복된 엔티티를 병합하고 참조 관계 정리

5. 통합 검색 시스템

• 하이브리드 검색: 텍스트, 벡터, 그래프 검색을 조합하여 최적의 결과 제공
• 텍스트 검색: 키워드 기반 정확한 매칭
• 벡터 검색: 의미 기반 유사 개념 탐색
• 스마트 그래프: Text-to-Cypher를 통한 복잡한 관계 쿼리
• 웹 인터페이스: PDF 뷰어, 채팅 시스템, 관리자 도구를 통합한 학습 환경

📁 프로젝트 구조

ladr-graph/
├── main.py                    # 웹 애플리케이션 실행
├── extract_entities.py        # 엔티티 추출 + 중복 제거
├── clear_db.py               # 데이터베이스 클리어
├── src/
│   ├── config.py             # 설정 관리
│   ├── extractor/            # 엔티티 추출 모듈
│   ├── graphdb/              # Neo4j 연동
│   ├── rag/                  # 검색 및 QA 시스템
│   ├── web/                  # 웹 애플리케이션
│   └── scripts/              # 실제 실행 스크립트
│       ├── extract_entities.py  # 추출 로직
│       └── remove_duplicates.py # 중복 제거
├── book/                     # PDF 파일
├── config/                   # 설정 파일
├── logs/                     # 로그 파일
└── tests/                    # 테스트

🚀 빠른 시작

1. 환경 설정

# 저장소 클론
git clone <repository-url>
cd ladr-graph

# Python 가상환경 생성 (uv 사용)
uv venv
source .venv/bin/activate

# 의존성 설치
uv pip install -r requirements.txt

2. 환경 변수 설정

# .env 파일 생성
export OPENAI_API_KEY="your_openai_api_key"
export NEO4J_PASSWORD="your_neo4j_password"

3. PDF 파일 준비

# book 디렉토리에 LADR PDF 파일 배치
mkdir -p book
# LADR PDF 파일을 book/ 디렉토리에 복사

4. 실행

# Neo4j 시작 (Docker)
docker-compose up neo4j -d

# 웹 애플리케이션 실행
python main.py

# 브라우저에서 http://localhost:8000 접속

📖 사용법

웹 인터페이스 (추천)

python main.py

• PDF 뷰어: 교재를 직접 확인
• 채팅 시스템: 질문하고 답변 받기
• 텍스트 선택: PDF에서 텍스트 선택 후 바로 질문
• 이미지 캡처 질문: PDF의 수식이나 다이어그램을 캡처해서 AI에게 직접 질문
• 관리자 페이지: http://localhost:8000/admin (엔티티 추출 및 관리)

이미지 캡처 질문 기능

PDF의 복잡한 수식이나 다이어그램을 이미지로 캡처해서 AI에게 직접 질문할 수 있습니다:

관리자 대시보드

시스템 관리와 모니터링을 위한 관리자 인터페이스를 제공합니다:

추출 관리 기능:

• 엔티티 추출 상태 모니터링
• 추출 작업 시작/중지 제어
• 데이터베이스 통계 확인
• 실시간 로그 확인

지식그래프 시각화:

• Neo4j 데이터의 대화형 그래프 뷰
• 노드 타입별 색상 구분 (정의, 정리, 증명, 예제 등)
• 관계 탐색 및 필터링
• 그래프 구조 분석 도구

참고: 관리자 패널은 현재 개발 중이며, 향후 업데이트에서 더 많은 기능이 추가될 예정입니다.

엔티티 추출

# 전체 문서 추출 (3페이지 슬라이딩 윈도우 + 자동 중복 제거)
python extract_entities.py

# 특정 페이지 범위 추출
python extract_entities.py --pages 1-10

# 검증 없이 빠른 추출
python extract_entities.py --no-validation

핵심 특징:

• 3페이지 슬라이딩 윈도우: 페이지 경계에 걸친 엔티티 누락 방지
• 자동 중복 제거: 추출 후 벡터 유사도 기반 중복 정리
• 교차 페이지 병합: 여러 페이지에 나뉜 엔티티 자동 통합

검색 인터페이스

# 대화형 검색
python -m src.rag.search_interface

# 명령행 검색
python -m src.rag.search_interface "vector space definition"

중복 제거

# 중복 분석
python src/scripts/remove_duplicates.py --analyze

# 중복 제거
python src/scripts/remove_duplicates.py --remove-all

🗄️ Neo4j 지식그래프

노드 타입

• Entity: 모든 수학적 엔티티의 기본
• Definition: 수학적 정의
• Theorem: 정리 및 명제
• Proof: 증명
• Example: 예제
• Exercise: 연습문제
• Remark: 주석

관계 타입

• USES: 개념 사용 관계
• PROVES: 증명 관계
• REFERENCES: 참조 관계
• EXEMPLIFIES: 예시 관계

Neo4j 브라우저 관리자 패널

Neo4j는 강력한 네이티브 브라우저 인터페이스를 제공합니다 (http://localhost:7474):

그래프 시각화 기능:

• 전체 지식그래프의 네트워크 뷰
• 96개 노드, 1,099개 관계 표시
• 노드 라벨별 색상 구분 (Entity, MathEntity, Page)
• 관계 타입별 통계 (APPEARS_IN, CONTAINS, BELONGS_TO 등)
• 대화형 탐색과 확대/축소

데이터 관리 기능:

• Cypher 쿼리 직접 실행
• 노드/관계 속성 상세 조회
• JSON 형태 데이터 구조 확인
• 실시간 쿼리 성능 모니터링
• 데이터베이스 스키마 분석

주요 활용법:

# 전체 엔티티 조회
MATCH (e:Entity) RETURN e LIMIT 25

# 특정 개념과 연관된 엔티티 찾기
MATCH (e:Entity)-[r]-(related) 
WHERE e.title CONTAINS "vector space" 
RETURN e, r, related

# 페이지별 엔티티 분포 확인
MATCH (p:Page)-[r:CONTAINS]->(e:Entity) 
RETURN p.number, count(e) as entity_count 
ORDER BY p.number

🔧 환경 설정

필수 환경 변수

# OpenAI API 설정
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

# Neo4j 데이터베이스 설정
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password_here

# PDF 파일 경로
PDF_PATH=book/LADR4e_ch1.pdf

Docker Compose

# Neo4j 시작
docker-compose up neo4j -d

# Neo4j 브라우저: http://localhost:7474

🔍 검색 기능

하이브리드 검색 시스템

• 텍스트 검색: Neo4j 전문 검색 인덱스 활용
• 벡터 검색: OpenAI 임베딩 기반 의미적 유사도
• 그래프 검색:
  • Text-to-Cypher 자동 변환
  • 실패시 미리 정의된 패턴으로 쿼리 수정 후 재시도
  • 관계 기반 연관 엔티티 탐색

검색 모드

• text_only: 텍스트 검색만
• vector_only: 벡터 검색만
• graph_only: 스마트 그래프 검색만
• hybrid_all: 모든 검색 방법 조합 (권장)

페이지 제약

# 15페이지 이전 내용만 검색
--max-page 15

# 교육적 맥락에서 유용
# (해당 페이지까지 학습한 내용만 참조)

🚨 문제 해결

일반적인 문제

1. OpenAI API 키 오류

   export OPENAI_API_KEY="your_api_key"

2. Neo4j 연결 오류

   docker-compose up neo4j -d
   # Neo4j 브라우저에서 비밀번호 확인: http://localhost:7474

3. PDF 파일을 찾을 수 없음

   ls -la book/
   # PDF 파일을 book/ 디렉토리에 복사

4. 검색 결과 없음

   # 먼저 엔티티 추출 실행
   python extract_entities.py --pages 1-10

디버깅

# 연결 테스트
python -c "
from src.extractor.data_manager import Neo4jOnlyDataManager
from src.config import get_config
config = get_config()
dm = Neo4jOnlyDataManager(config.neo4j_uri, config.neo4j_username, config.neo4j_password)
print(f'엔티티 개수: {dm.get_total_entity_count()}')
"

# 로그 확인
tail -f logs/extraction.log

🧪 테스트

# 기본 기능 테스트
python tests/test_extraction.py
python tests/test_unified_search.py
python tests/test_neo4j_crud.py

# 통합 테스트
python tests/test_integration.py

📊 성능 최적화

• 빠른 모델: OPENAI_MODEL=gpt-4o-mini
• 페이지 범위 제한: --pages 1-20
• 검증 비활성화: --no-validation
• 결과 개수 제한: limit=5

🔗 관련 문서

• 검색 시스템 상세 가이드
• Neo4j 브라우저
• 웹 인터페이스

🤝 기여하기

1. 이슈 리포트: GitHub Issues에 버그나 개선사항 등록
2. Pull Request: 코드 기여
3. 문서 개선: README나 코드 주석 개선

---

핵심 워크플로우:

1. python main.py → 웹 인터페이스 실행
2. 관리자 페이지에서 엔티티 추출
3. PDF 보면서 채팅으로 질문
4. 검색 결과로 학습 보조