altair823-org/kebab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

40 Releases 40 Tags

RSS Feed
  • v0.26.0 8dee610a97
    Compare

    v0.26.0 — arctic-embed 임베더 + 별칭 제거 Stable

    altair823 released this 2026-06-03 07:20:27 +00:00 | 33 commits to main since this release

    v0.26.0 — arctic-embed 임베더 + doc-side expansion(별칭) 제거

    v0.24.0 이후 두 개의 큰 변화가 쌓였습니다. 검색 임베더를 더 강한 모델로 교체할 수 있게 되었고(설명형/풀어쓴 질의의 검색 품질이 크게 올라갑니다), 그 과정에서 유지보수 부담만 크고 효과는 미미했던 별칭(doc-side expansion) 기능을 제거했습니다. 두 변화 모두 측정(나무위키 ~1000 문서, 132개 변형 질의 골든)으로 근거를 잡았습니다.

    1. 새 임베더: arctic-embed-l-v2.0 (provider candle / ollama) — opt-in

    무엇이 바뀌나. [models.embedding] 에서 기본 multilingual-e5-large 대신 Snowflake arctic-embed-l-v2.0 임베더를 선택할 수 있습니다. 측정에서 같은 골든의 recall@10 이 e5 123/132 → arctic 130/132 (+7), recall@50 은 132/132(완벽) 으로 올랐고, 결정적으로 용어·약어·영어·동의어 질의는 손실 없이(72/72 유지) 설명형/풀어쓴 질의만 끌어올렸습니다(예: "마지막에 넣은 것을 먼저 꺼내는 자료구조" → 스택 문서). 두 백엔드를 제공합니다:

    # (A) candle — 순수 Rust, in-process (NUMA 안전, macOS Metal GPU 가능)
[models.embedding]
provider = "candle"
model    = "snowflake-arctic-embed-l-v2.0"   # CLS pooling, query 에 "query: " 접두어
dimensions = 1024

# (B) ollama — 로컬/원격 Ollama 데몬에 위임 (POST /api/embed)
[models.embedding]
provider = "ollama"
model    = "snowflake-arctic-embed2"          # ollama pull 필요
dimensions = 1024
endpoint = "http://127.0.0.1:11434"           # 생략 시 [models.llm].endpoint 로 폴백

    Trade-off. arctic 으로 바꾸면 임베딩 벡터 공간이 달라지므로(embedding_version cascade) 기존 e5 KB 와 혼용할 수 없습니다 — 전환하려면 한 번 재색인이 필요합니다. 별칭과 달리 이 비용은 색인 1회뿐이고, per-query 추가 비용도 LLM 호출도 없어 살아있는(계속 갱신되는) KB 에 지속 가능합니다.

    Mitigation / 검증. 기본값은 그대로 e5-large 이므로 아무것도 안 바꾸면 동작·벡터가 100% 동일합니다(arctic 은 완전 opt-in). candle 백엔드의 정확성은 측정에 쓴 Ollama 경로와 코사인 0.999984 일치로 검증했고(같은 pooling/prefix), v0.26.0 실제 바이너리로 namu 를 재색인해 recall@10 130/132 를 종단 재현했습니다. 새 크레이트 kebab-embed-ollama 가 추가됐습니다.

    Upgrade 절차. (1) ollama pull snowflake-arctic-embed2(ollama 경로) 또는 candle 경로는 첫 색인 시 safetensors(~2GB) 자동 다운로드. (2) 위 config 로 변경 + dimensions = 1024. (3) kebab reset 후 재 ingest. macOS 는 cargo install --path crates/kebab-cli --features embed_metal --locked 로 candle GPU 가속.

    2. doc-side expansion(별칭) 기능 제거

    무엇이 바뀌나. 청크마다 LLM 을 호출해 "검색용 별칭"을 생성하던 기능([ingest.expansion])을 완전히 제거했습니다. 측정 결과 이 기능의 실효는 설명형 질의 +2 그룹뿐인데, 그 대가가 색인할 때마다 청크당 LLM 호출(나무위키 18문서 cold 2.5시간)이라 계속 갱신되는 KB 에서는 지속 불가능했습니다. 별칭이 노렸던 한↔영 교차언어 recall 은 임베더 단독으로 이미 충분했고, 남은 설명형 약점은 위 arctic 교체가 더 깔끔하게 해결합니다.

    Trade-off / 영향. 별칭은 이미 기본 비활성(default-off)이었으므로 일반 사용자 체감은 0 입니다. config.toml 에 [ingest.expansion] 섹션이 남아 있어도 무시되며(forward-compat), 신규 마이그레이션 V013 이 사용되지 않던 chunk_aliases_fts 테이블과 chunks.aliases 컬럼을 정리합니다. wire 의 ingest_progress.v1 에서 expansion_progress 이벤트가 빠졌습니다(추가 직후라 호환 영향 없음).

    기타

    • 상세 측정·방법 비교(리랭크 / query-side expansion / heading enrichment / bge-m3 등 대안 포함): tasks/HOTFIXES.md(2026-06-03 두 entry) + 연구 문서 docs/superpowers/research/2026-06-03-expansion-cost-rethink-research.md.
    • 잔존 설명형 약점 2개(추상적 정의 질의)는 후속 query-side 보강 후보로 남겨둠.
    • 문서 동기화: README Configuration, docs/SMOKE.md, docs/ARCHITECTURE.
    Downloads