AI导哈

文档语义搜索工具

一个基于RAG（检索增强生成）的本地文档语义搜索工具，使用向量嵌入和相似性搜索技术，适用于工程团队的知识库搜索和文档管理。

  • by Jaxsbr
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Jaxsbr/local-lense

使用说明

local_lense

一个生产就绪的RAG（检索增强生成）系统，可以使用向量嵌入和相似性搜索在本地文档中进行语义搜索。该工具使用TypeScript构建，演示了现代AI集成模式，包括向量数据库、嵌入生成和MCP（模型上下文协议）工具。

非常适合：需要智能文档搜索、知识库或RAG系统实现的工程团队。

什么是local_lense？

local_lense是一个基于RAG（检索增强生成）的文档搜索工具，它：

  • 为您的本地文档建立索引 -处理markdown、HTML、JSON、YAML和文本文件，以创建可搜索的向量索引
  • 语义搜索 -使用向量嵌入来根据含义而不仅仅是关键字查找相关内容
  • 光标集成 -通过MCP公开搜索功能，以便Cursor AI可以搜索您的文档
  • 快速和本地 -一切都在Qdrant矢量数据库本地运行
  • 可扩展 -支持自定义源处理器，用于对来自web、数据库或其他源的内容进行索引

运作原理

local_lense使用RAG（检索增强生成）架构：

  1. 索引阶段:

    • 扫描您配置的文档目录
    • 将文档分割成块
    • 使用变压器模型生成向量嵌入
    • 将嵌入存储在Qdrant向量数据库中

  2. 搜索阶段:

    • 接受自然语言查询
    • 为查询生成嵌入
    • 在Qdrant中搜索类似的文档块
    • 返回具有相关性得分的相关部分

  3. 刷新机制:

    • 使用在初始化时删除并重新索引的单个“文档”集合
    • 可靠索引的简单直接方法

  4. MCP集成 （未来）：

    • 将搜索作为MCP工具公开
    • Cursor AI可以直接查询您的文档
    • 与您的工作流程无缝集成

先决条件

  • Node.js （v18或更高版本）
  • 码头工人 和 Docker Compose （适用于Qdrant矢量数据库）
  • TypeScript （作为开发依赖项安装）

快速开始

1.克隆存储库

git clone <repository-url>
cd local_lense

2.安装依赖项

npm install

3.启动Qdrant矢量数据库

docker-compose up -d

这将在以下位置启动Qdrant容器 localhost:6333。数据保存在Docker卷中。

4.配置文档路径

编辑 configs.json:

{
  "sourcePath": "~/Documents/my-docs",
  "searchResultLimit": 3
}
  • sourcePath：文档目录的路径（支持 ~ 主目录）
  • searchResultLimit：要返回的最大搜索结果数

5.建设项目

npm run build

6.运行索引和搜索

目前，该工具作为测试脚本运行。编辑 src/main.ts 要配置搜索查询，请执行以下操作：

npm run dev

配置

configs.json

位于项目根目录中的主用户配置文件：

  • sourcePath （string，必填）：文档目录的路径

    • 重要：使用完全绝对路径-避免使用 ~ （波浪号）用于主目录扩展
    • 示例：使用 "/Users/username/Documents/my-docs" 而不是 "~/Documents/my-docs"
    • 完整路径确保跨不同上下文和环境的可靠操作

  • searchResultLimit （数字，可选）：每次搜索的最大结果数

    • 违约： 3

  • Boost关键字 （布尔值，可选）：启用基于关键字的分数提升，以提高与本地嵌入模型的相关性

    • 当查询关键字出现在文档内容或文件路径中时，得分会提高
    • 违约： true

  • 关键词体重 （数字，可选）：控制关键字增强的强度（0.0到1.0）

    • 更高的值会增加增压效果
    • 违约： 0.2 （重量增加20%）

备注：收款管理由系统自动处理。系统使用一个“文档”集合，该集合在初始化时总是被删除并重新索引。

Docker Compose

这 docker-compose.yaml 文件配置Qdrant：

  • 端口: 6333 （Qdrant HTTP API）
  • 存储：持续体积 qdrant_storage
  • 健康检查：自动集装箱健康监测

支持的文件类型

默认值 FileSourceProcessor （参见 src/ragIndexer/implementations/fileSourceProcessor.ts)支持以下文件类型：

全力支持

  • 标记语言: .md, .markdown
  • 超文本标记语言: .html, .htm
  • JSON: .json
  • YAML: .yaml, .yml
  • 文本: .txt, .text

其他文件

扩展名不受支持的文件将按以下方式处理 ContentType.OTHER。虽然它们将被索引，但内容可能不是最佳的搜索格式。

处理器递归扫描目录，并根据其扩展名自动检测文件类型。所有支持的文件都以UTF-8文本读取。

自定义源处理器

local_lense使用可插拔的源处理器架构。虽然默认实现处理本地文件，但您可以实现自定义源处理器来索引其他源的内容。

实现自定义处理器

要创建自定义源处理器，请实现 ISourceProcessor 界面（参见 src/ragIndexer/types.ts):

import { ISourceProcessor, SourceItem } from './types';

export class MyCustomProcessor implements ISourceProcessor {
    public get sourceItems(): ReadonlyArray<SourceItem> {
        // Return processed source items
    }

    public process(): ReadonlyArray<SourceItem> {
        // Fetch and process content from your source
        // Return array of SourceItem objects with:
        // - sourceLocation: identifier (file path, URL, etc.)
        // - contentType: ContentType enum value
        // - content: the actual content string
    }
}

自定义处理器的示例用例

  • 网络爬取：索引网站或web API中的内容
  • 数据库源：查询和索引数据库中的内容
  • 云存储：索引来自Google Drive、Dropbox等的文档。
  • RSS 订阅：索引博客文章或新闻文章
  • Git存储库：来自git repos的索引代码文档

看 src/ragIndexer/types.ts 获取完整的接口定义和类型定义。

在游标中使用

先决条件：在Cursor中使用local_lense之前，请确保Docker正在运行并且Qdrant已启动：

# In your local_lense directory
docker-compose up -d

这将启动Qdrant矢量数据库 localhost:6333，这是MCP工具所需要的。

配置：将local_lense添加到游标MCP服务器设置中：

{
  "mcpServers": {
    "local_lense": {
      "command": "node",
      "args": ["/full/path/to/your/local_lense/build/index.js"],
      "env": {}
    }
  }
}

重要说明:

  • 使用完整的绝对路径 build/index.js 在 args 领域
  • 由于Cursor MCP配置解析问题，避免在存储库/目录名称中使用连字符（改用下划线）
  • 有关重要的使用限制和建议，请参阅下面的“local_lense最佳工作时间”

当local_lense效果最佳时

可靠使用

从路径索引文档时 外面 游标的工作目录：

  • 示例： /Users/name/Documents/my-docs, /Users/name/notes，将目录与代码库分开
  • 游标将使用MCP工具，因为内置工具无法访问这些路径

使用受限

从路径索引文档时 在...之内 游标的工作目录：

  • 游标可能使用内置 grep 代替MCP工具
  • 这是一个可以接受的限制——内置工具将处理工作目录中的搜索。
  • 通过指定更直接的查询来解决这个问题。例如，“使用您注册的mcp工具中的‘搜索’和查询：{query}”

最佳实践

  • 目录放置：从项目工作区外的目录中索引文档，以获得最可靠的MCP工具使用
  • 路径配置：始终在中使用完全绝对路径 configs.json （见上文配置部分）
  • 存储库命名：在目录名中使用下划线而不是连字符，以避免MCP路径解析问题

示例用例

  • 工程文件：搜索团队Wiki、架构文档、API文档
  • 个人知识库：索引您的笔记、研究和个人文档
  • 项目文件：快速访问特定项目的文档和指南
  • 研究简报：跨研究论文和笔记的语义搜索

建筑

┌─────────────────────────────────────────────────────────┐
│                    RAG Pipeline                         │
└─────────────────────────────────────────────────────────┘

Indexing Flow:
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Documents   │ --> │   Chunking   │ --> │  Embeddings  │
│  (MD/HTML)   │     │   Strategy   │     │  Generation  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                   │
                                                   ▼
                                          ┌──────────────┐
                                          │   Qdrant     │
                                          │ Vector Store │
                                          └──────┬───────┘
                                                 │
Search Flow:                                      │
┌──────────────┐     ┌──────────────┐           │
│ User Query   │ --> │   Embed      │ ----------┘
│ (Natural Lang)│     │   Query      │
└──────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │ Similarity   │
                     │   Search     │
                     └──────┬───────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  Ranked      │
                     │  Results     │
                     └──────────────┘

故障排除

Qdrant连接错误

  • 确保Docker正在运行： docker ps
  • 检查Qdrant容器： docker-compose ps
  • 验证端口6333是否可用： curl http://localhost:6333/health

未找到路径错误

  • 验证 sourcePath 在 configs.json 存在（路径要求见配置部分）
  • 检查文件权限
  • 确保可以从local_lense工作目录访问该路径

空搜索结果

  • 先运行索引： await ragIndexer.init() 在 main.ts
  • 验证文件是否已处理（查看Qdrant仪表板http://localhost:6333/dashboard)
  • 确保“文档”集合存在并包含索引文档

构建错误

  • 确保已安装TypeScript： npm install
  • 检查Node.js版本： node --version （应该是v18+）
  • 清除构建缓存： rm -rf build && npm run build

MCP工具未使用

  • 症状：Cursor使用grep而不是local_lense搜索工具
  • 原因：文档路径位于Cursor的工作目录中
  • 解决方案：将文档移动到单独的目录或接受限制

带有连字符的存储库名称会导致路径截断

  • 症状：MCP服务器路径被截断（例如。， local-lense 成为 local)
  • 原因：Cursor的MCP服务器配置在解析包含连字符的路径时出现问题
  • 解决方案：在存储库/目录名称中使用下划线而不是连字符（例如。， local_lense 而不是 local-lense)
  • 备注：这是游标MCP配置限制，而不是local_lense问题

发展

项目结构

local_lense/
├── src/
│   ├── main.ts                    # Entry point (test script)
│   ├── services/                  # Core services
│   │   ├── configService.ts       # Configuration management
│   │   └── embedService.ts       # Embedding generation
│   ├── ragIndexer/                # Indexing logic
│   │   ├── ragIndexer.ts
│   │   └── implementations/
│   │       └── fileSourceProcessor.ts
│   └── ragSearch/                 # Search logic
│       ├── ragSearch.ts
│       └── implementations/
│           ├── qdrantVectorSearchService.ts
│           ├── qdrantVectorCollectionService.ts
│           └── qdrantVectorStorageService.ts
├── configs.json                   # Configuration file
├── docker-compose.yaml            # Qdrant setup
└── package.json

建筑

npm run build

输出转到 build/ 目录。

运行开发模式

npm run dev

用途 tsx 直接运行TypeScript而无需构建。

路线图

  • []用于Cursor集成的MCP服务器实现
  • []相关性得分调整和过滤

许可证

国际学生中心

相关 MCP