uncle6me-web
6846d6ddae
一、文案（portal/console/kbdb hint）：語意搜尋是一安裝就提供的功能，
降級＝故障。橫幅改「語意搜尋目前故障／我們的問題／你不用做任何事」，
拿掉「還沒開通、想開通請匯出診斷檔」這種要使用者申請開通的假框架。
kbdb 降級回應加 degraded_reason（module_off / embed_query_failed）。
二、查詢向量化失敗不再偽裝成空結果（leo 點名的謊）：
semanticSearch 舊行為「AI 額度用完 → 回 []」會讓使用者以為
自己的知識庫裡沒有這筆資料。改丟 EmbedQueryFailedError，
route 誠實降級 keyword＋照實告知是暫時故障。
三、源頭機制（裝好的實例為什麼會失去語意搜尋）：
- acr update：kbdb_embed 判斷 ===true → !==false。config 缺欄位時
redeploy 會把 [[vectorize]]+[ai] binding 靜默剝掉（wrangler deploy
整份覆蓋），一台正常實例就此壞掉。init 預設同步翻成 [Y/n]。
-（另 repo）deploy-all.mjs ensureVectorizeIndex 失敗改致命中止。
四、順手自癒：孤兒向量/下架殘影搜尋時背景清除；空結果且 pending>0
背景 backfill；no_index 拆「故障」vs「還沒有資料」兩態。
測試：kbdb 146/146（新增 degraded 6 案＋selftest 1 案）；cli 10/10；
瀏覽器端到端兩種故障畫面實測（local wrangler dev＋portal 真登入）。
無 SDD 對應：leo 直令修故障（同 08-07 檢修孔前例的人閘直接授權路徑）。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
431 lines
25 KiB
TypeScript
431 lines
25 KiB
TypeScript
// KBDB optional embed module (issue #7 / mira-dissolve SDD T2.4).
|
||
//
|
||
// 鐵律對齊：
|
||
// - embedding 屬 **base 的 optional 模組**（非 graph/ingest）。CF 內建（Vectorize+AI），程式薄。
|
||
// - **不拆 repo，binding 開/關**：有 env.VECTORIZE + env.AI 才啟用；沒有 → base 維持 LIKE keyword，API 不變。
|
||
// - 不動三表結構（只標既有 entries.is_embedded / content_hash bookkeeping 欄；那些 base 從不讀，embed 才寫）。
|
||
// - 不對每個 block 地毯式 embed（精耕，非 RAG 一股腦灌）：只 embed「被標記為 embeddable」的 entry
|
||
// （wiki 段落 + graph node gloss）。標記方式＝寫入時 metadata_json.embed === true（caller 顯式標）。
|
||
//
|
||
// 為何用 metadata flag 而非 entry_type 白名單：base 不該寫死「哪些 entry_type 該 embed」（那是上游語意，
|
||
// 會讓 base 知道 wiki/graph 概念，破壞解耦）。改由 caller（wiki/gloss 寫入端）顯式標 embed:true，
|
||
// base 只認這個通用旗標 → base 維持對內容語意無知。
|
||
|
||
import type { Bindings, Entry } from './types';
|
||
|
||
// ── 嵌入模型（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 對齊
|
||
|
||
// 🔴 2026-08-05 leo 實撞：換 bge-m3 後**語義搜尋全 0 命中**（新上傳的檔搜不到、舊檔偶爾才中）。
|
||
// 根因不在向量——實測 Vectorize 端排序完全正確（搜「閉環機」，目標檔穩坐 1-4 名）——
|
||
// 而在**分數閾值是綁在舊模型的分數尺度上的**：
|
||
// 舊 bge-base-en-v1.5：中文分數全擠 0.65-0.90（沒區辨力）⇒ t183 取 0.75 砍雜訊，對
|
||
// 新 bge-m3 ：分數尺度整體下移（相關 0.5-0.85、雜訊 0.4 上下）⇒ 0.75 砍掉的是**正解**
|
||
// youlin 實例實測分布（bge-m3，08-05，直打 Vectorize query）：
|
||
// 「閉環機」 0.638 / 0.603 / 0.588 / 0.552 ← 全是目標檔，**全被 0.75 砍光**
|
||
// ────── 斷崖 ────── 0.446 以下才是雜訊
|
||
// 「火星座標 奧林帕斯山」 0.750…0.500 全是火星座標，0.475 以下才是雜訊
|
||
// 「人力媒合系統規劃書」 0.842 ← 僥倖 >0.75 存活。**這就是 leo 看到「舊檔中、新檔不中」的由來**
|
||
// ⇒ 斷崖普遍落在 0.5 附近，取 **0.5**：相關的全留、雜訊仍砍。
|
||
// 誠實 trade-off：0.5 不是每個查詢都乾淨（實測「AI 上課名冊」0.658 的 ax-academy 會擠進來），
|
||
// 但「偶有雜訊」遠優於「什麼都搜不到」——後者是現在的狀態。
|
||
//
|
||
// 🔴 為什麼閾值住在這裡（而不是 portal）：它是**模型的性質**，不是頁面的偏好。
|
||
// 原本硬寫在 `cypher-executor/src/routes/portal-data.ts`，換模型時那裡沒人想到要改
|
||
// ——這正是 bge-m3 換代「四處同步」清單漏掉的第五處。放在模型常數旁邊，
|
||
// 下次換模型的人一定會看到它。**別再把數字複製回呼叫端。**
|
||
// 🔴 2026-08-05 二修（leo 實測「關懷型 AI」命中 20 筆、只有前 3 筆相關 ⇒「閾值設太寬？」——對）：
|
||
// **固定門檻兩頭都不對**，因為每個查詢的分數尺度不一樣：
|
||
// 查詢 正解區間 雜訊起點
|
||
// 關懷型 AI 0.645-0.770 0.547 ← 固定 0.5 會放進 6 筆雜訊
|
||
// 閉環機 0.552-0.638 0.446 ← 固定 0.6 會把正解砍到剩 2/4（＝今早那個 0 命中）
|
||
// 人力媒合系統規劃書 0.842 0.550
|
||
// ⇒ 改成**相對門檻**：跟著這次查詢的最高分走，取 `max(絕對下限, top × 比例)`。
|
||
// 實測五組（上表＋「閉環機是什麼」「火星座標 奧林帕斯山」）：
|
||
// 固定 0.5 → 正解全留，但混入 9 筆雜訊
|
||
// 固定 0.6 → 雜訊 0，但「閉環機」兩組正解被砍到 2/4、1/4
|
||
// 相對 → 四組雜訊 0 且正解全留；「火星座標」留 3/6
|
||
// （被砍的是同一份檔的其他段落，使用者照樣找得到那份檔）
|
||
// 絕對下限的作用：整批分數都很低時（查詢與知識庫無關），純比例會讓垃圾等比放行 ⇒ 兜底。
|
||
const MIN_SCORE_ABS_FLOOR = 0.45;
|
||
const MIN_SCORE_TOP_RATIO = 0.8;
|
||
|
||
/**
|
||
* 相對門檻：由「這批結果的最高分」推出要砍在哪。
|
||
*
|
||
* 🔴 為什麼不在 semanticSearch 裡直接套（寫測試時才發現的真問題，不是 fixture 過時）：
|
||
* Vectorize 端**不知道哪些已下架**（indexed metadata 沒有 status，見 upsert）。
|
||
* 若最高分那筆是已下架的殘影（實測有 0.971 這種），拿它當基準算出的門檻
|
||
* 會把真正的正解（0.6）一起砍光 ⇒ **又變成 0 命中**，正是 leo 08-05 早上撞的那個病。
|
||
* ⇒ 門檻必須在「hydrate＋濾掉下架」**之後**、對倖存者的最高分計算（見 routes/entries.ts）。
|
||
*/
|
||
export function relativeMinScore(topScore: number): number {
|
||
return Math.max(MIN_SCORE_ABS_FLOOR, topScore * MIN_SCORE_TOP_RATIO);
|
||
}
|
||
|
||
/** 實際使用的嵌入模型：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);
|
||
}
|
||
|
||
/** 一段文字 → 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(embedModel(env), { text: [t] })) as { data: number[][] };
|
||
return res?.data?.[0] ?? null;
|
||
}
|
||
|
||
/**
|
||
* 寫入時選擇性 embed（embed-on-write，#5 第4點併入此）。
|
||
* - 模組未開 → no-op（base 輕量）。
|
||
* - 只 embed 被標 embeddable 的 entry（metadata_json.embed === true）。其餘略過（非地毯式）。
|
||
* 失敗不致命（fire-and-forget 由 caller 用 waitUntil 包；這裡只負責「能 embed 就 embed」）。
|
||
* 回傳是否真的 embed 了（讓 caller 決定要不要標 is_embedded）。
|
||
*/
|
||
export async function embedOnWrite(env: Bindings, entry: Entry): Promise<boolean> {
|
||
if (!embedEnabled(env)) return false;
|
||
if (!isEmbeddable(entry)) return false;
|
||
const vec = await embedText(env, entry.content ?? '');
|
||
if (!vec) return false;
|
||
await env.VECTORIZE!.upsert([
|
||
{
|
||
id: entry.id,
|
||
values: vec,
|
||
// metadata 走 indexed 範圍：owner_id（租戶隔離）、entry_type、source（#5.1 過濾與語義共用）、
|
||
// library（portal-auth P1「庫」filter）。library 在寫入端正規化：未標記＝'general'（design §3.2
|
||
// 「未蓋章的舊資料視同 general」——D1 側用查詢端 COALESCE fallback，Vectorize filter 做不了
|
||
// COALESCE，故在 upsert 時蓋 'general'，查詢端單純 $in 即可）。
|
||
metadata: {
|
||
owner_id: entry.owner_id ?? '',
|
||
entry_type: entry.entry_type,
|
||
source: readSource(entry) ?? '',
|
||
library: readLibrary(entry) ?? 'general',
|
||
},
|
||
},
|
||
]);
|
||
// 標記 bookkeeping（既有欄，base 不讀、僅供「已 embed」可查）。不動表結構。
|
||
await env.DB.prepare('UPDATE entries SET is_embedded = 1 WHERE id = ?').bind(entry.id).run();
|
||
return true;
|
||
}
|
||
|
||
/** entry 是否該被 embed：caller 在 metadata_json 標 embed:true（精耕，非地毯式）。 */
|
||
function isEmbeddable(entry: Entry): boolean {
|
||
const meta = parseMeta(entry.metadata_json);
|
||
return meta?.embed === true;
|
||
}
|
||
|
||
function readSource(entry: Entry): string | null {
|
||
const meta = parseMeta(entry.metadata_json);
|
||
const s = meta?.source;
|
||
return typeof s === 'string' ? s : null;
|
||
}
|
||
|
||
/** metadata_json.$.library（portal-auth P1）。非字串/空字串一律視同未標記（→ caller fallback 'general'）。 */
|
||
function readLibrary(entry: Entry): string | null {
|
||
const meta = parseMeta(entry.metadata_json);
|
||
const l = meta?.library;
|
||
return typeof l === 'string' && l.trim() !== '' ? l : null;
|
||
}
|
||
|
||
function parseMeta(json: string | null): Record<string, unknown> | null {
|
||
if (!json) return null;
|
||
try {
|
||
const p = JSON.parse(json);
|
||
return p && typeof p === 'object' ? (p as Record<string, unknown>) : null;
|
||
} catch {
|
||
return null;
|
||
}
|
||
}
|
||
|
||
// SQL predicate for "an entry that SHOULD be embedded but isn't yet".
|
||
// - isEmbeddable 契約 = metadata_json.embed === true（base 通用旗標，對內容語意無知，不寫死 entry_type）。
|
||
// SQLite json_extract 對 JSON boolean true 回整數 1 → `= 1` 精確對齊 TS 的 `=== true`。
|
||
// - is_embedded = 0：尚未（對「當前」index）補嵌的 bookkeeping。
|
||
// - content 非空：空字串 embedText 會回 null，排除以免變成永遠清不掉的殘留候選。
|
||
const BACKFILL_PREDICATE =
|
||
"is_embedded = 0 AND content IS NOT NULL AND content <> '' AND json_extract(metadata_json, '$.embed') = 1";
|
||
|
||
export interface BackfillResult {
|
||
enabled: boolean; // 模組是否開（false → 什麼都沒做，caller 該誠實回錯，不假裝）。
|
||
processed: number; // 本次真的嵌進 Vectorize 並標 is_embedded=1 的筆數。
|
||
skipped: number; // 掃到但沒嵌（例如 embedText 回 null）的筆數。
|
||
remaining: number; // 本次之後仍待補嵌的筆數（可重複呼叫直到 0）。
|
||
scanned: number; // 本批掃出的候選筆數（受 limit 限制）。
|
||
}
|
||
|
||
/**
|
||
* Backfill（回填）：對「開 Vectorize 之前就寫入、或 embed-on-write 當時漏掉」的既有 entry 批次補嵌。
|
||
* 冪等（重跑已補嵌的不會重複算，upsert 同 id 冪等）、分批（單次 limit 上限，避開 subrequest/CPU/timeout）、
|
||
* 回傳處理筆數 + 剩餘筆數（caller 重複呼叫直到 remaining=0）。
|
||
* - 模組未開（無 VECTORIZE+AI）→ 誠實回 { enabled:false }，不假裝成功（mindset §7 禁假綠）。
|
||
* - 只補「isEmbeddable（metadata.embed===true）且 is_embedded=0」的 entry——與 embedOnWrite 同一契約，
|
||
* base 維持對內容語意無知（不知 triplet/wiki，只認通用 embed 旗標）。
|
||
* - 效率：整批用「單次 AI.run（陣列輸入）+ 單次 VECTORIZE.upsert（陣列）+ 單次 UPDATE ... IN(...)」，
|
||
* 一批 ≈ 3 個 subrequest，不隨 limit 線性增長 → free/paid tier 都安全。
|
||
*/
|
||
export async function backfillEmbeddings(
|
||
env: Bindings,
|
||
opts: { limit?: number; owner_id?: string; source?: string; reindex?: boolean; offset?: number } = {},
|
||
): Promise<BackfillResult> {
|
||
if (!embedEnabled(env)) return { enabled: false, processed: 0, skipped: 0, remaining: 0, scanned: 0 };
|
||
const limit = Math.min(Math.max(opts.limit ?? 25, 1), 100);
|
||
const offset = Math.max(opts.offset ?? 0, 0);
|
||
|
||
// reindex（Arcrun#11 根因修復）：對「既有已嵌」向量原樣重嵌重推 upsert，讓它們被『事後才建立』的
|
||
// Vectorize metadata index（owner_id/entry_type/source）收錄。Vectorize 只索引「metadata index
|
||
// 建立之後 upsert」的向量 → 既有向量不重推就永遠 filter 不到（= 本 bug）。upsert 同 id 冪等。
|
||
// 非 reindex（預設）＝原行為：只補 is_embedded=0 的漏網。
|
||
const basePredicate = opts.reindex
|
||
? "content IS NOT NULL AND content <> '' AND json_extract(metadata_json, '$.embed') = 1"
|
||
: BACKFILL_PREDICATE;
|
||
|
||
// 🔴 2026-08-05：**已下架的一律不嵌**（leo：「理論上它的向量也要刪掉，就不會有殘影了吧？」）。
|
||
// 沒有這條，下架時清掉的向量會在下一次 backfill 又被嵌回來 ⇒ 殘影復活，
|
||
// 而且 `reindex=true` 那條路更嚴重（它連 is_embedded=1 的都重推）。
|
||
const conds = [basePredicate, "COALESCE(json_extract(metadata_json, '$.status'), '') != 'deprecated'"];
|
||
const params: unknown[] = [];
|
||
if (opts.owner_id) { conds.push('owner_id = ?'); params.push(opts.owner_id); }
|
||
if (opts.source) { conds.push("json_extract(metadata_json, '$.source') = ?"); params.push(opts.source); }
|
||
const where = conds.join(' AND ');
|
||
|
||
const res = await env.DB
|
||
.prepare(`SELECT * FROM entries WHERE ${where} ORDER BY created_at ASC LIMIT ? OFFSET ?`)
|
||
.bind(...params, limit, offset)
|
||
.all<Entry>();
|
||
const rows = res.results ?? [];
|
||
const scanned = rows.length;
|
||
|
||
let processed = 0;
|
||
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(embedModel(env), { text: texts })) as { data: number[][] };
|
||
const data = out?.data ?? [];
|
||
const vectors = embeddable
|
||
.map((e, i) => ({ e, vec: data[i] }))
|
||
.filter((x): x is { e: Entry; vec: number[] } => Array.isArray(x.vec) && x.vec.length > 0)
|
||
.map((x) => ({
|
||
id: x.e.id,
|
||
values: x.vec,
|
||
metadata: {
|
||
owner_id: x.e.owner_id ?? '',
|
||
entry_type: x.e.entry_type,
|
||
source: readSource(x.e) ?? '',
|
||
library: readLibrary(x.e) ?? 'general', // 同 embedOnWrite：寫入端正規化（P1）
|
||
},
|
||
}));
|
||
if (vectors.length > 0) {
|
||
await env.VECTORIZE.upsert(vectors);
|
||
const ids = vectors.map((v) => v.id);
|
||
const placeholders = ids.map(() => '?').join(',');
|
||
await env.DB.prepare(`UPDATE entries SET is_embedded = 1 WHERE id IN (${placeholders})`).bind(...ids).run();
|
||
processed = vectors.length;
|
||
}
|
||
}
|
||
|
||
const remRow = await env.DB
|
||
.prepare(`SELECT COUNT(*) as c FROM entries WHERE ${where}`)
|
||
.bind(...params)
|
||
.first<{ c: number }>();
|
||
const totalMatching = remRow?.c ?? 0;
|
||
// 非 reindex：predicate 含 is_embedded=0，處理後該筆變 1 → COUNT 自然遞減（重呼直到 0）。
|
||
// reindex：predicate 不含 is_embedded，COUNT 恆等於總數 → 改用 offset 分頁計 remaining（否則永不終止）。
|
||
const remaining = opts.reindex ? Math.max(0, totalMatching - (offset + scanned)) : totalMatching;
|
||
return { enabled: true, processed, skipped: scanned - processed, remaining, scanned };
|
||
}
|
||
|
||
/** 補嵌進度統計（回報用；模組未開仍可查 pending 數，誠實標 enabled:false）。 */
|
||
export async function backfillStatus(
|
||
env: Bindings,
|
||
opts: { owner_id?: string; source?: string } = {},
|
||
): Promise<{ enabled: boolean; pending: number; embedded: number }> {
|
||
const conds: string[] = [];
|
||
const params: unknown[] = [];
|
||
if (opts.owner_id) { conds.push('owner_id = ?'); params.push(opts.owner_id); }
|
||
if (opts.source) { conds.push("json_extract(metadata_json, '$.source') = ?"); params.push(opts.source); }
|
||
const extra = conds.length ? ` AND ${conds.join(' AND ')}` : '';
|
||
const pendingRow = await env.DB
|
||
.prepare(`SELECT COUNT(*) as c FROM entries WHERE ${BACKFILL_PREDICATE}${extra}`)
|
||
.bind(...params)
|
||
.first<{ c: number }>();
|
||
const embeddedRow = await env.DB
|
||
.prepare(`SELECT COUNT(*) as c FROM entries WHERE is_embedded = 1 AND json_extract(metadata_json, '$.embed') = 1${extra}`)
|
||
.bind(...params)
|
||
.first<{ c: number }>();
|
||
return { enabled: embedEnabled(env), pending: pendingRow?.c ?? 0, embedded: embeddedRow?.c ?? 0 };
|
||
}
|
||
|
||
export interface SelfTestResult {
|
||
enabled: boolean; // embed 模組是否開（binding 都在）
|
||
tested: boolean; // 是否真的跑了一次自我查詢（false＝連測都測不了，非失敗）
|
||
passed: boolean | null; // 拿已嵌入卡片的內容查自己，能不能搜到自己（null＝沒測）
|
||
note: string; // 給人看的一句話結論，供檢修孔診斷檔直接引用
|
||
}
|
||
|
||
/**
|
||
* Embed 自我檢查（檢修孔用，2026-08-07 leo 直接指令：「先把檢修孔做出來發版」）。
|
||
*
|
||
* 為什麼需要這個，不只是 backfillStatus 的 pending/embedded 計數：08-05 撞過的真實故障
|
||
* 是「is_embedded=1（已嵌入）但語義搜尋還是搜不到」——metadata index 事後才建，既有向量
|
||
* 沒被收錄（Arcrun#11）。計數看不出這種病，因為計數只問「有沒有嵌」，不問「嵌完查得到嗎」。
|
||
* 本函式挑一筆「已標記已嵌入」的既有 entry，拿它自己的內容做一次真實語義查詢，檢查
|
||
* 「自己是否搜得到自己」——這是唯一能端到端驗證 index 真的可用的方法。
|
||
*
|
||
* 隱私邊界（檢修孔規格紅線：診斷檔不准帶卡片內容本體）：本函式只回布林 + 一句話 note，
|
||
* 不回傳卡片內容、不回傳 entry id。取樣內容只在函式內部這一次查詢中用過即丟。
|
||
*/
|
||
export async function embedSelfTest(
|
||
env: Bindings,
|
||
opts: { owner_id?: string } = {},
|
||
): Promise<SelfTestResult> {
|
||
if (!embedEnabled(env)) {
|
||
return { enabled: false, tested: false, passed: null, note: 'embed 模組未開（缺 Vectorize/AI binding），語義搜尋這條路目前不存在' };
|
||
}
|
||
const conds = ["is_embedded = 1", "content IS NOT NULL AND content <> ''"];
|
||
const params: unknown[] = [];
|
||
if (opts.owner_id) { conds.push('owner_id = ?'); params.push(opts.owner_id); }
|
||
const where = conds.join(' AND ');
|
||
const row = await env.DB
|
||
.prepare(`SELECT * FROM entries WHERE ${where} ORDER BY updated_at DESC LIMIT 1`)
|
||
.bind(...params)
|
||
.first<Entry>();
|
||
if (!row) {
|
||
return { enabled: true, tested: false, passed: null, note: '尚無任何卡片被標記為「已嵌入」，無法自我檢查（可能是還沒卡片，也可能是嵌入從未成功過）' };
|
||
}
|
||
const sample = (row.content ?? '').trim().slice(0, 200);
|
||
if (!sample) {
|
||
return { enabled: true, tested: false, passed: null, note: '取樣卡片內容為空，跳過自我檢查' };
|
||
}
|
||
// min_score:0——自我檢查要看「找不找得到」，不能被查詢端的相對門檻先濾掉。
|
||
let hits: SemanticHit[] | null;
|
||
try {
|
||
hits = await semanticSearch(env, sample, { owner_id: opts.owner_id, topK: 10, min_score: 0 });
|
||
} catch (e) {
|
||
if (e instanceof EmbedQueryFailedError) {
|
||
// 向量化本身失敗（額度用完/模型故障）＝「這條路現在是斷的」，誠實回報，不算 passed/failed。
|
||
return { enabled: true, tested: false, passed: null, note: `自我檢查沒跑成：${e.message}（語義搜尋此刻同樣會故障，多半是 Workers AI 額度或服務問題）` };
|
||
}
|
||
throw e;
|
||
}
|
||
if (hits === null) {
|
||
return { enabled: false, tested: false, passed: null, note: 'embed 模組回報未開（binding 檢查期間消失，罕見）' };
|
||
}
|
||
const passed = hits.some((h) => h.id === row.id);
|
||
return {
|
||
enabled: true,
|
||
tested: true,
|
||
passed,
|
||
note: passed
|
||
? '拿一張已標記「已嵌入」的卡片自我查詢，能搜到自己——語義搜尋這條路是通的'
|
||
: '拿一張已標記「已嵌入」的卡片自我查詢，卻搜不到自己——像是 index 沒收錄到這批向量（需要重新 reindex）',
|
||
};
|
||
}
|
||
|
||
export interface SemanticHit {
|
||
id: string;
|
||
score: number;
|
||
owner_id?: string;
|
||
entry_type?: string;
|
||
source?: string;
|
||
library?: string;
|
||
}
|
||
|
||
/**
|
||
* 查詢向量化失敗（2026-08-09 leo 直令：「查詢的向量化如果失敗（例如當天額度用完），
|
||
* 目前會回一個空的結果集——那是騙人，不是降級」）。
|
||
*
|
||
* 舊行為：embedText 拿不到向量 → semanticSearch 回 []，caller 分不出
|
||
* 「真的沒命中」和「根本沒查成」，使用者看到「查無資料」，以為知識庫裡沒有這筆東西。
|
||
* 新行為：AI.run 丟錯（額度用完/模型故障）或回不出向量 → 丟這個錯，
|
||
* 由 route 層誠實降級 keyword ＋告知「這是我們的故障」，不再偽裝成空結果。
|
||
*/
|
||
export class EmbedQueryFailedError extends Error {
|
||
constructor(detail: string) {
|
||
super(`查詢向量化失敗：${detail}`);
|
||
this.name = 'EmbedQueryFailedError';
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 語義搜尋（mode:'semantic'）。模組未開 → 回 null（caller 降級 keyword + 告知缺能力）。
|
||
* owner_id / source / entry_type 過濾走 Vectorize metadata filter（entry_type 已 index，見上 upsert metadata）。
|
||
* entry_type 是 base 通用 filter（caller 傳任意 type，base 不寫死語意）。
|
||
* library（portal-auth P1）：多值庫 filter 走 `$in`（官方支援已核實 2026-07-14：文件明列 $in/$nin＋
|
||
* workers-types 原生 typing；design §3.3 的 fan-out fallback 不需啟用）。未帶＝行為不變。
|
||
* 註：向量 metadata 的 library 在寫入端已正規化（未標記＝'general'），故 $in 不需 NULL 處理；
|
||
* 但「建 library metadata index 之前」upsert 的既有向量沒有此欄 → 部署清單強制 reindex backfill。
|
||
* min_score（issue #67）：分數閾值——Vectorize 只會硬湊 topK 筆，低分尾全是無關內容；
|
||
* 過濾放查詢端（非 Vectorize 端，API 無此參數）。
|
||
* 🔴 2026-08-05 起預設＝`DEFAULT_MIN_SCORE`（跟著模型走，見該常數的實測分布），
|
||
* 不再是 0（0＝不過濾＝#67 要修的病本身，而呼叫端各自硬寫數字則是 08-05 全 0 命中的根因）。
|
||
* caller 顯式傳值仍優先。
|
||
*/
|
||
export async function semanticSearch(
|
||
env: Bindings,
|
||
q: string,
|
||
opts: { owner_id?: string; source?: string; entry_type?: string; library?: string[]; topK?: number; min_score?: number } = {},
|
||
): Promise<SemanticHit[] | null> {
|
||
if (!embedEnabled(env)) return null;
|
||
// 空查詢＝真的沒東西可查（route 層已擋 q 必填，這裡只兜底），不算故障。
|
||
if (!(q ?? '').trim()) return [];
|
||
// 🔴 2026-08-09（leo 直令）：向量化失敗**不准**回空結果集。空結果=「你的庫裡沒有」，
|
||
// 向量化失敗=「我們沒查成」——兩者對使用者是完全不同的事實，混在一起就是說謊。
|
||
let vec: number[] | null;
|
||
try {
|
||
vec = await embedText(env, q);
|
||
} catch (e) {
|
||
throw new EmbedQueryFailedError(e instanceof Error ? e.message : String(e));
|
||
}
|
||
if (!vec) throw new EmbedQueryFailedError('Workers AI 沒有回出向量（回應形狀異常或空回應）');
|
||
const filter: VectorizeVectorMetadataFilter = {};
|
||
if (opts.owner_id) filter.owner_id = opts.owner_id;
|
||
if (opts.source) filter.source = opts.source;
|
||
if (opts.entry_type) filter.entry_type = opts.entry_type;
|
||
if (opts.library && opts.library.length > 0) filter.library = { $in: opts.library };
|
||
const res = await env.VECTORIZE!.query(vec, {
|
||
topK: Math.min(opts.topK ?? 20, 100),
|
||
returnMetadata: 'indexed',
|
||
...(Object.keys(filter).length ? { filter } : {}),
|
||
});
|
||
// 這裡只套**絕對下限**；相對門檻要等「濾掉已下架」之後才能算（見 relativeMinScore 的註解）。
|
||
const minScore = opts.min_score ?? MIN_SCORE_ABS_FLOOR;
|
||
return (res.matches ?? [])
|
||
.filter((m) => m.score >= minScore)
|
||
.map((m) => ({
|
||
id: m.id,
|
||
score: m.score,
|
||
owner_id: m.metadata?.owner_id as string | undefined,
|
||
entry_type: m.metadata?.entry_type as string | undefined,
|
||
source: m.metadata?.source as string | undefined,
|
||
library: m.metadata?.library as string | undefined,
|
||
}));
|
||
}
|