Global Campus Visa Navigator RAG

외국인 유학생 비자·학사 안내 근거중심 도우미

프로젝트 개요

항목	내용
프로젝트명	Global Campus Visa Navigator RAG
문제 정의	유학생 비자·학사 정보가 여러 문서에 분산되어 있어 정확한 조항을 빠르게 찾기 어려움
핵심 기능	① 하이브리드 질의응답 ② 정책 문서 인덱싱 파이프라인 ③ 리스크 최소화 응답 정책
기술 스택	Python, Gemini/OpenAI, Neo4j, SentenceTransformers, pdfplumber
마일스톤	16주 (W1~W16), 아래 표 참고

문제 정의

외국인 유학생은 대학 안내, 체류자격(비자), 출입국 신고 의무를 서로 다른 문서에서 확인해야 한다. 문서마다 표현 방식이 달라 단순 검색으로는 맞는 조항을 빠르게 찾기 어렵고, 잘못된 이해는 행정 불이익으로 이어질 수 있다.

이 프로젝트는 답변 자체보다 "근거 문서와 조항을 정확히 찾아 제시" 하는 것을 핵심으로 한다.

핵심 기능

1. 비자·학사 하이브리드 질의응답 벡터 검색(문맥 의미) + 그래프 검색(자격/전환/의무 관계)을 결합하고, 답변에 근거 문서명·조항·인용 스니펫을 포함한다.

2. 정책 문서 중심 인덱싱 파이프라인 PDF 로딩, 청킹, 임베딩, 조항 단위 메타데이터 추출을 자동화하며 개정일/시행일 기준으로 최신 버전을 우선 노출한다.

3. 리스크 최소화 응답 정책 근거 부족 시 단정 답변을 금지하고, 민원 채널(하이코리아/1345) 안내를 자동 첨부하며 회귀 질문셋으로 정확도와 근거 충실도를 자동 점검한다.

기술 스택

분류	기술
Language	Python 3.11+
LLM	Gemini / OpenAI / Ollama
Retrieval	SentenceTransformers, Hybrid (Vector + Graph)
Graph DB	Neo4j
Data Processing	pdfplumber, custom chunker/extractor
DevOps	Git, GitHub Actions

16주 마일스톤

기간	목표
W1-2	질문 시나리오 60개 수집, 성공 지표 정의
W3-4	PDF 코퍼스 분류, 메타데이터 스키마 설계
W5-6	인덱싱 파이프라인 구현 및 초기 코퍼스 적재
W7-8	하이브리드 검색 MVP + 중간 데모
W9-10	Fast/Deep 라우팅 고도화
W11-12	회귀 테스트 자동화, SLA 추적
W13-14	운영 안정화, 발표 시연 시나리오
W15	성능 튜닝, 문서화
W16	최종 발표 및 데모

시작하기 (처음 pull한 경우)

1. Ollama 설치 및 EXAONE 모델 다운로드

# Ollama 설치 (https://ollama.com/download)
# macOS
brew install ollama

# Windows — 위 링크에서 설치 파일 다운로드

# EXAONE 모델 다운로드 (~5GB, 최초 1회)
ollama pull exaone3.5:7.8b

# Ollama 서버 실행 (터미널 하나 점유)
ollama serve

2. 환경변수 설정

cp .env.example .env
# .env 파일을 열어 NEO4J_PASSWORD 등 필요한 값을 채운다

3. 의존성 설치 및 실행

pip install -r requirements.txt

# KB 구축 (PDF → Neo4j 인제스트)
python main.py --ingest

# 질의 루프 실행
python main.py --query

Docker로 실행하는 경우

# 첫 실행 — Ollama 컨테이너가 뜬 뒤 모델을 직접 pull해야 한다
docker compose up -d

# EXAONE 모델 pull (최초 1회, ollama 컨테이너 내부에서 실행)
docker compose exec ollama ollama pull exaone3.5:7.8b  # ~5GB

# 이후부터는 그냥 기동하면 됨 (모델은 ollama_data 볼륨에 저장됨)
docker compose up

LLM 공급자 전환 (선택사항)

목적	.env 설정
Ollama EXAONE (기본)	LLM_PROVIDER=ollama / RUNTIME_LLM=ollama
Gemini API	LLM_PROVIDER=gemini / RUNTIME_LLM=gemini + GEMINI_API_KEY=...
OpenAI API	LLM_PROVIDER=openai + OPENAI_API_KEY=...

---

폴더 구조

• agent/: 질의, 인제스트, 검색, LLM 연동
• graph_rag/: Neo4j 저장소, 임베딩, 파이프라인
• docs/: 설명 문서와 결과 기록
• pdf/: 입력 PDF 자료
• requirements.txt: 의존성 목록

실행

기존 단일 main.py 진입점은 제거되었습니다. 실제 실행은 agent/와 graph_rag/ 패키지 기반 진입점에서 구성합니다.

환경변수

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=YOUR_PASSWORD
PDF_DIR=C:\path\to\pdf
GEMINI_API_KEY=YOUR_GEMINI_API_KEY
GEMINI_MODEL=gemini-3.0-flash
GATE_MIN_TOP_SCORE=0.25
GATE_MIN_EVIDENCE=2
ENABLE_EXTERNAL_SEARCH=1
ALLOWED_EXTERNAL_SUFFIXES=go.kr,ac.kr,gov,edu,gov.cn,edu.cn,ac.uk,gov.uk
LATENCY_LOG_PATH=logs/latency_log.jsonl

설치

python -m pip install neo4j google-generativeai pdfplumber numpy scikit-learn sentence-transformers==3.0.1
python -m pip install --upgrade torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu

---

📝 이 문서는 작성 과정에서 생성형 AI(Claude)의 도움을 받아 작성되었습니다.