[hermes-agent] SQLite FTS5 최적화: CJK Bigram 인덱싱으로 검색 성능 개선하기

PR 링크: NousResearch/hermes-agent#69423 상태: Merged | 변경: +15960 / -11

들어가며

많은 한국어, 중국어, 일본어(CJK) 사용자들은 데이터베이스 검색 시 12글자 단어를 자주 사용합니다. 하지만 기존 SQLite FTS5의 unicode61 토크나이저는 CJK 텍스트를 하나의 토큰으로 처리하고, trigram 토크나이저는 3글자 이상의 단어만 지원합니다. 이로 인해 12글자 CJK 검색은 인덱스를 타지 못하고 LIKE를 이용한 전체 테이블 스캔(Full-table scan)으로 이어져, 수 기가바이트 규모의 DB에서 3~6초 이상의 지연을 발생시키는 병목이 되었습니다. 본 PR은 커스텀 FTS5 토크나이저를 도입하여 이를 해결합니다.

코드 분석

1. 커스텀 토크나이저 도입 (native/fts5_cjk/)

핵심은 cjk_unicode61이라는 로드 가능한 FTS5 토크나이저를 구현한 것입니다. 이는 unicode61을 래핑하여 CJK 텍스트를 중첩된 문자 Bigram으로 재구성합니다.

// CJK runs are re-emitted as overlapping character bigrams
// FTS5 phrase semantics turn a query term's consecutive bigrams 
// into exact substring matching down to 2 chars at index speed.

2. 스키마 통합 (hermes_state.py)

messages_fts_cjk라는 새로운 가상 테이블을 생성하여 기존 trigram 인덱스의 v23 외부 콘텐츠 레이아웃을 따르도록 설계했습니다. 특히, 인덱스 무결성을 위해 트리거를 정교하게 제어합니다.

# Before: LIKE full-table scans for 1-2 char CJK terms
# After: fts_cjk MATCH using custom tokenizer
CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts_cjk USING fts5(
    content,
    content='messages_fts_cjk_src',
    content_rowid='id',
    tokenize='cjk_unicode61'
);

3. 설정 브릿지 (cli.py, gateway/run.py)

사용자가 config.yaml을 통해 CJK FTS 기능을 제어할 수 있도록 환경 변수 브릿지를 추가했습니다.

# config.yaml의 설정을 내부 환경 변수로 전달
if "cjk_fts" in sessions_config:
    os.environ["HERMES_CJK_FTS"] = str(sessions_config["cjk_fts"])

왜 이게 좋은가

이 최적화의 핵심은 '인덱스 활용'입니다. 기존에는 1~2글자 검색 시 매번 전체 데이터를 스캔해야 했으나, Bigram 인덱싱을 통해 MATCH 연산으로 즉시 결과를 반환합니다.

• 성능 수치: 25GB 벤치마크 DB 기준, ASCII 검색(244ms)과 유사한 수준으로 CJK 검색 속도가 개선되었습니다. (기존 3.6s 대비)
• 교훈:
  1. 토크나이저의 중요성: 언어적 특성에 맞는 토크나이저 선택은 검색 성능의 핵심입니다.
  2. 점진적 마이그레이션: optimize-storage 명령을 통해 기존 DB를 점진적으로 업그레이드하고, 토크나이저가 없는 환경에서도 시스템이 깨지지 않도록 'Self-heal' 로직을 구현한 점이 매우 견고합니다.

리뷰어 피드백 반영

리뷰어들은 토크나이저 로드 실패 시의 무결성 문제를 지적했습니다. 이에 따라 load_fts5_cjk_extension 실패 시 트리거를 자동으로 제거하고 인덱스를 'stale' 상태로 표시하여, 데이터 손상 없이 시스템이 정상 작동하도록 보완되었습니다.

참고 자료

• https://www.sqlite.org/fts5.html
• https://www.sqlite.org/fts5.html#custom_tokenizers

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.