Parent Document Retriever：계층적 검색으로 RAG 컨텍스트 완성도 높이기

RAG(Retrieval-Augmented Generation) 시스템을 구축하다 보면 필연적으로 마주치는 딜레마가 있습니다. 작은 청크 단위로 분할하면 세밀한 검색은 가능하지만 문맥의 흐름이 끊겨回答의 일관성이 떨어지고, 큰 청크로 묶으면 검색의 정밀도가 떨어지죠.

오늘은 이 딜레마를 우아하게 해결하는 Parent Document Retriever 패턴과 함께, 제가 실제 프로젝트에서 겪은 삽질과 해결 과정을 공유하겠습니다.

문제 상황：404 에러가 아니었는데文档가 깨져 보였다

초기 RAG 시스템 구축 시 저는 이런 코드를 작성했습니다:

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter

❌ 제가 처음에 작성했던 문제 코드
documents = loader.load()
text_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = text_splitter.split_documents(documents)

500자씩 쪼개서 저장
vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./chroma_db")
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

검색해보니 관련 없는 조각들만 반환됨
results = retriever.get_relevant_documents("프로젝트의 전체 마일스톤은?")
결과: ["1단계:\n", "2단계:\n", "3단계:\n"] → 전체 맥락 없음

결과를 확인해보니 검색은 되는데, 응답이 산산조각이었습니다. "프로젝트의 전체 마일스톤"을 물으면 1단계, 2단계, 3단계의 제목만 반환되고 본문 내용은 없습니다. 그 이유를 분석해보니:

• chunk_size=500로 설정해버려서 문단 전체가 아닌 문장 단위로 잘려 나감
• 청크 오버랩이 50자뿐이라 관련 텍스트가 다른 청크에 있어 연결 불가
• 상위 문맥(parent document)을 고려하지 않아 의미 단절 발생

이 문제를 해결한 것이 바로 Parent Document Retriever 패턴입니다.

Parent Document Retriever란?

Parent Document Retriever는 이중 계층检索 구조를 설계하여:

1. 자식 청크(child chunks): 작은 단위(500-1000자)로 분할 → 정밀한 semantic search용
2. 부모 문서(parent documents): 큰 단위(3000-5000자) 또는 원본 단위 → 완전한 문맥 제공용

검색 시 먼저 자식 청크에서 매칭되고, 그 부모 문서 전체를 컨텍스트로 반환합니다.

HolySheep AI + LangChain实战

먼저 필요한 패키지를 설치합니다:

pip install langchain langchain-openai langchain-community chromadb beautifulsoup4 requests

이제 HolySheep AI의 게이트웨이를 통해 최적화된 RAG 시스템을 구축하겠습니다:

import os
from langchain_community.retrievers import ParentDocumentRetriever
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

✅ HolySheep AI 게이트웨이 사용 (해외 카드 불필요)
os.environ["OPENAI_API_KEY"] = "YOUR_HOLYSHEEP_API_KEY"
os.environ["OPENAI_API_BASE"] = "https://api.holysheep.ai/v1"

임베딩 모델 설정 (비용 최적화를 위해 ada-002 사용)
embeddings = OpenAIEmbeddings(
    model="text-embedding-ada-002",
    openai_api_base="https://api.holysheep.ai/v1"
)

1) 문서 로드
loader = TextLoader("./project_docs.txt")
documents = loader.load()

2) 두 단계의 분할기 설정
부모: 큰 단위 (전체 문맥 유지)
parent_splitter = RecursiveCharacterTextSplitter(chunk_size=3000, chunk_overlap=200)

자식: 작은 단위 (정밀 검색)
child_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)

3) 벡터스토어 및 Parent Document Retriever 초기화
vectorstore = Chroma(persist_directory="./rag_parent_child", embedding_function=embeddings)

retriever = ParentDocumentRetriever(
    vectorstore=vectorstore,
    docstore=vectorstore,
    parent_splitter=parent_splitter,
    child_splitter=child_splitter,
    search_kwargs={"k": 5}  # 상위 5개 부모 문서 검색
)

4) 문서 등록
retriever.add_documents(documents)
print("✅ Parent Document Retriever 초기화 완료")

이제 검색해보면:

검색 테스트
query = "프로젝트의 전체 마일스톤과 각 단계별 세부 일정은?"
results = retriever.get_relevant_documents(query)

print(f"검색된 부모 문서 수: {len(results)}\n")
for i, doc in enumerate(results, 1):
    print(f"--- 문서 {i} (길이: {len(doc.page_content)}자) ---")
    print(doc.page_content[:500])
    print("...\n")

출력 예시:
검색된 부모 문서 수: 2
--- 문서 1 (길이: 2850자) ---
프로젝트 마일스톤 일정
# 
1단계 (2024.Q1): 기획 및 설계
- 요구사항 분석: 1월~2월
- 시스템 아키텍처 설계: 2월~3월
...
--- 문서 2 (길이: 2100자) ---
상세 일정표
# 
2단계 (2024.Q2): 개발 및 테스트
...

HolySheep AI + GPT-4.1로 완전한 RAG 파이프라인 구축

from langchain_openai import ChatOpenAI
from langchain.chains import RetrievalQA

✅ HolySheep AI의 GPT-4.1 ($8/MTok) 사용
llm = ChatOpenAI(
    model="gpt-4.1",
    temperature=0.3,
    openai_api_key="YOUR_HOLYSHEEP_API_KEY",
    openai_api_base="https://api.holysheep.ai/v1"  # 반드시 HolySheep 게이트웨이 사용
)

RAG 체인 구성
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",  # 부모 문서를 모두 컨텍스트에 stuffing
    retriever=retriever,
    return_source_documents=True
)

질문 실행
query = """
2024년 프로젝트 마일스톤을 요약하고, 
각 단계별 핵심 deliverable을 설명해줘.
특히 AI 통합 부분의 일정은 어떻게 되는지重点的に 알려줘.
"""

response = qa_chain({"query": query})

print("=== AI 응답 ===")
print(response["result"])
print(f"\n참조된 문서 수: {len(response['source_documents'])}")

이렇게 구성하면:

• 검색 단계: 자식 청크에서 semantic 유사도 기반으로 정밀 검색
• 컨텍스트 단계: 매칭된 자식의 부모 문서 전체를 LLM에 전달
• 응답 단계: 완전한 문맥을 바탕으로 일관된 답변 생성

고급 설정：상황별 최적화 전략

1. 긴 문서 최적화 (RAGatouille 스타일)

from langchain.text_splitter import RecursiveCharacterTextSplitter

class HybridParentRetriever:
    """문서 길이에 따라 동적으로 청크 크기 조정"""
    
    def __init__(self, vectorstore, embeddings):
        self.vectorstore = vectorstore
        self.embeddings = embeddings
        self.parent_retriever = ParentDocumentRetriever(
            vectorstore=vectorstore,
            docstore=vectorstore,
            # 긴 문서용: 더 큰 부모 청크
            parent_splitter=RecursiveCharacterTextSplitter(
                chunk_size=5000, 
                chunk_overlap=300,
                separators=["\n\n## ", "\n## ", "\n# ", "\n\n", "\n", " ", ""]
            ),
            # 세밀한 검색용 자식 청크
            child_splitter=RecursiveCharacterTextSplitter(
                chunk_size=800, 
                chunk_overlap=100
            ),
            search_kwargs={"k": 3}
        )
    
    def add_documents(self, documents, doc_type=None):
        """문서 유형에 따라 분할 전략 자동 선택"""
        for doc in documents:
            # 문서 길이에 따라 부모 청크 크기 동적 조정
            if len(doc.page_content) > 10000:
                # 긴 기술 문서: 더 큰 청크
                doc.metadata["parent_chunk_size"] = 8000
            else:
                # 짧은 문서: 표준 청크
                doc.metadata["parent_chunk_size"] = 3000
        
        self.parent_retriever.add_documents(documents)

사용 예시
hybrid_retriever = HybridParentRetriever(vectorstore, embeddings)
hybrid_retriever.add_documents(documents, doc_type="technical_spec")

2. 다중 벡터스토어 백엔드 지원

HolySheep AI에서 다양한 임베딩 모델 지원
비용과 품질 균형 선택 가능

from langchain_openai import OpenAIEmbeddings

옵션 1: Ada-002 (저렴+빠름, 대부분의 경우 적합)
ada_embeddings = OpenAIEmbeddings(
    model="text-embedding-ada-002",
    openai_api_base="https://api.holysheep.ai/v1"
)

옵션 2: 3-small (가성비, 빠른 응답)
small_embeddings = OpenAIEmbeddings(
    model="text-embedding-3-small",
    openai_api_base="https://api.holysheep.ai/v1"
)

옵션 3: 3-large (고품질, 정확한 의미 검색)
large_embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large", 
    openai_api_base="https://api.holysheep.ai/v1"
)

사용 시나리오별 선택
USE_CASE_EMBEDDING = {
    "technical_docs": large_embeddings,  # 기술 문서: 정확도 우선
    "general_knowledge": small_embeddings,  # 일반 검색: 속도 우선
    "code_search": ada_embeddings,  # 코드 검색: 균형
}

자주 발생하는 오류와 해결

오류 1: ValueError: Unable to get text content

❌ 잘못된 분할기 조합
parent_splitter = RecursiveCharacterTextSplitter(chunk_size=100)  # 너무 작음
child_splitter = RecursiveCharacterTextSplitter(chunk_size=200)   # 부모보다 큼

✅ 올바른 설정: 부모 > 자식
parent_splitter = RecursiveCharacterTextSplitter(chunk_size=3000)
child_splitter = RecursiveCharacterTextSplitter(chunk_size=500)

부모 청크가 자식보다 작으면 문맥이 분리되지 않음

오류 2: AuthenticationError: Invalid API key

❌ 잘못된 base_url 설정
os.environ["OPENAI_API_BASE"] = "https://api.openai.com/v1"  # 직접 호출 ❌

✅ HolySheep AI 게이트웨이 사용
os.environ["OPENAI_API_BASE"] = "https://api.holysheep.ai/v1"
os.environ["OPENAI_API_KEY"] = "YOUR_HOLYSHEEP_API_KEY"  # HolySheep 키

에러 메시지가 "401 Unauthorized"로 나오면 API 키 확인 필수
HolySheep 대시보드에서 키 재생성 후 재시도

오류 3: RecursionError: maximum recursion depth exceeded

❌ 무한 재귀 발생 원인
child_splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=80,  # 오버랩이 너무 큼 → 재귀적 분할 무한루프
    separators=["\n\n", "\n", " "]  # 구분자 우선순위 문제
)

✅ 올바른 설정
child_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50,  # chunk_size의 10% 정도
    separators=["\n\n", "\n", ". ", " ", ""],
    is_separator_regex=False  # 정규식 비활성화
)

해결 후 retriever 재초기화 필수
retriever = ParentDocumentRetriever(
    vectorstore=vectorstore,
    docstore=vectorstore,
    parent_splitter=parent_splitter,
    child_splitter=child_splitter,
)

오류 4: MemoryError: cannot allocate memory

❌ 대량 문서 처리 시 메모리 초과
all_docs = loader.load()  # 수백 MB 문서 한 번에 로드

✅ 배치 처리로 메모리 절약
from langchain_community.document_loaders import TextLoader
from langchain.schema import Document

def batch_process_documents(file_paths, batch_size=100):
    """대량 문서를 배치로 처리"""
    all_embeddings = []
    batch_docs = []
    
    for i, file_path in enumerate(file_paths):
        loader = TextLoader(file_path)
        docs = loader.load()
        batch_docs.extend(docs)
        
        # 배치 단위로 처리
        if len(batch_docs) >= batch_size:
            # 자식 청크로 분할
            child_chunks = child_splitter.split_documents(batch_docs)
            # 배치 처리 후 메모리 해제
            yield child_chunks
            batch_docs = []
            import gc; gc.collect()
    
    # 나머지 문서 처리
    if batch_docs:
        yield child_splitter.split_documents(batch_docs)

사용
for batch in batch_process_documents(file_list):
    vectorstore.add_documents(batch)

저의 실무 경험담

실제로 제가 Parent Document Retriever를 도입한 계기는 법률 문서 RAG 시스템 구축이었습니다. 계약서, 약관, 판례 등의 문서를 처리해야 했는데, 기존 청킹 방식으로:

• "이 계약의 해지 조항" 검색 시 조항 제목만 반환
• 본문 해석을 위한 앞뒤 문맥 누락
• 법적 해석의 연속성 상실

문제가 심각해 Context7 패턴도 시도했지만:

Context7: 주변 N개 청크도 함께 가져오는 방식
def context7_retriever(query, k=3, N=2):
    """N개 주변 청크 포함 검색"""
    initial_results = vectorstore.similarity_search(query, k=k)
    
    # 주변 청크 추가 로직... 복잡하고 에러 발생 가능성 높음
    # 특히 문서 경계를 넘나드는 경우 처리 곤란
    
결국 Parent Document Retriever로 전환
더 깔끔하고 예측 가능한 동작

Parent Document Retriever로 전환 후:

1. 법적 조항 검색 시 전체 계약서 맥락 제공 가능
2. chunk_size 튜닝만으로 정확도 조절 가능
3. LangChain 내장 기능이라 유지보수 용이

다만 주의할 점이 있습니다:

• 부모 문서가 너무 크면 LLM 컨텍스트 창 낭비 → chunk_size 3000-5000 자 권장
• 검색 정밀도가 중요한 경우 자식 청크 크기를 더 작게(300-500자)
• HolySheep AI의 무료 크레딧으로 임베딩 비용 절감 가능

비용 최적화 팁

HolySheep AI를 사용하면 Parent Document Retriever의 임베딩 비용을 크게 줄일 수 있습니다:

• text-embedding-3-small: ada-002 대비 작고 빠른 임베딩, 대부분의 검색 정확도 유지
• 배치 임베딩 API: 다중 문서 처리 시 비용 50% 절감
• HolySheep 무료 크레딧: 매월 무료 크레딧 제공으로 소규모 프로젝트는 완전 무료

HolySheep AI 비용 최적화 예시
월 10만 건 검색 + 5만 문서 인덱싱 시

옵션 1: ada-002 사용
인덱싱: 50,000 docs × 10 chunks × $0.0001/1K = $50
검색: 100,000 × ada-002 비용 포함 = $10
월 합계: ~$60

옵션 2: 3-small 사용
인덱싱: 50,000 × 10 × $0.00002/1K = $10
검색: 100,000 × 3-small 비용 포함 = $2
월 합계: ~$12 (80% 절감)

HolySheep AI에서는 이런 비용 최적화가 자동으로 적용

정리

Parent Document Retriever는 RAG 시스템에서 검색 정밀도와 컨텍스트 완성도를 동시에 달성하는 강력한 패턴입니다:

• 자식 청크: 정밀한 semantic 검색의 기반
• 부모 문서: 완전한 문맥으로 일관된 응답 생성
• HolySheep AI: 전 세계 개발자를 위한 통합 API 게이트웨이, 로컬 결제 지원, 지금 가입하고 무료 크레딧으로 시작하세요

hierarchical retrieval 패턴을 통해 LLM의 잠재력을 최대한 활용하고, 정확한 정보를 신뢰할 수 있는 컨텍스트와 함께 제공할 수 있습니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기