[RAG] 깃허브 참고자료 (1) RAG Blueprint

 

이 글은 RAG Blueprint 레포지토리의 아키텍처를 분석하고 공부한 내용을 바탕으로 작성되었습니다.

GitHub - feld-m/rag_blueprint: A modular framework for building and deploying Retrieval-Augmented Generation (RAG) systems with

 

소프트웨어에서의 블루프린트(blueprint) 란 

• 건축의 설계도/청사진 역할 
• 표준화된 아키텍쳐와 미리 짜놓은 코드를 의미 
• 단순 개념만 설명하는 것이 아니라 실제 실행 가능한 코드 템플릿 제공 

 

---

 

RAG 레퍼런스를 찾아다니던 중 발견한 프로젝트이다. 

현재 우리 프로젝트의 RAG 시스템과 어떤 점이 다른지 비교해보고

아키텍쳐 구조, 구현 방법에 대한 여러 인사이트를 얻을 수 있을 것 같아서 살펴보기로 함

 

RAG Blueprint 

프로젝트 설명 

• 상용화 수준(production-ready)의 검색 증강 생성(RAG) 시스템 구축을 위한 포괄적인 오픈소스 프레임워크 
• 개발 복잡도는 낮추면서도 성능, 리소스, 평가에 대한 완전한 제어권을 제공하는 프레임워크
• 현재 다양한 RAG 프레임워크가 존재하지만, 실제 서비스 가능한 제품 수준으로 만드는 것은 어려움. 

제공하는 기능 

• 내장형 모니터링 및 관측 도구 
• LLM 기반 평가 지표 (RAGAS 같은 도구 활용법)
• 사용자 피드백 수집 기능 

기술 스택 (Tech Stack)

• 핵심 코어 엔진 : LlamaIndex 📌(우리 프로젝트는 LangChain 기반이라 구조적 차이가 있음)
• 모니터링 : Langfuse (LLM 기반 애플리케이션의 디버깅, 분석 및 개선을 지원하는 오픈소스 엔지니어링 플랫폼) 📌
• 평가 : RAGAS (LLM을 이용해 점수를 매기는 정량적 평가 도구 도입.)
• UI : Chainlit (빠르게 챗봇 화면을 띄워주는 도구) 

아키텍쳐 및 데이터 흐름

1. 추출 (Extraction) 

• 단순 수집이 아닌 마크다운 파싱을 수행함. 
• 문서를 그냥 텍스트로 긁어오는 것이 아니라, 제목/문단 구조를 살려서 마크다운으로 변환 후 저장함. 📌
• 이렇게 하면 청킹 품질이 좋아짐. 

2. 임베딩 

• 문맥을 고려해서 임베딩함. 📌

3. 증강-검색/리랭킹 

• 검색과 생성 파이프라인 정의 
• 랭퓨즈(Langfuse)를 사용해서 관리 가능하도록 함.

4. 평가 

• 사용자 피드백(Chainlit) + RAGAS 점수 측정. 📌 

폴더 구조 

.
├── build/            # Build and deployment scripts
│   └── workstation/  # Build scripts for workstation setup
├── configurations/   # Configuration and secrets files
├── data/             # Data for local testing
├── res/              # Assets
└── src/              # Source code
    ├── augmentation/   # Chainlit, Langfuse, and RAG processing components
    ├── core/           # Base package
    ├── extraction/     # Data sources extraction
    ├── embedding/      # Data embedding
    └── evaluate/       # Evaluation system
├── tests/            # Unit tests

• src 구조를 보면 기능별로 분리되어 있다. 현재 우리 프로젝트는 초반이기도 하고 기능 구분이 애매해서 src 에 한번에 넣어놨는데.. ㅎ 이 부분도 참고해야겠다. 
• 모니터링을 따로 하지 않고 일일이 로그를 찍어서 확인하고 있었다. 모델의 성능만큼 파이프라인의 관리 가능성이 프로젝트의 성패에도 큰 영향을 미칠 수 있겠다는 생각이 들었다.  

---

 

코드 분석 및 인사이트 

• 전체 파이프라인 중, 우리 프로젝트에 적용하고 싶은 부분을 발췌해보았음. 

(1) 문맥 고려 임베딩 (Context-Aware Embedding) 

• 일반적인 텍스트 splitter 는 글자수(예: 500자) 로 뚝뚝 자름. 이 방식의 치명적인 단점은 제목과 내용이 분리되어서 문맥을 잃게 된다는 것임. 
• 우리 프로젝트의 경우 먼저 제목 + 본문 합친 뒤, 통째로 chunk_size=600, overlap=60으로 설정했음. 
• 이는 가장 첫번째 청크에만 제목이 포함되어서 두번째부터는 제목 정보가 사라져 검색 검색 정확도가 떨어질 수 있음. 
• Blue print 의 경우 MarkdownNodeParser 메소드를 사용해  Markdown의 헤더 구조(#, ##)를 인식해서 자름. 
• 랭체인에서는 MarkdownHeaderTextSplitter 

 

1. 단순 자르기 vs 구조적 자르기 

#basic_markdown_splitter.py 
#__init__ 함수
self.markdown_node_parser = MarkdownNodeParser() 

#split 함수
#데이터를 그냥 자르는 것이 아니라, 마크다운 구조로 변환함. 
document_nodes = self.markdown_node_parser.get_nodes_from_documents([document])

#MarkdownNodeParser: LlamaIndex 내장함수 
#데이터의 구조를 인식해, 자동으로 문단을 구분한다.

 

2. 메타데이터를 보존함 

• 이 방식의 장점은 또한 내부적으로 헤더 경로(Header Path)를 저장해 metadata 로 저장한다는 점. 
• 이렇게 되면, LLM or 리랭커가 이 조각을 볼때 "이건 개요구나", "설명 파트이구나" 하고 문맥 파악 가능

3. 문서 길이에 따른 2차 가공 작업 

• 즉, 큰 덩어리를 잘게 쪼개더라도 model_copy()를 통해 메타 데이터를 분리된 조각에게 그대로 물려줌. 
• 또한 제목만 있고 내용이 너무 짧은 경우등의 너무 자잘한 조각들은 토큰 한도 내에서 앞뒤 조각과 합쳐서 문맥을 이어줌. 

#basic_markdown_splitter.py 
# _split_big_node 함수 내부
if document_node_size > self.chunk_size_in_tokens:
    # 문장 단위(SentenceSplitter)로 다시 쪼갠다.
    sub_texts = self.sentence_splitter.split_text(text)
    # 그리고 ! 부모 노드의 메타데이터(헤더 정보)를 복사해서 물려준다!
    sub_node = document_node.model_copy()

 

 

(2) 모니터링 (Observability)

• 현재 우리 프로젝트의 방식: 일일이 (f"[TIMER] 1차 검색 시간: {elapsed}s") 등을 찍어서 확인하고 있음.. ㅎ
  • 아직 기능별 테스트 단계라서 무리 없지만 전체 파이프 라인을 연결했을 땐 연속적으로 추적하기 어려울 것임. 
  • 중간 단계(예: 10단계 중 5~7번)의 데이터를 확인하려면, print문을 추가하고 전체 코드를 다시 실행해야 하는 번거로움이 있음. 
• Blueprint 방식 : Tracing(추적) 기술 사용. 
  • 사용자가 "안녕?" 이라고 말한 순간부터 답변이 나갈 때까지의 모든 과정이 하나의 타임라인으로 묶여서 Langfuse 서버로 자동 전송됨. 
  • 개발자는 웹 대시보드에서 시각화된 데이터를 확인할 수 있음. 
  • RAG은 여러 단계가 유기적으로 연결되어있음.
  • 즉, tracing 을 사용하면, 어느 단계에서 어떤 병목이 발생했는지, 어느 단계의 데이터가 이상했는지 클릭 한번으로 파악할 수 있어서 최적화, 디버깅 효율이 극대화 됨. 
• 내 프로젝트에 적용할때 필요한 것 
  • 우리 프로젝트의 경우 랭체인 + 파이썬 순수 코드로 구현이 된 프로젝트임. 
  • 그래서 CallbackHandler 같이 LlamaIndex/랭체인이 제공하는 클래스 말고 
  • langfuse 설치 후, @observe 데코레이터를 tracing 원하는 함수 바로 윗줄에 적어주면 함수 실행 과정이 Langfuse 에 기록됨. 

 

 

(3) 평가(Evaluation)

1. Ragas 평가 

• Langfuse 에 쌓인 실제 사용자 로그를 기반으로 평가 데이터셋을 구축하고 이를 Ragas 가 채점함. 
• Langfuse는 단순히 로깅툴이 아니라, 데이터셋 생성할 수 있는 기능도 있음. 
• 실제 유저 질문들을 가지고 평가 데이터셋으로 만들어줌. 

 

 

2. 사용자 피드백 기반 평가 

• 사용자 피드백(👍/👎)을 수집하는 인터페이스 역할
• 이 피드백을 Langfuse에 저장하고, 이를 다시 평가 데이터셋으로 활용
• 사용자에게 직접 받는 피드백 루프가 구축되어야 챗봇이 실전에서 계속 똑똑해질 수 있음. 
• Chainlit : 개발자와 기업이 대화형 인공지능 애플리케이션을 쉽고 빠르게 구축, 평가 및 개선할 수 있도록 설계된 파이썬 기반의 오픈소스 프레임워크이자 플랫폼. 

 

 

---

마무리 

이번 분석을 통해 RAG 시스템은 단순히 모델 성능(검색 속도, 리랭킹 점수)만 높인다고 끝나는게 아니라는 걸 깨달았다. 

데이터 전처리는 물론이고 모니터링, 그리고 피드백 루프까지 이어지는 전체 파이프라인의 관리시스템을 구축하는 것이 상용화의 핵심이다. 우리 프로젝트에도 Langfuse 와 구조적인 청킹을 도입해 한 단계 더 발전시켜야겠다.