docs(release-notes): add v0.20.2-draft (rag-v3 응답언어 + 검색 품질 eval 인프라)
v0.20.2 릴리즈 노트 초안 작성. 사용자 영향 4단락 구조로 각 finding 기술. - Finding #1/O-2: rag-v3 응답언어 자동 매칭 + refusal 언어중립화 - Finding #2: bulk search input schema 확정 (15필드) - Finding #3: list docs human-readable path 보강 - Finding #7: index_version 두 곳 구분 (vector vs FTS5) - eval --config facade + 검색 품질 baseline (hybrid hit@3=1.0 / MRR=0.833) - Finding #4/#5/#6/#8: docs/schema 정비 - version cascade 주의 (rag-v3 → eval compare) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
184
docs/release-notes/v0.20.2-draft.md
Normal file
184
docs/release-notes/v0.20.2-draft.md
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: kebab v0.20.2 release notes (draft)
|
||||
created: 2026-05-29
|
||||
status: draft
|
||||
release_trigger:
|
||||
- 사용자 도그푸딩 필요 (8-finding dogfood 라운드 완료)
|
||||
- RAG prompt_template_version default 변경 (rag-v2 → rag-v3 응답언어 매칭)
|
||||
- eval --config facade 패치 (검색 품질 eval dogfood KB 평가 enabler)
|
||||
---
|
||||
|
||||
# kebab v0.20.2 — Ask 응답언어 자동 매칭 + 검색 품질 eval 인프라
|
||||
|
||||
v0.20.1 (한국어 형태소 검색, 2026-05-28) 후속 patch release. 도그푸딩 8-finding 라운드에서 발견·수정된 문서/스키마/UX 표면 정비 + `rag-v3` 응답언어 규칙 + eval `--config` facade 패치를 한 번에 묶어 cut.
|
||||
|
||||
---
|
||||
|
||||
## 핵심 변경
|
||||
|
||||
### 1. Ask 응답언어 자동 매칭 (rag-v3, Finding #1 + O-2)
|
||||
|
||||
**변경 사실**: `SYSTEM_PROMPT_RAG_V3` 신설. `rag-v2` 의 7규칙 위에 "답변 언어 = 질문 언어" 규칙 추가. config `[rag] prompt_template_version` 의 default 가 `"rag-v2"` → `"rag-v3"` 로 변경.
|
||||
|
||||
```bash
|
||||
# v0.20.2 기본 동작
|
||||
kebab ask "What is the tokenizer?" # → 영어 답변
|
||||
kebab ask "토크나이저가 뭐야?" # → 한국어 답변
|
||||
|
||||
# 이전 v3 고정하려면 (이미 default, 명시 생략 가능)
|
||||
# [rag] prompt_template_version = "rag-v3"
|
||||
|
||||
# rag-v2 로 pin 하면 legacy 동작 (query 언어 무시)
|
||||
# [rag] prompt_template_version = "rag-v2"
|
||||
```
|
||||
|
||||
도그푸딩 확인: 영어 query → 영어 답변, 한국어 corpus 를 영어로 물으면 근거를 영어로 번역해 답함 (trade-off — 원문 보존이 필요하면 큰따옴표 직접 인용 규칙이 적용됨).
|
||||
|
||||
**trade-off**: 한국어 corpus 를 영어로 물을 때 LLM 이 근거를 영어로 번역해 답하므로 원문 표현이 일부 달라질 수 있다. 원문 그대로 필요하면 큰따옴표 직접 인용 (`[#번호]` 앞에 chunk 속 원문) 이 v3 에서도 유지된다.
|
||||
|
||||
**Finding O-2 — refusal 언어중립화**: refusal 문구의 한국어 리터럴 (`"근거가 부족합니다"`) → 언어중립 표현 (`"근거가 부족하면 답변 언어로 답변할 수 없습니다"`) 으로 변경.
|
||||
|
||||
**Known limitation**: gemma4:e4b 같은 소형 모델은 refusal 메시지의 언어가 query 언어와 불일치할 수 있음 (영어 query → 한국어 refusal 가능). refusal 판정 자체는 `<REFUSE>` marker 기반이라 정확도 영향 없음.
|
||||
|
||||
**mitigation**:
|
||||
- refusal 판정은 LLM 출력 내 marker 기반으로 항상 정상 동작.
|
||||
- 언어 불일치가 허용 불가한 경우 `"rag-v2"` 로 pin (이전 동작 보존).
|
||||
- 소형 모델 대신 gemma4:26b 등 대형 모델은 불일치 빈도가 현저히 낮음.
|
||||
|
||||
**upgrade 절차**: 기존 config 에 `prompt_template_version` 미명시 시 자동으로 v3 적용. v2 를 명시적으로 유지하려면 `[rag] prompt_template_version = "rag-v2"` 추가.
|
||||
|
||||
---
|
||||
|
||||
### 2. Bulk search input schema 확정 (Finding #2)
|
||||
|
||||
**변경 사실**: `docs/wire-schema/v1/bulk_search_input.schema.json` 이 15필드 완전 명세로 확정. `query` 누락 시 error shape hint 가 error.v1.message 에 포함됨.
|
||||
|
||||
```bash
|
||||
# query 필수, 나머지 optional (15필드 중 1필수 + 14선택)
|
||||
printf '%s\n' \
|
||||
'{"query":"한국","mode":"lexical","k":3}' \
|
||||
'{"query":"tokenizer","mode":"hybrid"}' \
|
||||
'{}' \
|
||||
| kebab search --bulk --json
|
||||
# 세 번째 줄 → error.v1 (code: invalid_input, message 에 schema hint 포함)
|
||||
```
|
||||
|
||||
**trade-off**: `query` 만 required, 나머지는 전부 optional + 스키마 검증은 agent 측 부담. error shape hint 로 agent 가 retry 없이 즉시 수정 가능.
|
||||
|
||||
**mitigation**: bulk cap 100 건 초과 시 즉시 `error.v1 (code: too_many_queries)` 반환.
|
||||
|
||||
**upgrade**: 기존 `{"query":"..."}` 형태는 완전 호환. 신규 optional 필드는 점진 추가 가능.
|
||||
|
||||
---
|
||||
|
||||
### 3. List docs human-readable path 보강 (Finding #3)
|
||||
|
||||
**변경 사실**: `kebab list docs` human-readable 출력이 `title \t doc_path` 에서 `doc_id \t title \t doc_path` 로 변경. title 중복(예: `README.md` + `README.md`) 시 doc_id 로 구분 가능.
|
||||
|
||||
```bash
|
||||
kebab list docs
|
||||
# 출력 예:
|
||||
# abc123 README.md /path/to/java/README.md
|
||||
# def456 README.md /path/to/kotlin/README.md
|
||||
```
|
||||
|
||||
`--json` 출력 (`doc_summary.v1` array) 은 wire shape 변경 없음.
|
||||
|
||||
**trade-off**: human-readable 컬럼이 늘어나 좁은 터미널에서 wrap 가능. `--json` 으로 programmatic 처리 권장.
|
||||
|
||||
---
|
||||
|
||||
### 4. schema `index_version` 두 곳 구분 (Finding #7)
|
||||
|
||||
**변경 사실**: `schema.v1.models.index_version` 과 `search_hit.v1.index_version` 이 서로 다른 축임을 README 및 schema description 에 명시.
|
||||
|
||||
- `schema.v1.models.index_version` = **vector store (LanceDB)** version.
|
||||
- `search_hit.v1.index_version` = **lexical (FTS5)** version.
|
||||
|
||||
cascade 에서 별도 추적 — 둘 중 하나가 변경돼도 나머지에 영향 없음.
|
||||
|
||||
**upgrade**: 기존 consumer 가 `index_version` 을 단일값으로 읽는 경우 fieldpath 확인 필요.
|
||||
|
||||
---
|
||||
|
||||
### 5. eval `--config` facade 패치 + 검색 품질 baseline 인프라
|
||||
|
||||
**변경 사실**: `kebab eval run / aggregate / compare` 가 `--config <path>` 를 honor. 이전에는 eval 이 XDG default config 만 읽어 dogfood KB (`/build/dogfood/config.toml`) 를 직접 평가할 수 없었음.
|
||||
|
||||
```bash
|
||||
# v0.20.2: dogfood KB 에서 직접 eval
|
||||
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
|
||||
kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10
|
||||
```
|
||||
|
||||
**검색 품질 baseline** (v0.20.2, `/build/dogfood/golden_queries.yaml` 10 query):
|
||||
|
||||
| Mode | hit@1 | hit@3 | hit@10 | MRR | recall@10 | empty |
|
||||
|------|-------|-------|--------|-----|-----------|-------|
|
||||
| hybrid | 0.7 | **1.0** | 1.0 | **0.833** | 1.0 | 0 |
|
||||
| lexical | 0.4 | 1.0 | 1.0 | 0.7 | 1.0 | 0 |
|
||||
|
||||
hybrid 가 vector 덕분에 top-1 정확도 우위. hit@3 이후는 두 모드 모두 완벽. 현재 ranking 조정 없이 달성 (`[[project_ranking_deferred]]` 결정 유효).
|
||||
|
||||
**golden 큐레이션 교훈**: 초기 dispatch.py 정답을 note 로만 한정한 것이 오류. eval 분해 시 vector 가 영어 docstring dispatch.py 를 top-1 으로 반환함을 발견, 정답에 추가 후 hit@3 0.9→1.0 개선. **교훈**: golden answer 는 "note 의 intent" 뿐 아니라 "합리적으로 관련된 모든 doc" 을 포함해야 함.
|
||||
|
||||
**trade-off**: `--config` 패치가 facade rule (kebab-cli → kebab-app `*_with_config`) 의 eval 적용. 누락 시 dogfood KB 와 XDG KB 의 결과가 섞여 eval 결과 오염.
|
||||
|
||||
**upgrade**: 기존 `kebab eval` 호출은 동작 변경 없음 (config 미명시 → XDG default 그대로).
|
||||
|
||||
---
|
||||
|
||||
### 6. 기타 docs/schema 정비 (Finding #4 · #5/#6 · #8)
|
||||
|
||||
**Finding #4 — doc.lang semantic 명시**: `lang = "und"` 는 소스코드 doc 의 정상 상태임을 README + schema description 에 명시. lingua 가 자연어 감지 대상 아님을 `lang_breakdown` 해석 가이드에 추가.
|
||||
|
||||
**Finding #5/#6 — fusion_score / score_kind**: `search_hit.v1` 의 `fusion_score` / `lexical_score` / `vector_score` / `lexical_rank` / `vector_rank` 가 모두 `retrieval` object 내부에 있음 (top-level 아님) 을 README 및 schema description 에 명시. 단일 mode (lexical/vector) 에서 `score == fusion_score == (lexical|vector)_score` 가 같은 값인 이유도 설명.
|
||||
|
||||
**Finding #8 — kebab init Ollama endpoint hint**: `kebab init` 이 생성하는 config.toml 에 `[models.llm] endpoint` 의 default 주석에 remote Ollama host 예시 추가.
|
||||
|
||||
---
|
||||
|
||||
## Version cascade 주의
|
||||
|
||||
| Version field | v0.20.1 | v0.20.2 |
|
||||
|---|---|---|
|
||||
| `prompt_template_version` default | `"rag-v2"` | **`"rag-v3"`** |
|
||||
| wire schema shape | unchanged | unchanged (additive description only) |
|
||||
| `eval config_snapshot_json` | `prompt_template_version: "rag-v2"` | `prompt_template_version: "rag-v3"` |
|
||||
|
||||
**eval compare 주의**: v0.20.1 eval run 과 v0.20.2 eval run 을 `eval compare` 할 때 `prompt_template_version` 이 다르므로 config_snapshot 이 다름. eval runner 가 snapshot 불일치를 경고하지 않으면 metric 변화의 원인이 rag 버전인지 corpus 변화인지 구분 불가. 정확한 비교는 `[rag] prompt_template_version = "rag-v2"` 로 pin 후 re-run.
|
||||
|
||||
---
|
||||
|
||||
## Breaking changes / 사용자 영향
|
||||
|
||||
- **prompt_template_version default 변경 (rag-v2 → rag-v3)**: 영어로 묻는 경우 영어로 답함. config 에 `prompt_template_version` 미명시한 사용자는 자동 적용. 이전 동작 유지는 `"rag-v2"` 명시.
|
||||
- **소형 모델 refusal 언어 불일치 known limitation**: gemma4:e4b 사용자는 refusal 메시지 언어가 가끔 틀릴 수 있음. 정확도(판정)는 영향 없음.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade 절차
|
||||
|
||||
```bash
|
||||
# 1. binary 교체
|
||||
git fetch && git checkout v0.20.2
|
||||
cargo build --release -p kebab-cli -j 4
|
||||
|
||||
# 2. rag-v3 동작 확인
|
||||
kebab ask "What is the tokenizer?" --hide-citations # 영어 응답 기대
|
||||
kebab ask "토크나이저가 뭐야?" --hide-citations # 한국어 응답 기대
|
||||
|
||||
# 3. eval baseline 측정 (선택)
|
||||
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
|
||||
kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- HOTFIXES entry: [`tasks/HOTFIXES.md`](../../tasks/HOTFIXES.md) 2026-05-29
|
||||
- DOGFOOD scenarios: [`docs/DOGFOOD.md`](../DOGFOOD.md) §3.6 + §10.2
|
||||
- eval `--config` facade: CLAUDE.md "The facade rule"
|
||||
- Golden queries: `/build/dogfood/golden_queries.yaml`
|
||||
- Eval logs: `/build/dogfood/logs/eval-{hybrid,lexical}-v0.20.2.json`
|
||||
Reference in New Issue
Block a user