Rag Vault

🚀 RAG Vault

掌控你的文档，掌控你的设备，掌控你的数据。

RAG Vault 让 AI 编码助手能够快速访问你的私有文档，如 API 规范、研究论文和内部文档。索引和搜索在本地运行，除非你明确从远程 URL 摄取内容，否则你的数据将始终保留在本地设备上。

只需一条命令，最少的设置，默认保护隐私。

🚀 快速开始

首次设置清单

在添加 MCP 配置之前：

1. 安装 Node.js 20 或更高版本。
2. 选择一个文档目录，并将 BASE_DIR 设置为该路径。
3. 确保你的 AI 工具进程可以读取 BASE_DIR。
4. 编辑配置后，重启你的 AI 工具。

不同工具的配置方法

对于 Cursor

在 ~/.cursor/mcp.json 中添加以下内容：

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "/path/to/your/documents"
      }
    }
  }
}

将 /path/to/your/documents 替换为你实际的绝对路径。

对于 Claude Code

在项目目录的 .mcp.json 中添加以下内容：

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "./documents",
        "DB_PATH": "./documents/.rag-db",
        "CACHE_DIR": "./.cache",
        "RAG_EMBEDDING_DEVICE": "cpu",
        "RAG_HYBRID_WEIGHT": "0.6",
        "RAG_GROUPING": "related"
      }
    }
  }
}

或者通过 CLI 内联添加：

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y github:RobThePCGuy/rag-vault

对于 Codex

在 ~/.codex/config.toml 中添加以下内容：

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "github:RobThePCGuy/rag-vault"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

安装技能（可选）

为了获得关于查询制定和结果解释的增强 AI 指导，请安装 RAG Vault 技能：

# Claude Code（项目级 - 推荐用于团队项目）
npx github:RobThePCGuy/rag-vault skills install --claude-code

# Claude Code（用户级 - 在所有项目中可用）
npx github:RobThePCGuy/rag-vault skills install --claude-code --global

# Codex（用户级）
npx github:RobThePCGuy/rag-vault skills install --codex

# 自定义位置
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/path

技能将教授 Claude 以下最佳实践：

• 查询制定和扩展策略
• 分数解释（< 0.3 = 匹配良好，> 0.5 = 跳过）
• 何时使用 ingest_file 与 ingest_data
• HTML 摄取和 URL 处理

重启你的 AI 工具，然后开始对话：

你: "Ingest api-spec.pdf"
AI:  成功摄取 api-spec.pdf（47 个块）

你: "How does authentication work?"
AI:  根据第 3.2 节，身份验证使用带有 JWT 令牌的 OAuth 2.0...

就是这么简单。无需 Docker，无需 Python，无需管理服务器基础设施。

✨ 主要特性

数据隐私保护

默认情况下，所有操作都在本地进行，索引和搜索无需进行后台云调用，你的数据始终保留在本地设备上。

混合搜索

结合语义搜索和精确匹配，能够捕捉到如 useEffect 这样的精确代码术语。

简单设置

只需一条 npx 命令和一个小的 MCP 配置块，即可完成设置。

免费使用

永久免费，无需订阅。

安全特性

包括 API 认证、速率限制、CORS 控制和安全头保护等功能，确保生产部署的安全性。

全功能 Web 界面

提供直观的用户界面，用于管理文档，无需使用命令行。

远程模式支持

可以作为 HTTP 服务器运行，供远程 MCP 客户端使用。

多格式支持

支持多种文档格式，如 PDF、DOCX、Markdown、TXT、JSON、JSONL 和 NDJSON 等。

📦 安装指南

安装 Node.js

确保你已经安装了 Node.js 20 或更高版本。

配置 MCP

根据你使用的 AI 工具（Cursor、Claude Code 或 Codex），按照上述“快速开始”部分的说明添加相应的 MCP 配置。

安装技能（可选）

运行相应的命令安装 RAG Vault 技能，以获得增强的 AI 指导。

💻 使用示例

搜索代码库文档

你: "Ingest all the markdown files in /docs"
AI:  摄取了 23 个文件（共 847 个块）

你: "What's the retry policy for failed API calls?"
AI:  根据 error-handling.md，失败的请求将重试 3 次，采用指数退避策略：1 秒、2 秒、4 秒...

索引 Web 文档

你: "Fetch https://docs.example.com/api and ingest the HTML"
AI:  摄取了 "docs.example.com/api"（156 个块）

你: "What rate limits apply to the /users endpoint?"
AI:  API 对 /users 端点的限制是每个 API 密钥每分钟 100 个请求...

构建个人知识库

你: "Ingest my research papers folder"
AI:  摄取了 12 个 PDF 文件（2341 个块）

你: "What do recent studies say about transformer attention mechanisms?"
AI:  根据 attention-mechanisms-2024.pdf，主要发现是...

搜索精确技术术语

RAG Vault 的混合搜索能够同时捕捉语义和精确匹配：

你: "Search for ERR_CONNECTION_REFUSED"
AI:  找到 3 个提及 ERR_CONNECTION_REFUSED 的结果：
     1. troubleshooting.md - "当你看到 ERR_CONNECTION_REFUSED..."
     2. network-errors.pdf - "常见原因包括..."

纯语义搜索可能会错过这些结果，但 RAG Vault 可以找到它们。

📚 详细文档

Web 界面

启动 Web UI

npx github:RobThePCGuy/rag-vault web

在浏览器中打开 http://localhost:3000。

功能介绍

• 上传文档：支持拖放 PDF、DOCX、Markdown、TXT、JSON、JSONL 和 NDJSON 文件。
• 即时搜索：输入查询并查看带有相关性分数的结果。
• 预览内容：点击任何结果以查看完整的块内容。
• 管理文件：查看所有已索引的文档并删除不需要的文件。
• 切换数据库：创建并切换多个知识库。
• 监控状态：查看文档数量、内存使用情况和搜索模式。
• 导出/导入设置：备份和恢复你的保险库配置。
• 主题偏好：在浅色、深色或系统主题之间切换。
• 文件夹浏览器：浏览目录以选择文档。

REST API

Web 服务器提供 REST API 以进行编程访问。设置 RAG_API_KEY 以要求身份验证：

# 带有身份验证（当设置了 RAG_API_KEY 时）
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# 搜索文档（如果未设置 RAG_API_KEY，则无需身份验证）
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# 列出所有文件
curl "http://localhost:3000/api/v1/files"

# 上传文档
curl -X POST "http://localhost:3000/api/v1/files/upload" \
  -F "file=@spec.pdf"

# 删除文件
curl -X DELETE "http://localhost:3000/api/v1/files" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/path/to/spec.pdf"}'

# 获取系统状态
curl "http://localhost:3000/api/v1/status"

# 健康检查（用于负载均衡器）
curl "http://localhost:3000/api/v1/health"

阅读器 API 端点

用于编程式文档读取和跨文档发现：

# 获取文档的所有块（按索引排序）
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"

# 查找相关块以进行跨文档发现
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"

# 批量请求多个块（适用于 UI）
curl -X POST "http://localhost:3000/api/v1/chunks/batch-related" \
  -H "Content-Type: application/json" \
  -d '{"chunks": [{"filePath": "/path/to/doc.pdf", "chunkIndex": 0}], "limit": 3}'

远程模式

RAG Vault 还可以作为 HTTP 服务器运行，供远程 MCP 客户端（如 Claude.ai、Claude Desktop 或任何支持可流式 HTTP 或 SSE 传输的客户端）使用。

# 启动远程服务器（默认端口 3001）
npx github:RobThePCGuy/rag-vault --remote

# 自定义端口
npx github:RobThePCGuy/rag-vault --remote --port 8080

Stdio 模式保持不变，省略 --remote 后，与 Cursor、Claude Code 和 Codex 的交互方式与之前相同。

从 Claude Desktop 连接

在你的 Claude Desktop 配置中添加以下内容：

{
  "mcpServers": {
    "rag-vault-remote": {
      "type": "url",
      "url": "http://localhost:3001/mcp"
    }
  }
}

或者通过 Claude Code CLI 添加：

claude mcp add --transport http rag-vault http://localhost:3001/mcp

从 Claude.ai 连接

对于 Claude.ai（Pro/Max/Team/Enterprise），添加自定义连接器，URL 为 https://your-host:3001/mcp。对于本地开发，使用隧道暴露你的服务器：

cloudflared tunnel --url http://localhost:3001

在远程暴露时，设置 RAG_API_KEY 以进行身份验证。服务器支持可流式 HTTP (/mcp) 和传统 SSE (/sse) 传输，以及 /health 健康检查。

🔧 技术细节

工作原理

文档 → 解析 → 按语义分块 → 本地嵌入 → 存储在 LanceDB
                         ↓
查询 → 嵌入 → 向量搜索 → 关键词增强 → 质量过滤 → 结果

• 智能分块：按语义分块，而不是按字符计数，保持代码块完整。
• 混合搜索：向量相似度搜索找到相关内容，关键词增强提高精确匹配的排名。
• 质量过滤：根据相关性差距对结果进行分组，而不是采用任意的前 K 截断。
• 默认本地运行：使用 Transformers.js 进行嵌入，使用 LanceDB 进行存储。仅在初始模型下载或明确摄取远程 URL 时需要网络。
• 包含 MCP 工具：query_documents、ingest_file、ingest_data、delete_file、list_files、status、feedback_pin、feedback_dismiss 和 feedback_stats。

支持的格式

格式	扩展名	说明
PDF	.pdf	全文提取，过滤页眉和页脚
Word	.docx	保留表格、列表和格式
Markdown	.md	保持代码块完整
文本	.txt	纯文本
JSON	.json	转换为可搜索的键值文本
JSONL / NDJSON	.jsonl, .ndjson	逐行解析日志和结构化记录
HTML	通过 ingest_data	使用 Readability 自动清理

配置

环境变量

变量	默认值	作用
BASE_DIR	当前目录	仅允许访问此路径下的文件
DB_PATH	./lancedb/	向量存储位置
CACHE_DIR	./models/	模型缓存目录
MODEL_NAME	Xenova/all-MiniLM-L6-v2	HuggingFace 嵌入模型
MAX_FILE_SIZE	104857600 (100 MB)	摄取文件的最大字节数
RAG_EMBEDDING_DEVICE	auto	推理设备：auto、cpu、cuda、dml、webgpu、wasm、gpu、webnn
WEB_PORT	3000	Web 界面端口
UPLOAD_DIR	./uploads/	Web UI 文件上传的临时目录

Windows 用户：RAG_EMBEDDING_DEVICE=auto 会尝试使用 GPU 提供程序（DirectML），如果 ONNX Runtime GPU 二进制文件不可用，可能会失败。如果你遇到嵌入初始化错误，请在 MCP 配置中设置 RAG_EMBEDDING_DEVICE=cpu 以确保可靠运行。有关详细信息，请参阅 GPU 加速常见问题解答。

可以使用以下命令进行一次性覆盖（无需编辑 .env）：

# MCP 模式
npx github:RobThePCGuy/rag-vault --embedding-device cpu

# Web 模式
npx github:RobThePCGuy/rag-vault web --embedding-device dml

# 显式强制自动检测
npx github:RobThePCGuy/rag-vault --gpu-auto

搜索调优

变量	默认值	作用
RAG_HYBRID_WEIGHT	0.6	关键词增强强度。0 = 仅语义搜索，1.0 = 仅 BM25 搜索，值越高，精确关键词匹配的增强越强
RAG_GROUPING	未设置	质量过滤分组模式：similar = 仅顶级组，related = 前 2 组
RAG_MAX_DISTANCE	未设置	过滤掉低于此相关性阈值的结果
RAG_GROUPING_STD_MULTIPLIER	1.5	用于检测结果组之间相关性差距的标准差乘数
RAG_HYBRID_CANDIDATE_MULTIPLIER	2	在关键词重排序之前获取的向量候选数量的乘数
RAG_FTS_MAX_FAILURES	3	全文搜索失败次数达到此值后，暂时禁用全文搜索
RAG_FTS_COOLDOWN_MS	300000 (5 分钟)	达到最大失败次数后，重试全文搜索的冷却时间

安全（可选）

变量	默认值	作用
RAG_API_KEY	未设置	用于身份验证的 API 密钥
CORS_ORIGINS	localhost	允许的源（逗号分隔，或 *）
RATE_LIMIT_WINDOW_MS	60000	速率限制时间窗口（毫秒）
RATE_LIMIT_MAX_REQUESTS	100	每个窗口的最大请求数

高级配置

变量	默认值	作用
ALLOWED_SCAN_ROOTS	主目录	允许进行数据库扫描的目录
JSON_BODY_LIMIT	5mb	最大请求体大小
REQUEST_TIMEOUT_MS	30000	API 请求超时时间
REQUEST_LOGGING	false	启用请求审计日志

复制 以获取完整的配置模板。

对于代码密集型内容，可以尝试以下配置：

"env": {
  "RAG_HYBRID_WEIGHT": "0.8",
  "RAG_GROUPING": "similar"
}

📄 许可证

本项目采用 MIT 许可证，可免费用于个人和商业用途。

致谢

本项目基于 Model Context Protocol、LanceDB 和 Transformers.js 构建。

本项目最初是 mcp-local-rag 的一个分支，由 Shinsuke Kagawa 创建。现在它已经发展成为一个独立的项目。 非常感谢上游贡献者奠定的基础，我在此基础上进行了大量的迭代。 始终坚持本地优先的开发工具。