-
altair823 released this
2026-06-04 22:34:52 +00:00 | 0 commits to main since this releasekebab v0.28.0 — config 스키마 v2→v3: 미디어 ingest 통합
v0.27.0(PP-OCRv5 ONNX OCR) 후속 minor release.
config.toml에 흩어져
있던 미디어 형식 설정을[ingest.*]우산 하나로 모은다. 기존 사용자는
아무것도 손대지 않아도 된다 — 옛 v2 파일은 로드 시 메모리에서 자동 변환되고,
검색·색인 결과는 바이트 단위로 동일하다(재색인 0).
변경 사실
미디어 형식 설정이 top-level 에서
[ingest.*]하위로 이동했다.v2 (top-level) v3 ( [ingest.*])[indexing](스칼라)[ingest]스칼라 (max_parallel_extractors등)[chunking][ingest.chunking][image.ocr][ingest.image.ocr][image.caption][ingest.image.caption][pdf.ocr][ingest.pdf.ocr][ingest.code][ingest.code](변화 없음)부수적으로
[ingest.pdf.ocr]가 paddle-onnx 모델 경로 키(det_model/rec_model/
dict/score_thresh/unclip_ratio/max_boxes)를 PDF 자체적으로 가질 수 있게
됐다(v2 는 image.ocr 의 값을 빌려썼다). 신규 envKEBAB_PDF_OCR_*6키.Trade-off
비-additive rename 마이그레이션이라(첫 사례), 옛 섹션 이름을 그대로 두면
serde 가 모르는 키로 무시될 수 있다. 이를 피하려고 두 겹의 안전장치를 깔았다:
(1)Config::from_file이 load 시 메모리에서 v3 로 자동 변환 — 미변환 v2 파일도
설정 유실 0. (2)kebab config migrate가 디스크 파일을 새 레이아웃으로 갱신하되
값·주석·대안(commented) 줄을 전부 보존하고 멱등이다.env override 이름(예
KEBAB_CHUNKING_TARGET_TOKENS,
KEBAB_INDEXING_MAX_PARALLEL_EXTRACTORS)은 그대로 유지된다 — 대입 대상만
새 경로로 바뀌므로 기존KEBAB_*스크립트는 손댈 필요가 없다.Mitigation — 재색인 0 보장
ingest_config_signature는 값 기반이라 struct 경로가 바뀌어도 출력 문자열이
v2 와 바이트 동일하다. paddle 모델 경로는 미디어별(image/pdf)로 호출자가
넘기도록 인자화했고, 마이그레이션이 v2 의 image↔pdf paddle 비대칭을 값 복사로
보존한다. 도그푸딩(v0.28.0 release 빌드)에서 v2 config 로 first ingest 후
(a) 동일 v2 config 재ingest(자동변환), (b) v3 로config migrate후 재ingest
모두new=0 updated=0 unchanged=2— 업그레이드 시 재색인이 발생하지 않음을
실증했다.Upgrade 절차
- 아무것도 안 해도 된다 — 옛
config.toml은 그대로 로드된다(자동 변환,
디스크 미변경, 일회성 warn 으로 안내). - 파일을 새 레이아웃으로 정리하려면:
kebab config migrate(자동.bak백업,
--dry-run으로 미리보기).kebab doctor가 갱신 필요 시 안내한다. kebab init으로 새로 만드는 config 는 v3 레이아웃 + per-option 주석 포함.
검색·RAG 결과와 색인은 변하지 않는다.
Downloads
- 아무것도 안 해도 된다 — 옛
-
2026-06-03 14:35:20 +00:00 | 22 commits to main since this releasev0.26.2 — ingest 설정 변경 시 영향 자산 자동 재색인
지금까지 증분 ingest 의 "변경 안 됨(skip)" 판정은 파일 내용 + parser/chunker/embedding 버전만 봤습니다. 그래서
config.toml에서 색인 결과를 바꾸는 설정(이미지 OCR/caption, 청킹 파라미터, PDF OCR, 코드 ingest 옵션)을 바꾼 뒤 다시kebab ingest해도, 파일 자체는 그대로니 자산이 그냥 건너뛰어졌습니다 — 바뀐 설정이 반영되지 않았죠. 이번 patch 가 그 갭을 일반화해 고칩니다.무엇이 바뀌나. 자산 타입별로 "그 자산의 색인 결과에 영향을 주는 설정"의 결정적 서명을 계산해 skip 판정에 포함시킵니다. 이제 해당 설정을 바꾸면
--force-reingest없이도 영향 받는 자산만 자동으로 다시 색인됩니다:[chunking](target_tokens/overlap_tokens/respect_markdown_headings/chunker_version) → 모든 자산 재색인[image.ocr]·[image.caption]→ 이미지만[pdf.ocr]→ PDF만[ingest.code]→ 코드 파일만
무엇은 안 바뀌나(중요). 색인 산출물과 무관한 설정 —
[search]/[rag]/[models.nli]/[ui]/[logging]/ 저장 경로, 그리고max_pixels/languages/*_timeout_secs같은 런타임 파라미터 — 는 바꿔도 재색인을 유발하지 않습니다(불필요한 전체 재색인 회피). 동일한 설정으로 다시 ingest 하면 종전처럼 전부 skip 됩니다.업그레이드 시 1회 재색인. 이 버전으로 올린 뒤 첫
kebab ingest에서는 기존 자산이 현재 설정대로 한 번 재색인됩니다(저장돼 있던 옛 parser_version 이 새 서명과 달라서). 임베딩은 내용 해시 기반 파생물 캐시(V012)가 그대로라 캐시 히트로 저렴하고, 그 1회 이후로는 설정을 바꾸지 않는 한 다시 skip 됩니다.--force-reingest는 전체 강제 재색인용으로 그대로 유지됩니다.호환성. CLI·config 키·wire schema·검색 결과 포맷에는 변화가 없습니다(내부 skip 판정만 정정) — 그래서 patch 릴리스입니다. 검증: clippy 0, 관련 크레이트 테스트 67 그룹 0 실패(토글/skip/제외 e2e 포함). 상세:
tasks/HOTFIXES.md2026-06-03 entry.Downloads
-
v0.26.1 — ingest 진행 로그 개선 Stable
2026-06-03 11:07:20 +00:00 | 27 commits to main since this releasev0.26.1 — ingest 진행 로그 개선
OCR/caption 이 켜진 볼트(이미지·PDF 혼재)를 색인할 때, 진행바가 멈춘 것처럼 보이는데 무엇 때문에 느린지 알 수 없던 문제를 해결합니다. 검색·색인 결과나 명령/설정은 전혀 바뀌지 않는 관측성(observability) 개선이라 patch 릴리스입니다(기본 동작 불변).
무엇이 보이게 되었나.
- 현재 파일명 — 진행바에 지금 처리 중인 파일이 표시됩니다 (
ingest [===>] 142/997 · vault/foo.png). - 느린 phase + 모델 — 이미지 OCR·caption·임베딩이 도는 동안 그 사실과 사용 모델이 실시간으로 보입니다 (
· OCR(gemma4:e4b)…). 이전엔 이미지 OCR/caption 에 진행 이벤트가 없어 "정지"처럼 보였습니다. - 경과시간 heartbeat — 한 파일이 오래 걸려도
(45s)처럼 경과초가 이벤트 사이에도 계속 갱신되어, 멈춘 게 아니라 무거운 작업 중임이 드러납니다. - 종료 요약 — 끝에 가장 오래 걸린 파일 top-5 가 출력되어 병목 파일을 사후에 바로 파악할 수 있습니다.
Trade-off / 호환성. 사람용 진행바(stderr) 표시만 풍부해졌고,
--json출력에는 additive wire 이벤트가 더해졌습니다 — 신규asset_phase(ingest_progress.v1) +asset_timings의ocr_ms/caption_ms필드. 모두 backward-compat(기존 소비자는 새 필드를 무시하면 그만)이라 wire major bump 없이 v1 유지. 미디어가 없는 텍스트 위주 ingest 의 표시·성능에는 변화가 없습니다.검증. clippy 0, kebab-app/cli 61 그룹·parse-image/tui 14 그룹 테스트 0 failed. 상세:
tasks/HOTFIXES.md2026-06-03 entry.참고: 색인이 느린 근본 원인이 미디어 OCR/caption 인 경우, 텍스트 위주 볼트라면
[image.ocr]/[image.caption]/[pdf.ocr]를enabled = false로 두면 크게 빨라집니다(이 릴리스의 로그가 그 판단을 돕습니다).Downloads
- 현재 파일명 — 진행바에 지금 처리 중인 파일이 표시됩니다 (
-
2026-06-03 07:20:27 +00:00 | 33 commits to main since this releasev0.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_versioncascade) 기존 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
- 상세 측정·방법 비교(리랭크 / query-side expansion / heading enrichment / bge-m3 등 대안 포함):
-
2026-06-02 17:46:47 +00:00 | 53 commits to main since this releasev0.24.0 — 상세 ingest 진행 로깅 (asset 내부 phase 가시화)
변경 사실
ingest 진행 표시가 asset(문서) 단위뿐이라, 한 문서 내부의 parse / chunk / expansion(별칭 LLM, 청크당 순차 호출) / embed / store 가 보이지 않았다. 큰 문서 하나가 expansion 으로 수십 분 걸려도 진행바가
1/N에 멈춘 듯 보여 병목을 찾기 어려웠다. 이번 릴리스는 asset 내부 phase 를 노출한다.추가된 것 (wire
ingest_progress.v1additive — 기존 consumer 호환)asset_chunked { idx, total, chunks }— 청킹 직후 즉시 "이 문서가 N청크" 표시 (큰 첫 문서가 멈춘 게 아님을 바로 확인).expansion_progress { idx, total, done, chunks }— 별칭 확장 중 라이브 카운터 (스로틀: 25청크 또는 1s).asset_timings { idx, total, parse_ms, chunk_ms, expansion_ms, embed_ms, store_ms }— 문서 종료 시 phase 별 소요시간 (markdown 경로).
사용자 체감
- 사람용 출력:
→ N chunks,별칭 확장 450/1843(라이브), 종료 시⏱ parse 3ms · chunk 673ms · expand 1980s · embed 12s · store 33ms. → 어느 phase 가 병목인지(expansion vs embed) 한눈에. --json: 새 이벤트가 line-delimited 로 흐름.--quiet억제.
호환 / 한계
- wire v1 backward-compat (신규
kind만 추가, 기존 필드 무변경). 동작/벡터/schema 메이저 변경 없음. - image/pdf 경로는 phase timing 없음(
asset_chunked만).expansion_progress비-TTY human 은 기본 억제(--json은 전량). store_ms= SQLite persist 전용,embed_ms= 임베딩 + 벡터 upsert + stale-vector purge (정확한 귀속).
Downloads
-
2026-06-02 12:26:10 +00:00 | 58 commits to main since this releasev0.23.1 — ingest 백엔드 표시 + KB 이전 문서
변경
kebab ingest시작 시 활성 임베딩 백엔드·모델·차원을 한 줄로 표시한다 (예:
임베딩 백엔드: candle (Metal/GPU 빌드) · 모델 multilingual-e5-large (1024-dim)).
--json/--quiet에선 출력하지 않는다. Metal 표기는embed_metal빌드 여부
기준이며, 확정된 런타임 디바이스는 kb.log 의candle device = …라인에 남는다.- README: "외부 계산 + 로컬 검색" 절에 어떤 파일을 옮기나(
kebab.sqlite,
lancedb/)와 어느 config 키([storage].sqlite/vector_dir, 베이스
data_dir)인지,models/·assets/는 복사 불필요, 동일 버전·모델 조건, rsync
예시를 추가.
동작·wire·schema·벡터 변경 없음 (CLI 출력 + 문서만).
Downloads
-
2026-06-02 11:42:22 +00:00 | 59 commits to main since this releasev0.23.0 — candle Metal (Apple Silicon GPU) 임베딩 가속 (opt-in)
변경 사실
v0.22.0 의 candle provider 는 NUMA 서버의 onnxruntime 크래시를 해결했지만, candle CPU 임베딩은 e5-large/512-tok 에서
1.51.9 s/chunk 로 느렸다(코어를 더 줘도 빨라지지 않음 — 병목은 커널 효율). 본 릴리스는 Apple Silicon 맥에서 candle 을 GPU(Metal)로 돌리는 opt-in build featureembed_metal을 추가한다.trade-off / 적용 대상
metalfeature 는 macOS 전용 컴파일. Linux/서버는 기존 CPU 빌드 그대로(default 동작·벡터 불변).- GPU 산출 벡터는 CPU candle 과 동일 모델이라 호환(패리티 2.01e-7). 따라서 맥에서 GPU 로 색인한 KB 를 그대로 Linux 서버에서 CPU candle 로 질의할 수 있다.
권장 워크플로 (대용량 코퍼스 + NUMA 서버)
- M-시리즈 맥에서 GPU 색인:
cargo install --path crates/kebab-cli --features embed_metal --locked # config: provider="candle", model="multilingual-e5-large", dimensions=1024 kebab ingest --config <config.toml> # 로그에 "candle device = Metal (GPU)" - 데이터만 서버로 복사:
kebab.sqlite+lancedb/를 서버 data_dir 로 (models/불필요). KB 는 이식 가능 —workspace_path상대경로 +chunks.text저장이라 검색에 원본 파일도 불필요. - 서버는 CPU candle 로 질의:
provider="candle". onnxruntime 미사용 → NUMA double-free 없음.
빌드 / 설치
# 빌드만 (macOS): cargo build --release --features embed_metal # 전역 설치: cargo install --path crates/kebab-cli --features embed_metal --locked상세는
tasks/HOTFIXES.md2026-06-02 항목 및 README "Apple Silicon GPU 가속" 참조.Downloads
-
2026-06-02 10:20:07 +00:00 | 62 commits to main since this releasetitle, created, status, release_trigger
title created status release_trigger kebab v0.22.0 release notes (draft) 2026-06-01 draft 신규 config surface (provider=candle, num_threads / KEBAB_EMBED_THREADS) — pre-1.0 minor bump 임베딩 백엔드 다변화 (NUMA-안전 candle provider 추가, opt-in) kebab v0.22.0 — candle 임베딩 provider (NUMA-안전, opt-in)
v0.21.1 (config 마이그레이션) 후속 minor release. 듀얼소켓 NUMA 서버에서
onnxruntime 의 스레드 하드코딩이 일으키던 ingest 크래시를 피하기 위해, 같은
임베딩 모델을 순수 Rust(candle) 로 돌리는 opt-in provider 를 추가한다.
기본 동작은 그대로다 — 기존 사용자는 아무것도 바꿀 필요가 없다.
핵심 변경
candle 임베딩 provider (
provider = "candle")변경 사실.
[models.embedding].provider에"candle"값이 추가됐다.
"fastembed"(기본, onnxruntime) /"candle"(순수 Rust) /"none"(lexical-only)
중 하나를 고를 수 있다. candle provider 는 fastembed 와 완전히 같은 모델
(intfloat/multilingual-e5-large, 1024-dim)을 쓰고, e5 prefix → mean pooling
→ L2 정규화 파이프라인도 동일하다. 첫 사용 시 safetensors(~2GB)를
{model_dir}/candle/아래로 자동 다운로드한다.[models.embedding] provider = "candle" # 기본은 "fastembed" — NUMA 서버에서만 candle 권장 num_threads = 8 # candle CPU 스레드 캡 (0 = auto = #cores)# env 로도 캡 가능 (config 보다 우선) KEBAB_EMBED_THREADS=8 kebab ingestTrade-off. candle 는 순수 Rust 라 onnxruntime 의 네이티브 SIMD 커널보다
CPU latency 가 느리다 (Phase 0 스파이크 측정 ~4×). 그래서 기본값은
fastembed 를 유지하고, candle 은 onnxruntime 가 죽는 NUMA 환경에서만 켜는
opt-in 으로 둔다. 단일 워크스테이션 사용자는 fastembed 가 더 빠르다.Mitigation (왜 안전한가). candle 의 CPU 백엔드는 글로벌 rayon 풀 크기로
스레드를 정한다.num_threads(또는 envKEBAB_EMBED_THREADS)가 그 풀을 한 번
캡하므로, onnxruntime 가 하드코딩하던 48 intra-op 스레드 → NUMA 힙 손상 →
double-free 경로를 원천 차단한다. NUMA 노드 바인딩이 더 필요하면numactl
과 조합한다.Upgrade 절차. 재색인 불필요. candle 과 fastembed 의 벡터는 사실상
동일(Phase 0 스파이크 코사인 1.000000)해서embedding_version을 유지했고,
기존 LanceDB 색인을 그대로 재사용한다. provider 를 바꿔도 검색 결과는
바뀌지 않는다. 기존config.toml은num_threads가 자동으로0(auto)으로
채워져 그대로 로드된다 —kebab config migrate도, 수동 편집도 필요 없다.
그 외
- 신규 crate
kebab-embed-candle(candle 의존성 트리를 이 crate 에 격리,
kebab-core/kebab-config외 다른 kebab-* 의존 없음). - Phase 0 feasibility 스파이크(
spike-embed-candle)는 production 흡수 후 제거. - 문서: README Configuration,
docs/SMOKE.mdconfig 예시,docs/ARCHITECTURE.md
crate 그래프/트리에 candle provider 반영.
검증 / 도그푸딩
- 패리티 (candle vs onnxruntime): 동일 e5-large 가중치로 cosine_min =
1.000000, 차원별 max 절대오차 = 2.01e-7. 벡터가 사실상 동일 →
embedding_version유지(재색인 0). 재현:crates/kebab-embed-candle/tests/parity.rs
(--ignored). - 전체 도그푸딩 (2026-06-02):
provider=candle로 도그푸딩 코퍼스 전체
재색인 — 997 docs / 23,151 chunks, 에러 0 완주 (≈9.5 h, 단일소켓 VM).
candle 가 23k+ 청크를 메모리 오류 없이 처리함을 확인. - A1(taskset/numactl) 반증: NUMA 서버에서
taskset -c 0-3으로 스레드를
4개로 묶어도 onnxruntime 은 그대로 죽었다(6/5150 segfault). 스레드 축소는
해법이 아니며,provider=candle만이 실 해법이다 (candle 은 onnxruntime 을
호출하지 않음). - 최종 인수 게이트 (사용자): 그 듀얼소켓 NUMA 서버에서
provider=candle로
ingest 가 EXIT=0 완주 — 배포·실사용이 이 검증을 겸한다.
성능 노트 (중요)
candle CPU 임베딩은 onnxruntime 대비 약 3~4× 느리다 (e5-large/512-tok 의
순수-Rust 커널 비용). 측정상 ~1.86 s/chunk, CPU 약 4코어 활용. 이는 의도된
트레이드오프 — onnxruntime 이 전 코어를 AVX-512 로 빡빡하게 굴리는 바로 그
경로가 NUMA 에서 힙을 손상시켜 죽기 때문이다. "느려도 완주" > "빨라도 크래시".- Intel MKL 가속을 실험했으나 부정 결과: MKL 은 코어를 더 쓰지만(8
9코어)50% 느렸다(과다구독 + MKL 2020.1 오버헤드). 채택하지 않음.
오히려 38 - 더 많은 코어/스레드로는 빨라지지 않는다(병목이 코어 수가 아님). 속도가
critical 하면 청크 길이 단축 / 더 작은 모델 / GPU 가 레버다(별도 검토). - 9.5 h 는 최초 전체 색인 1회 비용이며, 이후 증분 ingest 는 새/변경 문서만
처리해 저렴하다. 단일 워크스테이션(비-NUMA)에서는 기본fastembed가 더 빠르니
candle 은 NUMA 호스트 전용 opt-in 으로 둔다.
Downloads
- 신규 crate
-
v0.21.1 — config 마이그레이션 Stable
2026-05-31 13:58:08 +00:00 | 70 commits to main since this releaseconfig 마이그레이션 —
kebab config migrate(PR #198)config.toml 의 스키마가 버전을 거치며 늘어나도(예: v0.21.0 의
[ingest.expansion]), 기존 사용자의 config 파일은 그 새 섹션이 파일에 써지지 않아 파일을 열어봐도 새 노브의 존재를 알 수 없었습니다. 동작은serde기본값으로 호환됐지만, 사용자가 설정을 발견·조정할 길이 없던 셈입니다. DB 는 V00X refinery 마이그레이션이 있는데 config 에는 그런 메커니즘이 없었습니다 — 이번 릴리스가 이를 채웁니다.새 명령
kebab config migrate [--dry-run] [--json]- 기존
config.toml에서 빠진 섹션·키를 설명 주석과 함께 채워 넣습니다. 사용자가 직접 손본 값·주석·항목 순서는 그대로 보존합니다(없는 것만 추가). - 더 이상 쓰지 않는 항목(예:
workspace.include)은 정리합니다. - 멱등합니다 — 한 번 적용한 뒤 다시 실행하면
config 이미 최신입니다만 출력하고 파일을 건드리지 않습니다. - 변경 시 자동으로
<config>.bak백업을 만들고(원본과 바이트 동일), 임시 파일에 먼저 쓴 뒤 재파싱 검증에 성공해야 교체하므로 실패해도 원본이 보존됩니다. --dry-run으로 무엇이 바뀔지 미리 확인할 수 있고(파일 미수정),--json은config_migration.v1wire 스키마로 출력합니다.
함께 바뀐 것
kebab doctor에config_migration점검이 추가됐습니다. config 가 옛 스키마면ok=false로 표시하고kebab config migrate실행을 안내합니다(정상 동작하더라도 "정리할 게 있다"는 신호).kebab init이 생성하는 config.toml 이 이제 섹션별 설명 주석을 포함합니다(마이그레이션과 동일한 주석 원천을 공유).config.toml의schema_version이 그동안 장식이었으나, 이제 마이그레이션의 버전 축이자 동기화 마커로 의미를 갖고 기본값이1 → 2로 올라갑니다.
업그레이드 절차
기존 사용자는 한 번만 실행하면 됩니다:
kebab config migrate --dry-run # 무엇이 추가/정리될지 미리보기 kebab config migrate # 적용 (.bak 자동 백업)schema_version1→2 변경은 additive 입니다 — 데이터를 무효화하지 않고 읽기 호환도 유지되므로(옛 바이너리로 새 파일을, 새 바이너리로 옛 파일을 읽어도 동작), 재색인(reingest)은 필요 없습니다.검증
크레이트 테스트 +
clippy --workspace -D warnings+cargo test --workspace -j1(192 ok / 0 fail) + release 바이너리 도그푸딩(dry-run 미수정 /.bak바이트 동일 / 값·주석 보존 / deprecated 제거 / 새 섹션 가시화 / 멱등 / doctor /--json) 전부 통과. 상세는tasks/HOTFIXES.md2026-05-31 entry.Downloads
- 기존
-
2026-05-31 10:45:21 +00:00 | 82 commits to main since this release이번 릴리스는 검색 품질을 높이는 doc-side expansion(별칭), 비싼 색인 계산을 재사용하는 파생물 캐시(V012), 그리고 외부 서버에서 색인하고 로컬에서 검색하는 워크플로를 추가합니다.
1. doc-side expansion — 별칭 색인 (opt-in)
무엇이 바뀌나 색인 시 LLM이 각 청크에 "같은 의미의 다른 표현"(동의어·약어·한↔영 번역·풀어쓴 설명)을 별칭으로 생성해, 줄별 개별 dense 벡터로 색인합니다. 검색 시 별칭이 원본 문서로 매핑돼, 설명형 질문이나 영어↔한국어 cross-lingual 질문의 검색 일관성을 높입니다.
측정 나무위키 ~1000개 CS 문서(유사 주제 밀집) corpus에서 변형 일관성 14/18 → 16/18, 출렁임(spread@10) 0.222 → 0.111. 대조군(정답 없는 질문)에서 false-positive를 유발하지 않음을 확인했습니다.
트레이드오프 / 활성 청크당 LLM 호출이라 비용이 큽니다 → 기본 off.
config.toml에[ingest.expansion] enabled = true+embed_aliases = true로 켭니다. 켜지 않으면 기존 동작과 완전히 동일합니다.2. 파생물 캐시 (V012) — 재색인 145배
무엇이 바뀌나 embedding 벡터와 별칭 LLM 결과를 청크 내용 해시로 캐싱합니다(
derivation_cache테이블). 재색인이나 문서 갱신 시 내용이 같은 청크는 재계산을 건너뜁니다. 문서 중간에 내용을 추가해 청크 위치가 밀려도, 내용이 같은 청크는 캐시 히트라 비싼 임베딩·LLM 계산을 다시 하지 않습니다(DB row만 재기록, 계산은 변경분만).측정 정답 18문서 별칭 재색인 기준 cold 1879초(31분) → warm 13초 (≈145배).
안전성 캐시 키에 모델·프롬프트·차원 버전이 포함돼, 모델/프롬프트를 바꾸면 자동으로 캐시가 무효화됩니다(잘못된 옛 벡터 재사용 없음). 별도 설정 없이 투명하게 동작합니다.
알려진 제약 현재 캐시 자동 정리(TTL/LRU)는 미연결이라 캐시가 누적됩니다. 정리는
kebab reset으로만 가능합니다(후속 작업 예정).3. 외부 계산 + 로컬 검색 워크플로
kebab search/kebab ask는 asset 원본 파일 없이kebab.sqlite+lancedb만으로 동작합니다. 비싼 색인(임베딩·OCR·별칭 생성)을 성능 좋은 서버에서 수행한 뒤 이 두 산출물만 로컬로 복사하면 그대로 검색·질문할 수 있습니다. 캐시도 내용 해시 기반이라 머신 독립적으로 재사용됩니다.⚠️ 업그레이드 (중요)
V012 schema migration이 포함돼 이전 버전 binary로는 v0.21.0 데이터베이스를 열 수 없습니다(마이그레이션 mismatch). binary를 v0.21.0으로 교체하세요:
git pull && cargo install --path crates/kebab-cli --locked --force기존 색인 데이터의 재색인은 불필요합니다 — 본문 청크의 chunk_id와 벡터는 변하지 않았고(V012는 캐시 테이블 추가일 뿐 기존 데이터를 건드리지 않음), 새 binary 첫 실행 시 V012가 자동 적용됩니다.
상세 측정·설계 기록:
docs/superpowers/handoffs/2026-05-31-namu-wiki-alias-cache-study.mdDownloads