GiovanniPasq/agentic-rag-for-dummies

초보자를 위한 에이전틱 RAG

정의 – LangGraph 기반의 모듈형, 에이전트 기반 검색 증강 생성(RAG) 시스템의 최소 코드 예제입니다. 계층적 문서 인덱싱, 대화 메모리, 쿼리 명확화, 다중 에이전트 맵-리듀스 추론을 단일 확장 가능한 파이프라인으로 결합하는 방법을 보여줍니다.

---

핵심 개념

단계	설명
문서 준비	PDF를 Markdown으로 변환한 후, 컨텍스트를 위한 큰 부모 청크(Markdown 헤더 기준)와 정밀 검색을 위한 작은 자식 청크로 두 번 분할합니다.
대화 메모리	요약 및 최근 대화를 유지하여 LLM 컨텍스트를 과도하게 늘리지 않으면서 대화의 일관성을 유지합니다.
쿼리 명확화	모호한 질문을 재작성하고, 다중 파트 쿼리를 분할하며, 누락된 세부 정보를 사용자에게 질문할 수 있습니다.
다중 에이전트 맵-리듀스	각 하위 쿼리는 자체 LangGraph 서브 그래프(병렬 에이전트)에서 실행됩니다. 각 에이전트는 자식 청크를 검색하고, 해당 부모 청크를 가져오며, 결과가 약하면 자체 수정하고, 토큰 제한 내에서 컨텍스트를 압축합니다.
집계	모든 에이전트 응답을 단일의 유창한 응답으로 병합합니다.

---

주요 기능 (README에 명시된 대로)

• 계층적 인덱싱 – 작은 청크의 정밀도와 큰 부모 섹션의 풍부한 컨텍스트를 결합합니다.
• 대화 메모리 – 여러 턴에 걸쳐 컨텍스트가 유지됩니다.
• 인간 참여형 명확화 – 시스템이 진행 전에 사용자에게 명확화를 요청할 수 있습니다.
• 에이전트 오케스트레이션 – LangGraph가 전체 워크플로우를 조정합니다.
• 맵-리듀스 병렬 처리 – 여러 하위 쿼리를 동시에 처리합니다.
• 자기 수정 – 에이전트가 신뢰도가 낮을 때 자동으로 재쿼리합니다.
• 컨텍스트 압축 – 작업 메모리를 효율적으로 유지합니다.
• 관찰 가능성 – Langfuse와 통합하여 LLM 호출, 도구 사용, 그래프 실행을 기록합니다.
• 평가 – RAGAS 메트릭 스위트로 답변을 평가하는 노트북을 제공합니다.

---

기술 스택

• Python ≥ 3.11
• LangGraph (v1.2+) – 그래프 기반 에이전트 오케스트레이션
• Qdrant 벡터 저장소, 하이브리드 밀집 + 희소 검색(밀집은 HuggingFace 임베딩, 희소는 FastEmbed BM25)
• LLM 제공자 – 기본값은 Ollama(로컬 모델 granite4.1:8b)이지만, OpenAI, Anthropic, Google Gemini 또는 LangChain 호환 채팅 모델과도 작동합니다.
• Chunky (선택 사항) – PDF를 Markdown으로 변환하고 청크를 검사하는 헬퍼 도구 키트.
• Langfuse – 선택적 관찰 가능성 대시보드.
• RAGAS – 검색 및 답변 품질의 정량적 평가용.

---

시작하기 (개요)

1. 의존성 설치 – pip install -r requirements.txt (LangGraph, LangChain, Qdrant 클라이언트 등 포함).
2. 벡터 DB 설정 – 저장소는 로컬 Qdrant 인스턴스를 생성합니다 (client = QdrantClient(path="qdrant_db")).
3. 문서 추가 – PDF를 docs/에 넣고, 노트북이나 스크립트를 실행하여 Markdown으로 변환합니다 (pdfs_to_markdowns).
4. 인덱싱 – index_documents() 함수가 부모/자식 청크를 생성하고 자식 청크를 Qdrant에 저장합니다. 부모 메타데이터는 JSON 파일로 저장됩니다.
5. LLM 선택 – llm = ChatOllama(...) 줄을 편집하거나 적절한 API 키를 설정한 후 ChatOpenAI, ChatAnthropic 등으로 교체합니다.
6. 데모 실행 – notebooks/agentic_rag.ipynb를 열고(또는 Colab 배지를 실행) 채팅 인터페이스와 상호작용합니다.
7. 평가 – notebooks/evaluation.ipynb를 사용하여 생성된 답변에 대한 RAGAS 점수를 계산합니다.

---

대상 독자

• 에이전틱 RAG 파이프라인의 각 구성 요소를 설명하는 단계별 노트북을 원하는 학습자.
• 자신의 데이터, LLM 또는 도구에 맞게 포크하고 적용할 수 있는 즉시 사용 가능한 모듈형 아키텍처를 찾는 개발자.
• 다중 에이전트 검색, 자기 수정 또는 하이브리드 밀집-희소 검색을 실험하는 데 관심이 있는 연구자.

---

주요 기능 (README에 명시된 대로)

• 계층적 인덱싱 – 작은 청크의 정밀도와 큰 부모 섹션의 풍부한 컨텍스트를 결합합니다.
• 대화 메모리 – 대화 간 컨텍스트가 유지됩니다.
• 인간 참여형 명확화 – 시스템이 진행 전에 사용자에게 명확화를 요청할 수 있습니다.
• 에이전트 오케스트레이션 – LangGraph가 전체 워크플로우를 조정합니다.
• 맵-리듀스 병렬 처리 – 여러 하위 쿼리가 동시에 처리됩니다.
• 자기 수정 – 에이전트가 신뢰도가 낮을 때 자동으로 재쿼리합니다.
• 컨텍스트 압축 – 작업 메모리를 효율적으로 유지합니다.
• 관찰 가능성 – Langfuse와 통합하여 LLM 호출, 도구 사용, 그래프 실행을 기록합니다.
• 평가 – RAGAS 메트릭 스위트로 답변을 평가하는 노트북을 제공합니다.

---

기술 스택

• Python ≥ 3.11
• LangGraph (v1.2+) – 그래프 기반 에이전트 오케스트레이션
• Qdrant 벡터 저장소, 하이브리드 밀집 + 희소 검색(밀집은 HuggingFace 임베딩, 희소는 FastEmbed BM25)
• LLM 공급자 – 기본은 Ollama(로컬 모델 granite4.1:8b)이지만, OpenAI, Anthropic, Google Gemini 또는 LangChain 호환 채팅 모델과도 작동합니다.
• Chunky (선택 사항) – PDF를 Markdown으로 변환하고 청크를 검사하는 헬퍼 도구 키트.
• Langfuse – 선택적 관찰 가능성 대시보드.
• RAGAS – 검색 및 답변 품질의 정량적 평가용.

---

시작하기 (개요)

1. 의존성 설치 – pip install -r requirements.txt (LangGraph, LangChain, Qdrant 클라이언트 등 포함).
2. 벡터 DB 설정 – 저장소는 로컬 Qdrant 인스턴스를 생성합니다 (client = QdrantClient(path="qdrant_db")).
3. 문서 추가 – docs/에 PDF를 넣고, 노트북이나 스크립트를 실행하여 Markdown으로 변환합니다 (pdfs_to_markdowns).
4. 인덱싱 – index_documents() 함수가 부모/자식 청크를 만들고 자식 청크를 Qdrant에 저장합니다. 부모 메타데이터는 JSON 파일로 저장됩니다.
5. LLM 선택 – llm = ChatOllama(...) 줄을 편집하거나 적절한 API 키를 설정한 후 ChatOpenAI, ChatAnthropic 등으로 교체합니다.
6. 데모 실행 – notebooks/agentic_rag.ipynb를 열고(또는 Colab 배지를 실행) 채팅 인터페이스와 상호작용합니다.
7. 평가 – notebooks/evaluation.ipynb를 사용하여 생성된 답변에 대한 RAGAS 점수를 계산합니다.

---

대상 독자

• 학습자 – 에이전틱 RAG 파이프라인의 각 구성 요소를 설명하는 단계별 노트북을 원하는 분.
• 개발자 – 자신의 데이터, LLM 또는 도구에 맞게 포크하고 조정할 수 있는 즉시 사용 가능한 모듈형 아키텍처를 찾는 분.
• 연구자 – 다중 에이전트 검색, 자기 수정, 하이브리드 밀집-희소 검색을 실험하려는 분.

---

장점

• 모듈형 – 각 구성 요소(임베딩 모델, 벡터 저장소, PDF 변환, 에이전트 그래프)가 분리되어 있어 교체가 간편합니다.
• 공급자 중립 – 특정 벤더에 국한되지 않고 모든 LangChain 채팅 모델과 호환됩니다.
• 관찰 가능성 – 선택적 Langfuse 통합으로 LLM 호출 디버깅 및 모니터링에 도움이 됩니다.
• 평가 내장 – RAGAS 노트북이 정량적 피드백을 제공합니다.
• 인간 참여 루프 – 쿼리 명확화로 모호한 프롬프트로 인한 환각을 줄입니다.

---

제한 사항 / 미해결 과제

• 기본 Ollama 모델을 사용하려면 로컬 Qdrant 인스턴스와 GPU 지원 환경이 필요합니다. 클라우드 대안은 추가 설정이 필요합니다.
• 계층적 인덱싱 로직이 상당히 복잡하므로, 초보자는 병합/리밸런싱 단계를 이해하기 위해 헬퍼 함수를 읽어야 할 수 있습니다.
• 자기 수정 임계값(RETRIEVAL_SCORE_THRESHOLD = 0.4)이 하드코딩되어 있으며, 다양한 말뭉치에 맞게 조정이 필요할 수 있습니다.
• 데모는 PDF/Markdown 소스에 초점을 맞추고 있습니다. 다른 문서 유형은 추가 전처리 코드가 필요합니다.

---

빠른 시작 스니펫

from langchain_ollama import ChatOllama
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_qdrant.fastembed_sparse import FastEmbedSparse
from qdrant_client import QdrantClient

# LLM (로컬 Ollama)
llm = ChatOllama(model="granite4.1:8b", temperature=0, seed=42)

# 임베딩 (dense + sparse)
emb_dense = HuggingFaceEmbeddings(model_name="Qwen/Qwen3-Embedding-0.6B")
emb_sparse = FastEmbedSparse(model_name="Qdrant/bm25")

# 벡터 저장소
client = QdrantClient(path="qdrant_db")
# … 컬렉션 생성, 문서 인덱싱, 노트북에 표시된 대로 LangGraph 채팅 루프 시작.

---

결론 – 초보자를 위한 에이전틱 RAG는 계층적 청킹, 메모리, 명확화, 다중 에이전트 추론을 결합한 정교한 RAG 시스템의 구체적이고 실행 가능한 참조 구현체로, 모두 오픈소스 도구로 구축되었습니다. 학습 자료로도 훌륭하고, 프로덕션급 에이전틱 검색 파이프라인 구축을 위한 견고한 출발점이기도 합니다.

SUMMARY: LangGraph, 계층적 청킹, 대화 메모리, 쿼리 명확화, 다중 에이전트 맵-리듀스, 자기 수정, RAGAS를 통한 평가를 사용하여 모듈형 에이전트 기반 검색 증강 생성 시스템을 구축하는 방법을 보여주는 튜토리얼 스타일의 오픈소스 Python 프로젝트입니다. Ollama, OpenAI, Anthropic, Google Gemini, Qdrant 벡터 저장소 및 선택적 Langfuse 관찰 가능성과 함께 작동합니다.

TITLE: LangGraph로 모듈형 다중 에이전트 RAG 파이프라인 구축 – 전체 코드, 노트북, 평가 포함