Docker 컨테이너 기반 실행
컨테이너 환경에서 Local Deep Research를 실행하면 의존성 충돌을 방지하고 빠르게 서비스를 시작할 수 있다.
이미지 빌드 및 구동
git clone https://gitcode.com/gh_mirrors/lo/local-deep-research ldr-project
cd ldr-project
docker build -t ldr-app:latest .
docker run -d --rm -p 8080:5000 --name research-engine ldr-app:latest컨테이너가 정상적으로 실행되면 http://localhost:8080을 통해 웹 인터페이스에 접속할 수 있다.
Python 개발 환경 설정
로컬 시스템에 직접 설치하여 세부 설정을 제어하려는 개발자를 위한 방법이다.
요구사항
- Python 3.11 이상
- 패키지 매니저 (PDM 권장)
설치 프로세스
git clone https://gitcode.com/gh_mirrors/lo/local-deep-research ldr-dev
cd ldr-dev
pip install pdm
pdm sync
pdm run ldr-web서버가 기동된 후 http://localhost:5000로 접속하여 애플리케이션을 확인한다.
Unraid 환경에서의 배포
NAS 환경인 Unraid에서 Local Deep Research를 운영하기 위한 절차다.
- Unraid 웹 관리 페이지의 Docker 탭으로 이동한다.
- 'Add Container'를 클릭하여 새로운 컨테이너를 생성한다.
- Repository 항목에 로컬 이미지 이름인
ldr-app:latest를 입력한다. - 포트 매핑 설정에서 Host Port를
8081, Container Port를5000으로 지정한다. - 앱 구성 데이터 영속성을 위해
/app/.config/local_deep_research경로를 Unraid 공유 폴더와 연결한다. - 설정 적용 후 컨테이너를 시작한다.
컨테이너가 Running 상태가 되면 http://[Unraid_IP]:8081 주소로 접속한다.
아키텍처 및 데이터 처리 흐름
시스템은 사용자 쿼리를 벡터화하여 내장된 데이터베이스에서 관련 문서를 검색한 뒤, LLM을 통해 최종 분석 리포트를 산출하는 구조로 동작한다.
트러블슈팅
이미지 빌드 지연 및 실패
네트워크 환경으로 인해 베이스 이미지를 내려받지 못하는 경우 Docker 데몬의 레지스트리 미러를 설정하거나, 빌드 캐시를 초기화(docker builder prune)한 뒤 재시도한다.
포트 충돌 문제 해결
지정한 호스트 포트가 이미 사용 중인 경우, docker run 실행 시 바인딩 포트를 -p 9090:5000으로 변경하여 충돌을 회피한다.
의존성 설치 오류
Python 패키지 충돌이 발생하면 pdm cache clear 명령으로 로컬 캐시를 제거하고 pdm sync --reinstall 옵션을 통해 강제 재설치를 진행한다.