uncle6me-web
558e80b4da
wiki 已初始化過（push 檔活躍維護），本次補從沒建的 pull 層 + arcrun 化範本： - cards/decisions/ 14 張決策原子卡（含 gloss/實體/typed-edge 三元組）： 從 decisions-summary 全量改寫 13 + 新增「薄殼規則晚於實作-MCP漂移是歷史債」1 - TAXONOMY 從 PKM 範本換成 arcrun 軸（子系統 零件架構/cypher/credential/recipe/kbdb/ 薄殼/部署/平台原則 + 形態 架構決策/踩坑/機制說明/禁令/案例經驗） - principles 填 13 條跨全局原則（從 rules/ + mindset 蒸餾） - INDEX 真實視圖（子系統角度 + 決策角度，指向 cards） - system-dev/scripts/ + scripts/ install/update 安裝腳本（template 接入） 純基建/文檔，無業務 code（功能 code 見前一 commit）。 raw source（docs/）0 異動、wiki 卡際連結無斷鏈。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
44 lines
2.8 KiB
Markdown
44 lines
2.8 KiB
Markdown
---
|
||
tags: [kbdb, 架構決策]
|
||
gloss: embedding 機制歸 KBDB base 的 optional 模組，有 Vectorize binding 才啟用；無則降級 LIKE keyword，API 不變。
|
||
---
|
||
# Embedding 是 Base Optional 模組
|
||
|
||
← [[decisions/00-INDEX]]
|
||
|
||
**來源**：`system-dev/wiki/decisions-summary.md`（embedding 是 base optional 模組）、`docs/3-specs/arcrun/kbdb-base/` Phase 12
|
||
**最後更新**：2026-06-27
|
||
|
||
## 摘要
|
||
語義查詢/embedding 不是獨立模組或圖插件，而是 KBDB base 層的 optional 擴展。Vectorize + AI binding 存在時啟用；缺少時降級 keyword search + capability hint（發現閉環，不假綠）。
|
||
|
||
## 重點
|
||
- **歸屬**：embedding 機制屬 base 層（核心表 entries/templates/records），不是 graph 層（triplet 插件）、不是 ingest 層（爬蟲）。
|
||
- **啟用機制**：
|
||
- 部署時檢查 KBDB binding 是否含 `[ai]` + `[[vectorize]]` → 有則啟用 semantic search
|
||
- 無則 API 降級為 keyword LIKE + `capability_hint`（告知使用者「語義搜尋未啟用」）
|
||
- **API 簽名不變**（無論啟用否，查詢端點同一個 `/search`），降級轉換在後端
|
||
- **部署陷阱**：部署注入 `[ai]`/`[[vectorize]]` binding 必須在 `stripOfficialOnlyBindings` **之後**（否則 [ai] 被清）。
|
||
- **精耕策略**（非地毯式）：只 embed 標 `metadata_json.embed:true` 的 entry（wiki 段落 + gloss），不對每個 block 灌。
|
||
- **無白名單**：base 用通用 flag 判 embed:true，不寫死 entry_type 白名單（守解耦，base 對內容語意無知）。
|
||
- **向量存儲位置**：向量獨存 Vectorize，三表（entries/templates/records）不改動。
|
||
- **發現閉環**：無 embedding 時不假綠（回傳空結果假裝查到），而是明確 hint「語義未啟用」→ capability-driven 發現系統能自動 degrade。
|
||
|
||
## 實體
|
||
- **Base 層**（base layer）— KBDB 核心表（entries/templates/records）及其基本操作。
|
||
- **Optional 模組**（optional module）— 功能開/關不拆 repo，降級機制在 API 內部。
|
||
- **Vectorize**（Cloudflare Vectorize）— 向量資料庫 binding，儲存 embedding。
|
||
- **Semantic search**（語義搜尋）— 基於 embedding 的向量相似度查詢。
|
||
- **Capability hint**（能力提示）— API 回傳中明確標示「此能力未啟用」，供 client 判斷。
|
||
- **Embed flag**（embed:true）— 在 entry metadata_json 中設置，標示是否參與 embedding。
|
||
|
||
## 關聯
|
||
### 內文知識關係
|
||
- Vectorize binding >> 啟用 >> Semantic search
|
||
- 無 Vectorize >> 降級為 >> Keyword search
|
||
- Embed flag >> 控制 >> 哪些 entry 參與 embedding
|
||
- API >> 不變 >> 無論 embedding 啟用否
|
||
- Capability hint >> 發現 >> 語義搜尋未啟用
|
||
### 卡片關係
|
||
- [[embedding是base-optional模組]] >> 涉及部署 >> [[self-hosted部署-共享install加指紋跳過]]
|