AI导哈

向量与知识图谱查询服务

一个基于MCP协议的服务器，用于查询由lance-embedder项目创建的向量存储和知识图谱，支持语义搜索和关系感知检索。

  • by mark-hingston
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 mark-hingston/query-tool

使用说明

嵌入查询服务器

MCP（模型上下文协议）服务器，用于查询由 喷枪嵌入器 项目。

特性

  • 矢量搜索：使用语义搜索查询LanceDB矢量存储
  • 图形搜索：使用GraphRAG构建的查询知识图，用于关系感知检索
  • 自动模式：在可用时自动使用图形搜索，回退到矢量搜索
  • 标准运输：与Claude Desktop、Cursor和Windsurf等MCP客户端兼容

安装

npm install
npm run build

用法

必需参数

  • --index-path <path> -embedder创建的embeddings目录的路径
  • --base-url <url> -用于生成查询嵌入的LM Studio基本URL
  • --model <name> -嵌入模型名称（必须与用于索引的名称匹配）

可选参数

索引设置：

  • --table-name <name> -LanceDB表名（默认：“嵌入”）
  • --dimensions <number> -嵌入尺寸（默认值：1024）

查询设置：

  • --top-k <number> -要返回的结果数（默认值：10）

图形设置：

  • --enable-graph -启用图形搜索模式（默认：禁用以快速启动）
  • --graph-threshold <number> -图查询的相似性阈值（默认值：0.7）
  • --random-walk-steps <number> -图遍历步骤（默认值：100）
  • --restart-prob <number> -随机游走的重启概率（默认值：0.15）
  • --preload-graph -启动时在后台开始构建图形（允许通过矢量搜索进行即时查询）

性能设置：

  • --verbose -启用详细日志记录以进行调试和性能监控

例子

基本矢量搜索（快速启动）：

node dist/index.js \
  --index-path ./embeddings \
  --base-url http://localhost:1234/v1 \
  --model text-embedding-model \
  --top-k 5

使用图搜索（延迟加载-基于第一个查询构建）：

node dist/index.js \
  --index-path ./embeddings \
  --base-url http://localhost:1234/v1 \
  --model text-embedding-model \
  --enable-graph \
  --top-k 5

预加载背景图（最适合生产）：

node dist/index.js \
  --index-path ./embeddings \
  --base-url http://localhost:1234/v1 \
  --model text-embedding-model \
  --enable-graph \
  --preload-graph \
  --verbose

对于大型索引（10K+文件），建议设置：

node dist/index.js \
  --index-path ./embeddings \
  --base-url http://localhost:1234/v1 \
  --model text-embedding-model \
  --enable-graph \
  --preload-graph \
  --top-k 10 \
  --verbose

MCP工具：查询索引

服务器公开了一个名为 query_index.

输入参数

  • query （字符串，必填）-搜索查询文本
  • mode （枚举：“auto”|“vector”|“graph”，默认值：“自动”）-搜索模式
    • auto：如果存在图形数据，则使用图形搜索，否则使用矢量搜索
    • vector：仅通过LanceDB进行力矢量搜索
    • graph：强制图形搜索（如果没有图形数据则出错）

输出

返回一个按分数排序的结果数组（最高者优先），每个结果包含：

  • text -块内容
  • source -块来源的文件路径
  • score -相似性得分（嵌入相似性）
  • chunkIndex -块在源文件中的位置

项目结构

query-tool-server/
├── src/
│   ├── index.ts           # Main entry point and MCP server setup
│   ├── lib/
│   │   └── graph-store.ts # GraphRAG data loading
│   └── types/
│       └── index.ts       # TypeScript type definitions
├── dist/                   # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

性能优化

服务器为处理大型索引（10K+文件）实现了多项优化：

1. 延迟加载（默认）

  • 图构造被推迟到第一个查询
  • 即使索引很大，服务器也会立即启动
  • 第一个查询触发图形构建（10K文件可能需要30秒2分钟）
  • 后续查询使用缓存的图

2. 并行批量加载

  • 使用以下命令并行加载所有批处理文件 Promise.all()
  • 显著减少大型数据集的I/O时间
  • 进度日志显示大型索引的加载状态

3. 自动回退

  • 若查询在构建图时到达，它会自动回退到向量搜索
  • 没有因图构建时间而导致的查询失败
  • 警告已记录到控制台进行调试

4. 持久图形缓存

  • 图形元数据在首次构建后缓存到磁盘
  • 未来的优化可以序列化整个图结构
  • 目前受限于Mastra GraphRAG系列化API

5. 背景预加载（可选）

  • 使用 --preload-graph 在启动时开始构建图形
  • 服务器在构建过程中通过矢量搜索保持响应
  • 图形准备就绪后可用，无阻塞

6. 工作线程支持

  • 图形构建可以卸载到工作线程
  • 使主线程对查询保持响应
  • 目前处于实验阶段（见 graph-worker.ts)

运作原理

  1. 初创公司:

    • 验证配置并加载LanceDB索引
    • 加载图形元数据（但不是完整的图形-延迟加载）
    • 如果满足以下条件，则可选择启动背景图构建 --preload-graph 已设置
    • 服务器立即就绪

  2. 查询处理：收到查询时：

    • 使用指定的模型生成查询嵌入
    • 根据以下内容选择搜索模式（矢量或图形） mode 参数
    • 对于矢量搜索：直接查询LanceDB（总是很快）
    • 对于图形搜索：
      • 检查图形构建状态
      • 如果正在构建，则返回到带有警告的矢量搜索
      • 如果准备就绪，则使用图形进行关系感知搜索
      • 如果空闲，则触发延迟构建，然后使用图
    • 按分数对结果排序并返回前K

与嵌入器集成

此服务器旨在使用由创建的索引 嵌入器 项目：

  1. 使用embedder创建索引：

    embedder -d ./my-repo -o ./embeddings --enable-graph

  2. 启动指向该索引的查询服务器：

    node dist/index.js \
  --index-path ./embeddings \
  --base-url http://localhost:1234/v1 \
  --model text-embedding-model \
  --enable-graph

迁移指南：优化前后

之前（大索引启动缓慢）

  • 服务器将在启动时构建整个图形
  • 对于10K文件：服务器准备就绪可能需要2-5分钟
  • 在此期间无法处理任何查询
  • 即使不使用，也始终加载图形

之后（快速启动+延迟加载）

  • 服务器立即启动（<1秒）
  • Graph基于第一个查询构建（或在后台使用 --preload-graph)
  • 矢量搜索始终可用
  • 构建完成后，图形搜索变得可用
  • 并行加载可将构建时间缩短约50-70%

行为变化

没有 --enable-graph:

  • 无变化-仅矢量搜索，即时启动

随着 --enable-graph （默认-延迟加载）：

  • 服务器立即启动
  • 第一个图查询触发构建（大型索引为30s-2min）
  • 构建过程中的查询会自动回退到向量搜索
  • 后续查询使用缓存图

随着 --enable-graph --preload-graph （推荐用于生产）：

  • 服务器立即启动
  • 图形构建立即在后台开始
  • 所有查询都使用向量搜索，直到图形准备就绪
  • 没有用户面临的延迟，图表准备就绪后可用

错误处理

服务器在启动时进行验证：

  • 索引路径存在
  • LanceDB表存在
  • 如果请求图形搜索，则图形数据必须可用

所有错误均以MCP错误响应的形式返回，并带有描述性消息。

发展

# Run in development mode
npm run dev -- --index-path ./embeddings --base-url http://localhost:1234/v1 --model text-embedding-model

# Build for production
npm run build

# Run built version
npm start -- --index-path ./embeddings --base-url http://localhost:1234/v1 --model text-embedding-model

许可证

国际学生委员会

相关 MCP