local-deep-research

로컬 딥 리서치

AI 기반 연구 보조 도구로, 심층적이고 에이전트형 연구 수행

적절한 인용과 함께 여러 LLM과 검색 엔진을 사용해 심층적이고 에이전트형 연구를 수행합니다

🧪 단일 RTX 3090(Qwen3.6-27B)에서 완전 로컬로 구동되어 SimpleQA(n=500) 약 95%, xbench-DeepSearch(n=100) 77%를 로컬 하드웨어에서 보고한 최초의 오픈소스 프로젝트입니다. r/LocalLLaMA 공지와 벤치마크 데이터셋을 참고하세요.

▶️ The Art Of The Terminal의 리뷰 보기

🚀 로컬 딥 리서치란?
당신이 통제하는 AI 연구 보조 도구입니다. 프라이버시를 위해 로컬에서 실행하고, 어떤 LLM이든 사용하며, 검색 가능한 자신만의 지식 베이스를 구축하세요. 데이터는 당신의 것이며, 어떻게 작동하는지 정확히 확인할 수 있습니다.

⚡ 빠른 시작
옵션 1: Docker 실행 (Linux)

# 1단계: Ollama 풀 및 실행
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama pull gpt-oss:20b

# 2단계: 최적의 검색 결과를 위해 SearXNG 풀 및 실행
docker run -d -p 8080:8080 --name searxng searxng/searxng

# 3단계: 로컬 딥 리서치 풀 및 실행
# (URL 라인은 SearXNG의 주소를 고정하고 운영자 승인으로 표시합니다 —
# 비공개/localhost 엔진 URL은 v1.10.3부터 기본적으로 차단됩니다.
# 이 URL은 웹 UI에서 읽기 전용이 됩니다. docs/SearXNG-Setup.md에
# 대안(예: origin 허용 목록)이 나열되어 있습니다.)
docker run -d --network host \
--name local-deep-research \
--volume " deep-research:/data " \
-e LDR_DATA_DIR=/data \
-e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://localhost:8080 \
localdeepresearch/local-deep-research

Mac / Windows / WSL2 사용자: --network host는 네이티브 Linux에서만 작동합니다. Docker Desktop에서는 5000번 포트 게시가 조용히 실패하고 localhost가 LDR 컨테이너 자체를 가리키게 되어(Ollama/SearXNG에 도달할 수 없음) 작동하지 않습니다. 아래 옵션 2를 사용하거나, 작동하는 docker run 레시피는 Windows/WSL2 FAQ 항목을 참고하세요.

옵션 2: Docker Compose

CPU 전용 (모든 플랫폼):

curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && docker compose up -d
NVIDIA GPU 사용 (Linux):

curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && \
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.gpu.override.yml && \
docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d
약 30초 후 http://localhost:5000을 여세요. GPU 설정, 환경 변수 등은 Docker Compose 가이드를 참고하세요.

옵션 3: pip 설치

pip install local-deep-research
python -m local_deep_research.web.app # http://localhost:5000에서 웹 UI 시작

Ollama(또는 OpenAI 호환 LLM 엔드포인트)와 SearXNG도 실행 중이어야 합니다 — 전체 레시피는 pip 설치 가이드를 참고하세요.
Windows, macOS, Linux에서 작동합니다. SQLCipher 암호화는 사전 빌드된 휠로 포함되어 있어 컴파일이 필요 없습니다.
Windows에서 PDF 내보내기에는 Pango가 필요합니다 (설정 가이드).
개발용 폴백: LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true는 SQLCipher를 사용할 수 없거나 작동하지 않을 때만 평문 SQLite를 허용합니다. 작동하는 SQLCipher가 여전히 우선합니다. 이 폴백은 계정 비밀번호를 검증하지 않으므로 공유 배포에는 부적합합니다. 폴백 제한 사항을 참고하세요.

상세 설치 가이드: Docker · Docker Compose · pip · Unraid · 전체 설치 레퍼런스

구형 CPU(x86-64)? LDR은 AVX 지원 CPU가 필요합니다 — Intel Sandy Bridge / AMD Bulldozer(2011) 이상. 일부 과학용 Python 의존성(pandas, scikit-learn)은 구형 CPU에서 Illegal instruction으로 충돌하는 휠을 배포합니다. ARM64(aarch64)는 완전히 지원됩니다. 모든 릴리스는 AVX2 없는 AVX CPU를 포함해 이 최소 사양에 대해 스모크 테스트됩니다( #4480 ).

🏗️ 작동 방식
연구
복잡한 질문을 하면 로컬 딥 리서치(LDR)가:

자동으로 연구를 수행합니다
웹, 학술 논문, 자신의 문서를 검색합니다
모든 것을 적절한 인용과 함께 보고서로 종합합니다

상황에 맞는 연구 전략을 선택하세요: 빠른 사실 확인을 위한 빠른 파이프라인 모드, 또는 복잡한 분석과 학술 작업을 위한 완전한 에이전트형 딥 리서치.

LangGraph 에이전트 전략 — LLM이 무엇을 검색할지, 어떤 특화 엔진(arXiv, PubMed, Semantic Scholar 등)을 사용할지, 언제 종합할지를 결정하는 자율 에이전트형 연구 모드입니다. 발견한 내용에 따라 검색 엔진을 적응적으로 전환하며, 파이프라인 기반 전략보다 훨씬 많은 출처를 수집합니다 — 위의 약 95% SimpleQA 결과를 이끌어낸 전략입니다. 설정에서 langgraph-agent를 선택하세요.

지식 베이스 구축

flowchart LR
R[Research] --> D[Download Sources]
D --> L[(Library)]
L --> I[Index & Embed]
I --> S[Search Your Docs]
S -.-> R

Loading

모든 연구 세션은 가치 있는 출처를 찾습니다. ArXiv의 학술 논문, PubMed 기사, 웹 페이지를 암호화된 라이브러리에 직접 다운로드하세요. LDR은 텍스트를 추출하고 모든 것을 인덱싱하여 검색 가능하게 만듭니다. 다음에 연구할 때 자신의 문서와 실시간 웹을 함께 검색하며 질문하세요. 지식이 시간이 지남에 따라 축적됩니다.

🛡️ 보안

flowchart LR
U1[User A] --> D1[(Encrypted DB)]
U2[User B] --> D2[(Encrypted DB)]

Loading

데이터는 당신의 것입니다. 각 사용자는 AES-256으로 암호화된 자신만의 격리된 SQLCipher 데이터베이스를 가지며, 키는 비밀번호에서 파생됩니다. 비밀번호는 저장되지 않습니다 — 로그인은 데이터베이스 복호화를 시도하는 방식으로 작동하므로, 데이터베이스 파일 자체는 이를 입수한 누구에게도 사용할 수 없습니다. 사용자별 LLM API 키는 공유 서버 수준 저장소가 아닌 동일한 개인 데이터베이스 내부에 암호화되어 저장됩니다.

Docker 설정은 cap_drop: ALL, no-new-privileges, 비루트 런타임과 함께 제공되며, 번들 Ollama 및 SearXNG 이미지는 다이제스트로 고정됩니다. 번들 Ollama에서 모델을 실행하면 추론은 자신의 하드웨어에서 실행됩니다. LDR은 로컬리티를 주로 모델이 실행되는 위치가 아니라 제공자와 엔드포인트 주소로 판단하므로, 호스팅 모델로 중계하는 로컬 엔드포인트(Ollama 클라우드 모델, 또는 호스팅 API 앞의 로컬 LiteLLM이나 기타 OpenAI 호환 프록시)는 감지되지 않은 채로 프롬프트를 기기 밖으로 전송할 수 있습니다. 자체 호스팅 SearXNG도 검색 쿼리를 인터넷의 업스트림 엔진으로 전달합니다. 실행을 비공개 소스로 유지하려면 아래에 설명된 Private only 이그레스 범위에서 로컬 소스(컬렉션, 라이브러리)만 검색하세요. 이 범위는 최선의 노력 기반 가드레일이며 에어 갭이 아닙니다: 아래 이그레스 제어 섹션과 SECURITY.md를 참고하세요.

메모리 내 자격 증명: 자격 증명은 활성 세션 동안 프로세스 메모리에 보관됩니다. LDR은 수명을 제한하고 POSIX에서 웹 및 MCP 시작 시 프로세스 덤프 제어를 적용하며, Linux에서는 추가적인 덤프 가능성 제어를 적용합니다. 다른 플랫폼과 LDR을 임베딩하는 애플리케이션은 운영 체제 구성이 필요합니다. 범위와 플랫폼 세부 사항은 보안 정책을 참고하세요.

공급망 보안: Docker 이미지는 GitHub의 키리스 OIDC 흐름을 사용해 Cosign으로 서명되며, SLSA 출처 증명을 포함하고, 증명된 SPDX SBOM과 함께 제공됩니다. 단계별 검증 명령은 이미지 및 SBOM 검증을 참고하세요.

보안 투명성: 스캐너 억제는 Security Alerts Assessment, Scorecard Compliance, Container CVE Suppressions, SAST Rule Rationale에 근거와 함께 문서화되어 있습니다. 일부 경고(Dependabot, 코드 스캐닝)는 GitHub Security 탭 외부에서 억제하기가 매우 어렵거나 해제만 가능하므로, 위 파일들이 모든 해제된 발견 사항을 다루지는 않습니다.

상세 아키텍처 → | 보안 정책 → | 보안 검토 프로세스 →

🌐 이그레스 제어
모든 연구 실행에는 트래픽이 갈 수 있는 곳을 최선의 노력으로 제한하는 이그레스 범위가 있습니다: 어떤 검색 엔진이 실행되는지, LLM과 임베딩이 클라우드 서비스일 수 있는지, 어떤 결과 URL을 가져올 수 있는지. 설정 → 이그레스 범위에서 또는 연구 양식의 프라이버시 및 이그레스 패널에서 설정하세요. 패널에서 범위를 선택하면 기본 설정으로도 저장되어 이후 실행에도 사용됩니다.

모드
검색 소스
추론

적응형 (기본값)
기본 엔진을 따릅니다: 공개 엔진은 Public only처럼, 비공개 컬렉션이나 라이브러리는 Private only처럼 동작합니다. 공개로 표시한 로컬 저장 컬렉션을 기본으로 하면 비공개 컬렉션을 포함한 모든 분류된 엔진을 허용합니다
실행이 비공개일 때 로컬 전용으로 강제됩니다

Public only
공개 웹 및 학술 엔진; 비공개로 분류된 비공개 컬렉션과 로컬 문서 저장소는 제외됩니다(URL이 공개 호스트로 확인되거나 확인되지 않는 문서 저장소는 일반적으로 공개로 취급됨)
설정된 제공자; 클라우드 모델과 함께 문서 저장소를 기본으로 하면 웹 연구 양식을 통한 연구 실행은 일반적으로 시작 시 거부됩니다(/api/v1/quick_summary나 MCP처럼 연구 함수를 직접 호출하는 진입점은 제외)

Private only
로컬 소스만(컬렉션, 라이브러리, Paperless 같은 로컬 문서 저장소)
로컬로 강제됨; 클라우드 제공자는 일반적으로 거부됨

Strict
단일 기본 엔진, 확장 없음
로컬로 강제되지는 않지만 클라우드 모델은 보통 Strict에서 작동하지 않습니다(이그레스 모드의 Strict 섹션 참고)

Unprotected
무엇이든; 운영자가 LDR_POLICY_ALLOW_UNPROTECTED_EGRESS=true를 설정하지 않는 한 사용 불가
보통 무엇이든(운영자의 require-local 설정에 대한 환경 잠금은 여전히 적용됨)

Strict와 Private only(이로 해석되는 적응형 실행 포함)는 또한 연구 실행에 최선의 노력 기반 소켓 수준 가드를 활성화하여 일반적으로 공개 주소로의 연결을 거부합니다. 이는 알려진 격차가 있는 백스톱이며 보장이 아닙니다. 이그레스 모드의 Strict 섹션에는 포워드 프록시나 비공개 주소의 릴레이 같은 일부 격차가 나열되어 있습니다. 따라서 Strict에서는 공개 엔진, 공개 결과 가져오기, 클라우드 모델 호출이 보통 실패하므로 로컬 엔진과 로컬 모델과 함께 사용하세요.

로컬에서 호스팅되는 SearXNG는 공개 엔진으로 간주됩니다 — 검색을 인터넷으로 프록시하기 때문입니다 — 따라서 Private only에서는 사용할 수 없습니다. Strict에서는 여전히 기본 엔진으로 실행될 수 있으며, 그 경우 쿼리를 인터넷의 업스트림 엔진으로 전달합니다.

대부분의 검색 결과 및 문서 가져오기에 사용되는 LDR의 가드된 HTTP 계층은 또한 SSRF 규칙(169.254.169.254 같은 알려진 클라우드 메타데이터 주소 포함)에 대해 목적지를 확인하고 리디렉션을 재확인합니다. JavaScript 렌더링이 활성화되면(web.enable_javascript_rendering, 기본값 꺼짐), 필요한 페이지는 주소를 자체적으로 확인하는 헤드리스 Chromium에서 로드됩니다. 자세한 내용은 이그레스 모듈 README를 참고하세요.

로그인한 사용자가 검색 엔진을 비공개 주소로 지정할 수 있는지는 엔진 종류에 따라 다릅니다:

주소를 구성할 수 있는 공개 엔진(현재 SearXNG): 비공개 또는 루프백 URL은 일반적으로 운영자가 환경을 통해 옵트인하지 않는 한 거부됩니다(LDR_SEARCH_ALLOW_PRIVATE_ENGINE_URLS=true, LDR_SEARCH_PRIVATE_ENGINE_URL_ALLOWLIST의 정확한 origin, 또는 LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL로 URL 자체를 고정). 따라서 localhost의 SearXNG는 보통 이 중 하나가 필요합니다.
로컬 문서 저장소 엔진(Paperless-ngx 및 Elasticsearch): 이들의 주소 설정인 search.engine.web.paperless.default_params.api_url과 search.engine.web.elasticsearch.default_params.hosts는 비공개 호스트를 가리키도록 의도되어 있으므로 현재 옵트인이 적용되지 않습니다: 로그인한 사용자라면 누구나 이를 내부 주소로 설정할 수 있고 서버가 연결합니다. 이것이 허용되지 않는다면 해당 환경 변수(LDR_ 더하기 대문자로 변환하고 점을 밑줄로 바꾼 키, 예: LDR_SEARCH_ENGINE_WEB_PAPERLESS_DEFAULT_PARAMS_API_URL)로 이 설정을 고정하거나, LDR_APP_LOCK_SETTINGS=true로 설정 변경을 잠그세요.

이그레스 정책은 오구성과 프롬프트 주입 가져오기에 대한 프로세스 내 가드레일이며, 에어 갭이나 강력한 보안 경계가 아닙니다: 예를 들어 호스트 이름은 가져오기가 거부되기 전에 여전히 구성된 DNS 리졸버를 통해 확인되며, LDR 프로세스 내부에서 실행되는 코드를 안정적으로 제한할 수 없습니다. 강력한 경계를 위해서는 이그레스 필터링을 추가하세요…