Local Deep Research는 웹, 학술 데이터베이스, 로컬 문서, 외부 API를 결합해 다단계 리서치 보고서를 생성하는 오픈소스 연구 자동화 프로젝트다. 핵심 방향은 로컬 실행, 사용자별 암호화 저장소, 다양한 LLM·검색 엔진 선택권, 출처 기반 보고서 생성이다.
분석 기준: GitHub README,
docs/architecture.md,docs/features.md,docs/search-engines.md, Wiki, Discussions,pyproject.toml,package.json, Docker 구성,src/local_deep_research/소스 트리.
Quick Links
| 구분 | 링크 | 비고 |
|---|---|---|
| Repository | LearningCircuit/local-deep-research | 공식 GitHub 저장소 |
| Architecture | docs/architecture.md | Mermaid 기반 시스템 구조, 연구 흐름, 보안 계층 설명 |
| Features | docs/features.md | 리서치, 검색, LLM, API, 분석 대시보드 기능 정리 |
| Search Engines | docs/search-engines.md | arXiv, PubMed, Semantic Scholar, SearXNG, Brave, Tavily 등 검색 엔진 목록 |
| Installation | docs/installation.md | Docker, pip, 수동 설치 가이드 |
| API Quickstart | docs/api-quickstart.md | 인증 기반 REST API 사용법 |
| MCP Server | docs/mcp-server.md | Claude Desktop 등 외부 MCP 클라이언트 연동 |
| Benchmark Dataset |
Hugging Face benchmark dataset | 프로젝트가 공개한 벤치마크 데이터셋 |
| Demo / Review | The Art Of The Terminal review | README에 연결된 리뷰·데모 영상 |
| Wiki | Project Wiki | 로컬 검색, 설치, 개발자 가이드 |
| Paper | 별도 공식 논문은 확인되지 않음 | 현재는 문서·벤치마크 데이터셋 중심 공개 |
Key Features
1. 에이전틱 다단계 리서치
프로젝트의 중심 클래스는 AdvancedSearchSystem이며, 사용자의 질문을 전략 객체로 전달해 검색, 재검색, 결과 분석, 보고서 생성을 조율한다.
README와 아키텍처 문서는 표준 검색, 병렬 검색, 재귀 검색, focused iteration, LangGraph 기반 agent strategy, MCP strategy 등 20개 이상의 연구 전략을 설명한다.
문서별로 전략 수 표현은 다소 다르지만, 공통적으로 “단일 검색 → 요약”이 아니라 “질문 분해 → 다중 엔진 검색 → 근거 검증 → 종합” 흐름을 지향한다.
그림 설명: docs/architecture.md의 연구 흐름을 PNG로 재구성한 도식이다. 사용자의 질문이 세부 연구 질문으로 분해되고, 병렬 검색과 근거 분석을 거쳐 인용 가능한 최종 보고서로 합성되는 루프를 보여준다.
2. 웹·학술·기술·로컬 문서를 아우르는 검색 엔진 레이어
검색 엔진은 단순 웹 검색에 제한되지 않는다.
문서 기준으로 arXiv, PubMed, Semantic Scholar, Wikipedia, SearXNG, DuckDuckGo, GitHub, Elasticsearch, Wayback Machine, Brave, Tavily, Google 계열 검색, LangChain retriever, 로컬 문서 검색 등을 지원한다. src/local_deep_research/web_search_engines/에는 PubMed, OpenAlex, PubChem, Zenodo, StackExchange, GitHub, SearXNG, Brave, Tavily 등 엔진별 구현이 분리되어 있어 새 검색 공급자 추가가 비교적 명확하다.
그림 설명: 소스 트리 분석을 바탕으로 만든 코드 구조 맵이다. Web/API 계층이 AdvancedSearchSystem으로 요청을 보내고, 전략 레이어가 검색 엔진·LLM·문서 라이브러리·exporter를 조합하는 구조를 나타낸다.
3. 로컬 문서 기반 RAG와 개인 지식 베이스
Wiki의 로컬 검색 문서는 사용자가 지정한 로컬 폴더의 문서를 임베딩하고 벡터 데이터베이스에 색인해 검색 대상으로 활용하는 흐름을 설명한다.
이 기능은 단발성 웹 리서치 도구가 아니라, 사용자의 논문 PDF, 사내 문서, 프로젝트 노트, 실험 결과를 점진적으로 재사용하는 개인 연구 지식 베이스에 가깝다.
그림 설명: 저장소의 docs/images/Local Search.png 원본 이미지다. 로컬 문서가 임베딩과 벡터 인덱스를 거쳐 리서치 과정에서 검색 가능한 컬렉션으로 사용되는 방식을 설명한다.
4. 설정 UI를 통한 로컬 컬렉션 경로 지정
로컬 검색은 코드만 수정하는 방식이 아니라 Web UI의 설정에서 문서 경로를 지정하는 흐름을 갖는다.
연구자가 이미 보유한 PDF, 보고서, 텍스트 자료를 정해진 폴더에 넣고 컬렉션 단위로 색인하면, 이후 검색 전략에서 외부 웹 자료와 함께 내부 자료를 활용할 수 있다.
그림 설명: 저장소의 docs/images/local_search_paths.png 원본 이미지다. 로컬 컬렉션 경로를 UI에서 지정하는 설정 화면을 보여준다.
5. 임베딩 모델 선택과 벡터 검색 구성
로컬 문서 검색은 임베딩 모델 품질에 크게 의존한다.
Wiki는 로컬 컬렉션 설정에서 embedding model type을 지정하는 화면을 제공하며, pyproject.toml 기준으로 sentence-transformers, FAISS CPU, LangChain 관련 패키지를 포함한다.
즉, 검색 품질은 LLM만이 아니라 임베딩 모델, chunking, 벡터 인덱스 구성에도 영향을 받는다.
그림 설명: 저장소의 docs/images/local_search_embedding_model_type.png 원본 이미지다. 로컬 컬렉션 검색에 사용할 임베딩 모델 유형을 설정하는 UI를 보여준다.
6. 로컬·클라우드 LLM 모두 지원
README와 문서는 Ollama, LM Studio, llama.cpp 계열 로컬 모델뿐 아니라
OpenAI, Anthropic, Gemini, OpenRouter 등 클라우드 LLM도 지원한다고 설명한다.
이 선택권은 비용, 품질, 개인정보 요구사항에 따라 모드를 바꿀 수 있게 한다.
예를 들어 민감 문서가 많은 환경에서는 Ollama와 SearXNG를 조합한 완전 로컬 모드를 쓰고, 공개 웹 리서치나 고난도 추론에서는 클라우드 LLM을 선택할 수 있다.
7. 사용자별 암호화 저장소와 프라이버시 우선 설계
README와 API 문서는 사용자별 SQLCipher 데이터베이스, AES-256 암호화, 인증, CSRF 보호, rate limiting, 보안 헤더, 로컬 데이터 보관, 기본 no-telemetry 방향을 강조한다.
이는 의료·바이오·기업 문서처럼 민감한 컨텍스트를 다루는 연구 도구에서 중요한 차별점이다.
그림 설명: 문서와 소스 구조에서 확인한 보안 계층을 요약한 그림이다. 인증, CSRF, rate limiting, 사용자별 SQLCipher DB, 로컬 우선 운영, 보안 스캐닝을 하나의 흐름으로 표현했다.
8. 보고서 export, API, MCP 서버
결과물은 Markdown, PDF, LaTeX, Quarto, RIS/BibTeX 등으로 확장 가능하며, REST API와 MCP 서버도 제공된다.
MCP 문서는 quick_research, detailed_research, generate_report, analyze_documents, search, list_search_engines, list_strategies, get_configuration 같은 도구를 외부 에이전트 클라이언트에 노출하는 구조를 설명한다.
따라서 이 프로젝트는 웹앱이면서 동시에 다른 AI 에이전트가 호출할 수 있는 research backend 역할도 수행할 수 있다.
9. 벤치마크, 분석 대시보드, 저널 품질 필터링
README는 SimpleQA, BrowseComp, xbench-DeepSearch 계열 프로젝트 보고 벤치마크를 제시한다. docs/BENCHMARKING.md는 벤치마크 방식과 caveat를 설명하고, docs/analytics.md는 토큰·비용·세션·검색 엔진 상태·사용자 만족도 추적을 정리한다.
docs/journal-quality.md는 OpenAlex, DOAJ, predatory journal 목록을 활용한 저널 품질 점수화를 설명한다. 특히 의학·생명과학 리서치에서 단순 검색 결과보다 출처 품질을 평가하는 기능은 실용성이 높다.
Tech Stack
| 영역 | 주요 구성 | 버전·특징 |
|---|---|---|
| Runtime | Python | pyproject.toml 기준 >=3.12,<3.15 |
| Package version | Local Deep Research | src/local_deep_research/__version__.py 기준 1.6.11 |
| Backend Web | Flask, Flask-SocketIO, Flask-WTF, Flask-Login, Flask-Limiter | Flask 3.1.3, Socket.IO 5.6.1 계열 |
| Data / DB | SQLAlchemy, Alembic, SQLCipher | 사용자별 암호화 DB, 마이그레이션, 설정·히스토리 저장 |
| LLM / Agent | LangChain, provider adapters, LangGraph strategy | LangChain 1.2 계열, Ollama/OpenAI/Anthropic/Gemini/OpenRouter 등 |
| RAG / Embedding | sentence-transformers, FAISS CPU, pypdf, pdfplumber, unstructured | sentence-transformers 5.2, FAISS 1.13 계열 |
| Web crawling / content | Playwright, Crawl4AI, requests/httpx | Playwright 1.58 계열, 웹 페이지 수집·파싱 |
| Frontend | Node, Vite, Bootstrap, Chart.js, Socket.IO client | Node >=24.0.0, Vite 8.0.13, Bootstrap 5.3.8, Chart.js 4.5.1 |
| Export | WeasyPrint, Markdown/LaTeX/Quarto/RIS/BibTeX handlers | PDF 및 학술 인용 형식 export 지원 |
| DevOps | PDM, Docker, Docker Compose, pre-commit, ruff, mypy | Dockerfile은 Python 3.14.5-slim, PDM 2.26.2, Node 24.x 설치 흐름 사용 |
| Search providers | SearXNG, DuckDuckGo, Brave, Tavily, arXiv, PubMed, Semantic Scholar, OpenAlex, GitHub 등 | 무료·프리미엄·로컬 검색 엔진 혼합 |
Architecture
그림 설명: docs/architecture.md의 Mermaid 시스템 구조를 PNG로 재구성한 아키텍처 다이어그램이다. UI, Flask Backend, Research Engine, LLM Providers, Search Engines, Storage, Output 계층이 어떻게 연결되는지 보여준다.
계층별 해석
- User Interface
브라우저 기반 Web UI가 연구 요청, 설정, 히스토리, 문서 라이브러리, 진행 상태를 담당한다. Socket.IO를 통해 실시간 진행 상황을 보여주는 구조다. - Flask Backend
Flask app factory가 인증, CSRF, security headers, rate limiting, per-user database connection, cleanup scheduler 등을 초기화한다. 라우트는 연구 실행, 히스토리, 설정, 메트릭, 문서 라이브러리, API 기능으로 나뉜다. - Research Engine
AdvancedSearchSystem이 전략 팩토리를 통해 적절한 검색 전략을 생성한다. 전략은 검색 엔진, LLM provider, 문서 라이브러리, citation handler, report generator를 조합한다. - Search Engine Layer
웹 검색, 학술 검색, 기술 검색, 아카이브 검색, 로컬 문서 검색을 모두 별도 엔진 클래스로 관리한다. 이 레이어가 잘 분리되어 있어 새 엔진 추가나 특정 도메인 검색 특화가 가능하다. - Storage Layer
사용자별 SQLCipher DB, 파일 저장소, 벡터 인덱스가 결합된다. 연구 히스토리, 설정, 다운로드한 자료, 로컬 문서 chunk, 인용 정보를 저장한다. - Output Layer
최종 결과는 Markdown/PDF/LaTeX/Quarto 보고서와 RIS/BibTeX 인용 데이터, REST API/MCP 응답으로 확장된다.
Knowledge Loop
그림 설명: docs/architecture.md의 Knowledge Loop를 기반으로 재구성한 그림이다. 연구 중 발견한 자료가 다운로드, 라이브러리 저장, chunking, embedding, vector index를 거쳐 다음 연구에서 재사용되는 흐름을 나타낸다.
이 루프는 프로젝트의 장기 가치를 만든다.
한 번 검색한 공개 자료나 업로드한 내부 문서는 단순 히스토리로 남는 것이 아니라, 후속 연구의 retrieval context가 될 수 있다.
의료 AI나 바이오인포매틱스에서는 특정 질병군, pathway, assay, 임상 지침 문서가 반복적으로 재사용되므로 이 구조가 특히 유효하다.
Usage & Setup
그림 설명: README와 Docker Compose 구성을 바탕으로 만든 배포 모드 도식이다. 완전 로컬, 하이브리드, 클라우드 LLM/API 활용 모드를 비교한다.
1. Docker Compose 권장 설치
공식 문서는 Docker Compose를 가장 간단한 시작 방식으로 제시한다.
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml
docker compose up -d
브라우저에서 다음 주소로 접속한다.
http://localhost:5000
GPU 환경에서는 저장소의 docker-compose.gpu.yml override를 함께 사용하는 구성이 제공된다.
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d2. Docker 단독 실행 예시
README의 빠른 시작 예시는 Ollama, SearXNG, Local Deep Research 컨테이너를 조합한다.
# Ollama 실행 및 모델 다운로드
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama pull gpt-oss:20b
# SearXNG 실행
docker run -d -p 8080:8080 --name searxng searxng/searxng
# Local Deep Research 실행
docker run -d \
-p 5000:5000 \
--network host \
--name local-deep-research \
--volume "deep-research:/data" \
-e LDR_DATA_DIR=/data \
localdeepresearch/local-deep-research3. pip 설치
간단한 로컬 설치는 PyPI 패키지를 통해 가능하다.
pip install local-deep-research
ldr-web
대체 실행 방식은 다음과 같다.
python -m local_deep_research.web.app4. 개발자 설치
Wiki의 Developer Guide는 PDM 기반 개발 환경을 사용한다.
pdm install --no-self
pre-commit install
pdm venv activate
cd src
python -m local_deep_research.web.app
CLI 테스트는 다음 방식으로 실행할 수 있다.
python -m local_deep_research.main
패키지 빌드는 다음 명령으로 수행한다.
pdm build5. 로컬 문서 검색 구성 요약
- Web UI 설정에서 로컬 컬렉션 경로를 지정한다.
- embedding model type을 선택한다.
- 문서를 색인한다.
- 연구 전략에서 local document / collection search 엔진을 활성화한다.
- 외부 검색 결과와 내부 문서 검색 결과를 함께 사용해 보고서를 생성한다.
Personal Insights
의료 AI 관점
Local Deep Research는 의료 AI 리서치 보조 도구로 활용 가능성이 높다.
PubMed, Semantic Scholar, OpenAlex, 저널 품질 필터링, 로컬 문서 RAG가 결합되면 질병별 문헌 조사, 임상 가이드라인 비교, 약물·바이오마커 후보 조사, 논문 근거 정리에 유용하다.
다만 임상 의사결정 지원 시스템으로 쓰기에는 추가 검증이 필요하다. 특히 다음 조건이 필요하다.
- PubMed 검색 쿼리와 필터가 재현 가능해야 한다.
- 근거 수준, 연구 디자인, sample size, publication date, retraction 여부를 명시적으로 추적해야 한다.
- PHI/PII가 포함된 문서를 처리할 때는 배포 환경, 접근 제어, 감사 로그, 데이터 보존 정책이 의료 규제에 맞아야 한다.
- LLM이 생성한 의학적 결론은 자동 신뢰 대상이 아니라, 임상의 또는 도메인 전문가의 검토 대상이어야 한다.
Bioinformatics 관점
바이오인포매틱스에서는 문헌, preprint, GitHub repository, protocol, dataset metadata, pathway database, 실험 노트가 혼재한다.
이 프로젝트의 강점은 여러 출처를 하나의 리서치 워크플로로 결합할 수 있다는 점이다.
유용한 적용 예시는 다음과 같다.
- 특정 gene set 또는 pathway 관련 최신 문헌 조사
- PubMed + arXiv + Semantic Scholar + GitHub를 결합한 도구 탐색
- 로컬 실험 노트와 공개 논문을 함께 검색하는 private RAG
- single-cell, spatial transcriptomics, metagenomics pipeline 비교
- 분석 도구의 GitHub repository, benchmark, citation, issue history를 함께 검토
추가로 PubChem, Zenodo, OpenAlex 계열 검색 엔진을 활용하면 화합물, 데이터셋, 학술 메타데이터까지 조사 범위를 넓힐 수 있다.
다만 생물정보학 워크플로에서는 결과 재현성이 핵심이므로, 최종 보고서에 검색 쿼리, 검색 날짜, database version, tool version을 함께 남기는 기능이 중요하다.
Autonomous Agent 개발 관점
이 프로젝트는 agentic research system의 좋은 설계 사례다.
단일 대형 프롬프트로 모든 작업을 처리하지 않고, 검색 전략, 검색 엔진, LLM provider, 문서 저장소, exporter, API/MCP 레이어를 분리한다. 이 구조는 다음 장점을 만든다.
- 전략별 성능 비교가 가능하다.
- 특정 검색 엔진 장애가 전체 시스템 장애로 번지지 않도록 분리할 수 있다.
- 로컬 LLM과 클라우드 LLM을 비용·보안 요구에 따라 교체할 수 있다.
- MCP 서버를 통해 다른 에이전트가 Local Deep Research를 research tool로 호출할 수 있다.
- benchmark와 analytics를 통해 “그럴듯한 답변”이 아니라 “전략별 성능”을 추적할 수 있다.
개선 여지가 있는 지점도 있다.
의료·바이오 특화 에이전트로 발전하려면 provenance graph, evidence grading, conflict detection, query audit trail, structured extraction schema, 자동 retraction check, 임상/실험 도메인 ontology 연동이 필요하다.
특히 단순 citation보다 “어떤 근거가 어떤 결론을 지지했는지”를 그래프 형태로 남기는 기능은 향후 차별화 포인트가 될 수 있다.
Asset Mapping
| 파일 | 출처 | 문서 내 배치 | 설명 |
|---|---|---|---|
figures/architecture_overview.png |
docs/architecture.md Mermaid 구조를 재구성 |
Architecture | 전체 시스템 계층과 데이터 흐름 |
figures/research_flow.png |
docs/architecture.md 연구 흐름을 재구성 |
Key Features | 질문 분해, 병렬 검색, 분석, 보고서 생성 루프 |
figures/knowledge_loop.png |
docs/architecture.md Knowledge Loop 재구성 |
Architecture | 연구 자료가 개인 지식 베이스로 축적되는 흐름 |
figures/deployment_topology.png |
README 및 Docker Compose 구성 기반 재구성 | Usage & Setup | 완전 로컬, 하이브리드, 클라우드 모드 비교 |
figures/security_architecture.png |
README/API/소스 구조 기반 재구성 | Key Features | 인증, CSRF, 암호화 DB, no-telemetry 계층 |
figures/code_structure_map.png |
src/local_deep_research/ 소스 트리 분석 기반 재구성 |
Key Features | Web/API, core system, strategies, engines, storage 관계 |
figures/local_search_diagram.png |
저장소 원본 docs/images/Local Search.png |
Key Features | 로컬 검색과 벡터 인덱스 흐름 |
figures/local_search_paths.png |
저장소 원본 docs/images/local_search_paths.png |
Key Features | 로컬 컬렉션 경로 설정 UI |
figures/local_search_embedding_model_type.png |
저장소 원본 docs/images/local_search_embedding_model_type.png |
Key Features | 임베딩 모델 유형 설정 UI |
Bottom Line
Local Deep Research는 “로컬에서 실행 가능한 Perplexity/Deep Research 스타일 도구”에 머무르지 않는다.
검색 전략, 로컬 RAG, 암호화된 사용자별 저장소, 다중 LLM provider, API/MCP, benchmark/analytics, journal quality 기능을 결합해 개인·조직용 research operating system에 가까운 방향으로 설계되어 있다.
의료 AI와 Bioinformatics 관점에서는 PubMed·Semantic Scholar·OpenAlex·로컬 문서 검색을 결합한 evidence synthesis 도구로 가치가 크다.
Autonomous Agent 개발 관점에서는 전략 패턴, provider abstraction, MCP tool exposure, benchmark instrumentation이 잘 드러나는 참고 프로젝트다.
단, 고위험 도메인에서는 LLM 출력 검증, 근거 수준 평가, 감사 로그, 규제 준수 체계를 별도로 강화해야 한다.
