본문으로 건너뛰기

Build Logs · EP 03

한글 전문검색의 함정 — FTS5에서 조사(助詞)와 싸우고 Tantivy로 이주하기

"검색"을 쳤는데 "검색을"은 안 나온다. SQLite FTS5로 한글 검색을 만들다 만난 조사의 벽, trigram 우회, 그리고 Tantivy + 형태소 분석기로 넘어가기까지의 기술 선택을 정리했습니다.

· 3분 읽기

한글 전문검색의 함정 — FTS5에서 조사(助詞)와 싸우고 Tantivy로 이주하기

에이전트 세션 히스토리를 전문검색하는 기능을 만들면서, 한국어 개발자라면 누구나 한 번은 만나는 벽에 정면으로 부딪혔다. 이 글은 그 벽의 정체와, 상황별로 내린 두 가지 다른 기술 선택의 기록이다.

결론부터: 같은 “한글 검색” 문제라도 콘텐츠 성격에 따라 정답이 다르다. 세션 로그(영어·코드 혼합)에는 SQLite FTS5로 충분했고, 한글 노트 앱에는 Tantivy + 형태소 분석이 필요했다.

증상 — “검색”을 쳤는데 “검색을”이 안 나온다

SQLite FTS5로 전문검색 테이블을 만들고 한글 데이터를 넣었다.

CREATE VIRTUAL TABLE sessions_fts USING fts5(title, body);

-- 저장: "권한 릴레이 설계를 다시 생각하자"
-- 검색: SELECT * FROM sessions_fts WHERE sessions_fts MATCH '생각';
-- 결과: 0행

“생각하자”가 저장돼 있는데 “생각”으로 검색하면 안 나온다. 반대로 “생각하자”를 통째로 쳐야만 매칭된다.

원인 — 토크나이저는 형태소를 모른다

FTS5의 기본 토크나이저(unicode61)는 공백과 문장부호 기준으로 문자열을 자른다. 영어는 이 규칙 천국이다. 단어가 띄어쓰기로 분리되어 있으니, 잘리는 단위 = 검색되는 단위가 일치한다.

한글은 다르다. 교착어라서 단어에 조사가 붙는다.

저장된 토큰:  ["권한", "릴레이", "설계를", "다시", "생각하자"]
검색어 토큰:  ["생각"]
→ "생각" ≠ "생각하자" → 매칭 실패

영어의 “searching”을 “search”로 못 찾는 것과 같은 어형 변화 문제인데, 한글은 조사가 붙는 모든 명사에서 이 문제가 발생한다. 한글 문서에서 명사는 거의 항상 조사와 함께 등장하므로, 사실상 모든 검색이 운에 좌우된다.

우회로 1 — trigram: 정확도를 조금 팔아 리콜을 산다

FTS5에는 trigram 토크나이저가 있다. 3글자 단위로 잘라 부분 문자열 매칭을 가능하게 하는 방식.

CREATE VIRTUAL TABLE sessions_fts USING fts5(
  title, body,
  tokenize = 'trigram'
);
-- "생각하자"에 "생각"이 매칭된다 (3글자 이상부터)

장단점이 분명하다.

  • ✅ 의존성 없이 한 줄로 리콜(재현율)이 확 오른다
  • ❌ 1~2글자 검색 불가, 인덱스 크기 증가, “이것” 같은 조사 자체도 색인돼 노이즈

세션 로그에는 이 정도가 적당했다. 내용이 영어와 코드 식별자 중심이고, 한글은 보조적이며, 데몬 의존성을 Rust 크레이트 하나로 유지하고 싶었다. trigram으로 90%의 만족을 얻었다.

우회로 2 — Tantivy + 형태소 분석: 한글이 주 콘텐츠라면

문제는 로컬 노트 앱이었다. 콘텐츠의 100%가 한글. 노트 제목이 “배포 롤백 절차를 정리하자”면, 사용자는 “롤백”이나 “절차”로 검색한다. trigram의 노이즈와 2글자 제한이 실사용을 막았다.

그래서 이 프로젝트는 아예 검색 엔진을 바꿨다. Rust 진영의 Lucene이라 불리는 Tantivy에 한글 형태소 분석기를 결합했다.

let schema = ...;
let index = Index::create_in_dir(index_path, schema)?;

// 한글 형태소 분석기 토크나이저 등록
index.tokenizers()
  .register("korean", KoreanTokenizer::default());

// "롤백 절차를" → ["롤백", "절차"] 로 색인 → "롤백" 검색 성공

형태소 분석기는 “절차를”을 어간 “절차” + 조사 “를”로 분해해 준다. 색인 시점과 검색 시점 모두 분해하면, 어형 변화 문제가 원천에서 사라진다. Tantivy를 고른 이유:

  • Lucene급 검색 품질 — BM25 스코어링, 필드 가중치
  • 로컬 퍼스트 친화 — 임베디드, 파일 기반 인덱스. 데스크톱 앱(Tauri)에 딱
  • Rust 네이티브 — 백엔드와 하나의 바이너리로

의사결정 정리 — 무엇을 골라야 하나

상황추천이유
영어/코드 중심, 가벼운 로그 검색FTS5 (trigram)의존성 최소, 리콜 충분
한글 위주 콘텐츠, 노트/문서Tantivy + 형태소 분석기어형 변화 문제의 근본 해결
서비스 검색(운영 부담 감수)전문 검색 엔진(Elasticsearch류)운영 비용이 있어도 될 때

내 경우 두 프로젝트에서 두 답을 다 썼고, 둘 다 만족한다. “한글 검색”이라는 같은 문제에 상황별로 다른 정답 — 이게 이 글의 요지다.

마치며 — 토크나이저는 검색의 설계도

검색 품질의 80%는 모델링이나 랭킹이 아니라 토크나이저가 결정한다. 무엇을 하나의 단위로 볼지 — 이 결정이 색인과 검색 전체의 운명을 정한다.

한글을 다루는 개발자라면 “내 데이터는 어떻게 잘리는가”부터 확인하길 권한다. SELECT token FROM tokenize_table 한 번 떠보는 것으로, 이 글의 벽에 부딪히기 전에 설계를 고칠 수 있다.

Related

· 8 min read

Tauri 2.0 vs Electron 완벽 비교: 아키텍처부터 선택 기준까지

Tauri 2.0은 시스템 WebView와 Rust 코어를 조합해 Chromium 번들을 들고 다니지 않는 데스크톱 앱을 만드는 프레임워크입니다. Electron과의 아키텍처 차이, 리소스 사용량의 실상, 2.0의 모바일(iOS/Android) 지원과 capability 기반 보안 모델, 기존 Node.js 자산의 이관 난이도를 비교합니다. 프로젝트 상황별 판단을 돕는 선택 기준 체크리스트로 마무리하는 실전 비교 가이드입니다.

Rust프론트엔드
→