ObsidianRAG

로컬 우선(local-first) 하이브리드 RAG 인덱스로 여러분의 Obsidian 노트를 대상으로 질문하세요.

Tests

License

ObsidianRAG 4는 검색 엔진으로 SQLite FTS5와 임베디드 LanceDB만을 사용합니다. Obsidian 플러그인은 백엔드, 인덱스 생명주기(index lifecycle), 채팅 기능, 그리고 출처 링크를 관리합니다. 생성(Generation)은 Ollama, LM Studio, 그리고 OpenAI 호환 서버를 지원합니다.

주요 특징 (Highlights)

• 증분적 Copy-on-write 방식의 인덱스 개정판 (Incremental copy-on-write index revisions)
• 하이브리드 어휘 및 벡터 검색 (Hybrid lexical and vector retrieval)
• 숫자 출처 인용을 통한 근거 기반 답변 제공 (Grounded answers with numeric source citations)
• 명시적인 빌드(Build), 새로고침(Refresh), 전체 재구축(Full rebuild), 그리고 정리(Prune) 제어
• 새로고침 중 진행 중인 쿼리를 보호하는 리더 임대(Reader leases)
• 링크를 따라가지 않는 안전한 정규 Markdown 스캔 (Safe regular-Markdown scanning without following links)
• 플러그인과 백엔드 간의 API 4 호환성 검사
• 플러그인이 백엔드를 시작할 때 셸 호출 없음 (No shell invocation when the plugin starts the backend)

설치 (Install)

백엔드 설치:

uv tool install obsidianrag==4.0.1

plugin-v4.0.1 GitHub 릴리스에서 플러그인 에셋을 설치합니다:

• main.js
• manifest.json
• styles.css

이 파일들을 <vault>/.obsidian/plugins/vault-rag/에 배치한 후, Obsidian에서 Vault RAG를 활성화하세요.

첫 실행 (First run)

1. 생성 제공자(generation provider)를 시작하고 설정된 모델을 사용 가능하게 만듭니다.
2. **Vault RAG 설정(settings)**을 열고 백엔드 실행 파일(보통 obsidianrag 또는 Windows의 경우 obsidianrag.exe)이 올바른지 확인합니다.
3. 백엔드를 시작합니다.
4. **인덱스 빌드(Build index)**를 선택합니다.
5. 채팅 보기(chat view)를 엽니다.

백엔드는 시작 시 자동으로 인덱싱하지 않습니다.

CLI (Command Line Interface)

# API 4 시작
obsidianrag serve --vault /path/to/vault

...

제공자 (Providers)

obsidianrag serve --vault /path/to/vault --provider ollama --model gemma3

obsidianrag serve --vault /path/to/vault \
...

플러그인에 설정된 API 키는 세션 전용이며, 명령 인수가 아닌 백엔드 프로세스 환경을 통해 전달됩니다.

인덱스 아키텍처

flowchart LR
    Plugin[Obsidian 플러그인] --> API[FastAPI v4]
    API --> Pipeline[쿼리 파이프라인]
...

개정본은 다음 경로에 저장됩니다:

.obsidianrag/v4/
├── active.json
├── build.lock
...

새로고침(refresh) 시 정규 Markdown 파일을 스캔하고, 노트 내용을 해시화하며, 변경되지 않은 벡터는 제한된 배치에서 재사용하고, 변경된 노트만 임베딩합니다. 후보 개정본은 SQLite, FTS5, 결정론적 ID, 경로, 벡터 차원 및 유한 벡터 값이 성공적으로 검증된 후에만 활성화됩니다.

리더(Readers)는 현재 사용 중인 개정본을 임대(lease)합니다. 오래된 요청이 완료되는 동안 새로운 개정본이 활성화될 수 있으며, 비활성 상태로 임대한 개정본은 삭제될 수 없습니다.

API 4

3.x에서 마이그레이션

• 백엔드와 플러그인 4.0.1을 함께 설치합니다.
• 기존 .obsidianrag/v4 개정본은 호환되는 경우 재사용됩니다.
• 레거시 .obsidianrag/db Chroma 데이터는 무시되며 자동으로 삭제되지 않습니다.
• uv run obsidianrag와 같은 복합 백엔드 명령을 실행 파일 경로 또는 이름으로 대체합니다.
• 호환되는 개정본이 없는 경우 v4 인덱스를 명시적으로 구축합니다.
• 4.0.1 버전을 검증한 후에만 레거시 인덱스 데이터를 수동으로 제거합니다.

개발

git clone https://github.com/Vasallo94/ObsidianRAG.git
cd ObsidianRAG

...

테스트는 임시 피처(fixture) 볼트를 사용합니다. 실제 제공자(provider)가 필요한 통합 테스트는 일반 CI에서 제외됩니다.

릴리스

백엔드와 플러그인은 버전 4.0.1을 공유하지만 독립적으로 게시됩니다:

1. 태그 backend-v4.0.1을 지정하고 PyPI를 확인합니다.
2. 태그 plugin-v4.0.1을 지정하고 GitHub 릴리스 에셋을 확인합니다.

라이선스

MIT. LICENSE 참조.