docs(#5,#6): clarify retrieval.* nesting + single-mode score relation (Todo #5/#6)
README Score 해석 절에 score ↔ retrieval.* 구조 설명 추가: - fusion_score/lexical_score/vector_score/lexical_rank/vector_rank 는 retrieval 내부 (top-level 아님). - single-mode 에서 score==fusion_score==lexical/vector_score 가 같은 값인 것은 정상 (Finding X). search_hit.schema.json score 필드에 score_kind 관계 + single-mode 동일값 이유 설명 추가. search_hit.schema.json retrieval/index_version 설명은 Task 12 커밋에 포함 (같은 hunk). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
10
README.md
10
README.md
@@ -135,6 +135,16 @@ normalize: rrf_score = raw_rrf / (2 / (k_rrf + 1))
|
||||
|
||||
agent 가 trust threshold 가 필요하면 top-level `score` 가 아닌 nested `retrieval.lexical_score` (BM25 raw) / `retrieval.vector_score` (cosine raw) 사용.
|
||||
|
||||
#### `score` ↔ `retrieval.*` 구조 (v0.20.2 정정)
|
||||
|
||||
`fusion_score` / `lexical_score` / `vector_score` / `lexical_rank` / `vector_rank` 는 모두 **`retrieval` object 내부**에 있다 (top-level 아님). top-level `score` 는 canonical ranking score 이며 그 의미는 `score_kind` 가 선언한다.
|
||||
|
||||
- **hybrid**: `score == retrieval.fusion_score` (RRF normalized `[0,1]`), `score_kind = "rrf"`.
|
||||
- **lexical-only**: fusion 미실행 → `score == retrieval.fusion_score == retrieval.lexical_score` (raw BM25), `score_kind = "bm25"`.
|
||||
- **vector-only**: `score == retrieval.fusion_score == retrieval.vector_score` (raw cosine), `score_kind = "cosine"`.
|
||||
|
||||
즉 single-mode 에서 `score`/`fusion_score`/(lexical|vector)_score 가 같은 값인 것은 fusion 단계가 없기 때문이며 정상이다 (Finding X).
|
||||
|
||||
## 논리 아키텍처
|
||||
|
||||
```mermaid
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
"properties": {
|
||||
"schema_version": { "const": "search_hit.v1" },
|
||||
"rank": { "type": "integer", "minimum": 1 },
|
||||
"score": { "type": "number" },
|
||||
"score": { "type": "number", "description": "canonical ranking score. 의미는 `score_kind` 가 선언 (rrf/bm25/cosine). single-mode 에서는 fusion 미실행 → `retrieval.fusion_score` 와 동일." },
|
||||
"score_kind": {
|
||||
"type": "string",
|
||||
"enum": ["rrf", "bm25", "cosine"],
|
||||
|
||||
Reference in New Issue
Block a user