Kwipu — Markdown 기반 로컬 Graph RAG 엔진

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Kwipu는 Obsidian vault 같은 로컬 Markdown 저장소를 대상으로 동작하는 Graph RAG 엔진으로, 위키링크와 YAML frontmatter에서 엔터티-관계 트리플을 추출해 그래프를 구성하고 벡터 검색과 BM25, 시간 기반 신호를 결합한 하이브리드 검색으로 답변을 반환한다. 원문에는 다국어 지원과 클라우드 불필요성, Ollama와의 연동 가능성이 명시되어 있어 로컬 환경에서 프라이버시를 유지하면서 질의 응답 파이프라인을 구성할 수 있다. 게시물은 핵심 작동 요소와 호환성을 제시하나 설치 절차, 성능 수치, 재현 가능한 벤치마크는 포함하지 않아 실제 적용 전 리포지토리의 추가 문서를 확인해야 한다.

실용적 조언

로컬 Graph RAG를 도입하려는 경우 마크다운 파일의 일관된 링크 표기와 frontmatter 메타데이터 정비가 우선되어야 하며, 이는 엔터티 추출의 정확도를 높여 검색 품질에 직접적인 영향을 미친다.
하이브리드 검색을 활용할 때는 벡터 임베딩 모델과 BM25 인덱스의 상대 가중치를 실험해 사용 사례에 맞는 균형을 찾아야 하며, 시간 정보가 중요한 작업은 temporal 정렬을 활성화해 최신성을 반영하는 것이 유리하다.

섹션별 상세

로컬 노트 내 질의 기능의 필요성에서 출발해 Kwipu는 사용자의 로컬 마크다운 저장소를 직접 쿼리할 수 있는 엔진으로 설계됐다. 이 도구는 Obsidian vault 등 어떤 마크다운 폴더와도 동작하도록 구성되어 입력 파일을 그대로 읽고 메타데이터와 링크를 기반으로 인덱싱한다. 원문에는 "Designed for Obsidian vaults, it works with any Markdown file folder"라고 적혀 있어 통합 대상과 동작 범위가 분명히 드러난다. 로컬 실행으로 클라우드 의존도를 없애 사용자 프라이버시와 데이터 소유권을 유지할 수 있다는 점이 실무적 장점으로 연결된다.

문서 구조를 그래프로 모델링하기 위해 Kwipu는 문서 내 위키링크와 YAML 프론트매터에서 엔터티-관계 트리플을 추출해 그래프를 구성한다. 입력으로는 마크다운 파일의 링크와 메타데이터가 사용되며 처리 과정에서 각 링크와 필드가 엔터티와 관계로 변환되어 그래프의 노드와 에지로 저장된다. 원문은 "extracts entity-relation triples from wikilinks and YAML frontmatter"라고 표기돼 있어 핵심 데이터 소스와 변환 산출물이 명시되어 있다. 이 방식은 문서 간 연결성과 문서 내부 메타정보를 검색 신호로 활용함으로써 단순 텍스트 매칭보다 구조적 질의를 더 잘 지원할 가능성이 있다.

검색은 의미적 유사도와 전통적 키워드 매칭, 시간 기반 중요도를 결합한 하이브리드 방식으로 이뤄진다. 구체적으로는 문서 조각을 벡터로 임베딩해 벡터 검색을 수행하고 BM25로 키워드 기반 후보를 얻은 뒤 시간 정보로 결과를 재정렬하는 흐름이 암시된다. 원문에는 "retrieves answers via hybrid search (vector + BM25 + temporal)"라고 적혀 있어 사용된 신호들이 명확하다. 서로 다른 유사도 신호를 결합하면 키워드 민감성과 의미적 관련성 사이에서 더 균형 잡힌 결과를 얻을 수 있다.

운영 환경과 호환성 측면에서 Kwipu는 다국어를 처리하고 클라우드 없이 로컬에서 동작하도록 설계됐으며 특정 로컬 추론 런타임과의 호환성도 표기되어 있다. 원문에는 "Multilingual. No cloud required. Works on Ollama."라는 문장이 있어 다국어 지원과 로컬 전용 실행 철학, Ollama와의 연동 가능성이 동시에 드러난다. 이로 인해 민감한 자료를 외부로 전송하지 않고도 로컬 환경에서 질의 응답 워크플로를 구성할 수 있으며, Ollama 같은 로컬 추론 엔진을 백엔드로 연결해 응답 생성 파이프라인을 완성할 수 있다.

용어 해설

검색 증강 생성(RAG): — 이 글 맥락에서 RAG는 로컬 마크다운 문서로부터 그래프 구조나 벡터 인덱스를 활용해 질의 문장에 대한 관련 문서와 답변을 찾아내는 방식으로, 문서 검색과 생성 모델 출력을 결합해 더 풍부한 근거 기반 응답을 만든다는 점에서 중요하다.
BM25: — 이 글에서 BM25는 키워드 기반의 역문서빈도 가중치 검색 방식으로 사용자의 질의와 문서의 단어 빈도를 계산해 초기 후보를 뽑는 역할을 하며, 벡터 검색과 병합되어 하이브리드 검색을 구성한다.
임베딩(Embedding): — 문장을 고정 길이 벡터로 변환해 의미적 유사도를 계산하는 기법으로, 이 글에서는 문서 조각을 벡터화하여 벡터 검색과 BM25 결과를 함께 사용한 하이브리드 검색의 핵심 신호로 활용된다.
위키링크(Wikilinks): — 마크다운 문서 내부의 링크 표기 방식으로, 이 시스템은 위키링크를 파싱해 문서들 간의 연결 관계를 엔터티-관계 트리플로 변환하고 그래프 구조를 구성하는 입력 자료로 사용한다.
YAML 프론트매터(YAML frontmatter): — 마크다운 파일 상단의 메타데이터 블록으로, 이 글에서는 frontmatter의 필드들을 추출해 엔터티와 속성 정보로 변환함으로써 그래프 노드와 관계를 풍부하게 만드는 데 활용한다고 기술됐다.

언급된 도구

Kwipu중립링크

로컬 Markdown 기반 Graph RAG 엔진으로 엔터티-관계 추출과 하이브리드 검색을 수행

Obsidian중립

Markdown vault를 제공하는 노트 애플리케이션으로 Kwipu의 통합 대상

Ollama중립

로컬 추론 런타임으로 Kwipu와 연동해 응답 생성 백엔드로 사용 가능

언급된 리소스

GitHubKwipu GitHub