Skip to content

Commit 6a521d7

Browse files
authored
Merge pull request #594 from slow-stack/fix/embedding-cache-hot-path
perf(store): 向量解析缓存跟工作集自适应,并摘掉只取 id 的扫描上读整列向量的谓词
2 parents 4bf2f2a + cfb5406 commit 6a521d7

7 files changed

Lines changed: 502 additions & 60 deletions

File tree

‎dsh-mneme/lib/dream/clustering.js‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
// Cosine similarity of two equal-length numeric vectors. Returns 0 for empty
22
// or mismatched-length inputs, and for zero-norm vectors (numerically stable).
3+
// Accepts typed arrays (Float32Array) as well as plain arrays: store.js caches
4+
// vectors as Float32Array and `Array.isArray` is false for typed arrays — guarding
5+
// on it alone would silently score every cached vector as 0.
6+
const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
7+
38
export function cosineSimilarity(a, b) {
4-
if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) return 0;
9+
if (!isVec(a) || !isVec(b) || a.length === 0 || a.length !== b.length) return 0;
510
let dot = 0, na = 0, nb = 0;
611
for (let i = 0; i < a.length; i++) {
712
dot += a[i] * b[i];

‎dsh-mneme/lib/service.js‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -516,9 +516,12 @@ export function createService({ store, mirror, config, onWrite, logger, document
516516
// Weighted blend factor for hybrid search; exposed so callers can tune it.
517517
const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
518518

519-
// Cosine over two plain arrays (shared by the search-time semantic dedup).
519+
// Cosine over two numeric vectors (shared by the search-time semantic dedup).
520+
// Accepts typed arrays too — the store's cache holds Float32Array, and
521+
// `Array.isArray` is false for typed arrays (would score everything 0).
520522
function cosineVec(a, b) {
521-
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
523+
const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
524+
if (!isVec(a) || !isVec(b) || a.length !== b.length || !a.length) return 0;
522525
let dot = 0, na = 0, nb = 0;
523526
for (let i = 0; i < a.length; i++) {
524527
dot += a[i] * b[i];

‎dsh-mneme/lib/store.js‎

Lines changed: 102 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1514,35 +1514,99 @@ export function createStore(path) {
15141514
// Issue #202:embedding 解析缓存。检索路径此前每次调用都对全部带向量行
15151515
// JSON.parse(993 × 512 维 ≈ 48 ms/次,且 SQL 拖着 10 MB 的 TEXT),余弦本身
15161516
// 只占 3%。向量只经 setEmbedding 写入(单一失效点),把解析结果按 id 缓存,
1517-
// 命中即零解析;上限 FIFO 驱逐防大库内存无界(4000 × 512 维 double ≈ 16 MB)。
1517+
// 命中即零解析。
1518+
//
1519+
// 上限为什么不能是固定常量(2026-11-05 实测):上限 4000、活跃带向量行 6685,
1520+
// 扫到第 4001 条开始驱逐自己刚填的条目,扫完只剩最后 4000 条,下一轮又从第
1521+
// 一条 miss——四轮实测命中率恒 0.0%,缓存等于不存在,每次检索都全量重解析
1522+
// (实测 624 ms)。固定调大只是把复发推到下个月(活跃行近 30 天净增 6156 条,
1523+
// 上限 20000 也只撑到 2027-01-09),所以上限跟工作集自适应:
1524+
// · 每次全量扫(searchVector / vectorDimensionState)在循环前把上限抬到
1525+
// 「本次扫到的行数 ×1.25」,一次扫完不会被自己的驱逐打断;
1526+
// · 内存预算封顶(默认 256 MB),超预算的行仍按 FIFO 驱逐——大库退化回
1527+
// 「部分命中」,不会无界吃内存。
1528+
// 存储用 Float32Array。同一口径(GC 后 heapUsed + arrayBuffers,6730 条
1529+
// 1024 维全常驻)实测:number[] 56.4MB → Float32Array 29.7MB(heap 1.9 +
1530+
// arrayBuffers 27.8),省 26.7MB / 47%。注意 heapUsed 不统计 TypedArray 的
1531+
// 底层 ArrayBuffer,只看 heapUsed 会读成「省 96%」的假象;旧实现若保持上限
1532+
// 4000 则装不下工作集(常驻 31.9MB 但命中率 0%),两者不可比,所以对照组是
1533+
// 把旧上限抬到 20000 让工作集全常驻。cosine 全量 25.4ms → 18.0ms,前 50 条
1534+
// 排序精度差 0.00e+0。对外契约不变:
1535+
// getParsedEmbedding / getEmbeddings 仍返回 number[],只有内部热路径
1536+
// (readVector)拿 Float32Array。
15181537
const embeddingCache = new Map();
1519-
const EMBEDDING_CACHE_MAX = 4000;
1538+
const EMBEDDING_CACHE_FLOOR = 4000;
1539+
const EMBEDDING_CACHE_BUDGET_BYTES = 256 * 1024 * 1024;
1540+
let embeddingCacheCap = EMBEDDING_CACHE_FLOOR;
1541+
let embeddingCacheHits = 0;
1542+
let embeddingCacheMisses = 0;
1543+
1544+
/** Vector-like = number[] or Float32Array (typed). All cosine guards use this
1545+
* instead of Array.isArray, which is false for typed arrays — with the old
1546+
* guard every cached vector would silently score 0. */
1547+
function isVectorLike(v) {
1548+
return Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
1549+
}
15201550

15211551
function cacheEmbedding(id, vector) {
1522-
if (embeddingCache.size >= EMBEDDING_CACHE_MAX && !embeddingCache.has(id)) {
1552+
if (embeddingCache.size >= embeddingCacheCap && !embeddingCache.has(id)) {
15231553
const oldest = embeddingCache.keys().next().value;
15241554
embeddingCache.delete(oldest);
15251555
}
15261556
embeddingCache.set(id, vector);
15271557
}
15281558

1529-
/** Parsed embedding for one id (cache-first); undefined when none/parse
1530-
* failure. Single read path shared by searchVector / getEmbedding(s). */
1531-
function getParsedEmbedding(id) {
1559+
/** Raise the cap to fit a sweep of `rows` rows (×1.25 headroom), clamped by
1560+
* the memory budget. Called before a full scan so the scan itself does not
1561+
* evict what it just cached. */
1562+
function noteSweep(rows, avgDim) {
1563+
if (!rows || !avgDim) return;
1564+
const perVector = avgDim * Float32Array.BYTES_PER_ELEMENT;
1565+
const budgetRows = Math.floor(EMBEDDING_CACHE_BUDGET_BYTES / perVector);
1566+
const want = Math.ceil(rows * 1.25);
1567+
embeddingCacheCap = Math.max(EMBEDDING_CACHE_FLOOR, Math.min(budgetRows, want));
1568+
}
1569+
1570+
/** Cache-first read returning Float32Array (internal hot path only).
1571+
* undefined when none/parse failure. */
1572+
function readVector(id) {
15321573
const cached = embeddingCache.get(id);
1533-
if (cached) return cached;
1574+
if (cached) { embeddingCacheHits += 1; return cached; }
1575+
embeddingCacheMisses += 1;
15341576
const row = db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
15351577
if (!row?.embedding) return undefined;
15361578
try {
1537-
const v = JSON.parse(row.embedding);
1538-
if (Array.isArray(v) && v.length) {
1579+
const parsed = JSON.parse(row.embedding);
1580+
if (Array.isArray(parsed) && parsed.length) {
1581+
const v = new Float32Array(parsed);
15391582
cacheEmbedding(id, v);
15401583
return v;
15411584
}
15421585
} catch { /* corrupt embedding text: treated as absent */ }
15431586
return undefined;
15441587
}
15451588

1589+
/** Parsed embedding for one id (cache-first); undefined when none/parse
1590+
* failure. Single read path shared by searchVector / getEmbedding(s).
1591+
* Public contract: returns number[] (callers guard with Array.isArray). */
1592+
function getParsedEmbedding(id) {
1593+
const v = readVector(id);
1594+
return v ? Array.from(v) : undefined;
1595+
}
1596+
1597+
/** Cache instrumentation for the regression lock (hit rate must not collapse
1598+
* back to 0 when the working set outgrows a fixed cap). */
1599+
function embeddingCacheStats() {
1600+
const total = embeddingCacheHits + embeddingCacheMisses;
1601+
return {
1602+
size: embeddingCache.size,
1603+
cap: embeddingCacheCap,
1604+
hits: embeddingCacheHits,
1605+
misses: embeddingCacheMisses,
1606+
hitRate: total ? embeddingCacheHits / total : 0
1607+
};
1608+
}
1609+
15461610
// all()/list() 的显式列清单:从实际 schema 派生(迁移后),只排除 embedding
15471611
// 列——consolidation/sleep/inject 的消费方都不读向量,而它是全表里最重的一列
15481612
// (5k 行库 ≈ 9.4 MB TEXT),每次全表调用都白搬。经 PRAGMA 派生而非硬编码,
@@ -2413,7 +2477,10 @@ export function createStore(path) {
24132477
* name; omitting modelHash leaves the column untouched (callers that
24142478
* predate the column still work, their rows simply read as unknown). */
24152479
function setEmbedding(id, vector, modelHash) {
2416-
const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
2480+
// isVectorLike 而非 Array.isArray:调用方可能递进 Float32Array(本模块缓存的
2481+
// 就是它)。旧守卫对 typed array 返回 false,会把「设置向量」读成「清空向量」,
2482+
// 静默把行改成 NULL。
2483+
const json = isVectorLike(vector) && vector.length ? JSON.stringify(Array.from(vector)) : null;
24172484
if (json) {
24182485
if (modelHash !== undefined) {
24192486
db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?")
@@ -2426,15 +2493,10 @@ export function createStore(path) {
24262493
}
24272494
// Issue #202:单一写入口即单一失效点——重写缓存条目(向量在手上不必重解析),
24282495
// 清空则移除,删除过的 id 不会被下一次 searchVector 的 id 集合选中。
2429-
if (json) {
2430-
try {
2431-
const parsed = JSON.parse(json);
2432-
if (Array.isArray(parsed) && parsed.length) cacheEmbedding(id, parsed);
2433-
else embeddingCache.delete(id);
2434-
} catch { embeddingCache.delete(id); }
2435-
} else {
2436-
embeddingCache.delete(id);
2437-
}
2496+
// 缓存里存 Float32Array(与 readVector 同一表示),不存 JSON.parse 出来的
2497+
// number[],否则写后第一次读还要再转一次。
2498+
if (json) cacheEmbedding(id, new Float32Array(vector));
2499+
else embeddingCache.delete(id);
24382500
}
24392501

24402502
/** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
@@ -2595,18 +2657,21 @@ export function createStore(path) {
25952657
*/
25962658
function vectorDimensionState(dimension) {
25972659
if (!Number.isInteger(dimension) || dimension <= 0) return { state: "invalid" };
2598-
// 与 searchVector 的 WHERE 谓词逐条相同(顺序不同、语义等价)——同源行集,同步改。
2660+
// 与 searchVector 的行集逐条相同(顺序不同、语义等价)——同源行集,同步改。
2661+
// 同样不带 `embedding != ''`:只取 id,读 embedding 列纯属白搬;空串行由
2662+
// readVector 返回 undefined,落到下面 sawVector 分支(不影响 unreadable 判定)。
25992663
const rows = db.prepare(
26002664
`SELECT id FROM memories
2601-
WHERE embedding IS NOT NULL AND embedding != ''
2665+
WHERE embedding IS NOT NULL
26022666
AND forgotten = 0 AND archived = 0`
26032667
).all();
26042668
if (!rows.length) return { state: "none" };
26052669
let sawVector = false;
2670+
noteSweep(rows.length, dimension);
26062671
for (const row of rows) {
2607-
// 走 getParsedEmbedding 的解析缓存,不自己 JSON.parse——与 searchVector /
2608-
// getEmbedding(s) 同一条读路径,缓存热时零解析。
2609-
const v = getParsedEmbedding(row.id);
2672+
// 走同一解析缓存,不自己 JSON.parse——与 searchVector / getEmbedding(s)
2673+
// 同一条读路径,缓存热时零解析。
2674+
const v = readVector(row.id);
26102675
if (!v || !v.length) continue;
26112676
sawVector = true;
26122677
if (v.length === dimension) return { state: "match" };
@@ -2640,7 +2705,7 @@ export function createStore(path) {
26402705
// --- vector search ------------------------------------------------------
26412706

26422707
function cosine(a, b) {
2643-
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
2708+
if (!isVectorLike(a) || !isVectorLike(b) || a.length !== b.length || !a.length) return 0;
26442709
let dot = 0;
26452710
let na = 0;
26462711
let nb = 0;
@@ -2663,13 +2728,22 @@ export function createStore(path) {
26632728
// Issue #202:只取 id 列(~40 KB)而非 SELECT *(~11 MB)——向量从缓存取,
26642729
// 缓存未命中时按 id 点查 embedding 再解析回填。SQL 里保留 embedding 的
26652730
// IS NOT NULL 过滤,保证「有向量的行」集合始终以库为准(删除/清空即时生效)。
2731+
//
2732+
// 为什么不带 `embedding != ''`(2026-11-05 实测):`!= ''` 要读 embedding 列
2733+
// 才能判定,SQLite 就得把 134MB 向量文本整个从磁盘搬一遍——而这里只 SELECT
2734+
// id,一条文本都不用。真库副本实测:这条 SQL 单独跑 265ms → 96ms;落到
2735+
// 一轮完整检索上是 138ms → 47ms(省约 90ms,其余是解析/打分开销)。
2736+
// 空串行(外部直接 UPDATE 造出来的,setEmbedding 写的是 NULL)由 readVector
2737+
// 兜住:JSON.parse('') 抛错 → 返回 undefined → 跳过,既不计分也不崩。
26662738
const rows = db.prepare(
26672739
`SELECT id FROM memories
2668-
WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL AND embedding != ''`
2740+
WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL`
26692741
).all();
26702742
const scored = [];
2743+
// 自适应上限:本次要扫这么多行,先让缓存装得下,否则会边扫边驱逐自己。
2744+
noteSweep(rows.length, vector.length);
26712745
for (const row of rows) {
2672-
const v = getParsedEmbedding(row.id);
2746+
const v = readVector(row.id);
26732747
if (!v) continue;
26742748
// distill-tx-embed-gap 顺带修:维度不匹配的行按维度分流,直接跳过。旧路径
26752749
// 喂进 cosine 不等长就 return 0,换了模型/维度的旧向量以 0 分混进结果尾部
@@ -5082,6 +5156,7 @@ export function createStore(path) {
50825156
setEmbedding,
50835157
getEmbeddings,
50845158
getParsedEmbedding,
5159+
embeddingCacheStats,
50855160
embeddedCount,
50865161
needsEmbedding,
50875162
needsEmbeddingFor,

‎dsh-mneme/src/dream/clustering.js‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
// Cosine similarity of two equal-length numeric vectors. Returns 0 for empty
22
// or mismatched-length inputs, and for zero-norm vectors (numerically stable).
3+
// Accepts typed arrays (Float32Array) as well as plain arrays: store.js caches
4+
// vectors as Float32Array and `Array.isArray` is false for typed arrays — guarding
5+
// on it alone would silently score every cached vector as 0.
6+
const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
7+
38
export function cosineSimilarity(a, b) {
4-
if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) return 0;
9+
if (!isVec(a) || !isVec(b) || a.length === 0 || a.length !== b.length) return 0;
510
let dot = 0, na = 0, nb = 0;
611
for (let i = 0; i < a.length; i++) {
712
dot += a[i] * b[i];

‎dsh-mneme/src/service.js‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -516,9 +516,12 @@ export function createService({ store, mirror, config, onWrite, logger, document
516516
// Weighted blend factor for hybrid search; exposed so callers can tune it.
517517
const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
518518

519-
// Cosine over two plain arrays (shared by the search-time semantic dedup).
519+
// Cosine over two numeric vectors (shared by the search-time semantic dedup).
520+
// Accepts typed arrays too — the store's cache holds Float32Array, and
521+
// `Array.isArray` is false for typed arrays (would score everything 0).
520522
function cosineVec(a, b) {
521-
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
523+
const isVec = (v) => Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
524+
if (!isVec(a) || !isVec(b) || a.length !== b.length || !a.length) return 0;
522525
let dot = 0, na = 0, nb = 0;
523526
for (let i = 0; i < a.length; i++) {
524527
dot += a[i] * b[i];

0 commit comments

Comments
 (0)