併 bge-m3 換代（#59）＋補上分支漏做的另一半：Vectorize index 也換

leo 2026-08-05：「換 embed model 當然要合併，當然要換 vectorize，**原本的根本不能用**」
——我把已拍板的事當成待裁決，錯了。

## 為什麼非換不可（08-03 leo 拍板，5 組中文測資實證）
  @cf/baai/bge-base-en-v1.5   768   排序正確 2/5   margin -0.0413   1660ms  ← 舊
  @cf/baai/bge-m3            1024        5/5        +0.1410    959ms  ← 新
舊英文模型嵌中文：分數全擠在 0.65-0.81，區辨力接近沒有＝**根本不能用**。

## 🔴 分支只做了一半，另一半我補上
feat/embed-model-m3-t59 只改 kbdb（embed.ts / types.ts / 測試），**完全沒動 deploy.ts**
⇒ 就算合併，安裝器仍會建 **768 維的舊 index**，新向量根本收不進去。
（git show f3af5d3 --stat 實查：只有 3 個檔，全在 kbdb/）

本次補上安裝器那半：
· KBDB_VECTORIZE_INDEX: arcrun-kbdb-embed → **arcrun-kbdb-embed-m3**（換名字，非只換維度）
· ensureVectorizeIndex: dimensions 768 → **1024**
· kbdb/wrangler.toml 說明與 metadata-index 指令同步改新名（照抄不會建錯 index）
· embed.ts docstring「768 維向量」→ 1024（分支漏改，會誤導）

## 為什麼要換「名字」不是只改維度
① 維度 768→1024，舊 index 收不進新向量
② 就算維度相同也不能沿用——不同模型的向量混在同一 index 比對出來是垃圾，
   而 #58（Vectorize vector delete 未接）代表舊向量刪不掉
   ⇒ **開新名字反而順手繞開 #58**，且新舊並存可回滾。

## 查證（歷史警察 Q0-Q3，非假設）
· git log --all -S"arcrun-kbdb-embed-m3" / -S"dimensions: 1024" 皆空 ⇒ 無分支改過，非重造輪子
· **metadata index 用同一個常數**（deploy.ts:426 ensureVectorizeMetadataIndexes）
  ⇒ t36 的四個 metadata index（owner_id/entry_type/source/library，Arcrun#11 根因修復）
  會自動建在新 index 上，**不會因改名而遺失**——這點特地查過，不是假設。

## 驗
· kbdb 測試 87/87 綠（含新增 4 項 embed-model-config）
· cli tsc --noEmit **零錯誤**
· 三處一致性機械確認：embed.ts=bge-m3／deploy.ts=dimensions 1024／index=arcrun-kbdb-embed-m3
· 踩到並記錄：註解寫 `**dimensions=1024**​/metric` 會因 `*/` 提早關掉 block comment（TS1127）

## 既有實例遷移（尚未執行，需對實例操作）
建新 index → 重部署 kbdb（binding 指新 index）
→ POST /embed/backfill {"reindex":true} 到 remaining=0 → 舊 index 可刪。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

kbdb/src/embed.ts

@@ -13,18 +13,46 @@
 
 import type { Bindings, Entry } from './types';
 
-const EMBED_MODEL = '@cf/baai/bge-base-en-v1.5'; // 768-dim，與 Vectorize index dimensions=768 對齊
+// ── 嵌入模型（Arcrun#59：模型應可配置＋index 版本化，支援換代重刷）────────────────
+//
+// 2026-08-03 換代：`@cf/baai/bge-base-en-v1.5`（768-dim）→ `@cf/baai/bge-m3`（1024-dim）。
+//
+// 為什麼換（實測，不是憑感覺）：舊模型是**英文模型**，拿來嵌中文等於嵌一堆看不懂的 token。
+// 用 5 組中文問答測資（每組 1 問 + 2 段相關 + 3 段無關，無關的刻意放同一知識庫裡的其他主題），
+// 算 margin = min(相關分數) − max(無關分數)，margin ≤ 0 代表**排序是錯的**：
+//   @cf/baai/bge-base-en-v1.5   768   排序正確 2/5   平均 margin -0.0413   1660 ms  ← 舊
+//   @cf/google/embeddinggemma-300m  768   4/5   +0.1275   1174 ms
+//   @cf/baai/bge-m3            1024   **5/5**   **+0.1410**    959 ms  ← 新（品質最好且最快）
+//   @cf/qwen/qwen3-embedding-0.6b  1024   4/5   +0.1381   3238 ms
+// 舊模型最刺眼的一組：問「知識庫問答為什麼要標出處？」→「**會議室預約規則**」0.7789
+// 竟然高於真正相關的 0.7306。這正是 leo 2026-07-18 回報的「問 RAG 卻引用會議室規範」。
+//
+// 🔴 換模型＝**必須換 Vectorize index**，兩個理由：
+//   ① 維度不同（768→1024），舊 index 收不進新向量；
+//   ② 就算維度相同也不能沿用——不同模型的向量混在同一個 index，比對出來是垃圾，
+//      而 Arcrun#58（Vectorize vector delete 未接）代表舊向量**刪不掉**。
+//   ⇒ 開新 index 反而順手繞開 #58：新 index 天生乾淨，舊的整個丟掉。
+//
+// 換代步驟（installer 已把新 index 名與維度對齊）：建新 index → 重新部署 kbdb（binding 指新 index）
+//   → 打 backfill 的 `reindex=true`（把 embed=1 的既有 entry 全部重嵌）→ 舊 index 可刪。
+const DEFAULT_EMBED_MODEL = '@cf/baai/bge-m3'; // 1024-dim，與 Vectorize index dimensions=1024 對齊
+
+/** 實際使用的嵌入模型：env 可覆寫（#59），未設用預設。 */
+function embedModel(env: Bindings): string {
+  const m = (env.EMBED_MODEL ?? '').trim();
+  return m || DEFAULT_EMBED_MODEL;
+}
 
 /** embed 模組是否啟用（binding 都在才算開）。base 一切 embed 動作先過這關。 */
 export function embedEnabled(env: Bindings): boolean {
   return !!(env.VECTORIZE && env.AI);
 }
 
-/** 一段文字 → 768 維向量（Workers AI bge）。空字串回 null（不 embed）。 */
+/** 一段文字 → 1024 維向量（Workers AI bge-m3，可由 env.EMBED_MODEL 覆寫）。空字串回 null（不 embed）。 */
 async function embedText(env: Bindings, text: string): Promise<number[] | null> {
   const t = (text ?? '').trim();
   if (!t || !env.AI) return null;
-  const res = (await env.AI.run(EMBED_MODEL, { text: [t] })) as { data: number[][] };
+  const res = (await env.AI.run(embedModel(env), { text: [t] })) as { data: number[][] };
   return res?.data?.[0] ?? null;
 }
 
@@ -149,7 +177,7 @@ export async function backfillEmbeddings(
   const embeddable = rows.filter((e) => (e.content ?? '').trim().length > 0);
   if (embeddable.length > 0 && env.AI && env.VECTORIZE) {
     const texts = embeddable.map((e) => (e.content ?? '').trim());
-    const out = (await env.AI.run(EMBED_MODEL, { text: texts })) as { data: number[][] };
+    const out = (await env.AI.run(embedModel(env), { text: texts })) as { data: number[][] };
     const data = out?.data ?? [];
     const vectors = embeddable
       .map((e, i) => ({ e, vec: data[i] }))

kbdb/src/types.ts

@@ -16,6 +16,10 @@ export type Bindings = {
   // requires them; code checks `if (env.VECTORIZE && env.AI)` before touching embed.
   VECTORIZE?: VectorizeIndex;
   AI?: Ai;
+  // 嵌入模型（Arcrun#59）。未設＝用 embed.ts 的預設。設成別的模型時，**Vectorize index 的
+  // dimensions 必須跟著對**（維度不合 upsert 會被 CF 拒絕），且換模型必須換 index：
+  // 不同模型的向量不可共存於同一個 index（比對出來是垃圾），詳見 embed.ts 檔頭。
+  EMBED_MODEL?: string;
 };
 
 export type EntryType =