QMD로 옵시디언 문서와 AI 연결하기
정
정민송
실험
카테고리
비어 있음
들어가며
얼마전, 진행 중인 프로젝트에 관해 전체 흐름을 정리해야 할 일이 있었습니다.
관련 내용이 회의록, 녹취록(일상 대화 중 나온 것), 아이디어 메모, 일일 노트 등..
다양한 문서 형태로 각각의 폴더에 있는 상태였습니다.
다양한 문서 형태로 각각의 폴더에 있는 상태였습니다.
이런 일이 있을 때 원래는 Claude code나 Codex로
"옵시디언 볼트 전체에 관련 문서를 찾아 타임라인으로 정리해줘"라고 합니다.
"옵시디언 볼트 전체에 관련 문서를 찾아 타임라인으로 정리해줘"라고 합니다.
하지만 이번에는 아래 두가지 방식으로 따로 실행해보며
QMD라는 것을 테스트 해보았습니다. (QMD에 관한 설명은 아래에 간단히 언급했습니다.)
QMD라는 것을 테스트 해보았습니다. (QMD에 관한 설명은 아래에 간단히 언급했습니다.)
기존 방식: LLM이 직접 파일을 탐색
새로운 방식: QMD(Query Markup Documents)라는 로컬 검색 도구를 활용하여 탐색
결론부터 말씀드리면 'QMD가 무조건 최고의 선택지다!'는 아닙니다.
LLM만으로도 충분한 상황이 있고, QMD의 이점이 확실히 드러난 지점도 따로 있었습니다.
(QMD의 이점: 키워드가 명확하지 않은 상황일 때, 의미 기반의 탐색이 가능한 RAG를 손쉽게 구축/관리할 수 있다.)
◼︎ 배경: LLM으로 문서 탐색 할 때 생겼던 반복적인 문제들
QMD와 비교해볼 생각이 든 건, LLM에 문서를 넣어 작업할 때 발생하는 반복적인 문제들 때문이었습니다.
문제1. 문서를 제대로 읽지 않는다.
"ㅁㅁㅁㅁ프로젝트에 관해 멤버십 피벗 관련으로 논의된 것들 찾아줘" 라고 요청합니다.
답변을 확인하면 어딘가 찜찜합니다.
"ㅇㅇ 폴더 문서도 확인한거야?", "그런데 ㅁㅁㅁㅁ 문서 3번째 단락은 관련 내용 아니야?" 라고 물으면
AI가 "아! 죄송합니다, 놓쳤네요." 하는 답변이 돌아오는 경우가 적지 않았습니다.
대체로 문서 앞부분, 몇 줄만 확인하고 관련성을 판단해버리는거죠.
문제2. 전부 다 읽게 하면? 토큰 비용과 시간 측면에서 효율적이지 않다.
프롬프트를 통해 문서를 처음부터 끝까지 읽히게 할 수는 있습니다.
하지만 토큰을 많이 사용하게 되며 필요하지 않은 내용도 봐야하니 응답 시간도 길어집니다.
문제3. 관련 문서를 빠르게 선별하기 위해 문서 앞에 쓰는 '핵심요약'도 완벽한 대안은 아니다.
위 문제를 해결하기 위해 문서 앞에 TL;DR이나 핵심 요약을 써두는 편입니다.
하지만 요약은 기본적으로 손실 압축인지라 원문에만 있는 내용이 빠져버리면 LLM은 관련 문서가 아니라고 판단내리기 쉽습니다.
이런 문제를 갖고 있던 중, 지인으로부터
"QMD라는게 옵시디언 문서에서 필요한 내용을 잘 찾아준다더라"
는 이야기를 듣고 QMD에 관해 알아보게 되었습니다.
◼︎ 직접 실험: LLM only 🆚 LLM with QMD
QMD에 관해 간단히 설명드리자면, 풀네임은 Query Markup Documents.
RAG를 로컬에서 간편하게 돌릴 수 있게 만들어둔 로컬 검색 엔진 도구입니다.
쇼피파이 창립자인 토비아스 뤼트케(Tobias Lütke)가 만들었습니다.
QMD를 활용해 문서를 탐색하면, LLM처럼 전부 읽게하는 것이 아니라 RAG 기술을 활용합니다.
의미기반으로 문서를 탐색하기에 앞에서 언급한 세 문제의 해결책이 될 수 있습니다.
•
관련 문서 판별을 LLM이 아닌 검색 단계가 먼저 처리하고,
•
볼트 전체가 아니라 선별된 문서만 넘어가니 토큰·시간 부담이 줄고,
•
원문 자체를 검색하기 때문에 요약에서 빠진 단서도 살아 있습니다.
그러나 직접 눈으로 보지 않았으니 의구심은 생깁니다.
'QMD가 실제로 더 나은 결과를 주는 것일까요?'
'기존 방식과는 얼마나 차이가 있을까?'
그래서 직접, 간단히 실험해보기로 했습니다.
LLM만 사용하는 것(LLM only) vs LLM에 QMD를 붙인 것 (LLM with QMD)
참고로 LLM with QMD는 임베딩 모델을 두가지로 나눠서 했습니다.
•
QMD - Qwen3 0.6k
•
QMD - Qwen3 4B
질문은 모두 동일했습니다.
"오리지널스(진행하던 프로젝트)에 관하여 논의된 내용을 찾아 타임라인 순으로 정리해줘. 전체 볼트 폴더를 확인해야해."
실험 전에는 'QMD를 쓰면 LLM이 놓치는 문서까지 잡아낼테니 무조건 더 좋겠지?!' 하고 생각했습니다.
하지만 결과는 조금 달랐습니다.
👉 결과
<문서 확인 범위 기준 비교>
항목 | LLM only | with QMD (0.6k 임베딩) | with QMD (4B 임베딩) |
초기 검색 대상 | Grep 79개 파일 | QMD query → 20개 결과 반환 | QMD search + ls |
실제 내용 직접 확인한 파일 수 | 43개 (명시적 보고) | 13개 (QMD get으로 조회) | 수십 개 (multi-get/get 여러 번) |
전체 검색 문서 | 79개 Grep 결과 중 43개 Read | 전체 353개 문서 대상 검색 | 8개 컬렉션 순회 |
탐색 방법 | Grep + Read (LLM 직접 탐색) | QMD hybrid search (lex + vec + reranking) + get | QMD BM25 (키워드 검색) + ls + get(문서 불러오기) |
[LLM only]
Grep으로 프로젝트 명인 '오리지널스' 키워드를 검색해 43개 문서를 직접 읽었습니다.
피벗과 같은 핵심 이벤트를 모두 포착했습니다.
다만, 1차 답변에서는 빠진게 있어서 "모든 폴더를 확인한거 맞아?"라고 되묻는 과정은 필요했습니다.
→ '오리지널스'라는 키워드를 문서마다 링크해두어서인지 일일 노트에 있는 핵심 이벤트 내용도 잘 가져왔습니다.
[LLM with QMD(0.6k)]
이 조합에서는, Grep은 일절 사용하지 않았습니다.
13개의 문서만 읽고서 앞서 언급한 핵심 이벤트도 모두 포착했습니다.
[LLM with QMD(4B)]
4B모델은 기대가 컸지만 아쉽게도 제 환경(Metal GPU)에서 크래시가 발생해 제대로된 실험이 이뤄지지 않았습니다.
0.6k 임베딩 모델이 하이브리드 검색을 한 반면, 해당 임베딩 모델은 키워드 검색(BM25) 중심으로 우회했었습니다.
날짜 포인트는 가장 많이 커버했지만 피벗 전환 등의 결정적 이벤트는 놓쳤습니다.
👉 실험을 통해 배운 것
결과물들을 놓고 보니 QMD가 모든 상황에서 최고가 아님을 알았습니다.
키워드가 명확한 상황에서는 LLM이 Grep으로 직접 찾는 방식도 충분히 잘 작동하는걸 확인했습니다.
다만, 43개 파일을 전부 읽어야 했고 모든 문서/폴더를 제대로 본게 맞는지 확인하는 과정은 여전히 필요했습니다.
QMD(정확히는 RAG)의 이점도 확인할 수 있었습니다. 13개의 문서만으로 핵심 이벤트는 전부 잡아냈으니까요.
물론 이번 실험은 QMD의 강점을 극대화하지는 못했습니다.
의도한건 아니지만.. 질문에는 오리지널스라는 프로젝트명이 명확한 키워드로 있었습니다.
LLM의 키워드 검색만으로도 충분히 문서를 확인할 수 있죠.
LLM의 키워드 검색만으로도 충분히 문서를 확인할 수 있죠.
하지만 제가 주로 문서들에서 무언가를 찾을 때 떠올리는 질문은 이렇게 또렷한 키워드가 있기보단
•
"보안 관련해서 회의했던게 어디서 추가로 이야기가 나왔더라?"
•
"그 때 이 아이디어 냈던게 어느 리서치 기반이었지?"
처럼 키워드 하나로 해결되지 않는 경우가 많습니다.
QMD의 강점이 이런 곳에서 발휘됩니다. (이번에도 정확히 말하자면 RAG의 강점입니다.)
키워드가 정확히 일치하지 않아도, 비슷한 의미를 지닌 문서를 찾아낼 수 있습니다.
문서에 '보안'이라는 키워드가 정확히 없어도, '접근 권한', '암호화 정책' 같은 맥락만 있어도 의미상 가까이 있기에 함께 묶어낼 수 있습니다.
◼︎ 그렇다면 QMD 자체는 어떤 강점이 있나?
QMD만의 장점은 RAG와 비교했을 때 나타납니다.
단계 | RAG 직접 구축 | QMD |
초기 세팅 | - 임베딩 모델 선택 - 벡터 DB 설치·연결 - 청킹 전략 결정 - 검색기 · 리랭커 구현 | 설치 후 볼트 경로 지정 → 색인 자동 생성 (임베딩 모델 변경 가능합니다) |
검색 방식 | BM25·벡터·하이브리드 중 설계자가 선택해 구현 | 하이브리드 검색(BM25 + 벡터 + 리랭킹) 기본 제공 |
문서 갱신 | 추가·변경된 문서를 감지하는 파이프라인을 직접 구성해 색인 갱신 | 갱신 명령어 입력으로 해결 - qmd update & qmd embed |
초기 세팅도 편리하지만, 문서가 추가/변경될 때마다 색인을 갱신하는 과정이 몹시 편리합니다.
qmd update, qmd embed 이렇게 명렁어 두 번 입력하면 끝이거든요.
(참고: 저는 RAG를 직접 구축해본 적은 없어, RAG에 관해서는 알아본 범위 이내에서 정리했습니다.)
◼︎ 마무리
이번 과정은 RAG에 관한 이해도를 쌓을 수 있는 뜻깊은 시간이었습니다.
RAG 자체에 관한 흥미도 많이 생겼구요.
지금은 Claude Code에 QMD MCP를 연결하여 사용 중입니다.
이전에는 "qmd를 사용해"라고 프롬프트에 명시적으로 언급하거나, 직접 터미널 명령어를 입력했어야했습니다.
MCP 설치로 이 과정이 생략되고 알아서 qmd 쿼리를 실행하니 너무 편리합니다.
앞으로는 LLM wiki를 접목해보려합니다. 정보를 정리하고 탐색하는 시간을 최소화해서 본질에 집중할 수 있는 시스템을 계속해서 구축해나가는게 목표기 때문입니다.
긴 글 읽어주셔서 감사합니다.
Tip
임베딩 모델은 기본 설정값인 EmbeddingGemma보다 Qwen3가 더욱 좋다는 커뮤니티 의견이 많았습니다.
'Ming-story' 구독하기
사이트를 구독하면 새 포스트 등 최신 업데이트를 알림과 메일로 가장 먼저 받아보실 수 있습니다.
Slashpage에 가입하고 'Ming-story'을 구독하세요!
Slashpage에 가입하고 'Ming-story'을 구독하세요!
