NPU 语义检索 wsongyan1-commits/intel-npu-mcp

intel-npu-mcp

你电脑里那块 NPU，从买回来那天起，就一直在闲着。

你的笔记本里有一颗你付过钱的芯片，却从没用过。这个项目让它动起来。

你为它付过钱，却从没用过它

买 Intel Core Ultra 的时候，包装盒上印着「AI PC」。你多花了那笔钱。然后呢——写代码时忙的是 CPU，问 AI 时忙的是云端，那块 NPU 安安静静，一声不吭。

与此同时，你的 AI 编程助手有个说不出口的短板：它看不懂你的代码。

你想找「重试是怎么退避的」。你的代码里写的是 min(2 ** attempt, 60) —— 没有"重试"，也没有"退避"。于是它找不着，只好猜。它打开十几个不相干的文件，烧掉几千个 token，最后给你一个你自己还得再核一遍的答案。

不是它不够聪明。是它手里只有一把锤子，那把锤子叫 grep。

现在，给它换一套工具

intel-npu-mcp 把你电脑里那块闲置的 NPU，变成 AI 助手的一颗外挂大脑。

🔍 它开始真的看懂你的代码

不再是逐字比对。你问"哪儿在处理重试"，它能找到那句 min(2 attempt, 60) ——因为它是按意思找，不是按字面**找。

🧊 它不跟你抢电脑

索引你的仓库时，CPU 是空的。你该编译编译、该跑测试跑测试，风扇都不带多转一圈。

🔒 你的代码，一步都没离开这台电脑

没有 API key，没有上传，没有"我们可能会用您的数据改进服务"。
公司的代码库，也能放心用。

⚡ 而且它真的快

| | CPU | NPU |
| 索引速度 | 122 块/秒 | 240 块/秒 |
| 索引消耗的 CPU 时间 | 11.48 秒 | 0.05 秒 |

十万行代码的仓库，全量建索引大约 35 秒。之后每次改动都是增量刷新，几乎瞬间完成。

这些数字不是形容词。全部来自同一台 Core Ultra 9 185H 的实测，复现脚本就在 npu_bench 和仓库的测试里，你可以自己再跑一遍。

60 秒，让它跑起来

git clone https://github.com/wsongyan1-commits/intel-npu-mcp.git
cd intel-npu-mcp
pwsh -File bootstrap.ps1

bootstrap.ps1 会自动把运行环境和嵌入模型准备好（约 100 MB，一次性）。然后让你的 AI 助手调一次 npu_info，看到 has_npu: true 就通了。

它能接进你已经在用的四个工具 —— DeepSeek Harness、Codex、Claude Code、WorkBuddy：

以 DeepSeek Harness 为例，粘贴到 ~/.dsh/profiles/<profile>/cordis.patch.yml
- insert:
- id: mcp-npu
name: '@deepseek-ai/dsh-mcp-client'
config:
transport: stdio
serverName: npu
command: 'C:\path\to\python.exe'
args: ['C:\path\to\npu-mcp\server.py']
cwd: 'C:\path\to\npu-mcp'
env:
NPU_MCP_HOME: 'C:\path\to\npu-mcp'
toolCallTimeoutMs: 600000

完整步骤（含 Codex / Claude Code / WorkBuddy）见 INSTALL.md。
真实用例和排错见 USAGE.md。
装完之后，你的 AI 助手会自己读 AGENTS.md 学会怎么用它 —— 不用你教。

以下是技术细节

它到底是什么

一个 MCP 服务器。跑在本机，通过 OpenVINO 调用 Intel NPU，对外暴露七个工具：

| 工具 | 一句话 |
| npu_guide | 让助手读懂自己的说明书 |
| npu_info | 看看这台机器有什么设备、驱动什么版本 |
| npu_embed | 算文本 / 代码向量 |
| npu_index | 建立、增量刷新、查看、清除语义索引 |
| npu_search | 按语义找代码，返回文件和行号 |
| npu_run_model | 编译执行任意 ONNX / OpenVINO IR 模型 |
| npu_bench | CPU / GPU / NPU 延迟对比 |

内建嵌入模型：sentence-transformers/all-MiniLM-L6-v2（384 维，128 token 窗口）。

环境要求

| 项目 | 要求 |
| 系统 | Windows 10/11 |
| 硬件 | Intel Core Ultra（Meteor Lake 及以上）或任何带 Intel NPU 的平台；OpenVINO 支持的其他设备也能跑，device 参数可切 CPU/GPU |
| Python | 3.10+（bootstrap.ps1 自身只需标准库） |
| 磁盘 | 约 500 MB（OpenVINO 运行时 + 模型） |

实测数据

| 项目 | CPU | NPU |
| 代码索引吞吐 | 122 块/秒 | 240 块/秒（2×） |
| 索引 2000 块的 CPU 时间 | 11.48 s | 0.05 s（少 230×） |
| all-MiniLM-L6-v2 嵌入 | 73.5 句/秒 | 164.8 句/秒 |
| 向量一致性（CPU↔NPU） | — | 余弦 0.999995 |

设备：Intel(R) AI Boost，驱动 32.0.100.5540，OpenVINO 2026.4.1。

索引耗时参考（NPU 全量建索引）：

| 规模 | 耗时 |
| 17 个文件 / 239 块 | 2.7 s |
| 66 个文件 / 3525 块 | 18.5 s |
| 10 万行仓库（估算） | ~35 s |

文档与引导

引导随包发布，并用多种方式送到智能体面前，任意客户端都够得着：

| 文件 / 通道 | 给谁看 | 内容 |
| AGENTS.md | 智能体 | 决策规则（何时用 npu_search、何时继续用 grep）、工作流、防错清单 |
| USAGE.md | 人 + 智能体 | 13 个可照抄的用例，每个都带实测输出 |
| INSTALL.md | 人 | 四个客户端的接入步骤与回滚 |
| README.md | 人 | 就是本文件 |
| MCP instructions | 智能体 | 每次握手自动带上（约 1 KB） |
| MCP resources | 智能体 | npu-mcp://guide / usage / readme / status（最后一个是实时设备与索引状态） |
| npu_guide 工具 | 智能体 | 兜底：不支持 resources 的客户端也能取到全文 |

放在插件目录里的 AGENTS.md 会被编码智能体自动当作该目录的工作指令加载（DeepSeek Harness、Codex、Claude Code 都遵循这个约定），所以装完就生效，零额外配置。

客户端接入

DeepSeek Harness

追加到 ~/.dsh/profiles/<profile>/cordis.patch.yml（顶层 YAML 序列）：

- insert:
- id: mcp-npu
name: '@deepseek-ai/dsh-mcp-client'
config:
transport: stdio
serverName: npu
command: 'C:\path\to\python.exe'
args:
- 'C:\path\to\npu-mcp\server.py'
cwd: 'C:\path\to\npu-mcp'
env:
NPU_MCP_HOME: 'C:\path\to\npu-mcp'
NPU_MCP_ROOT: 'C:\path\to\workspace'
toolCallTimeoutMs: 600000
failOnStartupError: false

必须用 insert: 形式。 裸条目只会按 id 覆盖已存在的行；匹配不到时 DSH 只发一条 warning 然后静默跳过，服务器永远不会启动，而配置看起来完全正常。

Codex CLI — ~/.codex/config.toml

[mcp_servers.npu]
command = 'C:\path\to\python.exe'
args = ['C:\path\to\npu-mcp\server.py']
startup_timeout_sec = 120
tool_timeout_sec = 600

[mcp_servers.npu.env]
NPU_MCP_HOME = 'C:\path\to\npu-mcp'
NPU_MCP_ROOT = 'C:\path\to\workspace'

Claude Code

claude mcp add npu -- 'C:\path\to\python.exe' 'C:\path\to\npu-mcp\server.py'

WorkBuddy AI — ~/.workbuddy-ai/mcp.json

连接器 / MCP 设置里新增 stdio 服务器，参数同上。注意它的 MCP 配置不在 ~/.workbuddy/settings.json，而是独立的 ~/.workbuddy-ai/mcp.json。
详见 INSTALL.md。

设计要点

- 零第三方 MCP 依赖：stdio 上的 MCP 就是换行分隔的 JSON-RPC 2.0，mcp_server.py 用标准库直接实现，不装 mcp 包。
- 只声明宿主支持的 Schema 子集：DSH 注册工具前会用 assertSupportedJsonSchema 校验，只允许 type/oneOf/properties/required/additionalProperties/items/enum/const 加 description/title/default/examples。多写一个 minimum 就会让整个工具注册失败； tests/test_schemas.py 就是为此设的守卫。
- NPU 只吃静态 shape：所有编译路径都 reshape 成固定 [batch, seq]，尾部 batch 用重复填充，避免为尾巴再编译一个形状。
- 增量索引：按文件 mtime + size 判定复用；同时比对模型名与 seq，模型换了自动全量重建。
- 扫描护栏：默认跳过所有隐藏目录（.git、.pnpm-store、.venv…
仅放行 .github / .devcontainer），并有 max_files 上限（默认 8000），超限时结果里 truncated: true。否则一个含依赖缓存的工作区就能把工具调用挂死。
- 降级安全：OpenVINO 懒加载，缺运行时也能由 npu_info 报出诊断而不是崩溃。
- stdout 只走协议，日志一律 stderr。

限制（先说清楚）

- 首次编译某个形状需要几秒（NPU 编译器），之后命中驱动缓存（%LOCALAPPDATA%\Intel\NPU）。
- NPU 不适合低延迟单条小算子（有固定启动开销，实测 MLP：CPU 0.04 ms vs NPU 0.5 ms），适合批量 / 后台任务。
- 不要把 LLM 对话放 NPU：第三方实测首字延迟 6.9 s、6.86 tok/s，比集显还慢一倍。
- 大仓库首次全量索引要几分钟；建议把 <root>/.npu-index 加进 .gitignore。
- 它不会让你的对话模型变快 —— NPU 不参与 LLM 推理，它是嵌入和批处理的协处理器。

关于名字

仓库叫 intel-npu-mcp，但 MCP 服务器名固定是 npu （所以工具名是 mcp__npu__npu_search 这样），Python 包名是 npu_mcp。
三者有意不同 —— 改名会破坏已经装好的客户端配置。

许可

MIT。见 LICENSE。