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