fix(kbdb/embed): 語意查詢 metadata 過濾根因修復(Arcrun#11)

根因:Vectorize index 建了卻從沒建 metadata index。CF Vectorize v2 要對某
metadata 欄位下 filter,必須先為該欄建 metadata index,否則帶 owner_id/
entry_type/source 過濾的語意查詢一律回 0 命中(app 端 filter 接線本來就對)。
且 metadata index 只索引「建立後 upsert」的向量 → 既有向量須重推才會被收錄。

- deploy.ts:加 ensureVectorizeMetadataIndexes(),隨部署冪等建 owner_id/
  entry_type/source(string)三個 metadata index(self-host/官方帳號皆自動)。
- embed.ts / routes/embed.ts:backfillEmbeddings 加 reindex+offset,重推「所有
  embeddable(含 is_embedded=1)」既有向量,讓事後建立的 metadata index 收錄;
  POST /embed/backfill {"reindex":true} 觸發,offset 分頁到 remaining=0。
- wrangler.toml:註解補 create-metadata-index 手動步驟 + reindex 提示。
- tests:mock DB 對齊 LIMIT?/OFFSET? 與 reindex predicate;補 reindex 測試。

leo21c 已驗:owner_id=leo / entry_type 過濾修前 0→修後命中,不帶過濾不變。
已知後續(非本 bug 症狀):source 值 89-91 bytes 超過 Vectorize string
metadata index 的 64-byte 索引上限 → source 過濾對長值失效,另案。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HJiLCRUU2o3aSpPEzVCt2o
This commit is contained in:
kbdb-cc
2026-07-06 06:03:43 +00:00
parent 4439880bbd
commit befc63cfe0
5 changed files with 102 additions and 15 deletions
+7
View File
@@ -19,6 +19,13 @@ ENVIRONMENT = "production"
# Base 預設不開(free-tier 友善)。self-host 開語義查詢時,deploy.ts 偵測 config kbdb_embed:true
# → 取消下面兩段註解(注入 active binding)並 `wrangler vectorize create arcrun-kbdb-embed
# --dimensions=768 --metric=cosine`bge-base-en-v1.5 = 768 維)。官方帳號同理由 deploy 注入。
# ⚠️ Arcrun#11:光建 index 不夠。要對 owner_id/entry_type/source 下 filterowner-scoped/類型-scoped 語意查詢),
# 必須另建 metadata index,否則帶過濾一律回 0 命中:
# wrangler vectorize create-metadata-index arcrun-kbdb-embed --property-name owner_id --type string
# wrangler vectorize create-metadata-index arcrun-kbdb-embed --property-name entry_type --type string
# wrangler vectorize create-metadata-index arcrun-kbdb-embed --property-name source --type string
# metadata index 只收「建立後 upsert」的向量 → 既有向量須 `POST /embed/backfill {"reindex":true}` 重推。
# deploy.ts 的 ensureVectorizeMetadataIndexes() 已把上述三個 index 隨部署冪等建好。
# 沒有這兩個 binding 時,kbdb/src/embed.ts 的 embedEnabled() 回 false → 維持 LIKE keyword、API 不變。
#
# [[vectorize]]