---
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加指紋跳過]]