AI导哈

本地语义搜索工具

一款完全离线的本地语义搜索工具，支持多种文档格式，无需API密钥或云端服务，适用于个人文档库的快速检索。

  • by ZhuBit
  • Python
  • 本地部署
  • 29 星标
  • 更新于
在 GitHub 查看 ZhuBit/cowork-semantic-search

使用说明

协同语义搜索

如果你觉得这很有用，可以考虑给它一个⭐ — 它帮助其他人发现这个项目。

文档的本地语义搜索。没有API密钥。没有云。适用于任何MCP客户端。

为什么

AI编码工具功能强大，但在处理本地文件时存在盲点：

  • 冻结的知识 --训练数据有一个截止点。您最新的报告、笔记和合同在模型的世界中不存在。
  • 上下文窗口限制 --您无法将500个文档粘贴到提示中。
  • 无跨文件搜索 --你的AI工具可以一次读取一个文件，但无法在整个文档库中搜索相关部分。

这个插件弥合了这一差距。它将您的本地文档索引到一个小型、快速的矢量数据库中。当你问一个问题时，它只检索相关的部分——这样你的人工智能工具就可以用你的实际数据来回答。

Your documents --> chunked --> embedded --> local vector DB
                                                 |
         Your question --> embedded --> similarity search --> relevant chunks --> AI answers

特性

  • 完全离线 --一次性模型下载（约120MB），然后无需网络调用。没有数据离开你的机器。
  • 增量索引 --SHA-256内容哈希。只有更改的文件才会被重新处理。重新索引1000个文件，其中3个文件发生了更改，需要几秒钟的时间。
  • 多语言 --原生处理50多种语言。用一种语言搜索，用另一种语言查找结果。
  • 混合搜索 --通过互易秩融合将语义相似性与全文关键字搜索相结合。捕捉纯向量搜索遗漏的内容。
  • 多种格式 --txt、md、pdf、docx、pptx、csv开箱即用。
  • 任何MCP客户端 --适用于Claude Code、Cursor、Windsurf、Cline和任何其他MCP兼容工具。
  • 零基础设施 --LanceDB将所有内容都存储为本地文件。没有服务器，没有Docker，没有数据库需要管理。

支持格式

格式 扩展名 详细信息
纯文本 .txt UTF-8带回退
Markdown .md 保留原始文本
PDF .pdf 使用元数据进行页面级提取
Word .docx 完整段落提取
PowerPoint .pptx 使用元数据进行幻灯片级别提取
CSV .csv 基于行的文本提取

快速开始

1.安装

git clone https://github.com/ZhuBit/cowork-semantic-search.git
cd cowork-semantic-search
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

2.配置您的MCP客户端

将服务器添加到MCP客户端的配置中。用你自己的路径替换。

Claude Code -- .mcp.json in your project root 
{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/cowork-semantic-search",
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}
Cursor -- .cursor/mcp.json in your project root or ~/.cursor/mcp.json globally 
{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}
Windsurf -- ~/.codeium/windsurf/mcp_config.json 
{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}
Cline -- MCP Servers settings in the Cline VS Code extension

打开临床>MCP服务器图标>配置>高级MCP设置，然后添加：

{
  "mcpServers": {
    "semantic-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "server.main"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cowork-semantic-search"
      }
    }
  }
}

3.重新启动MCP客户端并继续

“为~/documents/projects中的所有文档建立索引”

“搜索‘季度收入报告’”

首先运行下载嵌入模型（约120MB），然后一切都离线运行。

示例：搜索黑曜石金库

如果你在黑曜石（或任何标记文件文件夹）中做笔记，这个插件会把你的人工智能工具变成你知识库的搜索引擎。

You: "Index my vault at ~/Documents/ObsidianVault"
AI:  Indexed 847 files -> 3,291 chunks in 42s

You: "What did I write about API rate limiting?"
AI:  Found 6 relevant chunks across 3 files:
       - notes/backend/rate-limiting-strategies.md
       - projects/acme-api/design-decisions.md
       - daily/2025-11-03.md
       ...

You: "Find anything about the client meeting last November, use hybrid search"
AI:  Found 4 results using hybrid search (vector + keyword):
       - meetings/2025-11-12-acme-kickoff.md
       - daily/2025-11-12.md
       ...

适用于PDF、Word文档、PowerPoint和CSV，只需将其指向文件夹即可。

工具

工具 说明
index_folder 索引或重新索引文件夹中的所有文档。增量--跳过未更改的文件。
semantic_search 使用自然语言搜索索引文档。支持 vector 和 hybrid 模式。
get_index_status 显示总块数、文件计数和索引文件列表。
reindex_file 强制重新索引单个文件，绕过哈希缓存。

运作原理

  1. 解析 --从每个文档中提取文本，保留结构（页面、幻灯片）
  2. 块 --拆分为~400个字符的重叠部分以进行精确检索
  3. 嵌入 --使用以下公式将每个块转换为384维向量 paraphrase-multilingual-MiniLM-L12-v2
  4. 商店 --将块+向量保存在LanceDB数据库中（本地文件，无需服务器）
  5. 搜索 --嵌入您的查询，通过余弦相似度查找最近的块，可选择通过RRF与全文关键字搜索相结合

高级用法

Use as a Python library 
from server.indexer import index_folder
from server.search import semantic_search

# Index a folder
result = index_folder("/path/to/docs")
print(f"{result['files_indexed']} files -> {result['total_chunks']} chunks")

# Search
results = semantic_search("project deadline", mode="hybrid")
for r in results["results"]:
    print(f"  {r['file_name']}: {r['text'][:100]}...")

建筑

server/
  main.py       # MCP server + tool definitions
  parsers.py    # Per-format text extraction
  chunker.py    # Text splitting with metadata
  indexer.py    # Discovery, hashing, embedding pipeline
  store.py      # LanceDB vector store + FTS + hybrid search
  search.py     # Query embedding + search orchestration
组件 选择 为什么
MCP框架 FastMCP 干净的工具定义，异步支持
嵌入 句子转换 离线、多语言、快速
Vector DB LanceDB 无服务器、嵌入式、FTS内置
分块 langchain文本拆分器 久经考验的递归拆分
PDF PyMuPDF 快速、准确的提取
DOCX python-DOCX 轻量级，无系统依赖
PPTX python-PPTX 幻灯片级别提取

发展

source .venv/bin/activate
pytest tests/ -v

56个测试，涵盖解析器、分块、索引、搜索和MCP工具集成。

欢迎投稿——打开问题或提交PR。

路线图

  • ONNX运行时实现更快的嵌入（删除PyTorch依赖关系）
  • 通过工具参数可配置块大小和重叠
  • 多文件夹命名索引
  • 元数据过滤（日期范围、标签、自定义字段）
  • 监视模式（文件更改时自动重新索引）

支持

如果这对你有用，考虑给它一个⭐ — 它帮助其他人找到项目。

许可证

AGPL-3.0——免费使用、修改和自托管。如果您将其作为网络服务提供，则必须共享源代码。看 许可证 了解详情。

相关 MCP