From e7b58017fd5815748af86c2b5268a1941b09a96c Mon Sep 17 00:00:00 2001 From: altair823 Date: Thu, 4 Jun 2026 13:12:01 +0000 Subject: [PATCH] =?UTF-8?q?docs(config):=20v3=20=EC=9E=AC=ED=8E=B8=20?= =?UTF-8?q?=EB=8F=84=EA=B7=B8=ED=91=B8=EB=94=A9=20evidence=20+=20release?= =?UTF-8?q?=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 도그푸딩(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 --- docs/release-notes/v0.28.0-draft.md | 66 +++++++++++++++++++++++++++++ tasks/HOTFIXES.md | 6 ++- 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 docs/release-notes/v0.28.0-draft.md diff --git a/docs/release-notes/v0.28.0-draft.md b/docs/release-notes/v0.28.0-draft.md new file mode 100644 index 0000000..ddb51a3 --- /dev/null +++ b/docs/release-notes/v0.28.0-draft.md @@ -0,0 +1,66 @@ +--- +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 결과와 색인은 변하지 않는다. diff --git a/tasks/HOTFIXES.md b/tasks/HOTFIXES.md index c2d3ce0..0564fc3 100644 --- a/tasks/HOTFIXES.md +++ b/tasks/HOTFIXES.md @@ -37,7 +37,11 @@ rename 매핑: `PdfOcrCfg` 에 paddle 대칭 6키 추가. `ser_f32_clean` 으로 f32 직렬화 정리(`0.30000001192092896`→`0.3`). per-option 인라인 주석(`key_comment`)을 init/migrate 산출 config 에 부착. -**도그푸딩.** (T10 후 채움) +**도그푸딩 (v0.28.0 release 빌드).** + +1. **사용자 실제 v2 config 변환** (`/build/dogfood/config-v3-test/`): `kebab config migrate` → `v2 → v3 (11 changes)`, `.bak` 백업. schema_version 2→3, 섹션 헤더만 [ingest.*] 로 이동(`[indexing]`/`[chunking]`/`[image.ocr]`/`[image.caption]`/`[pdf.ocr]` → `[ingest.*]`). 사용자 값 보존(`root`, `model = "snowflake-arctic-embed2"`, `endpoint = "http://192.168.0.2:11943"`, `score_gate = 0.30000001192092896` 그대로) + 대안 주석 보존(`# engine = "ollama-vision"`, `# provider = "candle"`). 재실행 멱등(`config 이미 최신입니다`). + +2. **재색인 0 실증** (`/build/dogfood/config-v3-reindex/`, lexical-only `provider = "none"`): v2 config(디스크 schema_version=2)로 first ingest `new=2`. (a) 동일 v2 config 재ingest(메모리 자동변환) → `new=0 updated=0 unchanged=2`. (b) 디스크 파일을 v3 로 `config migrate` 후 재ingest → `new=0 updated=0 unchanged=2`. signature 바이트 불변이 실제 업그레이드 경로(v2 자동변환 ↔ v3 디스크)에서 재색인 0 으로 확인됨 — 불변식 #1 검증. ## 2026-06-04 — PP-OCRv5 ONNX Rust 네이티브 OCR 엔진 (v0.27.0)