🧠 OmniDocs-RAG-CN

开箱即用的 AI Agent 个人知识库 — 原生中文支持 🇨🇳

索引本地文件、网页、GitHub 仓库、npm/PyPI 包 → 混合 AI 检索引擎 → IDE 聊天框内直接搜索。100% 本地运行，一条命令安装。

English | 中文

缘起

最初只是想搭个个人知识库，但很快发现 Obsidian 对 Agent 并不友好——目录树、双向链接、全文搜索，这些为人设计的功能在 Agent 眼里只是一堆需要遍历的文件路径。Agent 要的不是"翻文件"，而是"语义检索"：用自然语言问一个问题，从知识库中召回最相关的片段，再基于这些片段生成回答。

于是自然想到了向量数据库。把个人文档向量化存起来，Agent 用向量相似度来"找东西"，而不是翻文件夹。但翻遍 GitHub，没有一个现成的工具能直接做到这一点——要么缺 MCP 接口，要么对中文支持几乎为零（分句错、分词烂、BM25 失效）。

所以基于 OmniDocs-RAG v3.4 做了中文化适配和 MCP 接口封装，改出了 OmniDocs-RAG-CN。

最终的使用场景是这样的：

人通过 IDE（Claude Code / Cursor）跟 Agent 对话，问一个问题；Agent 通过 MCP 协议调用 OmniDocs-RAG-CN 的 search_docs，在个人向量知识库中做混合检索（语义 + 关键词 + 重排序），拿到最相关的文档片段后组织回答。

人和 Agent 从两个"端口"访问同一个个人数据库：人看到的是 IDE 聊天窗口里的自然语言回答，Agent 看到的是 chroma_db 里经过向量化的知识片段。人的入口是对话，Agent 的入口是 MCP 工具调用——同一份知识，两种访问方式。

这就是"人与 Agent 协作"的知识管理：不是人翻了文件喂给 Agent，也不是 Agent 替代人去读文档；而是人决定"哪些知识值得存"，Agent 负责"在需要的时候精准找到"，人再做最终的判断和创造。知识库从一个人的第二大脑，变成了人和 Agent 共享的外部记忆。

Related MCP server: punt-quarry

人-Agent 协作架构

┌─────────────────────────────────────────────────────────┐
│                      人 👤                              │
│   IDE 聊天框                                            │
│   "帮我查一下认证逻辑怎么实现的？"                          │
│   → 看到自然语言回答，做决策、创作                          │
└──────────────────────┬──────────────────────────────────┘
                       │ 自然语言对话
                       ▼
┌─────────────────────────────────────────────────────────┐
│                    Agent 🤖                              │
│   Claude Code / Cursor 等                                │
│   → 理解问题 → 调 MCP 工具 → 综合回答                     │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP 协议（search_docs）
                       ▼
┌─────────────────────────────────────────────────────────┐
│               OmniDocs-RAG-CN                            │
│   ┌───────────────────────────────────────────────┐     │
│   │  混合检索引擎                                    │     │
│   │  向量语义 + BM25 关键词(jieba) + RRF 融合        │     │
│   │  + Cross-Encoder 重排序 + 去重                   │     │
│   └───────────────────────────────────────────────┘     │
│                         │                                │
│                         ▼                                │
│   ┌───────────────────────────────────────────────┐     │
│   │  ChromaDB 向量数据库 (chroma_db/)               │     │
│   │  你的文档 → 向量化 → 语义可检索                   │     │
│   └───────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────┘

两个端口，同一份知识。人从对话进去，Agent 从 MCP 进去。

🚀 快速开始

1. 环境要求

• Python 3.10+

• git

2. 一键安装

git clone https://github.com/ybhuang995-dev/personal-data-for-agents.git
cd personal-data-for-agents
python install.py

install.py 自动完成一切：pip 依赖安装 → GPU 检测 + PyTorch 安装 → AI 模型下载（~2.3GB，仅首次）→ IDE 的 MCP 连接自动配置。

3. 使用

直接在 IDE 聊天框里说人话：

帮我索引我的文档目录
搜索：认证逻辑怎么实现的？
把 https://fastapi.tiangolo.com 的文档也加进知识库
用 rag_status 看看知识库状态

Agent 自动调用 MCP 工具，不需要你点任何按钮。

✨ 功能特性

🔍 混合搜索管道

📁 多源摄入

• 40+ 文件格式 — .md .py .js .pdf .docx .xlsx .pptx 等

• 网页 — 异步 BFS 爬虫，支持 robots.txt、sitemap.xml

• GitHub 仓库 — github://owner/repo 直接抓取

• npm / PyPI / ZIP — npm://package pypi://package file:///path.zip

• JS 渲染页面 — 可选 Playwright 支持

⚡ 性能

• GPU 加速 — CUDA 自动检测（索引速度提升 ~11x）

• 增量索引 — MD5 哈希，只处理变化的文件

• BM25 持久化 — pickle 缓存，服务重启即恢复

🛠️ 管理

• 多集合 — 不同项目用不同知识库

• 自动分类 — YAML frontmatter → H1 标题 → 文件名

• 文件监控 — watchdog 监听变动，自动增量索引

• 100% 本地 — 无 API Key、无云服务、无月费

🛠️ MCP 工具（9 个）

index_url() 示例

# 网页（异步 BFS 爬虫）
index_url("https://docs.python.org/3/library/asyncio.html")

# GitHub 仓库
index_url("github://tiangolo/fastapi/docs")

# npm 包
index_url("npm://axios@1.6")

# PyPI 包
index_url("pypi://fastapi")

# ZIP 压缩包
index_url("file:///path/to/docs.zip")

🇨🇳 中文适配（7 处改动）

所有改动在代码中以 # [中文化] 注释标记。详见 CHANGES_CN.md。

⚙️ 环境变量

❓ 常见问题

Q: 数据会发送到外部吗？ A: 不会。100% 本地运行。模型从 HuggingFace 下载一次后离线使用，无 API Key，无云服务。

Q: 需要 GPU 吗？ A: 不必须，但有最好。CPU 搜索约 200ms，GPU 索引加速约 11x。设置 RAG_DEVICE=cuda 开启。

Q: 如何更新索引？ A: 增量索引——只有变化的文件会重新处理。再调一次 index_documents() 即可，或开启文件监控自动更新。

Q: 首次搜索为什么慢？ A: Cross-Encoder（~1.1GB）在首次搜索时惰性加载。后续搜索即时响应。

Q: 支持中文吗？ A: 这就是做这个项目的原因。原生 jieba 分词、中文分句、中文分块、CN→EN 查询扩展。bge-m3 还支持 100+ 其他语言。

Q: 能建多个知识库吗？ A: 可以。用 collection 参数区分：index_documents(path, collection="项目A")，搜索时指定 collection="项目A"。

📄 许可证

基于 Apache License 2.0 开源。详见 LICENSE。

原项目：ElvinBayramov/OmniDocs-RAG