Skip to content

Commit 4954f7b

Browse files
committed
feat(standalone): /context 补 embed-dimension 档位并把 tier 扫进文档(#508 评审)
#508 评审三点,逐条落实: 1. 「维度不符」此前被 embed-error 吸收,但它不是同一件事:前四个原因是 「没拿到向量」,维度不全是「拿到了却不可比」——searchVector 对 `v.length !== vector.length` 的行直接跳过(distill-tx-embed-gap 的 处置),不抛错、只是命中为零,召回静默退回关键词/规则档,而嵌入侧 一切正常。这正是 issue #383 点名的那一种悄悄退化,且原来的实现根本 观测不到它(嵌入成功即报 full)。现在单开 embed-dimension 一档。 检测用 store.storedEmbeddingDimension():只读一行,O(1)。不复用 embeddingDimensionBreakdown——那是给 /semantic 状态页用的全表扫 (每行 JSON.parse 一个向量),按请求跑会把语义路成本翻倍,且它不在 standalone 的装配里。库里没有向量时探针回 null,继续报 full: 「没有东西可比」与「维度对不上」是两种空,不能压成一个读数。 2. 判档预算写进注释与两份文档:q 非空且装了 embedder 时,一次 /context 真的会起一次查询嵌入(一次网络往返 + embedTimeoutMs 的超时窗口), 因为档位要回答的正是「这次嵌入成不成」。 3. 文档扫面补齐:README 外部 API 段新增「/context 的 tier 档位信号」小节 (三态表 + 五值原因 + 预算),docs/DAEMON.md §2 同步,并写明两套消费者 的分工——tier 是响应读数(给调用方),diag.reason 是日志读数(给运维, 走 daemon stderr,不进响应体)。CHANGELOG 那条是 #370 的历史发布记录, 按仓内约定不动。 测试:补「维度不符报 degraded」与「库里没有向量不算维度不符」两条, 均已验红→绿(把检测短路掉,前者转红)。 Refs #508
1 parent 84b63dc commit 4954f7b

9 files changed

Lines changed: 205 additions & 19 deletions

File tree

‎dsh-mneme/README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -535,10 +535,26 @@ dsh plugin --profile web add "C:/path/to/modusensus-dsh-mneme-0.9.0.tgz"
535535
| `PUT` | `/memories/:id` | 局部更新 `{title?,content?,type?,importance?,tags?,reason?,agent_scope?,workspace_scope?}`;content 改写按 human_override 入档 |
536536
| `DELETE` | `/memories/:id` | 删除记忆 |
537537
| `GET` | `/search?q&mode=keyword\|vector\|hybrid\|auto&topK&occurred_from&occurred_to&agent_scope&workspace_scope` | 搜索(关键词 / 向量 / hybrid=向量领位关键词补位 / 自动)。scope 两参声明调用方身份(不传 = 不解析,行为与旧版一致;任一给出则 strictScope 硬过滤与 A2 软加权随之生效) |
538-
| `GET` | `/context?q&topK&threshold&agent_scope&workspace_scope` | 注入候选一站式聚合(issue #370,#363 承诺):宿主注入管线 `injectCandidates` 全语义(优先级分层 / 编码门控 / heat / scope 软加权 / hybrid 语义路 / pin 前置)+ 画像 + 规则,返回 `{profile, rules, items, pinnedCount}` 结构化条目,不含渲染文本。`threshold` 是 **importance 阈值**(默认 3,与 `/search` 的相似度阈值同名不同义);`topK` 默认 5(对齐宿主 `maxInjectedItems`);scope 语义与 `/search` 同口径;跨轮轮换 / 热记忆 / 时间前缀不含(调用方自管);recall_runs 注入分账与宿主注入同口径(#217 `mode='inject'`) |
538+
| `GET` | `/context?q&topK&threshold&agent_scope&workspace_scope` | 注入候选一站式聚合(issue #370,#363 承诺):宿主注入管线 `injectCandidates` 全语义(优先级分层 / 编码门控 / heat / scope 软加权 / hybrid 语义路 / pin 前置)+ 画像 + 规则,返回 `{profile, rules, items, pinnedCount, tier}` 结构化条目,不含渲染文本。`threshold` 是 **importance 阈值**(默认 3,与 `/search` 的相似度阈值同名不同义);`topK` 默认 5(对齐宿主 `maxInjectedItems`);scope 语义与 `/search` 同口径;跨轮轮换 / 热记忆 / 时间前缀不含(调用方自管);recall_runs 注入分账与宿主注入同口径(#217 `mode='inject'`) |
539539
| `POST` | `/bootstrap` | 冷启动(v0.8.4):从仓库目录反向构建初始记忆,body `{dir}` 必填;幂等((type,title,scope) 去重 + `_overwrite` 原地刷新),零 LLM、必有产出 |
540540
| `POST` | `/maintenance/reclaim` | 无损回收(#275 / #411,与面板同口径):**只有 POST**(独立面没有 GET 预估分支)。字段只从 JSON body 读;`dryRun` 默认 `true`,只有 `dryRun:false` 且 `confirm:true` 才真删;`vacuum` 只允许显式指定 |
541541

542+
#### `/context` 的 `tier` 档位信号(#383)
543+
544+
`GET /context` 的响应多一个 `tier` 字段,回答「这次注入跑在哪一档」。嵌入降级在调用方视角原本完全静默——`items` 看着正常,只是召回质量悄悄变差,外部集成方无从感知自己长期跑在降级档上。
545+
546+
| `tier` | 含义 |
547+
|--------|------|
548+
| `full` | 语义档:查询嵌入成功,且与库里的向量维度可比 |
549+
| `degraded` | 规则档:语义路本次不可用(原因见日志) |
550+
| `unknown` | 语义路未启用(`q` 为空)——那不是降级,但也不宣称 `full` |
551+
552+
**两套消费者的分工:** `tier` 是**响应读数**,给调用方——三态、fail-closed(判不出来报 `unknown`,不报 `full`),用于在集成侧告警或切换策略。降级的**具体原因**是**日志读数**,给运维——走 daemon 的 stderr(`dsh-mneme: /context degraded to the rule tier (<reason>)`),不进响应体。原因枚举五值,互不吞并:`embed-unavailable`(无可用嵌入接口)/ `embed-empty`(返回了空或非数组向量)/ `embed-timeout`(接口挂起,被超时护栏按缺失处理)/ `embed-error`(接口抛错)/ `embed-dimension`(接口成功了,但维度与库里已有向量不一致)。
553+
554+
`embed-dimension` 值得单说:它是「拿到了向量却不可比」——`searchVector` 对维度不符的行直接跳过,不抛错、只是命中为零,于是召回静默退回关键词/规则档,而嵌入侧一切正常。修法是重建索引,不是查端点,所以它必须和前四个分开。
555+
556+
**预算:** 判档不是免费的。`q` 非空且装配了 embedder 时,一次 `/context` 真的会起一次查询嵌入(一次网络往返 + `embedTimeoutMs` 的超时窗口)——档位要回答的正是「这次嵌入成不成」。这里没有复用 `/health` 的数据源:standalone 的 `/health` 只回 `{ok:true}`,而 `embeddingDimensionBreakdown` 是宿主面的一次全表扫(每行 JSON.parse 一个向量),按请求跑会把语义路成本翻倍。维度探针因此走 `store.storedEmbeddingDimension()`——只读一行,O(1)。
557+
542558
### curl 示例
543559

544560
```bash

‎dsh-mneme/docs/DAEMON.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ daemon 是**数据面**,不是第二个宿主:
1515

1616
路由面 = `src/api-standalone.js` 全表(health/status/profile/rules/memories 读写/search/context/maintenance/bootstrap),鉴权同源(Bearer + timingSafeEqual,`GET /health` 免鉴权)。daemon 自身零新路由;#370 的 `/context` 落在 api-standalone 工厂里,宿主外部访问与 daemon 自动同享(参数、scope 语义与 recall_runs 注入分账见包 README 路由表)。daemon 侧唯一自有选项是 `strictPort`(见 §4)。
1717

18+
`/context` 的档位信号(#383):响应多一个 `tier`(`full` 语义档 / `degraded` 规则档 / `unknown` 语义路未启用,fail-closed),**具体降级原因只在 stderr**——`dsh-mneme: /context degraded to the rule tier (<reason>)`,不进响应体。原因是给运维的读数(`embed-unavailable` 无接口 / `embed-empty` 空向量 / `embed-timeout` 挂起 / `embed-error` 抛错 / `embed-dimension` 维度不符),`tier` 是给调用方的读数,两套消费者分开。这里最值得盯的是 `embed-dimension`:嵌入接口一切正常,但库里是旧维度向量,`searchVector` 直接跳过、不抛错,召回静默退回关键词档——修法是重建索引,不是查端点。判档有成本:`q` 非空且装了 embedder 时一次 `/context` 会真起一次查询嵌入(一次往返 + `embedTimeoutMs` 窗口),维度探针本身是 O(1)(只读一行),不复用 `/health`(它只回 `{ok:true}`)也不做全表扫。
19+
1820
CLI:
1921

2022
```bash

‎dsh-mneme/lib/api-standalone.js‎

Lines changed: 40 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -227,8 +227,15 @@ async function handlePutBody(res, service, logger, id, text) {
227227
* (embedSingle 优先,兼容 embed-only 的 OpenAI 兼容客户端,issue #10)。
228228
* 调用方负责 catch——嵌入失败降级规则档,绝不因此 500。
229229
*
230-
* `diag`(optional,issue #383):拿不到向量时把原因写进去(`embed-unavailable`
231-
* 无可用接口 / `embed-empty` 空或非数组向量),供 daemon 侧日志枚举降级原因。
230+
* `diag`(optional,issue #383):拿不到向量时把原因写进去,供 daemon 侧日志枚举
231+
* 降级原因。五值,互不吞并:
232+
* embed-unavailable 无可用接口(embedder 上没有 embedSingle / embed)
233+
* embed-empty 接口返回了,但向量是空数组 / 非数组
234+
* embed-timeout 接口挂起,被 embedTimeoutMs 护栏按缺失处理
235+
* embed-error 接口抛错(HTTP 4xx/5xx、网络、解析失败……)
236+
* embed-dimension 接口成功了,但维度与库里已有向量不一致
237+
* 前四个是「没拿到向量」,第五个是「拿到了却不可比」——分开是因为修法不同:
238+
* 前者查嵌入配置与端点,后者查「是不是换了模型、旧向量该重建索引了」。
232239
* 不传则行为与既往逐字节一致。
233240
*/
234241
async function embedQueryVector(embedder, q, diag) {
@@ -256,7 +263,7 @@ async function embedQueryVector(embedder, q, diag) {
256263
* 无害;挂起的主要成本是一个泄漏的挂起任务,可接受。嵌入先完成时清掉定时器
257264
* (CodeRabbit 同轮 Minor:别让每个请求都留一枚要等满超时的计时器)。
258265
*
259-
* `diag`(optional,issue #383):超时写 `embed-timeout`,与上面两个原因同一套枚举。
266+
* `diag`(optional,issue #383):超时写 `embed-timeout`,与上面几个原因同一套枚举。
260267
*/
261268
function withEmbedTimeout(promise, timeoutMs, diag) {
262269
let timer;
@@ -688,8 +695,8 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
688695
const threshold = Number.isFinite(thresholdRaw) ? thresholdRaw : 3;
689696
const scope = scopeFromSearchParams(url);
690697
// #383:降级原因记账用。embedQueryVector / withEmbedTimeout 只负责「拿不到
691-
// 向量时返回 undefined」,原因(无可用接口 / 空向量 / 超时)在这里回收,
692-
// 供 daemon 侧日志枚举——响应体只多 tier 一个键,不加第二个字段。
698+
// 向量时返回 undefined」,原因(无可用接口 / 空向量 / 超时 / 抛错 / 维度不符)
699+
// 在这里回收,供 daemon 侧日志枚举——响应体只多 tier 一个键,不加第二个字段。
693700
const diag = {};
694701
void Promise.resolve(q && embedder ? withEmbedTimeout(embedQueryVector(embedder, q, diag), embedTimeoutMs, diag) : undefined)
695702
.catch((err) => { diag.reason = "embed-error"; return undefined; }) // 查询嵌入失败降级规则档(与 searchMemories 同口径)
@@ -699,15 +706,39 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
699706
// #383 档位信号:嵌入降级在调用方视角原本完全静默(items 看着正常,只是
700707
// 召回质量悄悄变差),外部集成方无从感知自己长期跑在降级档上。
701708
// 三态 fail-closed——判不出来报 unknown,不报 full:
702-
// full 语义档,查询嵌入真的成功了
703-
// degraded 规则档,且是因为 embedder 缺 / 嵌入超时 / 不可用向量
709+
// full 语义档,查询嵌入真的成功了且与库里的向量可比
710+
// degraded 规则档:embedder 缺 / 嵌入超时 / 不可用向量 / 抛错 /
711+
// 维度不符(拿到了向量但语义召回整个不可用)
704712
// unknown 语义路未启用(空 q)——那不是降级,但也不能宣称 full
705713
// 比 /search 的 mode 更精确:/search 把「空查询」和「向量失败」都报
706714
// keyword,这里能分开(空 q 直接可观测)。
715+
//
716+
// 预算:判档不是免费的——q 非空且配了 embedder 时,它真的会起一次查询
717+
// 嵌入(一次网络往返 + embedTimeoutMs 的超时窗口),因为档位要回答的
718+
// 正是「这次嵌入成不成」。这里**没有**复用宿主 /health 那份现成数据源:
719+
// standalone 的 /health 只回 {ok:true},而 embeddingDimensionBreakdown
720+
// 是 src/api.js 里的一次全表扫(每行 JSON.parse 一个向量),按请求跑会
721+
// 把语义路成本翻倍,且它根本不在 standalone 的装配里。所以维度探针用
722+
// store.storedEmbeddingDimension()——只读一行,O(1)。
707723
let tier = "unknown";
708-
if (q && queryVector) tier = "full";
709-
else if (q) {
724+
if (q && queryVector) {
725+
const storedDim = typeof service.storedEmbeddingDimension === "function"
726+
? service.storedEmbeddingDimension()
727+
: null;
728+
if (typeof storedDim === "number" && storedDim !== queryVector.length) {
729+
// 维度不符:searchVector 对不等长的行直接跳过(见 store.js 的
730+
// distill-tx-embed-gap 注释),不抛错、只是命中为零——于是召回静默
731+
// 退回 BM25/规则档,而嵌入侧一切正常。这是 issue #383 点名的那一种
732+
// 「悄悄退化」,必须有自己的名字:修法是重建索引,不是查端点。
733+
diag.reason = "embed-dimension";
734+
tier = "degraded";
735+
} else {
736+
tier = "full";
737+
}
738+
} else if (q) {
710739
tier = "degraded";
740+
}
741+
if (tier === "degraded") {
711742
logger?.warn?.(`dsh-mneme: /context degraded to the rule tier (${diag.reason ?? (embedder ? "embed-failed" : "no-embedder")})`);
712743
}
713744
sendJson(res, 200, {

‎dsh-mneme/lib/service.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2670,6 +2670,10 @@ export function createService({ store, mirror, config, onWrite, logger, document
26702670
// passthrough 形状与 embeddedCount 同款,api 层不直接摸 store。
26712671
embeddingModelBreakdown: () => store.embeddingModelBreakdown(),
26722672
embeddingDimensionBreakdown: () => store.embeddingDimensionBreakdown(),
2673+
// #383:O(1) 的维度探针(读一行,不扫表),供 /context 判「维度不符」。
2674+
// 与上面那个全表扫的 breakdown 是两件事:一个是状态页的完整分布,一个是
2675+
// 每请求用得起的布尔信号。透传而非让 api 层摸 store,与同组其他条目一致。
2676+
storedEmbeddingDimension: () => store.storedEmbeddingDimension(),
26732677
list: (o) => store.list(o),
26742678
all: () => store.all(),
26752679
count: (type, opts) => store.count(type, opts),

‎dsh-mneme/lib/store.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1801,6 +1801,36 @@ export function createStore(path) {
18011801
}, new Map());
18021802
}
18031803

1804+
/**
1805+
* 库里已有向量的维度——**只读一行**,不是 embeddingDimensionBreakdown 的全表扫。
1806+
*
1807+
* #383 要的是「查询嵌入成功了,但语义召回其实死了」这个读数。它的成因是维度
1808+
* 不符:searchVector 对 `v.length !== vector.length` 的行直接跳过(见下方
1809+
* distill-tx-embed-gap 注释),换了嵌入模型之后旧维度向量整个不可比,而这条路
1810+
* **不抛错**——嵌入侧、检索侧都一切正常,只是命中数为零。调用方从响应上看不出
1811+
* 任何异常,这正是 issue #383 点名的那一种「悄悄退化」。
1812+
*
1813+
* 为什么不用 embeddingDimensionBreakdown:那是给 /semantic 状态页用的全表扫
1814+
* (每行 JSON.parse 一个向量),按请求跑一遍会把语义路的成本翻一倍。这里只要
1815+
* 一个「不一致」的布尔信号,一行足够;混合维度的完整分布仍归状态页。
1816+
*
1817+
* @returns {number|null} 首个可解析向量的维度;库里没有可用向量时 null
1818+
* (那不是维度不符,是没有东西可比——两种空的读数必须分开)。
1819+
*/
1820+
function storedEmbeddingDimension() {
1821+
const row = db.prepare(
1822+
`SELECT embedding FROM memories
1823+
WHERE embedding IS NOT NULL AND embedding != ''
1824+
AND forgotten = 0 AND archived = 0
1825+
LIMIT 1`
1826+
).get();
1827+
if (!row) return null;
1828+
try {
1829+
const parsed = JSON.parse(row.embedding);
1830+
return Array.isArray(parsed) && parsed.length ? parsed.length : null;
1831+
} catch { return null; }
1832+
}
1833+
18041834
function search(query, { limit = 20, includeArchived = false } = {}) {
18051835
const q = String(query).trim();
18061836
if (!q) return [];
@@ -3367,6 +3397,7 @@ export function createStore(path) {
33673397
hasStaleEmbedding,
33683398
embeddingModelBreakdown,
33693399
embeddingDimensionBreakdown,
3400+
storedEmbeddingDimension,
33703401
searchVector,
33713402
saveDreamRun,
33723403
lastDreamRunAt,

0 commit comments

Comments
 (0)