v0.28.0 403e162ac0

kebab v0.28.0 — config 스키마 v2→v3: 미디어 ingest 통합 Stable

altair823 released this 2026-06-04 22:34:52 +00:00 | 0 commits to main since this release

kebab 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 의 값을 빌려썼다). 신규 env KEBAB_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

40 Releases 40 Tags