QMD(Query Markup Documents): 로컬 환경에서 구현하는 하이브리드 문서 검색 엔진

이 글은 **QMD(Query Markup Documents)**라는 온디바이스 문서 검색 엔진을 중심으로, 해당 기술의 개념과 등장 배경, 핵심 특징, 그리고 실제 사용 방법까지 정리한 IT 기술 소개 글입니다.
마크다운 노트, 회의록, 업무 문서, 지식 베이스처럼 흩어져 있는 개인·업무 문서를 로컬 환경에서 효율적으로 검색하고, 이를 AI 에이전트나 LLM 워크플로우와 연계하고 싶은 분들을 위해 QMD가 어떤 문제를 해결하고 어떤 가치를 제공하는지 단계적으로 설명합니다.

반응형

---

QMD란 무엇인가

QMD(Query Markup Documents)는 로컬 환경에서 동작하는 온디바이스 검색 엔진입니다.
개인의 마크다운 노트, 회의 기록, 기술 문서, 사내 문서 저장소 등을 색인(Index)하고, 키워드 검색과 자연어 검색을 모두 지원합니다.

가장 큰 특징은 모든 검색 과정이 로컬에서 실행된다는 점입니다.
BM25 기반의 전통적인 전체 텍스트 검색, 벡터 기반 의미 검색, 그리고 LLM 기반 재정렬(Re-ranking)을 하나의 파이프라인으로 결합하면서도, 외부 서버 없이 node-llama-cpp와 GGUF 모델을 활용해 로컬에서 처리합니다.

---

QMD가 등장한 배경과 필요성

문서가 많아질수록 다음과 같은 문제가 반복됩니다.

• 파일은 많지만, 정확한 위치를 기억하지 못함
• 키워드 검색은 되지만, “의도” 기반 검색은 어려움
• 클라우드 검색 도구는 보안·비용·지연 문제 존재
• AI 에이전트에 문서를 넘기려면 별도 전처리 필요

QMD는 이런 문제를 해결하기 위해 개인 지식 관리 + 로컬 AI 검색 + 에이전트 연동이라는 요구를 하나의 도구로 묶어 제공합니다.

---

QMD의 핵심 개념: 하이브리드 검색

QMD의 검색 방식은 단순하지 않습니다. 다음 세 가지를 결합합니다.

1. BM25 기반 전체 텍스트 검색

• SQLite FTS5를 활용한 고속 키워드 검색
• 정확한 문자열 매칭에 강점
• 빠른 응답 속도 제공

2. 벡터 기반 의미 검색

• 문서를 임베딩해 의미 유사도로 검색
• “어떻게 배포하지?” 같은 자연어 질문에 유리
• 키워드가 달라도 맥락이 비슷하면 검색 가능

3. LLM 재정렬(Re-ranking)

• 상위 후보 문서를 LLM이 다시 평가
• “이 문서가 질문에 정말 답이 되는가?”를 기준으로 정렬
• 단순 유사도 이상의 품질 확보

이 세 가지를 결합한 것이 QMD의 하이브리드 검색 파이프라인입니다.

---

QMD의 차별화 포인트

컨텍스트(Context) 트리 구조

QMD의 가장 중요한 기능 중 하나는 컨텍스트 관리입니다.

• 문서 경로 단위로 설명(Context)을 추가 가능
• 검색 결과와 함께 해당 컨텍스트가 반환됨
• LLM이 문서를 선택할 때 훨씬 정확한 판단 가능

예를 들어:

• notes → “개인 아이디어 및 메모”
• meetings → “회의 녹취 및 회의 메모”
• docs → “업무 문서 및 기술 자료”

이 구조 덕분에 QMD는 단순 검색 도구가 아니라 AI 친화적인 문서 인덱스 역할을 합니다.

---

QMD 사용 방법: CLI 기준 간단 예제

1. 설치

npm install -g @tobilu/qmd
# 또는
bun install -g @tobilu/qmd

---

2. 문서 컬렉션 등록

qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs

---

3. 컨텍스트 추가

qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"

이 단계가 QMD 검색 품질을 결정짓는 핵심입니다.

---

4. 임베딩 생성

qmd embed

벡터 검색을 위한 문서 임베딩을 생성합니다.

---

5. 검색 실행

qmd search "project timeline"        # 키워드 검색
qmd vsearch "how to deploy"          # 의미 기반 검색
qmd query "quarterly planning"       # 하이브리드 검색 + 재정렬

---

AI 에이전트와 함께 사용하는 QMD

QMD는 단순 CLI 도구에 그치지 않습니다.

• JSON 출력 지원 → LLM 입력에 바로 사용 가능
• MCP(Model Context Protocol) 서버 제공
• Claude Desktop, Claude Code 등과 직접 연동 가능

이를 통해 QMD는 AI 에이전트의 장기 기억 장치처럼 활용할 수 있습니다.

---

SDK로 사용하는 QMD

QMD는 Node.js/Bun 환경에서 라이브러리 형태로도 사용 가능합니다.

import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
    },
  },
})

const results = await store.search({ query: "authentication flow" })
await store.close()

CLI에서 가능한 대부분의 기능을 코드로 제어할 수 있습니다.

---

아키텍처 관점에서 본 QMD

QMD는 다음과 같은 흐름으로 동작합니다.

1. 사용자 쿼리 입력
2. LLM 기반 쿼리 확장
3. BM25 + 벡터 검색 병렬 실행
4. RRF(Reciprocal Rank Fusion)로 결과 통합
5. LLM 재정렬
6. 위치 인식 기반 점수 블렌딩

이 구조는 정확한 키워드 결과를 보호하면서도 의미 검색의 장점을 살리는 설계입니다.

---

728x90

QMD는 단순한 문서 검색 도구가 아닙니다.
로컬 환경에서 실행되는 하이브리드 검색 엔진이자, AI 에이전트와 자연스럽게 연결되는 지식 인프라입니다.

정리하면 QMD가 주는 기대 효과는 다음과 같습니다.

• 개인·팀 문서의 검색 생산성 극대화
• 클라우드 의존 없는 보안 친화적 구조
• AI 에이전트와의 실질적인 연계 가능
• 장기적으로 확장 가능한 지식 관리 기반

로컬 AI와 에이전트 기반 워크플로우를 고민하고 있다면, QMD는 충분히 검토해볼 만한 기술적 선택지입니다.

300x250

https://github.com/tobi/qmd

GitHub - tobi/qmd: mini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approac