Files

altair823 e7b58017fd docs(config): v3 재편 도그푸딩 evidence + release notes

도그푸딩(release 빌드): 사용자 실제 v2 config 변환(값·주석 보존·멱등) +
재색인 0 실증(v2 자동변환·v3 디스크 양 경로 unchanged). v0.28.0 release notes
draft(변경/trade-off/mitigation/upgrade 4단락).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-04 13:12:01 +00:00

3.2 KiB

Raw Blame History

title, created, status, release_trigger

title

created

status

release_trigger

kebab v0.28.0 release notes (draft)

2026-06-04

draft

config 스키마 v2→v3 재편 (config 레이아웃 rename + 신규 env) — pre-1.0 minor bump

frozen 설계 변경 (2026-06-04-config-schema-reorg-design)

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 결과와 색인은 변하지 않는다.

3.2 KiB Raw Blame History