Obsidian(옵시디언)이나 마크다운으로 개인 위키를 구축해 본 분들이라면 공감하실 겁니다. 처음에는 파일 수가 적어 기본 검색이나 폴더 분류만으로도 충분히 노트를 찾을 수 있습니다. 하지만 문서가 수백, 수천 개로 쌓이기 시작하면 상황이 완전히 달라집니다.

단순 키워드 매칭(grep)은 질문의 단어와 문서의 단어가 조금만 달라도 원하는 문서를 찾지 못하고, 일반 인공지능(AI) 채팅창에 매번 모든 문서를 수동으로 주입하는 것은 극도로 비효율적입니다. 이처럼 로컬 마크다운 저장소의 검색 한계를 해결하기 위해 등장한 초경량 하이브리드 검색 엔진이 바로 Qmd(큐엠디)입니다.

이 글에서는 키워드 매칭과 의미론적 벡터 검색, 그리고 AI 가상 답변(HyDE)까지 결합한 로컬 RAG 검색 도구인 Qmd의 핵심 개념, 3대 검색 모드, 그리고 AI 에이전트 연동법을 자세히 소개합니다.

📊 Qmd의 3대 검색 모드 비교

검색 모드 동작 원리 및 특징 추천 활용 시나리오
🏷️ 키워드 형태소 검색 (BM25) 정확한 어구 매칭과 빈도 분석을 활용한 고속 텍스트 검색 (qmd search "키워드") 정확한 문서 제목, 고유 명사, 에러 코드 등을 찾을 때
🧠 하이브리드 의미 검색 (Semantic) RRF(Reciprocal Rank Fusion) 알고리즘으로 벡터 점수와 BM25 점수를 합성하고 2차 LLM Re-ranking 적용 (qmd query "자연어") 개념적으로 기술되어 키워드 직접 매칭이 어려울 때
🗺️ 구조화된 다차원 검색 (Structured) 의도(intent), 필수어(lex), 자연어 설명(vec), 가상 답변(HyDE) 구조를 결합해 복합 탐색 실행 난이도가 매우 높고 복합적인 지식 노트를 발굴할 때

1. Qmd 하이브리드 검색 엔진의 작동 원리

전통적인 검색엔진은 단어가 똑같이 일치해야만 검색 결과로 내보냅니다. 반면, 일반적인 벡터 검색 엔진은 텍스트의 맥락적 의미는 잘 찾지만, 정밀한 에러 코드나 학술용 고유명사 같은 '정확한 매칭'에는 쥐약입니다.

Qmd는 이 두 가지 방식의 단점을 완벽히 극복하기 위해 **RRF(Reciprocal Rank Fusion)**를 기반으로 키워드 검색 점수와 의미론적 벡터 검색 점수를 지능적으로 결합합니다. 이에 더해 LLM이 가상의 모범 답변을 먼저 생성하여 검색 후보군을 좁히는 **HyDE(Hypothetical Document Embeddings)** 기술을 탑재하여 검색 정확도를 일반 키워드 검색 대비 획기적으로 끌어올렸습니다.

2. Qmd의 핵심 워크플로우와 다이어그램

Qmd는 로컬 저장소를 실시간 검색하여 최적의 후보군을 도출하고 본문을 확보하는 2단계 프로세스를 거쳐 작동합니다.

1. 검색 질의 접수 (자연어 / 구조화 쿼리)
▼
Qmd 하이브리드 RAG 코어 엔진
▼
[1단계: 후보 도출] qmd query RRF & LLM 재평가로 상위 문서 번호(#abc123) 리턴
[2단계: 본문 획득] qmd multi-get 배치 다운로드로 전체 컨텍스트 일괄 확보
▼
3. AI 에이전트 RAG 컨텍스트 완성 & 팩트 기반 답변 조립

⚡ 획기적인 문서 다중 배치 추출 (multi-get)

검색을 통해 최적의 문서 후보 아이디(예: #abc123, #def456)가 확보되면 에이전트는 스니펫만 보고 유추하지 않고 qmd multi-get "#abc123,#def456" --md 명령어를 통해 전체 소스를 마크다운 형태로 일괄 확보합니다. 이를 통해 사실에 입각한(Ground-truth) 완벽한 답변을 작성하게 됩니다.

3. AI 에이전트 RAG 파이프라인의 백엔드 & MCP 연동

Qmd는 Bun 런타임 기반의 초경량 바이너리(~/.bun/bin/qmd)로 설치되어 동작하며, MCP(Model Context Protocol) 서버 기능을 기본적으로 내장하고 있습니다.

💡 **에이전트와의 RAG 연동 장점:** "Claude Code나 Antigravity 등의 최신 자율형 AI 에이전트에 Qmd를 MCP 도구로 연결해 주면, 에이전트가 로컬 위키를 마음대로 검색할 수 있는 툴 권한을 얻게 됩니다. 매 질문마다 에이전트가 백그라운드에서 직접 Qmd를 호출하여 관련 노트를 찾아내므로, 사용자 개입 없이 완벽한 온프레미스 RAG가 활성화됩니다."

❓ 자주 묻는 질문 (FAQ)

Q. 구조화된 고차원 검색에서 HyDE가 어떻게 동작하나요?

A. 사용자가 복잡한 쿼리를 던지면 내부 LLM이 질문에 해당하는 '가상의 정답 구절(Passage)'을 1차적으로 임시 생성합니다. 그리고 그 가상 정답과 가장 의미적 유사도가 높은 실제 로컬 문서를 검색합니다. 질문의 키워드만 맞비교하는 것보다 검색 정확도가 수 배 이상 뛰어납니다.

Q. qmd를 사용하려면 로컬 PC 사양이 높아야 하나요?

A. 아닙니다. Qmd는 Bun 런타임을 활용해 동작하도록 경량 설계되어 매우 빠르며, 로컬의 마크다운 저장소 크기가 수천 개 수준이라 하더라도 수 밀리초(ms) 단위로 고속 검색을 지원합니다.

🔗 같이 보면 좋은 문서

로컬에 저장된 무수히 많은 지식 조각들이 머릿속에서 희미해지고 있다면, 키워드와 맥락을 동시에 장악하는 Qmd 검색 엔진을 연동해 보세요. AI 비서가 당신의 과거 기록과 위키 노트를 정확히 찾아내어 즉각 지식을 합성해 줍니다.