[Claude Code + OpenViking] 내 AI 에이전트가 드디어 wiki를 제대로 검색한다 — OpenViking Hybrid Retrieval 구축기

📝 바쁘시면 이것만 읽어도 돼요:

• Claude Code + OpenViking으로 개인 wiki 65개 파일에 하이브리드 검색(키워드 + 의미 기반) 구축

• CPU가 AVX를 지원 안 해도 Jina 클라우드 API 무료 티어로 해결 가능

• AI 에이전트가 실제로 검색 명령을 실행하는지는 도구 트레이스에서 눈으로 확인할 수 있다

• AGENTS.md에 명령어를 쓸 때 외부 실행파일임을 명시해야 AI가 헷갈리지 않는다

• wiki가 쌓일수록 검색 정확도가 올라가는 구조를 갖추게 됐다

🎯 이런 분들께 도움돼요

• OpenViking 구축을 진행 중인 분

• Hermes(Claude Code CLI)로 개인 wiki를 운영 중인 분

• AI 에이전트에 검색 기능을 붙이고 싶은데 어디서부터 시작할지 모르는 분

😫 문제 상황 (Before)

현재 개인 지식 관리 wiki를 운영하고 있으며 뉴스레터, 경쟁사 분석, 제품 지식 등 업무에서 수집한 자료들을 AI 에이전트 Hermes가 정리해서 wiki 페이지로 만들어 준다.

그런데 문제가 있었다. Hermes에게 "AIOps와 ITSM의 관계 설명해줘"라고 물어보면, Hermes는 wiki 파일을 하나씩 직접 열어보는 방식으로 답변했다. wiki에 파일이 65개가 됐는데도 여전히 "어느 파일에 뭐가 있는지"를 눈으로 뒤지는 방식이었다. 검색 레이어가 없었던 것이다.

이참에 OpenViking Hybrid Retrieval을 활용하여 제대로 붙여보기로 했다.

🛠️ 사용한 도구

• 도구: Claude Code (이 채팅창), Hermes (Claude Code CLI 터미널)

• 모델: Claude Sonnet 4.6 (이 채팅창), Claude Haiku 4.5 (Hermes)

• OpenViking: v0.3.23

• 임베딩: Jina Embeddings v3 (클라우드 API, 무료 티어)

🔧 작업 과정

설치하다가 벽을 만났다 — CPU 호환성 문제

OpenViking 설치는 순조로웠다. 그런데 임베딩 모델(문장을 숫자로 변환하는 AI)을 고르는 화면에서 문제가 생겼다.

Embedding provider 선택 화면에서 어떤 걸 골라야 해?

로컬에 AI 모델을 설치하는 옵션을 선택했더니, 내 CPU가 해당 모델이 요구하는 AVX 명령어 집합을 지원하지 않는다는 오류가 났다. 설치가 아예 안 되는 것이었다.

Claude Code가 대안을 제시했다. Jina 클라우드 API를 쓰면 된다는 것이다. 로컬에 모델을 깔 필요 없이, Jina가 운영하는 서버에서 임베딩을 계산해서 돌려주는 방식이다. 무료 티어로 분당 100회 요청이 가능하고, 개인 wiki 65개 파일을 등록하는 데 충분했다.

방향을 바꾸어서 설치했다.

65개 파일을 등록하는 데 15분 걸렸다 — Rate Limit와의 싸움

wiki 파일들을 OpenViking에 등록하는 과정에서 429 오류가 계속 떴다. "분당 100회 요청 초과"라는 Rate Limit 오류였다.

기다리는 시간이 너무 오래 걸리는데?
아까 보낸 이미지 상태에서 변동없이 그대로인데?

멈춘 것처럼 보였지만 사실 OpenViking이 내부적으로 자동 재시도를 하고 있었다. 약 15분을 기다렸더니 65개 파일, 295개 벡터가 모두 등록 완료됐다. 그냥 기다리면 되는 문제였다.

3주차 과제 완료 — 검색하고, 읽고, 판단하다

과제 내용은 이랬다: "내 wiki에서 질문 하나를 골라 후보 검색 → 원문 확인 → Canonical Wiki(신뢰할 수 있는 출처인지) 판단".

선택한 질문은 "출처와 최신성은 어떻게 확인할 것인가?"였다. OpenViking의 의미 기반 검색(ov find)을 실행했더니 self-eval-harness.md가 유사도 0.396으로 1순위에 올라왔다. 원문을 직접 읽어보니 ontology.md의 verified 승격 조건과 정확히 일치했다.

Hit = Truth. 검색 결과가 실제 원문과 맞아떨어진 것을 확인하고 과제를 완료했다.

AI 에이전트가 검색 명령을 "이해"는 하되 "실행"은 안 했다

과제 완료 후, Hermes가 실제로 OpenViking 명령어를 쓰는지 테스트했다. "wiki 페이지 상태를 올리는 조건이 뭐야?"라고 물어봤는데, 답변은 나왔지만 OpenViking이 아니라 Hermes 자체 검색 도구를 쓴 것이었다.

저기서 ov find나 ov grep이 돌고 있다는 것을 어떻게 알 수 있어?

확인 방법을 물어봤더니, 터미널 화면에서 질문 바로 아래에 나오는 도구 실행 줄을 보면 된다고 했다. ov.exe grep ... 또는 ov.exe find ...가 보이면 OpenViking이 실행된 것이고, read, grep 같은 네이티브 도구만 보이면 OpenViking을 쓰지 않은 것이다.

더 근본적인 문제도 있었다. Hermes가 ov grep을 자기 자신의 TUI 명령으로 오해하고 있었다.

아, "ov grep"은 Hermes의 TUI 명령이군요. 현재 저는 CLI 세션에 있으므로 직접 실행할 수 없습니다.
대신 mcp_search_files로 동일하게 검색한 결과: ...

OpenViking은 Hermes 내부 명령이 아니라 별도로 설치된 외부 프로그램인데, Hermes가 자기 명령어인 줄 알고 실행을 거부한 것이었다.

해결 방법은 AGENTS.md(Hermes의 행동 규칙 파일)를 수정하는 것이었다. "ov는 외부 실행파일이다, Hermes 자체 명령이 아니다"라는 설명과 함께 WSL 환경에서의 전체 경로를 명시했다.

터미널 트레이스에서 실행을 눈으로 확인했다

수정 후 Hermes에게 다시 질문했다. 이번에는 터미널 화면 위쪽에 이런 줄이 나타났다:

'/mnt/c/Users/User/AppData/Local/Programs/Python/Python312/Scripts/ov.exe' read "viking://resources/wiki/_meta/ontology/ontology.md"  0.2s

OpenViking이 실제로 실행됐다. Hermes가 wiki 파일을 그냥 열어본 게 아니라, OpenViking을 통해 검색하고 원문을 읽어온 것이다. 도구 트레이스에서 직접 눈으로 확인하는 순간이었다.

✅ 결과 (After)

Before vs After

결과물

• OpenViking: 65개 파일, 295개 벡터 등록 완료

• GPters 3주차 과제 제출 완료

• Hermes가 ov.exe read로 원문을 직접 읽는 것 확인

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. CPU 오류가 나면 클라우드 API로 우회한다 — AVX 미지원 오류는 흔한 문제다. Jina Embeddings v3 무료 티어로 개인 wiki 규모는 충분히 커버된다

2. 멈춘 것처럼 보여도 기다린다 — Rate Limit 429 오류는 실패가 아니라 재시도 중이다. 15분이면 된다

3. 도구 트레이스를 본다 — AI가 뭘 실행하고 있는지는 화면 위쪽 트레이스에 다 나온다. "잘 되고 있나?" 싶을 때 트레이스를 먼저 확인하면 된다

이렇게 하면 안 돼요

1. AGENTS.md에 명령어만 쓰고 설명을 빠뜨리면 안 된다 — AI는 낯선 명령어를 자기 것으로 오해한다. "이건 외부 프로그램이다"라고 명시해야 한다

2. PowerShell로 설정 파일을 저장하면 안 된다 — BOM(바이트 순서 표시) 문제로 파싱 오류가 난다. Python으로 저장해야 한다

🌍 다른 업무에 적용한다면?

• 회사 내부 문서나 보고서 모음에 같은 방식을 적용하면, AI가 문서 전체를 뒤지지 않고 관련 부분만 정확히 찾아서 답변할 수 있다

• 노트 앱(Obsidian 등)과 연결하면 개인 지식 베이스에 의미 기반 검색을 붙일 수 있다

🚀 앞으로의 계획

wiki에 문서가 더 쌓일수록 OpenViking 검색이 어떻게 달라지는지 계속 써볼 예정이다. 지금은 65개 파일이지만, 100개 200개가 됐을 때 키워드 검색과 의미 기반 검색의 차이가 얼마나 벌어지는지가 궁금하다.

📋 재사용 가능한 프롬프트

프롬프트 1: OpenViking 설치 전 CPU 확인 요청

내 PC에서 OpenViking 로컬 임베딩 모델을 쓸 수 있는지 확인해줘. CPU가 AVX를 지원하지 않으면 Jina 클라우드 API로 대신 설정해줘.

프롬프트 2: AGENTS.md에 외부 도구 명령어 추가 요청

AGENTS.md의 Query 섹션에 [도구명] 검색 명령어를 추가해줘. [도구명]은 외부 실행파일이고 WSL에서 실행되며, 경로는 [전체 경로]야. Hermes가 자체 명령으로 오해하지 않도록 설명도 함께 써줘.

프롬프트 3: 검색 결과 원문 확인 요청

검색 결과 상위 3개의 원문을 직접 읽고, 내 질문 "[질문 내용]"에 실제로 답이 있는지 확인해줘. 검색 결과가 맞으면 Hit = Truth라고 표시하고, 틀리면 이유를 설명해줘.