feat(expansion): doc-side expansion 별칭 개별 dense 벡터 + 파생물 캐시(V012) #195
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: altair823-org/kebab#195
Reference in New Issue
Block a user
Delete Branch "feat/doc-side-expansion"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
doc-side expansion 별칭 개선 + 파생물 캐시 (V012)
변경
{chunk}#alias#N)로 색인 + boilerplate 청크 skip. 본문 벡터는 불변.derivation_cache). 재색인·갱신 시 내용 같은 청크는 재계산 skip. 버전 키로 cascade 안전.측정 (나무위키 ~1000문서 CS corpus, 유사 주제 밀집)
kebab.sqlite+lancedb만으로 동일 동작(asset 불필요) → 외부서버 계산 + 로컬검색 워크플로 가능.상세:
docs/superpowers/handoffs/2026-05-31-namu-wiki-alias-cache-study.mdknown limitation
🤖 Generated with Claude Code
별칭 dense 벡터({orig}#alias) hit 을 원본 chunk_id 로 strip 해 hydrate, body+alias 중복은 첫(높은 score) 하나만 유지. overfetch 2→3 (dedup 후 k 확보). wire/RetrievalDetail 무변경. vector/hybrid 회귀 0, clippy green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>별칭 dense 벡터를 sentinel chunk_id({orig}#alias)로 색인하려면 chunks 에 없는 chunk_id 가 embedding_records 에 들어가야 한다. V001 의 chunk_id REFERENCES chunks ON DELETE CASCADE FK 가 이를 SQLite 787 로 막으므로 테이블을 FK 없이 재생성한다. status/vector_committed(V003) + 3개 인덱스 보존, chunks_bd_tombstone_embeddings trigger 무수정. DROP→RENAME 시 dangling trigger 재파싱을 피하려 legacy_alter_table=ON. 사라진 CASCADE 는 put_chunks + purge 두 경로(purge_orphan_at_workspace_path, purge_deleted_workspace_path)의 명시 DELETE 로 대체 — chunks 삭제 직전 원본 + {id}#alias sentinel embedding_records 를 함께 정리. corpus_revision baseline 2→3. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>LanceDB 후보의 sentinel chunk_id({orig}#alias)는 chunks JOIN 에서 탈락해 VectorRetriever strip 이전에 사라진다. candidate 를 kebab_core::strip_alias_suffix 로 원본 chunk_id 로 strip 해 IN-list/JOIN 에 넣어(committed 판정은 원본 body chunk 기준) 통과시키되, 반환은 입력 candidate 형태(sentinel 유지) — VectorRetriever 가 그 sentinel 을 받아 strip+dedup 한다. SQL replace 대신 (b) Rust strip 채택(명확). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>별칭을 줄별 개별 dense 벡터(sentinel `{chunk}#alias#N`)로 색인하고 boilerplate 청크는 별칭 생성을 skip. 묶음 1벡터 방식은 평균화로 특정 표현이 희석돼 오히려 회귀(13/18)했던 것을 폐기. 변형 일관성 14/18 → 16/18, mean_spread@10 0.222 → 0.111 (나무위키 ~1000 문서 CS corpus). `kebab-core::strip_alias_suffix` 가 suffix 형과 per-alias 형 둘 다 처리. 파생물 캐시(V012): embedding 벡터 + 별칭 LLM 결과를 청크 내용 해시 키로 캐싱해 재색인 시 내용 불변 청크의 재계산을 skip. cache_key = blake3(kind ‖ text_blake3 ‖ version_key)[:32], version_key 에 model/prompt/dimensions 포함 → §9 cascade 와 정합(버전 bump 시 자동 miss). 측정: 정답 3개 cold 1879s → warm 13s ≈ 145배. 순수 가산이라 corpus_revision bump 없음. search/ask 는 kebab.sqlite+lancedb 만으로 동작 → 외부 서버 색인 후 DB 만 복사하는 이식 워크플로 가능. V012 schema migration + 신규 surface 로 workspace version 0.20.2 → 0.21.0 (minor) bump. README/HANDOFF/ARCHITECTURE/HOTFIXES sync. known limitation: stack·svm 설명형 2개 잔존 + grounded 판정이 부분 인용을 grounded 로 오분류(후속 후보). 측정 상세: docs/superpowers/handoffs/2026-05-31-namu-wiki-alias-cache-study.md Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>MAJOR: 별칭 dense 벡터의 chunk_id 가 레거시 단일 `{id}#alias` 에서 줄별 `{id}#alias#0`, `#alias#1`, … 로 바뀌었으나 orphan cleanup 이 단일 sentinel 하나만 삭제해 `#alias#N` 벡터가 LanceDB / embedding_records 에 누수됐다. - kebab-app: `alias_sentinel_ids_to_delete` 헬퍼 추가(접근법 A) — 본문 + legacy `{id}#alias` + `{id}#alias#0`..`{id}#alias#{max-1}` 를 모두 delete-set 에 포함. max=expansion.max_aliases_per_chunk(= parse_aliases 의 하드 cap)와 일치. parser-bump / edited-asset / deleted-file 세 LanceDB cleanup 경로 모두 이 헬퍼를 사용. - kebab-store-sqlite: embedding_records 명시 DELETE 4 경로(put_chunks / purge_*_except_doc_id / purge_orphan_at_workspace_path / purge_deleted_workspace_path)를 정확 일치(`|| '#alias'`)에서 `{id}#alias%` 프리픽스 LIKE 로 전환. 본문 chunk_id 는 32자 hex 라 LIKE 와일드카드 없음. MINOR 1: alias 캐시 히트 시 비-UTF8 payload 를 미스로 강등(재생성 분기로) — embedding 경로의 decode-실패→미스 강등과 동작 일치. MINOR 2: embedding version_key 맨 앞에 kind 토큰("doc") 추가 — 임베더가 kind 별 프리픽스를 붙이므로 미래에 query 임베딩이 같은 캐시를 타도 충돌 방지. 회귀 테스트: - kebab-app: alias_sentinel_ids_to_delete 단위 테스트 2건. - kebab-store-sqlite: per-alias sentinel embedding_records 가 세 cleanup 경로 모두에서 사라지는지 핀하는 통합 테스트 3건. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>