zilliztech/deep-searcher 딥다이브
— 내 문서에 대고 굴리는 오픈소스 "딥리서치"

1한 줄 정체

DeepSearcher는 "내 문서 더미를 벡터DB에 넣어두면, 복잡한 질문에 대해 스스로 여러 번 검색·추론해서 근거 있는 보고서를 써 주는 에이전트"다. 일반 챗봇에게 "우리 회사 2024 회계 보고서 요약해줘"라고 하면 한 번 검색하고 끝이지만, DeepSearcher는 질문을 잘게 쪼개 여러 각도로 검색하고, 나온 자료가 충분한지 스스로 점검한 뒤 부족하면 다시 검색한다.

기술적으로는 두 단계다. ① 오프라인 적재(ingestion) — 로컬 파일이나 웹페이지를 잘게 쪼개(chunk) 임베딩해서 벡터DB에 넣어둔다. ② 온라인 질의(query) — 질문이 들어오면 라우터가 적절한 에이전트를 골라, 하위질문 분해 → 반복 검색 → 반성 → 종합의 에이전트 루프를 돌려 답을 만든다.

2왜 주목받는가 — "딥리서치"를 내 데이터로

2025~2026년 AI 업계의 핫한 키워드가 바로 "Deep Research(딥리서치)"다. OpenAI·구글·퍼플렉시티가 "한 번 묻고 끝"이 아니라 몇 분간 스스로 웹을 뒤져 리포트를 써 주는 기능을 내놨다. 그런데 이들에겐 공통된 한계가 있다:

• 내 데이터를 못 본다 — 사내 위키, 계약서, 연구 노트는 클라우드 딥리서치가 접근할 수 없다(보안·비공개).
• 블랙박스다 — 어떤 순서로 검색하고 무엇을 근거로 삼았는지 뜯어볼 수 없다.
• 돈·종속 — 특정 벤더에 묶이고, 모델·검색 방식을 내 마음대로 못 바꾼다.

DeepSearcher는 이 세 가지를 정면으로 뒤집는다. 내 벡터DB(Milvus 등)에 넣은 사내 데이터에 대고, 오픈소스 코드로 절차가 다 보이게, LLM·임베딩·벡터DB를 자유롭게 갈아끼우며 딥리서치를 돌린다. 게다가 Milvus를 만든 Zilliz가 직접 만들어 벡터 검색 부분이 특히 탄탄하다.

3기술 스택 전체 지도

런타임 & 빌드 도구

공급자(provider) 전체 목록 — 이 표가 알맹이다

DeepSearcher의 진짜 힘은 "무엇이든 갈아끼운다"는 데 있다. 아래는 소스의 __init__.py export 기준(README 표는 일부 낡음)이다. 다섯 축 전부가 플러그인처럼 교체된다.

4아키텍처 심화 — 라우터·딥서치·체인오브RAG

전체 흐름 한 장

핵심 패턴 ① — 에이전트를 LLM이 고른다 (RAGRouter)

DeepSearcher엔 성격이 다른 에이전트가 둘 있다: DeepSearch(넓은 보고서형)와 ChainOfRAG(콕 집은 사실·멀티홉). 어느 걸 쓸지 사람이 정하지 않고 LLM이 고른다. 각 에이전트는 @describe_class(...) 데코레이터로 "나는 이런 질문에 강해"라는 설명을 달고 있고, 라우터는 그 설명들을 LLM에게 보여주며 최적의 하나를 고르게 한다.

# agent/chain_of_rag.py — 데코레이터가 라우팅의 근거가 된다
@describe_class(
  "This agent can decompose complex queries and gradually find the "
  "fact information of sub-queries. It is very suitable for handling "
  "concrete factual queries and multi-hop questions."
)
class ChainOfRAG(RAGAgent):
    ...

핵심 패턴 ② — "부족함을 스스로 찾는" 반성 루프

DeepSearch의 진짜 알맹이는 _generate_gap_queries()다. 한 바퀴 검색한 뒤, 지금까지 모은 근거를 LLM에게 보여주며 "이 질문에 답하기엔 아직 뭐가 빠졌지? 빠진 걸 채울 새 질문을 만들어"라고 시킨다. 빈 리스트가 나오면(=충분함) 루프를 빠져나가고, 새 질문이 나오면 그걸 들고 다시 검색한다. 이 "검색→반성→재검색"이 단순 RAG와 딥리서치를 가르는 결정적 차이다.

# agent/deep_search.py — 병렬 검색 + LLM 재순위(요지)
# 하위 gap 질문들을 한꺼번에 비동기 검색
search_tasks = [self._search_chunks_from_vectordb(q, sub_gap_queries)
                for q in sub_gap_queries]
search_results = await asyncio.gather(*search_tasks)

# 각 청크를 LLM이 YES/NO로 걸러 accept
if "YES" in response_content and "NO" not in response_content:
    all_retrieved_results.append(retrieved_result)
    references.add(retrieved_result.reference)

핵심 패턴 ③ — ChainOfRAG: 멀티홉을 한 걸음씩

"A의 상사가 세운 회사의 본사는 어디?" 같은 멀티홉 질문은 한 번에 검색이 안 된다. ChainOfRAG(논문 arXiv 2501.14342 기반)는 매 홉마다 ① 다음에 무엇을 물어야 할지 후속 질문 생성(FOLLOWUP_QUERY_PROMPT) → ② 검색해 중간 답 도출 → ③ 근거 문서 선별 → ④ "이제 최종 답을 낼 만큼 정보가 모였나?"(early stopping) 판단을 반복한다. 마지막에 중간 Q-A 사슬을 엮어 최종 답을 만든다.

핵심 패턴 ④ — 공급자 팩토리 (동적 import)

17개 LLM을 if provider == "OpenAI": ... elif ...로 나열하지 않는다. config.yaml의 provider 문자열(=클래스 이름)을 그대로 받아 동적으로 import·인스턴스화한다. 새 공급자를 추가해도 이 팩토리는 손댈 필요가 없다.

# configuration.py — ModuleFactory 요지
class_name = self.config.provide_settings[feature]["provider"]
module = __import__(module_name, fromlist=[class_name])
class_ = getattr(module, class_name)
return class_(**self.config.provide_settings[feature]["config"])

핵심 패턴 ⑤ — 추론 모델을 위한 출력 살균

추론 모델은 <think>...</think> 같은 사고 과정을 답 앞에 붙이거나, 리스트를 ```python ... ``` 코드펜스로 감싸 뱉는다. BaseLLM.remove_think는 사고 블록을 잘라내고, literal_eval은 코드펜스를 벗겨 첫 리스트/딕셔너리만 안전하게 추출한다. "LLM 출력은 못 믿는다"를 전제로 한 방어 코드다.

# llm/base.py
@staticmethod
def remove_think(response_content: str) -> str:
    if "<think>" in response_content and "</think>" in response_content:
        end = response_content.find("</think>") + len("</think>")
        response_content = response_content[end:]
    return response_content.strip()

5디렉토리 구조 해부

코드 무게중심을 줄 수가 말해준다. 가장 무거운 건 벡터DB 백엔드(oracle.py 536줄)와 두 핵심 에이전트(chain_of_rag.py 326, deep_search.py 319)다. 즉 이 레포의 지식은 agent/와 vector_db/에 몰려 있다.

6학습 포인트 — 기술별 배울 것

실습 아이디어 (짧게)

• Milvus Lite(uri: "./milvus.db")로 벡터DB 세팅 없이 PDF 몇 개 넣고 질문해 보기.
• DeepSearch에 로그를 추가해 하위질문·gap질문·YES/NO 판정을 눈으로 추적하기.
• 같은 질문을 naive_rag_query와 query로 각각 돌려 답 품질을 비교하기.

7시스템 / 실행 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub: github.com/zilliztech/deep-searcher — 소스·README·config.yaml
• 문서 사이트: 저장소 docs/(mkdocs-material) · DeepWiki deepwiki.com/zilliztech/deep-searcher
• PyPI: pip install deepsearcher (v0.0.2, Apache-2.0)
• 배경 논문: ChainOfRAG — arXiv 2501.14342
• 핵심 의존 기술: Milvus(벡터DB), LangChain Text Splitters, FastAPI, Ollama(로컬 LLM)