Arcrun/system-dev/wiki/cards/decisions/embedding是base-optional模組.md

tags, gloss

tags	gloss
kbdb 架構決策	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加指紋跳過