코딩 없이 벡터DB 기반 RAG 시스템 구축하기: Hermes Agent 활용법

사내 Google Drive에는 일정표, 회의록, 제품 사양서, 부품 데이터시트, 설계도면이 계속 쌓입니다. 파일명과 폴더 위치를 정확히 기억할 때는 검색이 어렵지 않지만, “B2C 메인보드 커넥터 배치가 바뀐 자료”처럼 내용과 의미로 찾아야 하는 질문은 금방 막힙니다. 이 글에서는 로컬 검색 엔진 qmd로 이런 내부 문서를 찾고, 답변 근거로 쓰는 RAG 시스템을 구성합니다.

처음에는 벡터DB를 직접 만들고 RAG 파이프라인까지 연결해야 하나 싶었습니다. 막상 해보니 외부 벡터DB를 따로 구축할 필요는 없었습니다. Hermes Agent에 qmd를 연결한 뒤, 설치부터 문서 변환·OCR·임베딩·검색까지 대화로 맡기면 됩니다.

제가 채팅에 입력한 건 아래 세 문장 정도입니다.

qmd를 설치해 줘.
이 Drive 폴더를 지식베이스에 넣어줘.
메인보드 변경 도면을 찾아줘.

명령 실행과 오류 복구는 Hermes의 몫입니다. 이 글에서는 qmd 명령어를 하나씩 외우기보다, 코드를 직접 작성하지 않는 사용자가 Hermes와 qmd를 어떻게 나눠 쓰면 되는지를 살펴봅니다.

먼저 구분할 점: “코딩 없이 사용한다”는 말은 시스템 안에 코드가 전혀 없다는 뜻이 아닙니다. 사용자가 파이썬 수집기나 벡터 DB API를 직접 작성하지 않고, Hermes가 필요한 명령과 변환 스크립트·자동화 파이프라인을 대신 만들고 실행한다는 의미입니다.

qmd는 벡터DB와 BM25를 결합한 로컬 검색 엔진

qmd(Query Markup Documents)는 Markdown 문서와 지식베이스를 장치 안에서 검색하는 온디바이스 검색 엔진입니다. 공식 저장소 기준으로 다음 기능을 결합합니다.

구성	역할
BM25 전체 텍스트 검색	파일명, 부품 번호, 도면 번호처럼 정확한 단어를 빠르게 찾음
벡터 유사도 검색	표현이 달라도 의미가 비슷한 문서를 찾음
쿼리 확장	사용자의 질문을 검색에 유리한 표현으로 넓힘
RRF 결합	키워드와 벡터 검색의 순위를 하나로 합침
로컬 LLM 재랭킹	상위 후보가 질문 의도에 맞는지 다시 정렬함
MCP 서버	Hermes 같은 AI 에이전트가 검색·문서 조회 도구를 호출하게 함

qmd의 검색 모드는 크게 세 가지로 나뉩니다.

search  → BM25 키워드 검색
vsearch → 벡터 의미 검색
query   → 키워드 + 벡터 + 쿼리 확장 + 재랭킹

일상적인 질문에는 품질을 우선해 하이브리드 검색을 쓰고, 정확한 도면 번호나 파일명을 찾을 때는 빠른 키워드 검색을 함께 쓰는 식입니다. 사용자가 이 모드를 매번 골라도 되지만, Hermes가 질문을 해석해 적절한 검색 방법을 선택하도록 맡길 수 있습니다.

Hermes Agent와 qmd로 로컬 RAG 시스템 구축하기

이번에 구성한 흐름을 한 줄로 펼치면 다음과 같습니다.

Google Drive·Notion·로컬 파일·코드 저장소
  ↓ 수집
형식별 텍스트·Markdown 변환
  ↓ 보강
출처 메타데이터 + OCR + Vision 의미 설명
  ↓ 저장
로컬 qmd 컬렉션
  ↓
BM25 인덱싱 + 벡터 임베딩
  ↓ MCP
Hermes Agent의 자연어 검색과 출처 포함 답변

qmd가 Google Drive API나 Notion 권한을 대신 해결해 주는 것은 아닙니다. 외부 자료를 읽어 오는 권한과 변환 과정은 별도로 필요합니다. 여기서 Hermes의 역할은 각 도구를 연결하고, 실패 로그를 읽고, 필요한 스크립트를 만들고, 최종 검색 결과를 사용자에게 설명하는 것입니다.

Hermes 공식 선택형 스킬: qmd는 사용자가 외부에서 임의의 스킬을 찾아 추가하는 방식이 아니라, Hermes Agent와 함께 배포되는 공식 선택형 스킬 카탈로그에 포함돼 있습니다. 처음부터 활성화된 번들 스킬은 아니며 필요할 때 명시적으로 설치합니다. 식별자는 official/research/qmd이며, 설치 후 Hermes가 qmd의 설치·인덱싱·검색·MCP 연동 절차를 일관되게 수행하는 데 사용합니다.

1. Hermes Agent에서 qmd 스킬 설치하기

시작할 때 사용자에게 필요했던 문장은 짧았습니다.

qmd를 설치하고 진행해 보자.

Hermes는 설치 명령부터 무작정 실행하지 않습니다. 먼저 현재 환경을 살핍니다.

1. Node.js와 npm 버전 확인
2. Raspberry Pi의 ARM64 아키텍처 확인
3. Hermes와 함께 배포되는 공식 선택형 official/research/qmd 스킬 확인·설치
4. qmd 네이티브 모듈에 필요한 C/C++ 빌드 도구 확인
5. @tobilu/qmd 전역 설치
6. 첫 실행에서 임베딩·쿼리 확장·재랭킹용 로컬 GGUF 모델 준비
7. 테스트 문서로 BM25·벡터·하이브리드 검색 확인
8. qmd MCP 서버를 Hermes에 등록하고 연결 테스트

공식 qmd 문서의 현재 요구 사항은 Node.js 22 이상 또는 Bun입니다. 로컬 모델은 첫 사용 시 내려받아 qmd 캐시에 보관하므로, 설치 파일 외에 모델 저장 공간과 다운로드 시간도 고려해야 합니다.

ARM64 qmd 설치에서 make 오류가 나올 때

Raspberry Pi에서는 npm 패키지만 내려받는다고 끝이 아닙니다. 이 환경에는 make가 없어서 네이티브 Node 모듈 빌드 단계에서 설치가 한 번 멈춥니다.

이럴 때는 오류 해결 명령을 따로 검색하지 않고 채팅에 이렇게 이어서 적으면 됩니다.

설치가 실패한 원인을 확인하고 필요한 것만 설치한 뒤 다시 진행해 줘.

로그에는 빌드 도구가 없다는 내용이 나옵니다. Hermes가 컴파일러와 make를 설치하고 qmd 설치를 다시 진행합니다. 여기서 볼 것은 “설치 완료”라는 한 줄이 아닙니다. 어디서 막혔는지, 다시 설치한 뒤 실제 검색까지 통과했는지를 확인해야 합니다.

Claude Code와 Codex에 qmd MCP 연결하기

Claude Code와 Codex에는 Hermes의 official/research/qmd 같은 공식 선택형 스킬이 없습니다. 대신 qmd를 직접 설치하고 MCP 서버로 한 번 등록하면 됩니다.

먼저 qmd를 설치합니다.

npm install -g @tobilu/qmd
qmd --version

Claude Code에서는 다음 명령으로 사용자 범위에 등록합니다.

claude mcp add -s user qmd -- qmd mcp
claude mcp list

Codex는 명령 형식이 조금 다릅니다.

codex mcp add qmd -- qmd mcp
codex mcp list

등록이 끝나면 두 도구에서도 “이 폴더를 qmd 컬렉션에 넣고 임베딩해 줘” 또는 “내부 문서에서 커넥터 변경 자료를 찾아줘”처럼 말하면 됩니다. 다만 MCP를 붙였다고 Google Drive 변환, OCR, 주기적인 동기화까지 저절로 생기는 것은 아닙니다. 그런 작업은 Claude Code나 Codex에 별도로 요청해 스크립트와 처리 흐름을 준비해야 합니다.

2. Google Drive 문서를 qmd에 임베딩하기

검색할 Google Drive 폴더는 링크 하나로 지정합니다.

이 폴더를 지식베이스에 넣어 보자.
https://drive.google.com/drive/folders/...

Hermes는 연결된 Google 계정이 읽을 수 있는 범위 안에서 지정한 폴더만 대상으로 삼았습니다.

Google Drive 폴더
→ 하위 폴더 재귀 탐색
→ 지원 문서 다운로드 또는 내보내기
→ Markdown 변환
→ 출처·메타데이터 추가
→ qmd 인덱싱
→ 벡터 임베딩

처리한 주요 형식은 다음과 같습니다.

• Google Docs
• Google Sheets
• Google Slides
• PDF
• DOCX
• XLSX
• PPTX
• Markdown과 일반 텍스트

Google Docs·Sheets·Slides는 Drive의 내보내기 기능을 이용합니다. Office 문서와 PDF에는 형식에 맞는 로컬 변환기를 붙입니다. qmd는 Markdown 중심의 로컬 문서를 검색하므로, 원본을 검색 가능한 텍스트로 바꾸는 단계가 먼저 필요합니다.

3. 검색 결과에 Google Drive 원본 링크 남기기

문서 본문만 변환하면 검색 결과는 나오지만, 어느 원본에서 나온 내용인지 추적하기 어렵습니다. 그래서 각 Markdown 문서 앞에 다음 메타데이터를 붙입니다.

title: "문서 제목"
source: "google-drive"
source_id: "Google Drive 파일 ID"
source_url: "원본 Google Drive URL"
source_path: "Drive 내부 폴더 경로"
mime_type: "원본 파일 형식"
modified_time: "마지막 수정 시각"
converter: "사용한 변환 방식"

각 필드의 용도는 분명합니다.

• source_id: 같은 파일을 다시 동기화할 때 중복을 피하는 식별자
• source_url: 답변 뒤 원본 문서를 직접 열 수 있는 링크
• source_path: 같은 파일명이 여러 폴더에 있을 때 문맥을 구분하는 경로
• modified_time: 로컬 사본이 최신인지 판단하는 기준
• converter: 변환 결과가 이상할 때 어느 처리기를 썼는지 추적하는 정보

이 메타데이터 덕분에 Hermes는 검색된 내용을 요약하는 데서 멈추지 않고, 답변에 원본 Google Drive 링크를 함께 제공할 수 있습니다.

4. 텍스트 없는 PDF 설계도면을 OCR·Vision으로 검색하기

일반 PDF 텍스트 추출만으로는 설계도면, 회로도, 부품 데이터시트처럼 이미지가 중심인 문서를 제대로 검색하기 어렵습니다. 실제 테스트 문서 중에는 추출 결과가 0자로 나오는 PDF도 있습니다.

하지만 도면의 검색 의도는 단순 문자보다 넓습니다.

• 어떤 제품의 도면인지
• 메인보드인지 기구물인지
• 어떤 부품과 커넥터가 표시되어 있는지
• 도면 번호와 개정 번호가 무엇인지
• 변경 전후를 비교하는 문서인지
• PCB 풋프린트용 자료인지

이미지 중심 PDF는 다음 순서로 다룹니다.

PDF 기본 텍스트 추출
→ 페이지당 텍스트 양 측정
→ 이미지 중심 PDF 후보 분류
→ PDF 페이지를 이미지로 렌더링
→ Tesseract 한국어·영어 로컬 OCR
→ Vision 모델로 문서 의미 분석
→ 의미 설명과 검색 키워드를 Markdown에 추가
→ qmd 임베딩

텍스트 추출 결과가 0자였던 문서도 로컬 OCR을 거치면 수천 자가 나옵니다. 도면 번호와 부품 번호는 OCR로 찾고, 문서가 무엇을 설명하는지는 Vision으로 보완합니다.

Vision 설명은 검색용 Markdown에 함께 저장

## AI 시각 분석 기반 문서 설명

### 문서 의미
Molex 53259 계열 3.5mm 피치 와이어-투-보드 커넥터의
기구 치수와 PCB 권장 홀 패턴 도면이다.

### 주요 관찰 사항
- 제조사: Molex
- 문서 번호: SD-53259-003
- 피치: 3.5mm
- 권장 PCB 홀 치수 포함
- 회로 수별 주문 번호와 치수표 포함

### 검색 키워드
Molex, 53259, 3.5mm pitch, wire-to-board connector,
PCB footprint, recommended PCB hole

여기에는 분명한 한계가 있습니다. qmd가 이미지 자체를 임베딩하는 것은 아닙니다. 로컬 OCR이 읽은 문자와 Vision 모델이 만든 설명을 텍스트로 저장한 뒤, qmd는 그 텍스트를 임베딩합니다.

기밀 문서 주의: Tesseract OCR은 로컬에서 실행할 수 있지만 외부 Vision 모델을 사용하면 렌더링한 도면 이미지가 모델 제공자에게 전송될 수 있습니다. 회사 보안 정책, NDA, 고객 자료 반출 기준을 먼저 확인하고, 외부 전송이 허용되지 않는 문서는 로컬 OCR까지만 사용하거나 승인된 사내 Vision 환경을 사용해야 합니다.

5. qmd 명령어 없이 대화형으로 문서 추가하기

구성이 끝나면 터미널에서 qmd update나 qmd embed를 직접 실행할 일이 거의 없습니다. 자료의 출처에 맞춰 평소 말하듯 요청하면 됩니다.

파일을 첨부해서 추가하기

이 파일을 지식베이스에 넣어줘.

채팅 내용을 검색 자료로 남기기

이 내용을 나중에 검색할 수 있게 저장해 줘.

Google Drive 폴더 추가하기

이 Drive 폴더를 지식베이스에 추가해 줘.

기존 Drive 폴더 다시 동기화하기

개발 관리 Drive 폴더를 최신 상태로 다시 동기화해 줘.

Notion 페이지 추가하기

이 Notion 페이지와 하위 페이지를 검색할 수 있게 넣어줘.

로컬 코드 저장소 추가하기

이 코드 저장소를 검색 가능하게 만들어 줘.

Hermes는 요청을 해석해 자료를 로컬 컬렉션으로 가져오고, 형식 변환과 메타데이터 추가, 필요한 OCR·설명 생성을 거쳐 인덱스를 갱신합니다. 코드 저장소는 qmd의 AST-aware 청킹을 선택할 수 있지만, 일반 Markdown 문서는 제목·문단·코드 블록 같은 자연스러운 경계를 기준으로 나뉩니다.

6. Hermes Agent에서 qmd로 로컬 문서 검색하기

검색할 때도 평소 말투 그대로 물어봅니다.

B2C 메인보드 커넥터 배치 변경 자료 찾아줘.

3.5mm 커넥터의 PCB 풋프린트 도면이 있어?

뉴트리션 엔진 개발 일정이 들어 있는 문서를 찾아줘.

모터 테스트 결과가 기록된 시트를 요약해 줘.

Hermes는 질문이 내부 문서에 관한 것이라고 판단하면 qmd MCP 도구 또는 qmd CLI를 사용합니다.

사용자 자연어 질문
→ Hermes가 내부 문서 검색 필요성 판단
→ qmd 키워드·벡터·하이브리드 검색
→ 관련 문서 본문과 메타데이터 확인
→ 출처를 포함한 답변 생성

반대로 최신 뉴스, 날씨, 일반 상식처럼 내부 지식베이스가 필요 없는 질문에는 qmd를 사용하지 않습니다. “모든 질문을 로컬 검색으로 보낸다”가 아니라, 질문의 출처가 내부 자료인지 외부 최신 정보인지 구분하는 것이 에이전트의 역할입니다.

7. 검색 결과를 원본 PDF에서 다시 확인하기

검색은 두 단계로 나누는 편이 낫습니다.

1단계: qmd로 관련 문서 찾기

qmd는 다음 정보를 이용해 관련 문서를 빠르게 좁힙니다.

• 파일명과 문서 제목
• Google Drive 폴더 경로
• 변환된 본문 텍스트
• 로컬 OCR 결과
• AI가 생성한 문서 의미 설명
• 부품명·도면 번호·개정 정보
• 추가한 검색 키워드

2단계: 원본에서 치수와 배치 확인하기

Hermes는 후보 문서의 source_url을 확인해 원본 링크를 답변에 포함합니다.

문서: Molex 3.5mm 커넥터 도면
검색 근거: PCB 권장 홀 패턴과 회로 수별 치수표가 있는 문서
원본: https://drive.google.com/file/d/.../view

도면 치수나 부품 배치를 묻는 질문에는 저장된 요약만으로 답하지 않습니다. 원본 PDF를 다시 내려받아 관련 페이지만 Vision으로 확인합니다.

이 도면에서 변경 전후 차이를 알려줘.

커넥터 피치와 공차를 원본에서 확인해 줘.

이 회로도의 핀 배치를 표로 정리해 줘.

이 방식은 검색할 때마다 모든 PDF를 처음부터 Vision으로 재분석하는 것보다 빠르고 비용이 적습니다. qmd는 후보를 찾는 역할, 원본 재확인은 정확한 근거를 검증하는 역할로 나눕니다.

8. Raspberry Pi ARM64에서 qmd 설치·임베딩 오류 해결하기

설치와 임베딩은 한 번에 끝나지 않는 경우가 많습니다.

문제	Hermes가 취한 대응
ARM64에서 네이티브 Node 모듈 빌드 실패	컴파일러·make 등 필요한 빌드 도구를 확인해 설치 후 재시도
PPTX로 표시되지만 실제 크기가 0바이트인 Drive 파일	전체 작업을 중단하지 않고 메타데이터 문서로 남겨 원본 상태 표시
이미지 중심 PDF의 텍스트 추출 실패	페이지 렌더링 후 Tesseract OCR과 선택적 Vision 분석 수행
CPU 임베딩이 세션 제한을 넘어 일부 청크 실패	실행 제한을 조정하고 배치 크기를 줄여 실패 청크만 재처리
SolidWorks·STL·DWG 등 미지원 형식 발견	실패 목록에 분리하고 별도 변환 파이프라인이 필요하다고 표시

특히 Raspberry Pi처럼 범용 AI 가속에 적합한 전용 GPU·VRAM이 없는 환경에서는 대량 임베딩과 재랭킹이 오래 걸릴 수 있습니다. 한 번에 모든 파일을 다시 처리하기보다 새 파일과 수정 파일만 갱신하고, 실패한 청크만 재시도하는 방식이 현실적이었습니다.

qmd 공식 문서에는 임베딩 배치의 문서 수와 메모리 사용량을 제한하는 옵션도 있습니다. 사용자가 플래그를 외울 필요는 없지만, Hermes에게 다음처럼 조건을 줄 수 있습니다.

CPU와 메모리를 과하게 쓰지 않도록 작은 배치로 처리해 줘.
실패하면 전체를 처음부터 하지 말고 실패한 문서와 청크만 다시 처리해 줘.

팀 문서 검색에서 접근권한 확인하기

로컬 검색이라는 말이 자동으로 안전한 권한 관리를 의미하지는 않습니다.

• qmd는 로컬 인덱스를 만들지만 Google Drive의 팀별 접근권한을 그대로 재현하지 않습니다.
• Drive와 Notion은 연결된 계정 또는 Integration이 읽을 수 있는 범위만 가져올 수 있습니다.
• 여러 사용자가 같은 qmd 인덱스를 검색한다면 원본 서비스의 사용자별 권한이 우회될 수 있습니다.
• Slack 메시징 연결과 Slack 전체 기록을 읽는 데이터 권한은 서로 다른 문제입니다.
• OCR 결과와 AI 설명에는 원본 이미지에서 읽힌 민감 정보가 포함될 수 있습니다.
• source_url을 제공해도 답변을 받는 사용자가 원본 문서를 열 권한이 있는지는 별도로 확인해야 합니다.

따라서 개인용 또는 단일 운영자용 검색에서 시작하고, 팀 공유로 확장할 때는 컬렉션 분리·OS 계정 권한·암호화·원본 접근권한·로그 정책을 별도로 설계하는 편이 안전합니다.

로컬 문서 검색의 한계와 보안 주의점

1. 모든 형식이 자동 지원되는 것은 아닙니다. SolidWorks, DWG, STL 같은 CAD 파일은 별도 변환기가 필요합니다.
2. OCR 결과는 원본과 다를 수 있습니다. 작은 치수, 공차 기호, 회전된 글자, 표 셀은 반드시 원본을 다시 봐야 합니다.
3. Vision 설명은 사실 확인이 필요합니다. 문서 의미를 찾는 힌트이지 도면 승인 근거가 아닙니다.
4. CPU 환경에서는 시간이 걸립니다. Raspberry Pi에서 대량 문서의 임베딩·쿼리 확장·재랭킹은 GPU 환경보다 느립니다.
5. 한글 중심 자료는 모델 선택을 점검해야 합니다. qmd 공식 문서는 기본 임베딩 모델 외에 CJK를 포함한 다국어용 Qwen3-Embedding 모델 설정 방법도 안내합니다. 모델을 바꾸면 기존 벡터와 호환되지 않으므로 전체 재임베딩이 필요합니다.
6. 동기화는 별도 작업입니다. Drive나 Notion의 변경 내용을 언제 다시 가져올지 주기와 실패 알림을 정해야 합니다.

Hermes Agent 설치·검색 요청문 예시

처음부터 모든 세부 명령을 적을 필요는 없습니다. 대신 범위와 검증 조건을 명확히 줍니다.

이 Google Drive 폴더만 읽기 대상으로 사용해 줘.
하위 폴더를 포함해 지원 문서를 Markdown으로 변환하고,
원본 URL·Drive 경로·파일 ID·수정 시각을 메타데이터로 남겨 줘.

텍스트가 거의 없는 PDF는 별도 목록으로 분류하고,
먼저 로컬 OCR을 적용해 줘.
외부 Vision 모델로 보낼 문서는 실행 전에 목록과 개인정보 위험을 보여 줘.

qmd 인덱싱과 임베딩이 끝나면
처리 성공·건너뜀·실패 파일 수와 실패 이유를 표로 정리해 줘.
테스트 질문 3개를 실제로 검색하고 원본 링크까지 확인해 줘.

이 요청에서 중요한 부분은 “알아서 해줘”가 아니라 다음 경계를 적은 것입니다.

• 읽을 폴더 범위
• 원본 추적용 메타데이터
• 로컬 OCR 우선 원칙
• 외부 Vision 전송 전 확인
• 실패를 숨기지 않는 결과 표
• 실제 검색과 원본 링크 검증

설치와 로컬 문서 검색 점검하기

Google Drive와 PDF 문서를 대화형으로 검색하기

사용자 관점에서 필요한 것은 세 문장이었습니다.

qmd를 설치해 줘.
이 Drive 폴더를 지식베이스에 넣어줘.
메인보드 변경 도면을 찾아줘.

환경 확인, 설치, 문서 수집, 형식 변환, OCR, 필요한 페이지만 골라 보는 이미지 분석, 인덱싱, 임베딩, 오류 복구, 원본 링크 확인은 Hermes Agent가 맡습니다.

핵심은 벡터 데이터베이스 API나 qmd 명령어를 먼저 배우는 것이 아닙니다. Hermes에게 어떤 자료를 어디까지 넣을지 자연어로 설명하고, 성공 조건과 개인정보 경계를 정한 뒤, 검색 결과를 원본으로 검증하는 것입니다.

qmd는 로컬 하이브리드 검색 엔진을 제공하고, Hermes는 그 엔진을 설치·운영하며 사용자 질문과 연결합니다. 두 역할을 나누면 코드를 직접 작성하지 않는 사용자도 자신의 문서 지식베이스를 대화로 만들고 검색할 수 있습니다.

라즈베리파이에서 대량 임베딩이 오래 걸린 이유와 GPU 머신으로 옮길 작업이 궁금하다면 다음 글로 이어서 볼 수 있습니다.

이어 읽기 · AI 머신 역할 분담 로컬 AI에 VRAM이 필요한 이유 벡터DB 저장과 임베딩 연산을 구분하고, qmd·Ollama·ComfyUI·Whisper에서 GPU가 필요한 작업을 살펴봅니다. VRAM 글 이어서 보기 →

공식 문서

• qmd 공식 GitHub 저장소
• Hermes Agent 공식 선택형 Skills 카탈로그
• Hermes Agent MCP 안내