Skip to content

Commit 60620ea

Browse files
committed
feat(standalone): 维度探针改存在性判据,降级原因收口成单一枚举(#508 二轮评审)
CodeRabbit 在 #508 首轮之后提了四条,逐条落实: 1(Major)探针判据从「读一行的维度」换成**存在性**。原判据 LIMIT 1 拿 任意一条向量代表全库,在混合维度库里两个方向都错:抽到与查询不符的那条 → 明明有可比的向量却误报 degraded;首条恰好解析失败 → 其余有效向量都不 匹配时又漏报成 full。现在问的是「有没有一条活跃向量的维度等于查询维度」, 行集与 searchVector 同源(WHERE 谓词逐条相同)。 返回值扩成五态:match / mismatch / none / unreadable / invalid。 unreadable 与 none 分开——「还没有内容」与「内容在那儿却读不出来」是两种 空,后者判不出来,按 fail-closed 落 unknown,绝不因为读不到就宣称 full。 invalid 收查询维度非正整数的情形,同样不落到 full 上。 成本模型如实写进注释:一次无 LIMIT 的全 id 扫描 + 按匹配短路。全库同维度 (常态)循环第一行就返回,只解析 1 个向量;只有一条都不匹配时才走完整个 循环,而那正是要报 degraded 的情形,值得。解析复用 getParsedEmbedding 的 缓存;缓存热不热取决于 injectCandidates 是否真走了 vectorIndex 分支, 这点也写明了,没有假装它永远热。 2(Minor)降级原因收口成 src/api-standalone.js 导出的 frozen 常量 CONTEXT_DEGRADE_REASONS(六值)。此前「没装配 embedder」这条路不写 diag.reason,靠日志行的兜底表达式临时拼一个 no-embedder,而那个值不在 文档声明的枚举里;同一表达式里还躺着第二个越界字面量 embed-failed,且 它那个 embed-error 分支在 embedder 存在时一次都走不到,却会把未来任何 新增的未记账失败一律谎报成「接口抛错」。现在默认值只有决策点一个来源, 日志行不再兜底,越界或漏记账都露出 (undefined)——看得见的缺陷信号, 不是一个编出来的因。 no-embedder 保留为独立第六值、不并进 embed-unavailable:两者共用「语义路 没通」的结果,但一个是适配器坏了(异常)、一个是语义路没开(设计内常态), 并过去会让按 embed-unavailable 告警的面板对每个轻量模式安装报警。用词与 宿主面 /api/dsh-mneme/semantic 的 reason 对齐;那边是另一套同名枚举、 另一个消费者,注释里写明不要顺手统一。 3(Minor)探针自身抛异常(库被锁 / 半开 / 旧装配没这方法)不再掉进最终 .catch() 把已算好的 items 变成 500。隔离在调用侧:store 与 service 透传 都保持抛出口,不把异常吞成某个 state;api 侧判不出来就留 unknown。sentinel 不用 null/undefined——那正是「库里没有向量」的合法读数,混起来会把一次 真实的探针故障谎报成 full。 另加一层:unknown 有三个生产者(空 q / 探针没跑成 / 有行却一条都读不出), 响应体只有 tier 一个键分不出它们,而调用方对 unknown 的策略常常是「不告 警」——所以判不出来的情形另打一行 `tier left unknown: <what>`。它不是六值 的一员,运维程序不要按原因枚举解析它。 4 顺带:每处 logger 调用各自包 try/catch。logger 来自宿主,stdout 管道断裂 时 warn 自身抛错是真实可发生的,而 logger?.warn?.() 只防 logger 缺失。 测试:新增 11 条,含 - 三侧枚举契约(代码导出 / README / docs/DAEMON.md 同集合,漏改一边就红) - 六条降级路径逐个抓 warn 行断言 reason ∈ 枚举 - Major 两个场景(混合维度有可比向量→full;首条损坏其余不匹配→degraded) - 探针抛错 → unknown 且 items 不丢、绝不 500 - 探针方法缺失 / 返回垃圾 / 异步漂移 → 一律 unknown - logger 自身抛错仍 200 - 五态状态机 均已验红→绿(把探针退回 rows[0] 判据,4 条转红,含两个 Major 场景)。 本地全量 2319 passed / 0 failed,npm run sync 后 lib 与 src 一致。 Refs #508
1 parent 9a1efce commit 60620ea

9 files changed

Lines changed: 691 additions & 112 deletions

File tree

‎dsh-mneme/README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -547,13 +547,15 @@ dsh plugin --profile web add "C:/path/to/modusensus-dsh-mneme-0.9.0.tgz"
547547
|--------|------|
548548
| `full` | 语义档:查询嵌入成功,且与库里的向量维度可比 |
549549
| `degraded` | 规则档:语义路本次不可用(原因见日志) |
550-
| `unknown` | 语义路未启用(`q` 为空)——那不是降级,但也不宣称 `full` |
550+
| `unknown` | 语义路未启用(`q` 为空),或判不出来(维度探针没跑成 / 一条向量都读不出)——那不是降级,但也不宣称 `full` |
551551

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`(接口成功了,但维度与库里已有向量不一致)。
552+
**两套消费者的分工:** `tier` 是**响应读数**,给调用方——三态、fail-closed(判不出来报 `unknown`,不报 `full`),用于在集成侧告警或切换策略。降级的**具体原因**是**日志读数**,给运维——走 daemon 的 stderr(`dsh-mneme: /context degraded to the rule tier (<reason>)`),不进响应体。原因枚举六值,互不吞并(成例是「修法不同就分开」):`embed-unavailable`(无可用嵌入接口:embedder 对象在,上面没有 `embedSingle` / `embed`)/ `embed-empty`(返回了空或非数组向量)/ `embed-timeout`(接口挂起,被超时护栏按缺失处理)/ `embed-error`(接口抛错)/ `embed-dimension`(接口成功了,但库里没有一条维度相符的活跃向量)/ `no-embedder`(压根没装配 embedder——daemon `--embed off`、lightMode、宿主未装配;**这是预期态,不是故障**)。六值的唯一真源是 `src/api-standalone.js` 导出的 `CONTEXT_DEGRADE_REASONS`,契约测试从它派生断言集合。
553553

554-
`embed-dimension` 值得单说:它是「拿到了向量却不可比」——`searchVector` 对维度不符的行直接跳过,不抛错、只是命中为零,于是召回静默退回关键词/规则档,而嵌入侧一切正常。修法是重建索引,不是查端点,所以它必须和前四个分开。
554+
`embed-dimension` 值得单说:它是「拿到了向量却不可比」——`searchVector` 对维度不符的行直接跳过,不抛错、只是命中为零,于是召回静默退回关键词/规则档,而嵌入侧一切正常。修法是重建索引,不是查端点,所以它必须和前四个分开。`no-embedder` 与前四个也分开:前者(`embed-unavailable`)是适配器坏了、要修代码,后者是语义路没开、要把嵌装扮上或开起来,主体与动作都不同;并成一个值会让按 `embed-unavailable` 告警的面板对每个轻量模式安装报警。用词则与宿主面 `/api/dsh-mneme/semantic` 的 `reason` 对齐——同一个物理条件在两个面叫同一个名字(那边是另一套枚举、另一个消费者,别顺手统一)。
555555

556-
**预算:** 判档不是免费的。`q` 非空且装配了 embedder 时,一次 `/context` 真的会起一次查询嵌入(一次网络往返 + `embedTimeoutMs` 的超时窗口)——档位要回答的正是「这次嵌入成不成」。这里没有复用 `/health` 的数据源:standalone 的 `/health` 只回 `{ok:true}`,而 `embeddingDimensionBreakdown` 是宿主面的一次全表扫(每行 JSON.parse 一个向量),按请求跑会把语义路成本翻倍。维度探针因此走 `store.storedEmbeddingDimension()`——只读一行,O(1)。
556+
**`unknown` 之下的判档故障另有一条 warn:** `unknown` 有三个生产者(空 `q` / 维度探针没跑成 / 有行却一条向量都读不出来),响应体只有 `tier` 一个键、分不出它们,而调用方对 `unknown` 的策略常常是「不告警」——所以判不出来的情形会另打一行 `dsh-mneme: /context tier left unknown: <what>`(探针抛错 / 没有可读的向量可比)。**它不是上面那六值的一员**(`tier` 不是 `degraded`,没有降级原因可记),运维程序不要按原因枚举解析它。
557+
558+
**预算:** 判档不是免费的。`q` 非空且装配了 embedder 时,一次 `/context` 真的会起一次查询嵌入(一次网络往返 + `embedTimeoutMs` 的超时窗口)——档位要回答的正是「这次嵌入成不成」。这里没有复用 `/health` 的数据源:standalone 的 `/health` 只回 `{ok:true}`,而 `embeddingDimensionBreakdown` 是宿主面的一次全表扫(每行 JSON.parse 一个向量),按请求跑会把语义路成本翻倍。维度探针因此走 `service.vectorDimensionState()`——**按匹配短路的存在性判据**(有没有一条活跃向量的维度等于查询维度),不是「读一行的维度」:混合维度库里 `LIMIT 1` 会抽错维(明明有可比的向量却报 `degraded`),首条恰好解析失败时又会漏报成 `full`。成本是一次无 `LIMIT` 的全 id 扫描 + 按匹配短路的解析:全库同维度(常态)时循环第一行就返回,只解析 1 个向量;只有一条都不匹配时才走完整个循环,而那正是要报 `degraded` 的情形,值得。解析复用 `getParsedEmbedding` 的缓存,缓存热不热取决于 `injectCandidates` 是否真的走了 vectorIndex 分支。
557559

558560
### curl 示例
559561

‎dsh-mneme/docs/DAEMON.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ 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}`)也不做全表扫。
18+
`/context` 的档位信号(#383):响应多一个 `tier`(`full` 语义档 / `degraded` 规则档 / `unknown` 语义路未启用或判不出来,fail-closed),**具体降级原因只在 stderr**——`dsh-mneme: /context degraded to the rule tier (<reason>)`,不进响应体。原因是给运维的读数,六值互不吞并(成例「修法不同就分开」):`embed-unavailable` 无可用接口(embedder 对象在、缺 `embedSingle`/`embed`,修适配器)/ `embed-empty` 空向量 / `embed-timeout` 挂起 / `embed-error` 抛错 / `embed-dimension` 维度不符(有向量但没有一条与查询同维,修法是重建索引)/ `no-embedder` 压根没装配 embedder(`--embed off` / lightMode / 宿主未装配,**预期态不是故障**,修法是把嵌装扮上或开起来)。`tier` 是给调用方的读数,两套消费者分开;六值的唯一真源是 `src/api-standalone.js` 的 `CONTEXT_DEGRADE_REASONS`,契约测试从它派生。`unknown` 之下(维度探针没跑成 / 有行却一条向量都读不出来)另有一行 `dsh-mneme: /context tier left unknown: <what>`,**不是**那六值的一员(`tier` 不是 degraded,没有降级原因可记),运维程序不要按原因枚举解析它——没有它,调用方对 unknown 的策略是「不告警」时,一次真实的判档故障会整个消失。`no-embedder` 不并进 `embed-unavailable` 是故意的:那两者共用「语义路没通」的结果,但一个是适配器坏了(异常)、一个是语义路没开(设计内常态),并成一个值会让按 `embed-unavailable` 告警的面板对每个轻量模式安装报警;用词则与宿主面 `/api/dsh-mneme/semantic` 的 `reason` 对齐(那边是另一套枚举、另一个消费者,别顺手统一)。这里最值得盯的是 `embed-dimension`:嵌入接口一切正常,但库里是旧维度向量,`searchVector` 直接跳过、不抛错,召回静默退回关键词档——修法是重建索引,不是查端点。判档有成本:`q` 非空且装了 embedder 时一次 `/context` 会真起一次查询嵌入(一次往返 + `embedTimeoutMs` 窗口),维度探针本身是**按匹配短路的存在性判据**(有没有一条活跃向量与查询同维,不是 `LIMIT 1` 读一行——混合维度库里那会抽错维误报 degraded、首条损坏又会漏报 full):一次无 `LIMIT` 的全 id 扫描 + 短路解析,同维度健康库只解析 1 个向量,只有要报 degraded 时才走完全表;不复用 `/health`(它只回 `{ok:true}`)也不做全表扫。
1919

2020
CLI:
2121

0 commit comments

Comments
 (0)