dsh-intel-npu

English | 中文

把 DeepSeek Harness 的知识库检索放到 Intel NPU 上跑：在进程内提供本地 OpenAI 兼容的 embeddings 与 rerank 服务，不依赖 Python，也不需要额外常驻进程。

dsh-knowledge 默认在 CPU 上为每个分块和每次查询做向量化。本插件把这部分工作交给 Intel NPU（AI Boost），并可按配置自动把 dsh-knowledge 指向自己。

dsh-knowledge ──/v1/embeddings──┐
               ──/v1/rerank─────┤   dsh-intel-npu（跑在 DSH 自己的 web 服务里）
                                └──▶ openvino-node ──▶ Intel NPU

为什么需要它

DSH 本身不做本地推理——对话走 DeepSeek 云端。知识库增强场景下唯一的本地推理就是 embedding 与 rerank，而它原本跑在 onnxruntime-node 的 CPU 上。Core Ultra 机器上的 NPU 就这样闲着；本插件把它擅长的工作（固定形状、可批处理、容忍延迟的向量运算）交给它。

兼容性

| | | |---|---| | DSH | >=0.1.5-rc.3 <0.2.0 或 >=0.2.0-rc.1 <0.3.0 | | Node.js | >=21 | | 硬件 | Intel Core Ultra（Meteor Lake 及更新），NPU 驱动正常 | | 平台 | Windows x64（依赖的 openvino-node 提供 win-x64 运行时） |

先确认驱动：npu_status 会报出设备列表；没有可用 NPU 的机器会直接拒绝服务。

安装

1. 先放行运行时构建脚本。 openvino-node 靠 postinstall 下载约 227 MB 的 OpenVINO 运行时，而 npm / pnpm 默认拦截这类脚本。必须在安装前把它加入 profile 的白名单，否则依赖 装上了却没有运行时。

profile 目录下的 pnpm-workspace.yaml（%USERPROFILE%\.dsh\profiles\<名称>\pnpm-workspace.yaml）：

allowBuilds:
  openvino-node: true

（若用 npm 安装，则在 .npmrc 的 allow-scripts 里加上 openvino-node。）

2. 安装 bundle。

dsh plugin --profile web add dsh-intel-npu

3. 重启 DSH。 模型在启动后台加载：embedding 几秒可用，rerank 首次较慢（见「耗时」）。

提供的能力

• /intel-npu/v1/embeddings —— OpenAI 格式，512 维，CLS 池化 + L2 归一化 （Xenova/bge-small-zh-v1.5，fp32）
• /intel-npu/v1/rerank —— {query, documents[], top_n} → {results:[{index, relevance_score}]}，分数在 [0,1] （Xenova/bge-reranker-base，fp32）
• /intel-npu/health、/intel-npu/status、/intel-npu/config、/intel-npu/reindex —— 供脚本与面板查询、控制
• 浏览器状态面板（/intel-npu/）—— 打开 http://127.0.0.1:<DSH 端口>/intel-npu/ 即可看到设备与模型状态、耗时、流量统计、dsh-knowledge 接线情况，并可一键触发重建索引。 它是由插件自己渲染的单个自包含 HTML 文档；为何不作为 UI 插槽见下文。
• npu_status 与 npu_reindex 工具 —— 给 agent 用
• 自动接线：默认通过 dsh-knowledge 自己的设置路由写入六个 provider 字段 （embeddingProvider: openai、rerankModel: … 及两个 base URL）。设 autoConfigureKnowledge: false 可改为手工配置。

所有接口都挂在 DSH 现有 HTTP 服务的 /intel-npu 前缀下——不占额外端口、不起额外进程。

为什么不做成 UI 插槽

DSH 插件可以通过 dsh.client 与 @deepseek-ai/dsh-client-ui-slots / dsh-client-runtime 往 Web 客户端里注册 React 组件。本插件刻意没有那么做：

• 这两个包在发行树里没有任何文档——没有 README、没有可对照的类型说明；
• 它们在 DSH 各版本间并不一致：0.1.5 树里两个包都不存在，0.2.x 则把它们塞在桌面版的 app.asar 里，因此一份 dsh.client.inject 列表无法同时服务两条线；
• 写插槽意味着要额外提供构建后的客户端 bundle，给一个本来纯 ESM 的插件引入构建链。

而由插件自己渲染页面，在各版本上行为一致、无需构建、还能用 curl 直接检查。 若你确实想要嵌入式面板，/intel-npu/status 的 JSON 就是现成的数据源。

int8 陷阱（为什么必须 fp32）

dsh-knowledge 下载的是 int8 量化 ONNX。NPU 会照常编译它，然后静默返回错误结果—— 不报错、不告警：

| 模型 | 文件 | NPU 上的结果 | |---|---|---| | bge-small-zh-v1.5 | model_quantized.onnx | 句向量余弦 0.44（对比 CPU，纯垃圾） | | bge-small-zh-v1.5 | model.onnx（fp32） | 余弦 0.999998 ✅ | | bge-reranker-base | model_quantized.onnx | 排序一致率 50%（等于随机） | | bge-reranker-base | model.onnx（fp32） | 排序一致率 100% ✅ |

因此本插件只解析 onnx/model.onnx（fp32），绝不回退到量化文件，并且在 requireFp32: true（默认）下直接拒绝量化路径。若你手工接线，请继续使用本插件下载的 fp32 文件。

耗时实测

Core Ultra 9 185H（Meteor Lake，NPU 3720），512 token 输入，两模型均 fp32，已预热：

| 环节 | CPU | NPU | | |---|---|---|---| | embedding，bge-small-zh-v1.5 | 46.5 ms | 21 ms | 2.2× | | rerank，bge-reranker-base | 227.7 ms | 约 70 ms | 3.4× |

编译每进程一次，在 NPU 上完成，且驱动会缓存：

• embedding：约 0.2–2 s
• rerank：驱动缓存命中时 约 2 s；1.06 GB fp32 模型首次编译 约 18 s

因为加载在后台进行，DSH 不会为此等待；模型就绪前接口返回 503，dsh-knowledge 会自动退回原始排序。

配置

在 profile 的 patch 层（cordis.patch.yml）中设置，或在你自己的 patch 里覆盖该行：

| 字段 | 默认 | 含义 | |---|---|---| | device | NPU | OpenVINO 设备：NPU、GPU、CPU | | modelCacheDir | <DSH_HOME>/cache/dsh-intel-npu/models | fp32 权重目录 | | hfEndpoint | '' | 镜像站，如 https://hf-mirror.com；空则读 HF_ENDPOINT 环境变量，否则 huggingface.co | | embedding.enabled | true | 是否提供 embedding | | embedding.model | Xenova/bge-small-zh-v1.5 | HF 仓库 id | | embedding.maxLength | 512 | NPU 固定序列长度 | | rerank.enabled | true | 是否提供 rerank | | rerank.model | Xenova/bge-reranker-base | HF 仓库 id | | rerank.maxLength | 512 | NPU 固定序列长度 | | autoConfigureKnowledge | true | 自动把 dsh-knowledge 指向本服务 | | requireFp32 | true | 拒绝量化权重 | | autoDownload | true | 缺文件时从 Hugging Face 下载 | | requestTimeoutMs | 120000 | HTTP 时间预算 |

模型目录结构

<modelCacheDir>/Xenova/bge-small-zh-v1.5/
    onnx/model.onnx          fp32（自动下载）
    tokenizer.json
    tokenizer_config.json
<modelCacheDir>/Xenova/bge-reranker-base/
    onnx/model.onnx          fp32，约 1.06 GB（自动下载）
    tokenizer.json
    tokenizer_config.json

缺失文件会在首次使用时从 Hugging Face 端点获取。若你本地已有（例如 dsh-knowledge 下载到的目录），把 modelCacheDir 指向那个根目录即可——目录结构一致。

工具与接口

| 接口 | 用途 | |---|---| | npu_status 工具 | 设备、就绪模型、耗时、流量、接线状态 | | npu_reindex 工具 | 重建知识库索引，让 NPU 重新向量化每个分块 | | GET /intel-npu/health | 与 npu_status 同数据，供脚本使用 | | POST /intel-npu/reindex | {"baseId": "…"}，或 {} 表示全部库 |

装好后请跑一次 npu_reindex：CPU（int8）与 NPU（fp32）产生的向量来自不同精度， 重建能让索引自洽。

卸载

dsh plugin --profile web remove dsh-intel-npu

然后在 dsh-knowledge 的设置面板里把它指回本地模型，并再重建一次索引。

许可

MIT