docs(dogfood): add §10.2 search quality baseline scenario (v0.20.2 golden suite)
eval --config facade 패치로 dogfood KB 직접 평가 가능해짐에 따라 §10 Eval 에 §10.2 검색 품질 baseline 섹션 추가. - golden suite 실행 명령 (hybrid + lexical eval run → aggregate) - v0.20.2 metric baseline 표 (hybrid hit@3=1.0 / MRR=0.833) - 정성 체크리스트 (한국어 2자 hit@3, empty=0, MRR 임계치) - golden 큐레이션 절차 + dispatch.py 오류 교훈 - §10.1 로 기존 basic eval run 재구성 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -685,13 +685,65 @@ ajv-cli validate -s docs/wire-schema/v1/<schema>.schema.json -d <output>
|
||||
|
||||
## §10 Eval (P5)
|
||||
|
||||
### §10.1 Basic eval run
|
||||
|
||||
```bash
|
||||
"$RELEASE_BIN" eval --config "$DOGFOOD/config.toml"
|
||||
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
|
||||
"$RELEASE_BIN" --config "$DOGFOOD/config.toml" eval run --mode hybrid --k 10
|
||||
```
|
||||
|
||||
**verify**:
|
||||
- golden query suite 의 metrics (MRR / Recall / NDCG).
|
||||
- regression detection (snapshot 비교).
|
||||
- `eval aggregate <run_id> --json` 로 metric object 확인.
|
||||
|
||||
### §10.2 검색 품질 baseline (v0.20.2 golden suite, spec §4.6)
|
||||
|
||||
v0.20.2 dogfood 에서 확립한 baseline. eval `--config` facade 패치로 dogfood KB 를 직접 평가할 수 있게 됨.
|
||||
|
||||
**실행 절차**:
|
||||
|
||||
```bash
|
||||
# 1. eval run (hybrid + lexical 각각)
|
||||
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
|
||||
"$RELEASE_BIN" --config /build/dogfood/config.toml eval run --mode hybrid --k 10 --json \
|
||||
| tee /build/dogfood/logs/eval-hybrid-$(date +%Y%m%d).json
|
||||
|
||||
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
|
||||
"$RELEASE_BIN" --config /build/dogfood/config.toml eval run --mode lexical --k 10 --json \
|
||||
| tee /build/dogfood/logs/eval-lexical-$(date +%Y%m%d).json
|
||||
|
||||
# 2. aggregate
|
||||
RUN_ID=$(jq -r '.run_id' /build/dogfood/logs/eval-hybrid-$(date +%Y%m%d).json | head -1)
|
||||
"$RELEASE_BIN" --config /build/dogfood/config.toml eval aggregate "$RUN_ID" --json
|
||||
```
|
||||
|
||||
**v0.20.2 metric baseline** (`/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 |
|
||||
|
||||
**정성 체크리스트**:
|
||||
- [ ] 한국어 2자 정답 (`'한국'` / `'서울'` 등) 이 hit@3 이내에 등장.
|
||||
- [ ] `empty_result_rate = 0` — 10개 query 전부 ≥ 1 hit.
|
||||
- [ ] hybrid MRR ≥ 0.8 (baseline 0.833).
|
||||
- [ ] lexical MRR ≥ 0.65 (baseline 0.7).
|
||||
- [ ] `eval compare <run_a> <run_b>` 의 delta MRR 이 ±0.1 이내면 ranking 건강.
|
||||
|
||||
**큐레이션 절차 (spec §4.6)**:
|
||||
- golden answer 는 "note 의 intent 와 가장 가까운 chunk" 가 아닌 "합리적으로 관련된 모든 doc" 포함 권장.
|
||||
- 코드와 note 가 동시에 정답일 수 있음 — eval 분해 후 vector hit 를 직접 확인해 golden 보완.
|
||||
- 초기 라벨링 후 `eval aggregate --json` 의 per-query breakdown 으로 false-negative 정정.
|
||||
- 정정 시 `hit@3` 등 상위 metric 이 0.9→1.0 수준으로 개선되면 curated golden 으로 확정.
|
||||
|
||||
**인사이트**:
|
||||
- hybrid 가 vector 덕분에 top-1 정확도 우위 (0.7 vs lexical 0.4). hit@3 이후는 두 모드 모두 완벽.
|
||||
- lexical (V009 형태소) 이 짧은 한국어 토큰을 top-3 에 정확히 배치.
|
||||
- ranking 조정 없이 현재 hybrid RRF 가 baseline 달성 (`[[project_ranking_deferred]]` 결정 유효).
|
||||
|
||||
Cross-link: `tasks/HOTFIXES.md` (2026-05-29 — 검색 품질 baseline entry), `/build/dogfood/golden_queries.yaml`, `/build/dogfood/logs/`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user