altair823
e7b58017fd
도그푸딩(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>
67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
---
|
|
title: kebab v0.28.0 release notes (draft)
|
|
created: 2026-06-04
|
|
status: draft
|
|
release_trigger:
|
|
- 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 절차
|
|
|
|
1. 아무것도 안 해도 된다 — 옛 `config.toml` 은 그대로 로드된다(자동 변환,
|
|
디스크 미변경, 일회성 warn 으로 안내).
|
|
2. 파일을 새 레이아웃으로 정리하려면: `kebab config migrate` (자동 `.bak` 백업,
|
|
`--dry-run` 으로 미리보기). `kebab doctor` 가 갱신 필요 시 안내한다.
|
|
3. `kebab init` 으로 새로 만드는 config 는 v3 레이아웃 + per-option 주석 포함.
|
|
|
|
검색·RAG 결과와 색인은 변하지 않는다.
|