diff --git a/docs/superpowers/specs/2026-05-30-dense-alias-vectors-design.md b/docs/superpowers/specs/2026-05-30-dense-alias-vectors-design.md new file mode 100644 index 0000000..8c655f1 --- /dev/null +++ b/docs/superpowers/specs/2026-05-30-dense-alias-vectors-design.md @@ -0,0 +1,118 @@ +--- +title: 별칭 dense 별도 벡터 — 설계 spec +date: 2026-05-30 +status: 설계 확정 (brainstorm + PoC 측정 완료) — plan 대기 +phase: Phase 2 (query-paraphrase robustness 처방 — dense 활용) +related: + - docs/superpowers/specs/2026-05-30-doc-side-expansion-design.md + - memory: project_paraphrase_robustness, project_ranking_deferred, feedback_search_quality_dogfood +contract_sections: + - "design §6 (retrieval / vector store + hybrid)" + - "design §9 (versioning cascade)" +--- + +# 별칭 dense 별도 벡터 + +## 0. 한 줄 요약 + +doc-side expansion 의 별칭(`chunk.aliases`)은 현재 lexical FTS 채널(`chunk_aliases_fts`)에만 색인돼 +dense(e5)가 활용하지 못한다. 설명형 패러프레이즈는 dense 의 영역인데(단어 안 겹쳐도 의미 매칭), dense 가 +별칭 덕을 못 봐 `recall@50=0` 으로 남았다. **별칭을 별도 dense 벡터로 색인**(sentinel chunk_id, 본문 +벡터 불변)해 dense 가 별칭 순수 신호로 설명형을 잡게 한다. **flag off 기본**, variants + 전체 golden 회귀로 측정. + +## 1. 진단 (PoC 측정 근거, 2026-05-30) + +별칭을 **본문에 concat 해 한 벡터**로 임베딩한 PoC(dogfood topics 7 doc): +- 종합 `fully_consistent 2→6, A_dominant 2→0, B_dominant 4→2, spread@10 0.75→0.25` — **명사형·한국어 + 설명형·일부 영어 설명형 회복, 명사형 회귀 0**. dense 가 설명형의 본령임을 실증. +- 남은 미회복: mvcc/raft **영어 설명형**(`how databases serve reads without locking rows`, + `how nodes agree on a single ordered log`) — vector/hybrid 모두 top-50 밖. +- 질문형 프롬프트 강화(`max_tokens` 384 + "질문 형태 생성") 시도 → 동일 `6/0/2/0.25`, 영어 설명형 미회복. +- **가설**: concat 은 긴 본문 + 짧은 별칭을 한 벡터로 합쳐 **본문 의미가 별칭 신호를 희석**. 한국어 + 설명형은 한국어 별칭이 풍부해 회복됐으나, 영어 설명형은 별칭 신호가 약함. → 별칭을 **별도 순수 벡터**로 + 색인하면 본문 희석 없이 dense 매칭 가능(미검증 — 본 작업이 검증). + +## 2. 설계 결정 + +| # | 결정 | 선택 | 근거 | +|---|------|------|------| +| D1 | 별칭 dense 색인 방식 | **별도 벡터(sentinel chunk_id)** | concat 은 본문 벡터 변경(전체 corpus 회귀 부담) + 본문 희석. 별도 벡터는 본문 벡터 불변(회귀 안전) + 별칭 순수 신호. lexical `chunk_aliases_fts` 와 대칭. | +| D2 | flag | **`ingest.expansion.embed_aliases` default false** | `expansion.enabled`(별칭 생성)와 별개 축. 독립 on/off 측정([[feedback_search_quality_dogfood]]). | +| D3 | RRF 통합 | VectorRetriever 내부 dedup (2채널 유지) | lexical 의 body+alias merge 와 대칭. `RetrievalDetail`/wire schema `search_hit.v1` 무변경. | + +## 3. 아키텍처 + +### 3.1 데이터 흐름 + +``` +ingest_one_asset (embed + upsert): + body : emb.embed(chunk.text) → VectorRecord{chunk_id: orig} (변경 없음) + alias : if embed_aliases && aliases → emb.embed(aliases) [NEW] + → VectorRecord{chunk_id: "{orig}#alias", text: aliases, doc_id: 동일} + vec_store.upsert([body, alias]) # LanceDB MergeInsert keyed on chunk_id → 별도 row 공존 + +검색 (VectorRetriever.search): + store.search(query_vec) → raw_hits (orig + "{orig}#alias" 섞임) + 각 hit: chunk_id 가 "#alias" 로 끝나면 → 원본 strip + seen(원본 chunk_id) dedup: 같은 원본이 body+alias 둘 다 → 첫(높은 score) 유지 + hydrate(원본 chunk_id) → SearchHit (원본 chunk_id, body 메타) + → 단일 vector 결과. HybridRetriever.fuse(lexical, vector) 2채널 그대로. +``` + +### 3.2 sentinel chunk_id + +- `ALIAS_SUFFIX = "#alias"`. ChunkId 는 blake3 hex(32 영숫자)라 `#` 미포함 → 충돌 없음. +- alias VectorRecord: `chunk_id = format!("{orig}{ALIAS_SUFFIX}")`, `embedding_id = + id_for_embedding(&alias_chunk_id, ...)`, `text = aliases`(별칭 원문), `doc_id`/`heading_path` 동일. +- strip 헬퍼: `fn strip_alias_suffix(id: &str) -> &str { id.strip_suffix(ALIAS_SUFFIX).unwrap_or(id) }`. + +### 3.3 컴포넌트 + +- **ingest (kebab-app/src/lib.rs)**: embed 블록 확장. `embed_aliases` on 이고 별칭 있는 청크는 별칭도 + 임베딩 → alias VectorRecord 생성. body VectorRecord 는 그대로(chunk.text). 한 `upsert` 에 body+alias 함께. +- **VectorRetriever.search (kebab-search/src/vector.rs)**: raw_hits 순회 시 chunk_id strip + seen + dedup. candidate_ids/hydrate 는 strip 된 원본 사용. build_hit 도 원본 chunk_id. overfetch + multiplier 상향(별칭 벡터로 dedup 후 k 미달 방지 — `VECTOR_OVERFETCH_MULTIPLIER` 2→3). +- **purge**: `purge_vector_orphans_for_workspace_path`(stale_chunk_ids_at 기반) + `sweep_deleted_files` + 가 stale/삭제 chunk_id 의 `{id}#alias` 도 함께 `delete_by_chunk_ids`. (별칭 벡터는 SQLite chunks 에 + 없어 stale 목록에 안 잡히므로 명시 추가 — 안 하면 orphan 별칭 벡터 누적.) +- **config**: `IngestExpansionCfg.embed_aliases: bool`(default false) + `KEBAB_INGEST_EXPANSION_EMBED_ALIASES`. + +### 3.4 격리 / 회귀 안전 + +- body 벡터(chunk.text 임베딩) **불변** → 기존 명사형/본문 dense 매칭 회귀 0(concat 과 달리). +- 별칭 벡터는 sentinel row 라 본문 벡터와 독립. flag off 면 별칭 벡터 미생성 → 기존과 동일. + +## 4. versioning (design §9) + +- 별칭 dense 는 additive(별도 벡터). `try_skip_unchanged` 의 기존 5버전 판단 무변경(별칭 부재가 자동 + 재색인 트리거 안 함). 재생성은 `--force-reingest`. +- embed_aliases flag 토글은 임베딩 정책 변경이나 별도 벡터라 body 임베딩 version 불변. wire 무변경(flag off). + +## 5. 측정 (§4.6) + +- dogfood topics 7 doc, embed_aliases on 재임베딩 → `kebab eval variants`. +- **효과**: 영어 설명형(mvcc/raft) `recall@50` 0→양수 회복되는지(concat 미회복분). 종합 B_dominant↓. +- **회귀**: body 벡터 불변이라 명사형/단일쿼리 회귀 0 기대 — 전체 golden 로 확인. +- concat PoC(6/0/2/0.25) 대비 별도 벡터가 영어 설명형까지 잡으면 추가 개선, 못 잡으면 e5 한계로 기록. + +## 6. 범위 밖 (YAGNI) + +- dense 모델 교체(e5 유지 — research 권고). +- 별칭별 다중 벡터(별칭 전체를 1벡터로). +- lexical 긴 쿼리 완화(content-OR) — dense 가 설명형 본령이라 폐기(2026-05-30 brainstorm). + +## 7. 테스트 (TDD) + +- `strip_alias_suffix`: `"abc#alias"`→`"abc"`, `"abc"`→`"abc"`. +- ingest: embed_aliases on + 별칭 청크 → vector store 에 `{orig}#alias` row 존재. off → 없음. +- VectorRetriever dedup: 같은 원본이 body+alias 둘 다 hit → 결과에 1개(원본 chunk_id), 높은 score 유지. +- VectorRetriever strip: alias-only hit → 원본 chunk_id 로 hydrate(원본 chunk 메타). +- purge: 청크 재처리 시 `{orig}#alias` 벡터도 삭제(orphan 잔존 0). +- 회귀: embed_aliases off → vector 결과가 기존과 동일. + +## 8. PR / 문서 + +- doc-side expansion 과 같은 PR. README Configuration 에 `embed_aliases`(off 기본) 명시. + ARCHITECTURE 에 별칭 dense 별도 벡터(sentinel) 1~2줄. HOTFIXES dated entry(lexical 별칭 + dense 별칭 측정 표). +- versioning cascade 없음(body 임베딩 불변). flag off 라 wire 무변경.