Spring Boot RAG 에이전트

Spring boot RAG 에이전트 Github

• 기간: 2025.12 - 2026.02

• 개인 프로젝트

프로젝트 개요

현재 AI는 Spring Boot 4.0.x보다 3.5.x 버전에 더 익숙한 상태입니다. 본 프로젝트는 이러한 AI의 최신 프레임워크 대응 격차를 해소하기 위해 시작되었습니다.

LangChain 프레임워크를 기반으로 최신 개발 문서의 지식을 정확하게 검색하고 응답하는 RAG 에이전트 및 파이프라인을 구축하는 것을 핵심으로 합니다.

Spring Boot, Spring Data Redis 등의 공식 문서를 크롤링하고 하이브리드 검색과 Reranker를 결합해 높은 검색 정확도를 달성했습니다.

프로젝트 목표

• RAG 파이프라인 구축: 단순 DB 임베딩 방식 단일 검색을 넘어, 의미 기반 검색과 키워드 기반 검색의 이점을 살린 하이브리드 검색 및 딥러닝 기반 Reranking 처리로 응답의 정확성과 신뢰성 확보.

• RAG 에이전트 구축: Spring 공식 문서 등 방대한 기술 문서를 학습(Indexing)하여, 할루시네이션을 최소화하고 최신 정보에 기반한 정확한 기술 답변을 제공합니다

• MCP 서버 구축: MCP 서버를 구축하여 외부 AI 어시스턴트 환경에서도 RAG 파이프라인의 검색 결과를 실시간 도구로 연동하고 확장할 수 있는 범용적인 아키텍처 구현

• RAG 시스템 평가 도입 (LLM-as-a-Judge): LangSmith와 LLM을 통해 RAG 파이프라인의 핵심 성능 지표(정확성, 검색 결과 적합성, 근거성 등)를 정량적/정성적으로 모니터링하여 평가 자동화 환경 구축.

사용 기술

• AI & Frameworks : LangChain, LangGraph, OpenAI GPT-5-mini, Cohere Reranker API

• Database: ChromaDB, Redis

• Evaluation: LangSmith, openevals

• Data Collection & Parsing: BeautifulSoup, markdownify

• Data Visualization: Matplotlib

주요 기능

• RAG 검색 엔진 설계
  • Markdown 정규화 및 하이브리드 청킹 전략: BeautifulSoup과 markdownify 라이브러리를 사용해 복잡한 HTML 기술 문서를 Semantic Markdown 구조로 데이터 정제.
  • 하이브리드 검색 (Hybrid Search): 의미론적 검색인 Dense 검색(ChromaDB, 가중치 0.7)과 키워드 기반인 Sparse 검색(BM25, 가중치 0.3) 방식을 RRF 알고리즘으로 결합시켜 1차 후보군 데이터 넓게 확보.
  • Cohere Reranker 통합: 초기 추출된 후보군 문서를 Cohere Reranker 딥러닝 기반 재배열 처리 모듈에 통과시켜 최종 우선순위를 정밀하게 재배치해 도출, Top-1 / Top-5 검색 적중률 대폭 개선.

• 시스템 자동 성능 평가
  • LangSmith 연동: 평가관 LLM을 활용한 LLM-as-a-Judge 도입. 정확성(Correctness), 사실 근거 일치성(Groundedness), 질의와 검색 문서 연관성(Retrieval relevance) 에 대해 정량/정성 평가 진행 후 LangSmith 대시보드를 통해 실시간 트래킹 모니터링.
  • Retriever 자체 벤치마킹: Top-1/5/10 Hit Rate, MRR, Redundancy 와 같은 핵심 성능 평가 지표를 로컬에서 자동 산출.

• 에이전트 워크플로우
  • 단순 검색이 아닌 사용자의 질문 의도를 파악하고, 필요시 쿼리를 재작성 하거나 도구를 선택하여 답변을 생성하는 에이전트 로직을 포함합니다.
  • MCP 서버를 통해 외부 도구와의 연동 가능성을 열어두었습니다.

• Semantic Caching
  • 사용자의 질문에 대한 답변을 캐싱하여 비슷한 질문에 대해 캐싱된 답변을 사용하여 응답 속도 향상 및 API 비용 절감(Reranker API, GPT API 호출 스킵).

프로젝트의 성과 및 인사이트

• 고도화된 하이브리드 검색 기반 및 성능 벤치마킹 실험을 통해 단순 Vector 임베딩 검색 구조가 갖는 전문 용어 및 특정 기술 코드 검색에 대한 한계점을 검증할 수 있었으며, 이를 Reranker 모델 투입 과정으로 보완함으로써 안정성 높은 자체 검색 엔진 튜닝 경험을 만들었습니다.

• LangSmith와 자동화된 스크립트 시스템 파이프라인을 구축해 시스템 품질을 명확한 지표(Hit Rate, MRR, Correctness 등)로 가시화하여 프로젝트 결과를 명료하게 증빙하고, 품질 통제를 개발하는 역량을 크게 키울 수 있었습니다.

RAG 성능 평가

평가 셋

• Dev 182 / Test 77

평가 방법(요약)

• 벡터스토어에서 임의의 청크를 샘플링한 뒤, LLM으로 해당 청크 기반 질문을 생성
  • 일반적인 질문이 아닌 Hit Rate 를 낮추기 위해 키워드 제한, 다른 의미의 단어를 사용하였음

• Retriever가 질문에 대해 원본 청크를 Top-k로 회수하는지로 평가

• Metrics: Recall@1/5/10, MRR

비교 실험

• Dense

• Hybrid (Dense + BM25, 가중치 스윕: 0.7/0.3, 0.5/0.5, 0.3/0.7)

• Hybrid (0.7/0.3) + Reranker

관찰 및 해석

• BM25 가중치가 증가할수록 Recall@1(Top-1) 성능은 상승, Recall@5 이상 구간에서는 성능 감소 경향
  • 키워드 매칭(BM25)이 최상위 1개를 정확히 올리는 데 유리한 반면, Dense 기여도가 줄어 상위 후보군 다양성이 감소한 것으로 해석

• LangSmith(LLM-as-a-Judge) 기반 평가는 질문 난이도 영향으로 전반적으로 고득점(0.9+)이 많았으나, 저득점 케이스는 리트리버 점수가 낮은 케이스와 대부분 겹쳤음
  • 절대 점수보다 저득점 케이스 분석 중심으로 해석했으며, 최종 응답 품질의 병목이 retrieval 품질에 크게 좌우됨을 확인

• LLM을 검색 도구(tool)와 연결해 Query Rewrite를 제한 없이 적용했을 때, 원문 질의 그대로 검색하는 방식 대비 검색 정확도 저하와 지연 시간 증가를 확인
  • 따라서 운영/평가 파이프라인에서는 기본적으로 rewrite를 사용하지 않는 방향으로 설계

MMR 실험 (Dense vs Dense+MMR)

• Spring Boot 공식 문서는 기능 단위로 내용이 분리되어 문서 간 의미적 중복도가 상대적으로 낮음

• 따라서 다양성 확보 목적의 MMR 효과가 제한적으로 나타난 것으로 해석

RAG 에이전트 실험 (query rewrite)

• 평가 방법: LLM-as-a-judge (openevals, LangSmith)

• 데이터셋: 임의의 청크 추출 및 LLM 질답 생성

• A: 청록 B: 분홍 C: 파랑

• A: 기본 입력 사용후 필요시 1회 재작성 B: 기본 입력 사용 C: 매번 재작성

결과 해석

A. 기본 검색 후 필요 시 쿼리 재작성

• 먼저 원문 질의로 검색을 수행한 뒤, 검색 결과가 부족할 경우에만 질의를 보완하는 방식.
  • 세 가지 방법 중 비교적 높은 정확도와 검색 관련성을 보였지만, 지연시간과 토큰 사용량이 증가하는 trade-off가 확인.

B. 기본 입력 사용

• 사용자 질의를 그대로 검색에 사용하는 방식.
  • 성능은 A보다 약간 낮았지만 지연시간과 토큰 사용량 측면에서 가장 효율적인 결과를 보임.

C. 처음부터 쿼리 재작성

• 검색 전에 질의를 LLM으로 재작성한 뒤 검색하는 방식.
  • 질의의 일부 기술 용어가 변형되면서 검색 관련성과 정확도가 상대적으로 낮게 나타난걸로 추정.

결론

• 필요시 질의 재작성을 적용하는 방식이 가장 높은 정확도를 보였으나, 지연 시간과 토큰 사용량 측면에서의 trade-off가 확인되었다.

• 기본 질의를 그대로 사용하는 방식도 준수한 정확도를 보였지만, 사용자의 질문이 모호하거나 품질이 낮아질수록 두 방식 간 정확도 차이가 커질 가능성이 있을 것으로 판단된다.