Paperless NGX Dedupe

A document deduplication and AI-powered metadata companion for Paperless-NGX. It syncs your documents, identifies duplicates using MinHash/LSH algorithms, and extracts metadata with LLMs through a web UI and REST API.

기능 (Features)

중복 제거 (Deduplication)

• 지능형 중복 감지 -- 효율적인 O(n log n) 후보 검색을 위한 MinHash 시그니처 + Locality-Sensitive Hashing (LSH)
• 유사도 점수 측정 -- 가중 Jaccard 유사도 및 판별적 페널티를 적용한 퍼지 텍스트 매칭으로, 단순히 서식(boilerplate text)만 공유하는 쌍의 점수를 낮춤
• 나란히 검토 (Side-by-side review) -- OCR 텍스트 차이 비교를 통해 중복 문서를 개별적으로 또는 일괄적으로 해결할 수 있음

AI 메타데이터 추출 (AI Metadata Extraction)

• 자동 분류 -- OpenAI 모델을 사용하여 문서 텍스트에서 담당자, 문서 유형 및 태그 추출

• 신뢰도 점수 측정 -- 적용하기 전에 검토할 수 있도록 필드별 신뢰도 점수와 근거 스니펫 제공

• 참조 기반 (Reference-aware) -- 기존의 담당자, 문서 유형, 태그를 LLM에 선택적으로 공급하여 중복 생성을 방지

• 배치 처리 -- 전체 라이브러리 또는 새 문서를 구성 가능한 배치로 자동 처리

• 문서 동기화 (Document sync) -- Paperless-NGX 인스턴스로부터 전체 및 증분 동기화

• 백그라운드 처리 (Background processing) -- Server-Sent Events를 통해 실시간 진행 상황을 제공하는 워커 스레드

• 웹 UI (Web UI) -- 대시보드, 문서 브라우저, 중복 검토, AI 결과 검토 기능

• 배치 작업 (Batch operations) -- 중복 및 AI 결과를 대상으로 한 일괄 검토, 적용, 거부 및 삭제

• 데이터 내보내기 (Data export) -- CSV 중복 보고서 및 JSON 설정 백업/복원

• 관찰 가능성 (Observability) -- 선택적 Prometheus 스크랩 엔드포인트와 내장 Paperless-NGX 시스템 메트릭 수집기를 갖춘 OpenTelemetry 트레이스, 메트릭 및 로그

• 단일 컨테이너 배포 (Single container deployment) -- 외부 종속성이 없는 임베디드 SQLite를 사용한 Docker

빠른 시작 (Quick Start)

1. .env 파일 생성: Paperless-NGX 연결 세부 정보를 포함하여 파일을 만듭니다:

PAPERLESS_URL=http://your-paperless-instance:8000
PAPERLESS_API_TOKEN=your-api-token-here

API 토큰(권장) 또는 사용자 이름/비밀번호로 인증할 수 있습니다. 모든 옵션은 설정 (Configuration)을 참조하세요.

2. 컨테이너 시작:

docker compose up -d

3. http://localhost:3000 에 접속하여 설정 (Settings) > 연결 테스트 (Test Connection) 로 이동해 연결성을 확인합니다.

4. 동기화 및 분석: 대시보드에서 동기화 (Sync) 를 클릭하여 문서를 가져온 다음, 분석 (Analyze) 을 클릭하여 중복을 감지합니다. 두 작업 모두 실시간 진행 상황과 함께 백그라운드 작업으로 실행됩니다.

5. 중복 검토: /duplicates 에서 중복된 문서를 검토하고 비교하며 해결합니다.

전체 워크스루는 시작 가이드 (Getting Started Guide)를 참조하세요.

문서화 (Documentation)

• 시작하기 -- 설치, 첫 실행 가이드, 업그레이드
• 설정 -- 환경 변수, 알고리즘 튜닝, Docker 설정
• API 참조 -- curl 예제를 포함한 전체 REST API
• 작동 방식 -- 중복 제거 파이프라인 설명
• 문제 해결 -- 일반적인 문제 및 해결책

개발(Development)

just --list로 작업 목록을 확인하거나, just --show <recipe>로 특정 작업을 검사할 수 있습니다.

just setup            # 의존성 설치
just run              # 개발 서버 시작 (http://localhost:5173)
just build            # 프로덕션 빌드
...

참고: 백그라운드 작업(동기화, 분석, 일괄 삭제)은 Vite 외부에서 실행되는 워커 스레드(worker threads)를 사용하며 원시 Node.js 프로세스로 작동합니다. 이들은 Node.js가 TypeScript 소스 파일을 직접 실행할 수 없기 때문에 just run에서는 작동하지 않습니다. 전체 워크플로우를 테스트하려면 로컬 개발 시 just docker-dev를 사용하십시오.

라이선스(License)

GNU General Public License v3