Skip to content

Commit 3b2b443

Browse files
feat(runtime): 自管本地推理运行时(PR-A,issue #131) (#132)
* feat(runtime): 新增插件自管运行时的目录契约与结构检查(issue #131) profile 是所有插件共用的依赖图。@huggingface/transformers 及其原生闭包 (onnxruntime-node 解包 210 MB / tarball 86 MB、onnxruntime-web 128 MB、 sharp 19 MB)只要留在 dependencies 里,就会让「装或更新任何插件」都得重走 一遍这条链,弱网下直接把 profile 安装卡死。本提交先定义运行时落地契约与 结构检查,作为后续 adopt / install / verify 的地基;依赖声明本提交不动。 契约(<runtimeDir>/<payloadId>/): mneme-runtime.json 来源与版本清单 node_modules/ 扁平依赖闭包(与 hoisted 同形) 必须是扁平结构:transformers.node.mjs 内部全是裸导入(`import sharp`、 `import * as ONNX_NODE from "onnxruntime-node"`),按自身位置解析;把闭包按 扁平结构放好、对入口做绝对 file URL import,整套即可运行,无需动宿主 node_modules,也无需 overrides。 - src/runtime/layout.js:payloadId、defaultRuntimeDir、listPayloadDirs、 describePayload(只做结构检查,功能验证留给后续 verify 模块,避免枚举 sharp 平台分片包带来的脆性)、transformersVersionOk(只实现本包需要的 一条区间,不做通用 semver) - test/runtime-layout.test.js:11 个用例(完整 / 缺件 / 版本越界 / 平台 子树缺失 / 目录不存在) - lib/runtime/layout.js:由 npm run sync 同步 测试:全量 50/51 通过。test/peer-blockers.test.js 的「8 进程并发原子递增」 用例在本机沙箱下失败(子进程 spawn EPERM,命名管道限制),与本次改动无关, CI 环境不受影响。 * feat(runtime): 依赖闭包遍历与平台过滤(issue #131) adopt(从宿主 node_modules 收编)与 export(导出给别的机器)共用的地基: 给定源 node_modules 与入口包,算出「一份能跑的运行时需要哪些包、各自落到 哪个相对位置」。 - 按源布局镜像、不压平。入口内部是裸导入,靠 Node 逐级向上查找解析;压平会 悄悄改掉「同一个包的两个版本分别落在不同层」的解析结果——用例用 onnxruntime-web 自带的那份 onnxruntime-common 守住这条。 - 解析绝不越出源 node_modules:越出就记 gap,保证产出是自包含的。 - 平台过滤:os/cpu 支持正向匹配与 `!` 反向排除,不匹配的记进 skipped。 onnxruntime-node 单包内含三平台、sharp 走 @img/sharp-* 分片,这条是止血点。 - 可选依赖缺失静默跳过(平台分片包在别的平台就是这个形态);必需依赖缺失 才记 gap。 - 跳过 peerDependencies:宿主提供的服务实现不该被复制进插件自管的运行时。 - maxPackages 防呆上限,命中如实上报 truncated,不静默丢包。 - src/runtime/closure.js:planClosure / resolvePackageDir / matchesPlatform - test/runtime-closure.test.js:9 个用例(嵌套镜像、平台过滤、peer 排除、 可选缺失、成环终止、截断上报、入口缺失、解析边界、平台匹配语义) - lib/runtime/closure.js:由 npm run sync 同步 测试:runtime 两个测试文件 20/20 通过。 * feat(runtime): 运行时验证三件套(结构 / 功能 / 完整性) 为什么要分三层,而不是「能 import 就算通过」: - 结构:入口在不在、版本对不对、平台子树对不对、闭包有没有缺口。便宜、确定, 能立刻发现「解压到一半」。 - 功能:真的 import 入口并跑一次推理。这是唯一能证明「这份运行时在这个环境里 真的算得出来」的一层——结构全对但原生二进制与本机 ABI 不匹配时只有它能发现。 - 完整性:只对「有原始产物可比对」的来源做(下载的 tarball、本地 tarball); 收编来的目录没有原始产物,如实标 unverified,不假装验过。 - src/runtime/verify.js:verifyFunctional(断言行数一致、维度一致、L2 归一、 非退化;一切失败返回结果对象而不抛异常——验证本身必须 fail-safe,否则一条 坏运行时会把面板和状态接口一起带崩)、verifyPayload(结构不过就跳过功能 验证,省掉一次无谓的加载;integrity 由调用方传入)、defaultEngine(强制 env.allowRemoteModels = false:验证过程绝不能偷偷下载模型,否则「验证」 本身就成了新的网络依赖点) - test/runtime-verify.test.js:10 个用例,重点覆盖「坏的那几种能被抓住」—— 行数不符、非归一化向量、向量退化、加载失败、推理失败、空向量、结构不过时 跳过功能验证、unverified 不判失败、哈希不匹配时整体不通过 - lib/runtime/verify.js:由 npm run sync 同步 测试:runtime 四个测试文件 37 通过。 * feat(runtime): 收编宿主已有的运行时(硬链接 + 回退复制) 老用户 profile 里已经装好、而且能跑的那套闭包,先收进插件自管目录;后续 profile prune 掉依赖时才不会让本地嵌入断掉——这是「分两步发版」第一步的全部意义。 - src/runtime/adopt.js: · materializePackage —— 跳过嵌套 node_modules(那些包在闭包计划里是独立条目, 各自落到自己的相对位置,不跳就重复搬一遍);跳过符号链接并记 warnings (不跟随 pnpm isolated 布局指向虚拟 store 的链接,避免把宿主 store 拖进来、 也让目录层级失真);同卷走 linkSync,失败则逐个文件回退 copyFileSync。 · adoptRuntime —— 闭包计划 → 物化 → 写 mneme-runtime.json;目标已存在且未 overwrite 时拒绝;入口包未解析时返回可读原因,不抛异常。 - 回退原因如实记进清单 materialize.{mode, linkError},并整体只记一条 warning: 「收编本该不占盘却占了盘」时用户和面板要能看到原因;静默回退会让预期落空却 无从查起。link 做成可注入,本机不可复现的环境差异(跨卷 EXDEV / 权限 EPERM) 因此可测。 - test/runtime-adopt.test.js:8 个用例,含注入 EPERM 覆盖回退分支,并断言整次 收编只记一条回退原因(这条断言当场抓到了「按包去重」的真 bug)。 实测(本机真实 profile 树,源目录全程只读):闭包 49 包 / 375.0 MB;收编 3183 个文件;收编产物跑真推理通过(维度 512,约 370ms,离线)。 环境说明:本机沙箱拒绝把 workspace 之外的文件硬链接进来(EPERM),因此实测走 的是回退复制;真实插件进程无此限制,同卷(~/.dsh/mneme/runtime 与 profile 同在 C:)会走硬链接。硬链接路径由单元测试覆盖(同根目录下 linked > 0)。 * feat(runtime): 三层运行时解析加载器 self-managed runtime 缺的最后一块:插件怎么找到并加载那份运行时。 三层,缺一层都不行: - ① `~/.dsh/mneme/runtime/<payloadId>/`(收编来的或下载来的)——import 绝对 file URL 而不是改 node_modules:入口内部全是裸导入(`import sharp from "sharp"`、 `import * as ONNX_NODE from "onnxruntime-node"`),按自身位置解析,把扁平闭包放好 再用绝对 URL import 入口,整套就自洽了。 - ② 宿主裸 specifier —— PR-A 期间依赖声明不动,老用户宿主那份还在,这层保证他们 在完成收编前照常可用;等 PR-B 真的摘掉依赖、pnpm prune 掉宿主那份之后,第 ① 层顶上。 - ③ 两层都没有 —— 抛 MNEME_RUNTIME_UNAVAILABLE,带可执行的下一步(面板安装 / runtime adopt)与「每层各自为什么失败」,由调用方降级为关键词/BM25 检索。 两条不放过的细节: - 降级不许静默:第 ① 层「找到了却加载不起来」与「本机根本没有」是两件事,前者 必须经 onFailure 回吐给面板/日志,不能因为退到第 ② 层成功就当无事发生。 - 第 ③ 层的错误要能直接展示:把两层失败原因都列出来,而不是一句 module not found。 - src/runtime/loader.js:resolveRuntimeEntry / loadTransformers (importModule 可注入,测试不需要真的加载原生模块) - test/runtime-loader.test.js:6 个用例(自管优先、退回宿主、坏 payload 可见、 两层都失败的错误内容与 error.code、多 payload 取可用者、根目录不存在返回 null) - lib/runtime/loader.js:由 npm run sync 同步 测试:runtime 五个测试文件 43 通过。 * feat(runtime): 本地嵌入/重排改经三层解析加载运行时(issue #131) 接线:embedder 与 reranker 不再各自 `await import("@huggingface/transformers")`, 统一走 src/runtime/loader.js —— ① 自管 payload 优先,② 宿主裸 specifier 兜底。 - src/config.js:新增 runtimeDir(默认空字符串 = ~/.dsh/mneme/runtime) - src/index.js:把 cfg.runtimeDir 传给 createEmbedderByProvider 与 LocalReranker - src/local-embedder.js:defaultPipelineLoader 经 loadTransformers 取 module; LocalEmbedder 新增 this.runtimeDir,随 engine factory 的 options 传递 (runtimeDir 取走后不混进 transformers 的 pipeline 选项) - src/reranker.js:同样处理;_engineOptions() 带上 runtimeDir - 惰性加载语义不变:动态 import 只出现在 loader 内部,index.js 仍按需触发 (rerank 的 opt-in 门、openai 分支不加载 ONNX 都保持原样) test/config.test.js 的启动探针(防止静态导入把 onnxruntime 拉进模块加载)随之 更新判据 —— 不是放宽:原来断言 reranker.js 里存在 `await import("@huggingface/transformers")`;现在改成断言 reranker 经 runtime/loader.js 取运行时、且 loader 里才是唯一的动态 import 落点,并保留 「任何形式的静态导入都不允许」。 测试:config 4/4、local-embedder 14/14、reranker 14/14、lib-smoke 5/5、semantic 7/7。 * feat(runtime): 运行时状态探针与收编/验证入口(issue #131) - loader 新增 describeLocalRuntime:只读结构探针,functional 如实为 unknown (GET 端点不该加载原生模块跑推理);available 分支复用 resolveRuntimeEntry, 保证「状态报的那份」就是「真正加载的那份」。 - 空/空白 runtimeDir 统一按默认目录处理:配置项默认值是空串,原样传下去会变成 相对路径,把「没配」误报成「坏了」。 - /api/dsh-mneme/semantic 增加 localRuntime 字段(面板与 CLI 同源)。 - 新增 scripts/mneme-runtime.mjs:status / adopt / verify,退出码 0 健康 / 1 不健康 / 2 用法错误。不放 bin/cli.mjs —— 那个 CLI 是需服务在跑的外部 API 客户端, 而收编恰恰发生在服务没起来、插件装不上的时候。 - defaultModelCacheDir 收敛到 layout.js:embedder / reranker / verify 共用同一份, 避免漂移后「拿另一份模型去验证」而得到假证据。 - 修正上一提交里指向不存在子命令的错误提示,并加测试守住该提示路径真实存在。 本机测试 791 passed / 1 failed;唯一失败 test/peer-blockers.test.js 属环境限制 (Node 子进程 piped stdio 在本沙箱 spawn EPERM),改动前即如此,与本次无关。 * docs: 补自管运行时的收编/校验说明(issue #131) - LOCAL_MODEL.md 新增 §2.5:status / adopt / verify 三个命令、退出码语义、 「先收编再升级」的原因(profile 是全部插件共用的依赖图)。 - 修正 :16 的依赖描述:解析是三层的,且当前仍声明在 dependencies, 摘掉声明需先把运行时收编到位,否则升级后本地嵌入不可用。 - 修正缓存布局描述:实测 transformers.js 4.2.0 离线加载按 <cacheDir>/<org>/<model>/ 解析(本机验证时的报错路径即为此),与原文的 hub/models-- 布局不一致。 - README 语义增强一节补该能力与三条命令。 * test(runtime): entryUrl 断言改用 fileURLToPath 精确比较(修 Windows CI 误报) 原断言拿 file URL 字符串去 includes 一个 OS 路径字符串,会被 pathToFileURL 的 百分号编码打败(含空格等字符的路径上必误报)—— CI 的 windows-latest 上就挂了, 本机路径恰好没有这类字符所以一直没暴露。 改为断言「URL 反解回来就是那个入口文件」,并把两个值带进失败信息, 以后这类不一致能直接读出是谁错了。本机 10/10。 * fix(runtime): 按评审修收编覆盖/截断、架构校验、向量假通过与端点信息泄漏 - adopt:overwrite 前先清空目标目录。不清的话 linkSync 对已存在目标抛 EEXIST, 每个文件都掉进复制分支 —— 物化方式假报成 copy、警告错说「硬链接不可用」、 整份闭包真实占盘,且上次收编的残留文件永远清不掉。真实数据复验:49 包 / 3203 文件 / 393206416 字节,覆盖后仍为 hardlink。 - adopt:物化前拒绝 plan.truncated。结构检查只看必需包/版本/入口,截断的 payload 会被判为可用、被 loader 选中,直到 import 原生模块才失败;错误现场离原因太远。 - layout:describePayload 的 arch 参数此前文档里写了却没用(loader 也只传 platform), 于是 linux-arm64 的 payload 在 linux-x64 上能通过结构检查。现在点名到 bin/napi-v6/<平台>/<架构>(真实包结构即如此),并让 loader 把 arch 透传下去。 - verify:先逐行确认「是数组」且「全为有限数」。non-finite 会让 abs(NaN - 1) > tol 这类比较恒为 false —— 坏运行时会被判成「验证通过」,这是最危险的假通过; 非数组行还会直接抛,违背「任何失败都返回结果对象,不抛」的契约。 - api/loader:新增 publicRuntimeStatus 投影。/semantic 是免鉴权端点,而完整状态里有 runtimeDir 绝对路径、hint 内嵌的脚本路径、以及 reason/reasons 里的原始文件路径, 属于信息泄漏(CWE-200)。用精确白名单投影,完整诊断留给本机 CLI。 - reranker:补上 cache_dir → env.cacheDir 的镜像。embedder 侧早就有了(issue #13), reranker 侧一直漏着 —— 已缓存 + 离线时重排初始化会失败。 本机 801 passed / 1 failed(唯一失败为环境限制:test/peer-blockers.test.js 的 Node 子进程管道 stdio 在本沙箱 spawn EPERM,改动前即如此)。 * fix(cli): 参数解析严格化,并把 CLI 纳入测试覆盖 - 带值选项缺值时必须是用法错误(exit 2)。宽松处理会让 --runtime/--from/--cache-dir 变成 true,再被当成一个叫 "true" 的路径用下去,最后以 exit 1 收场 —— 真正的「少打一个值」被伪装成「运行时坏了」。未知选项同样立刻报错。 - 新增 test/runtime-cli.test.js:动态 import 本脚本(脚本侧加 invokedDirectly 守卫, import 不会顺带跑 CLI)。这条覆盖是被迫补的 —— 之前本文件不在任何测试覆盖里, 我在 USAGE 模板字面量里写了一个反引号把它整个截断,CI 依然全绿,脚本直接坏掉。 现在语法错会让测试当场炸。 本机:runtime-cli 4/4;三个缺值场景 + 未知选项 + 未知命令 + 无命令均实测 exit 2, 正常路径 exit 0。 * fix(cli): adopt 失败时报干净原因,并把闭包缺口纳入退出码(评审阻塞项) - runAdopt 在 adoptRuntime 返回 ok:false 时直接打印 reason 并 exit 1。此前它无条件 用 result.payloadDir,而「入口包解析不到」这条路径上该字段不存在,于是用户看到的是 TypeError: The "path" argument must be of type string. Received undefined 的堆栈 —— 而这是文档里给用户的第一条迁移命令,也是最容易踩的两种输入(profile 没装、 --from 指错目录)。 - adopt 退出码改为 structural.ok && plan.gaps.length === 0。describePayload 只点 REQUIRED_PACKAGES 那三个包,不看闭包计划的必需依赖缺口,所以「闭包缺件、入口一 import 就炸」的收编此前报 exit 0 —— 脚本化 gate 会在最需要它的时候误报健康。 - 新增 3 条 CLI 用例:源无入口包(不抛、报原因、exit 1)、缺必需传递依赖 (结构检查通过但 exit 1)、闭包完整仍 exit 0(防止上面那条修复过度触发)。 本机 804 passed / 1 failed;唯一失败仍是 test/peer-blockers.test.js 的 spawn EPERM (本环境禁止 Node 子进程管道 stdio,CI 上通过)。真实命令行复现:--from 指向没有 transformers 的目录现在输出「收编失败:入口包不存在」exit 1;真实源仍 49 包 / 3203 文件 / exit 0。 --------- Co-authored-by: Modusensus <[email protected]>
1 parent 7bbfe40 commit 3b2b443

30 files changed

Lines changed: 3424 additions & 38 deletions

‎dsh-mneme/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,9 +153,18 @@ v0.2 起新增**完全离线的语义记忆引擎**(本地模型 + 精排 +
153153
- **Rerank 精排**:`Xenova/bge-reranker-base` 对召回候选交叉编码精排,提升 Top-K 准确率
154154
- **autoDream 语义增强**:对记忆向量聚类(`clusterMemories`),自动发现主题相近 / 疑似矛盾的记忆,巩固更精准
155155
- **搜索流水线**:混合召回(关键词 + 向量)→ Rerank → Top-K
156+
- **自管运行时**:本地推理的依赖闭包(`@huggingface/transformers` + `onnxruntime-node` + `sharp`,本机实测 49 个包 / 约 393MB)可收编到 `~/.dsh/mneme/runtime/`,与 profile 的依赖图解耦——由于 profile 是所有插件共用的依赖图,这份闭包留在此前的位置会让「安装任何插件」都替它重走一遍整条依赖链;收编优先硬链接,同盘时几乎不额外占盘
156157

157158
配置只需在 `cordis.patch.yml` 里设置 `embedProvider`(默认 `openai`,保持 v0.1 行为;改为 `local` 即离线)。升级无需迁移数据。
158159

160+
```bash
161+
node scripts/mneme-runtime.mjs status # 运行时在哪、来源、结构是否完整(不加载模型)
162+
node scripts/mneme-runtime.mjs adopt --from ~/.dsh/profiles/<profile>/node_modules
163+
node scripts/mneme-runtime.mjs verify # 真加载运行时并跑一次推理
164+
```
165+
166+
> 三个命令的退出码为 `0` 健康 / `1` 不健康 / `2` 用法错误,便于脚本 gate;`--json` 输出机器可读结果。运行时不可用时不会崩——检索降级为关键词/BM25,读写不受影响。详见 [本地模型部署指南 §2.5](docs/LOCAL_MODEL.md)。
167+
159168
### 实体结构化记忆(Entity Gene)🧬
160169

161170
v0.3.0 起新增**记忆基因**层:从记忆里抽取**命名实体**、**带时间轴的属性**、**实体间关系**,让搜索从"字面关键词"升级为"按实体/属性精确召回"。

‎dsh-mneme/docs/LOCAL_MODEL.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,11 @@
1313
| GPU(可选) | 显存 ≥ 2GB | 开启 `localEmbedDevice: "gpu"`(onnxruntime 需要额外安装 cuda 后端) |
1414
| 网络 | 仅首次下载模型需要 | 已下载后可完全离线(默认走 Hugging Face,可换镜像源) |
1515

16-
> 依赖:`@huggingface/transformers`(transformers.js)已声明在插件 `package.json` 的 `dependencies`;`onnxruntime-node` 作为可选原生后端列在 `allowScripts`(首次安装需确认脚本),无需手动额外安装。
16+
> 依赖解析分三层:① **插件自管运行时目录**(`~/.dsh/mneme/runtime/`,见 §2.5,优先);② 宿主 profile 里已装的 `@huggingface/transformers`;③ 都没有则本地推理不可用,检索自动降级为关键词/BM25(读写在任何情况下都不受影响)。
17+
>
18+
> 目前插件仍把 `@huggingface/transformers` 声明在 `dependencies`,所以第 ② 层恒可用;后续版本会摘掉该声明、改由自管运行时承接。**建议提前按 §2.5 收编一份**,否则升级后本地嵌入会不可用。
19+
>
20+
> `onnxruntime-node` 作为可选原生后端列在 `allowScripts`(首次安装需确认脚本),无需手动额外安装。
1721
1822
## 2. 模型安装 / 下载
1923

@@ -31,6 +35,8 @@ node scripts/benchmark-embed.js --provider local --model Xenova/bge-small-zh-v1.
3135
- Linux/macOS:`~/.dsh/mneme/models/`
3236
- Windows:`%USERPROFILE%\.dsh\mneme\models\`
3337

38+
> 实测 transformers.js 4.2.0 在离线加载(`allowRemoteModels=false`)时按 `<cacheDir>/<org>/<model>/` 解析模型文件,例如 `<cacheDir>/Xenova/bge-small-zh-v1.5/config.json`。与本段上面描述的 `hub/models--…` 布局不一致时,以实际报错里给出的路径为准;缓存不在默认位置时按 §2.5 用 `--cache-dir` 指过去。
39+
3440
### 2.2 手动指定缓存目录
3541

3642
内存受限/离线机器可把模型缓存放到指定位置(迁移、共享缓存):
@@ -61,6 +67,32 @@ Ollama Embedder 走 `/api/embeddings`,**不下载任何文件到插件缓存**
6167
rm -rf ~/.dsh/mneme/models/hub/models--Xenova--bge-small-zh-v1.5
6268
```
6369

70+
### 2.5 自管运行时(收编 / 校验 / 排查)
71+
72+
本地推理真正要用的是一整套依赖闭包:`@huggingface/transformers` + `onnxruntime-node` + `sharp`(本机实测 49 个包、3203 个文件、约 393MB)。插件支持把它收编到自管目录 `~/.dsh/mneme/runtime/`,与宿主 profile 的依赖图解耦;收编**优先使用硬链接**,同盘时几乎不额外占盘。
73+
74+
**为什么值得提前做**:这份闭包此前留在插件 `dependencies` 里,而 profile 是所有插件共用的依赖图,于是「装任何插件」都要替它重走一遍整条链,弱网下极慢。摘掉该声明后,运行时由自管目录承接——所以要**先收编、再升级**,否则升级后本地嵌入不可用。
75+
76+
```bash
77+
# 在插件目录下运行(例如 node_modules/@modusensus/dsh-mneme)
78+
79+
# 1) 看状态:在哪、来源、结构完不完整(不加载模型,秒回)
80+
node scripts/mneme-runtime.mjs status
81+
82+
# 2) 收编宿主里已有的那份(只读源、只写自管目录,不安装任何东西)
83+
node scripts/mneme-runtime.mjs adopt --from ~/.dsh/profiles/<profile>/node_modules
84+
85+
# 3) 真加载运行时并跑一次推理,确认可用
86+
node scripts/mneme-runtime.mjs verify --cache-dir ~/.dsh/mneme/models
87+
```
88+
89+
- 退出码:`0` 健康 / `1` 不健康或失败 / `2` 用法错误(便于脚本直接 gate,区分「没装」和「装坏了」看输出里的 `status`)。加 `--json` 得到机器可读结果。
90+
- `verify` 的功能验证**不触网**(`allowRemoteModels=false`):模型必须已在缓存目录里,否则会明确失败——这是有意的,验证不该偷偷触网。缓存不在默认位置时用 `--cache-dir` 指到与 `embedModelCacheDir` 一致的位置。
91+
- 收编来的目录没有可比对的原始产物,完整性如实标 `unverified`,不假装验过;结构检查通过 ≠ 功能可用,两者分开报。
92+
- `status` 只做结构检查,所以 `functional` 恒为 `unknown`——要看真实推理结果就跑 `verify`。
93+
- 运行时不可用时插件不会崩:检索降级为关键词/BM25,读写在任何情况下都不受影响;错误信息会带上 `adopt` 的具体命令。
94+
- 同一份状态也能从 `GET /api/dsh-mneme/semantic` 的 `localRuntime` 字段读到(面板与 CLI 同源)。
95+
6496
## 3. 配置
6597

6698
### 3.1 插件配置(`~/.dsh/profiles/web/cordis.patch.yml`)

‎dsh-mneme/lib/api.js‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { TYPE_FILE, renderMirrorText, parseHumanEdits } from "./mirror.js";
66
import { langOf } from "./lang.js";
77
import { computeHeat } from "./heat.js";
88
import { describeStreamFailure, resolveRoute } from "./dream.js";
9+
import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
910

1011
// headers:少数端点(/export 附件下载)需要追加 Content-Disposition 等响应头。
1112
function sendJson(res, status, payload, headers = {}) {
@@ -616,7 +617,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
616617
modelHash: embedder?.modelHash ?? null,
617618
dimension: embedder?.dimension ?? null,
618619
reranker: semantic?.reranker ? "ready" : null,
619-
index: stats
620+
index: stats,
621+
// issue #131 / PR-A:自管运行时的状态。无论当前 provider 是不是 local
622+
// 都报 —— 面板需要区分「已收编但没启用」和「要用本地却没收编」。
623+
// 这里只做结构检查(不跑推理),失败降级成状态对象,不会让本端点 500。
624+
// 必须经 publicRuntimeStatus 投影:本端点是免鉴权的,绝对路径与原始错误
625+
// 文本不能出去(CWE-200)。完整诊断走本机 CLI 的 status。
626+
localRuntime: publicRuntimeStatus(describeLocalRuntime({ runtimeDir: config?.runtimeDir ?? "" }))
620627
});
621628
} catch {
622629
sendJson(res, 500, { error: "internal" });

‎dsh-mneme/lib/config.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,12 @@ export const Config = z.object({
138138
embedModelCacheDir: z.string().default(""),
139139
embedModelMirror: z.string().default("https://hf-mirror.com"),
140140

141+
// 自管运行时目录(issue #131)。空 = ~/.dsh/mneme/runtime:里面放收编或下载来的
142+
// transformers + onnxruntime 闭包,插件经 src/runtime/loader.js 的三层解析加载它。
143+
// 目的就是让这条重依赖不必留在宿主 profile 的依赖图里——profile 是所有插件共用的
144+
// 依赖图,留在里面会让「装任何插件都要替它重走一遍这条链」。
145+
runtimeDir: z.string().default(""),
146+
141147
// Vector search tuning.
142148
vectorSearchTopK: z.natural().min(1).max(100).default(20),
143149
vectorSearchThreshold: z.number().min(0).max(1).default(0.65),

‎dsh-mneme/lib/index.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ export const apply = (ctx, config) => {
225225
device: cfg.localEmbedDevice,
226226
batchSize: cfg.localEmbedBatchSize,
227227
cacheDir: cfg.embedModelCacheDir,
228+
runtimeDir: cfg.runtimeDir,
228229
baseUrl: cfg.ollamaBaseUrl,
229230
logger: ctx.logger
230231
});
@@ -276,6 +277,7 @@ export const apply = (ctx, config) => {
276277
scoreThreshold: cfg.rerankScoreThreshold,
277278
device: cfg.localEmbedDevice,
278279
cacheDir: cfg.embedModelCacheDir,
280+
runtimeDir: cfg.runtimeDir,
279281
logger: ctx.logger
280282
});
281283
service.setReranker(reranker);

‎dsh-mneme/lib/local-embedder.js‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
// old embedding.js logic). All classes share one interface so the orchestrator
44
// can pick a backend by provider name and degrade gracefully on failure.
55
// Methods throw on error — the caller decides the fallback chain.
6-
import os from "node:os";
7-
import path from "node:path";
6+
import { defaultModelCacheDir, defaultRuntimeDir } from "./runtime/layout.js";
7+
import { loadTransformers } from "./runtime/loader.js";
88

99
const DEFAULT_TIMEOUT_MS = 15000;
1010

@@ -20,16 +20,28 @@ function modelHash(model) {
2020
return `${model}#${hashString(model)}`;
2121
}
2222

23-
/** Lazy default loader: dynamic import keeps module load cheap. */
23+
/**
24+
* Lazy default loader: dynamic import keeps module load cheap.
25+
*
26+
* 经 runtime/loader.js 的三层解析取运行时(自管 payload 优先,其次宿主裸 specifier):
27+
* 这样 PR-B 把 @huggingface/transformers 从 dependencies 摘掉、pnpm 把宿主那份 prune
28+
* 掉之后,本地嵌入仍然可用;而在那之前,宿主那份照样能被第 ② 层兜住。
29+
* runtimeDir 从 options 里取走后再传 pipeline,免得把插件自己的配置项混进
30+
* transformers 的选项里。
31+
*/
2432
async function defaultPipelineLoader(task, model, options) {
25-
const { env, pipeline } = await import("@huggingface/transformers");
33+
const { runtimeDir, ...pipelineOptions } = options ?? {};
34+
const { module } = await loadTransformers({
35+
runtimeDir: runtimeDir || defaultRuntimeDir()
36+
});
37+
const { env, pipeline } = module;
2638
// issue #13: transformers.js's get_tokenizer_files() drops the caller's
2739
// cache_dir when it pre-checks tokenizer_config.json metadata, so the HEAD
2840
// request falls back to env.cacheDir and hits the network even when the
2941
// model is fully cached locally. Mirroring the cache_dir onto env.cacheDir
3042
// makes that pre-check resolve locally too — fully offline loading.
31-
if (options?.cache_dir) env.cacheDir = options.cache_dir;
32-
return pipeline(task, model, options);
43+
if (pipelineOptions.cache_dir) env.cacheDir = pipelineOptions.cache_dir;
44+
return pipeline(task, model, pipelineOptions);
3345
}
3446

3547
/** Flatten a transformers.js Tensor [batch, dim] into number[][]. */
@@ -56,9 +68,9 @@ export class LocalEmbedder {
5668
this._dimension = opts.dimension || 512;
5769
this.device = opts.device || "cpu";
5870
this.batchSize = opts.batchSize || 8;
59-
this.cacheDir =
60-
String(opts.cacheDir ?? "").trim() ||
61-
path.join(os.homedir(), ".dsh", "mneme", "models");
71+
this.cacheDir = String(opts.cacheDir ?? "").trim() || defaultModelCacheDir();
72+
// 自管运行时根目录(issue #131):空表示用默认位置,具体解析交给 loader。
73+
this.runtimeDir = String(opts.runtimeDir ?? "").trim();
6274
this.useDtype = opts.useDtype || "q8";
6375
this.logger = opts.logger ?? null;
6476
// Test hook: replace the pipeline factory without touching modules.
@@ -77,6 +89,8 @@ export class LocalEmbedder {
7789
device: this.device
7890
};
7991
if (this.cacheDir) options.cache_dir = this.cacheDir;
92+
// 传给注入的 engineFactory,由 defaultPipelineLoader 取走后交给三层解析。
93+
if (this.runtimeDir) options.runtimeDir = this.runtimeDir;
8094
this.extractor = await this.engineFactory("feature-extraction", this.model, options);
8195
this.ready = true; // service reads this to flush queued re-embeds
8296
this.logger?.info?.(

‎dsh-mneme/lib/reranker.js‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import os from "node:os";
2-
import path from "node:path";
1+
import { defaultModelCacheDir, defaultRuntimeDir } from "./runtime/layout.js";
2+
import { loadTransformers } from "./runtime/loader.js";
33

44
// Cross-encoder re-ranker for dsh-mneme recall candidates. Uses
55
// bge-reranker-base through transformers.js: tries the native `rerank` task
@@ -19,10 +19,24 @@ function modelHash(model) {
1919
return `${model}#${hashString(model)}`;
2020
}
2121

22-
/** Lazy default pipeline factory: dynamic import keeps module load cheap. */
22+
/**
23+
* Lazy default pipeline factory: dynamic import keeps module load cheap.
24+
*
25+
* 与 local-embedder 一样经 runtime/loader.js 的三层解析取运行时(自管 payload 优先,
26+
* 其次宿主裸 specifier),这样 PR-B 把依赖从 profile 摘掉后 rerank 也还能用。
27+
* runtimeDir 取走后不混进 transformers 的选项。
28+
*/
2329
async function defaultPipelineLoader(task, model, options) {
24-
const { pipeline } = await import("@huggingface/transformers");
25-
return pipeline(task, model, options);
30+
const { runtimeDir, ...pipelineOptions } = options ?? {};
31+
const { module } = await loadTransformers({
32+
runtimeDir: runtimeDir || defaultRuntimeDir()
33+
});
34+
const { env, pipeline } = module;
35+
// issue #13 同款处理:transformers.js 在预检 tokenizer_config.json 元数据时会丢掉调用方
36+
// 的 cache_dir,回退到 env.cacheDir —— 即使模型已完全缓存在本地也会去请求网络。
37+
// embedder 侧早就镜像了,reranker 侧一直漏着,于是「已缓存 + 离线」时重排初始化会失败。
38+
if (pipelineOptions.cache_dir) env.cacheDir = pipelineOptions.cache_dir;
39+
return pipeline(task, model, pipelineOptions);
2640
}
2741

2842
/** Flatten a transformers.js Tensor [batch, seq, dim] into number[][] rows. */
@@ -68,9 +82,9 @@ export class LocalReranker {
6882
this.maxCandidates = opts.maxCandidates || 30;
6983
this.scoreThreshold = opts.scoreThreshold ?? 0.1;
7084
this.device = opts.device || "cpu";
71-
this.cacheDir =
72-
String(opts.cacheDir ?? "").trim() ||
73-
path.join(os.homedir(), ".dsh", "mneme", "models");
85+
this.cacheDir = String(opts.cacheDir ?? "").trim() || defaultModelCacheDir();
86+
// 自管运行时根目录(issue #131):空表示用默认位置,解析交给 loader。
87+
this.runtimeDir = String(opts.runtimeDir ?? "").trim();
7488
this.logger = opts.logger ?? null;
7589
this.engineFactory = opts.engineFactory || defaultPipelineLoader;
7690
// Injectable seam: async (query, passage) => number. When set, init()
@@ -107,6 +121,7 @@ export class LocalReranker {
107121
_engineOptions() {
108122
const options = { device: this.device };
109123
if (this.cacheDir) options.cache_dir = this.cacheDir;
124+
if (this.runtimeDir) options.runtimeDir = this.runtimeDir;
110125
return options;
111126
}
112127

0 commit comments

Comments
 (0)