rag-vault

RAG Vault

你的文档。你的设备。由你掌控。

RAG Vault 可以让 AI 编码助手搜索你的私人文档，例如 API 规范、研究论文和内部文档。一切都在本地运行，数据会留在你的设备上，除非你选择从远程 URL 拉取内容。

只需一条命令即可运行，设置简单，默认保护隐私。

为什么选择 RAG Vault？

安全性

RAG Vault 内置了安全功能：

• API 身份验证：可通过 RAG_API_KEY 设置 API 密钥
• 速率限制：可以限制请求频率
• CORS 控制：限制允许的来源
• 安全标头：由 Helmet.js 提供保护

完整文档请参阅 SECURITY.md。

首次设置检查清单

添加 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"

安装 Skills（可选）

如果你希望 AI 编写更好的查询并更准确地理解结果，请安装 RAG Vault skills：

# Claude Code (project-level - recommended for team projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code

# Claude Code (user-level - available in all projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code --global

# Codex (user-level)
npx github:RobThePCGuy/rag-vault skills install --codex

# Custom location
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/path

Skills 会教 Claude 以下最佳实践：

• 查询构造和扩展策略
• 分数解读。在 boost 模式下，低于 0.3 表示匹配度较高，高于 0.5 则值得跳过。RRF 模式则根据排名评分。
• 何时使用 ingest_file，何时使用 ingest_data
• HTML 导入和 URL 处理

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

You: "Ingest api-spec.pdf"
AI:  Successfully ingested api-spec.pdf (47 chunks)

You: "How does authentication work?"
AI:  Based on section 3.2, authentication uses OAuth 2.0 with JWT tokens...

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

Web 界面

RAG Vault 提供 Web UI，让你无需接触命令行即可管理文档。

启动 Web UI

npx github:RobThePCGuy/rag-vault web

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

默认情况下，Web 服务器绑定到 127.0.0.1（环回地址），因此只有这台设备可以访问。要从网络上的其他设备使用它，请设置 RAG_BIND_HOST=0.0.0.0，并同时设置 RAG_API_KEY，因为 API 默认未经过身份验证。

可执行的操作

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

REST API

Web 服务器提供可直接调用的 REST API。设置 RAG_API_KEY 可要求进行身份验证：

# With authentication (when RAG_API_KEY is set)
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}'

# Search documents (no auth needed if RAG_API_KEY isn't set)
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# List all files
curl "http://localhost:3000/api/v1/files"

# Upload a document
curl -X POST "http://localhost:3000/api/v1/files/upload" \
  -F "[email protected]"

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

# Get system status
curl "http://localhost:3000/api/v1/status"

# Health check (for load balancers)
curl "http://localhost:3000/api/v1/health"

Reader API 端点

这些端点可用于读取文档并查找文档之间的关联：

# Get all chunks for a document (ordered by index)
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"

# Find related chunks for cross-document discovery
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"

# Batch request for multiple chunks (efficient for UIs)
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 服务器运行，让 Claude.ai、Claude Desktop 等远程 MCP 客户端，或任何支持 Streamable HTTP 或 SSE 的客户端连接到它。

# Start remote server (default port 3001)
npx github:RobThePCGuy/rag-vault --remote

# Custom port
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

远程服务默认也会绑定到 127.0.0.1（环回地址）。若要直接接受来自其他机器的连接，请设置 RAG_BIND_HOST=0.0.0.0。在将服务器公开到环回地址之外时（包括通过隧道公开），请设置 RAG_API_KEY 进行身份验证。服务器支持 Streamable HTTP（/mcp）和旧版 SSE（/sse）传输方式，并在 /health 提供健康检查。

实际示例

搜索代码库文档

You: "Ingest all the markdown files in /docs"
AI:  Ingested 23 files (847 chunks total)

You: "What's the retry policy for failed API calls?"
AI:  According to error-handling.md, failed requests retry 3 times
     with exponential backoff: 1s, 2s, 4s...

为 Web 文档建立索引

You: "Fetch https://docs.example.com/api and ingest the HTML"
AI:  Ingested "docs.example.com/api" (156 chunks)

You: "What rate limits apply to the /users endpoint?"
AI:  The API limits /users to 100 requests per minute per API key...

构建个人知识库

You: "Ingest my research papers folder"
AI:  Ingested 12 PDFs (2,341 chunks)

You: "What do recent studies say about transformer attention mechanisms?"
AI:  Based on attention-mechanisms-2024.pdf, the key finding is...

搜索精确技术术语

RAG Vault 的混合搜索兼顾含义和精确匹配：

You: "Search for ERR_CONNECTION_REFUSED"
AI:  Found 3 results mentioning ERR_CONNECTION_REFUSED:
     1. troubleshooting.md - "When you see ERR_CONNECTION_REFUSED..."
     2. network-errors.pdf - "Common causes include..."

纯语义搜索会漏掉这类内容，而 RAG Vault 可以找到它。

工作原理

Document → Parse → Chunk by meaning → Embed locally → Store in LanceDB
                         ↓
Query → Embed → Vector search + BM25 → Fusion → Optional reranking → Results

智能分块：按含义而非字符数拆分，并保持代码块完整。

混合搜索：提供两种融合模式，将向量相似度与 BM25 关键词匹配结合起来：

• 增强模式（默认）：BM25 以乘法方式增强向量搜索距离。简单且可预测。
• RRF 模式（通过 RAG_SEARCH_MODE=rrf 启用）：倒数排名融合 将向量搜索和 BM25 视为独立的投票者。这可以找出仅靠向量搜索会漏掉的文档。

交叉编码器重排（可选启用）：首轮搜索后，交叉编码器模型（Xenova/ms-marco-MiniLM-L-6-v2，约 23MB）会对每个（查询、段落）组合进行评分，从而更精确地排序相关性。设置 RAG_RERANKER_ENABLED=true 即可启用。

查询扩展（可选启用）：当搜索内容采用释义或概念化表达时，生成改写后的查询以提高召回率。提供两种后端：基于本地模板的扩展（默认，完全离线），或通过外部 API 使用基于大模型的 HyDE。设置 RAG_HYDE_ENABLED=true 即可启用。

质量过滤：根据相关性差距对结果分组，而非采用随意设定的前 K 个结果截断方式。

默认本地运行：通过 Transformers.js 生成嵌入，使用 LanceDB 存储。只有在首次下载模型或明确摄取远程 URL 时才需要联网。

内置 MCP 工具：query_documents、ingest_file、ingest_data、delete_file、list_files、status、feedback_pin、feedback_dismiss 和 feedback_stats。

支持的格式

配置

环境变量

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

单命令覆盖（无需编辑 .env）：

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

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

# Explicitly force auto detection
npx github:RobThePCGuy/rag-vault --gpu-auto

搜索调优

Cross-Encoder 重排（可选启用）

查询扩展 / HyDE（可选启用）

隐私提示： api 后端会将查询文本发送到外部 LLM 端点，因此无法保证“零云端”运行。默认的 rule-based 后端完全在本地运行。

安全（可选）

高级设置

复制 .env.example 获取完整的配置模板。

对于代码内容较多的内容，请尝试：

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

常见问题

"env": {
  "RAG_EMBEDDING_DEVICE": "cpu"
}

"MODEL_NAME": "onnx-community/embeddinggemma-300m-ONNX"

开发

git clone https://github.com/RobThePCGuy/rag-vault.git
cd rag-vault
pnpm install
pnpm -C web-ui install

# Install local git hooks (recommended, even for solo dev)
pnpm hooks:install

# Fast local quality gate (backend + web-ui type/lint/format, deps, unused, build, unit tests)
pnpm check:all

# Unit tests only (no model download required)
pnpm test:unit

# Integration/E2E tests (requires model download/network)
pnpm test:integration

# Build
pnpm build

# Run MCP server locally (stdio)
pnpm dev

# Run MCP server locally (remote HTTP + SSE)
pnpm dev:remote

# Run web server locally
pnpm web:dev

# Release to npm (local, guarded)
pnpm release          # patch
pnpm release:minor
pnpm release:major
pnpm release:dry

测试层级

• pnpm test:unit：用于本地/CI 质量检查的确定性测试。不包含模型下载集成路径。
• pnpm test:integration：完整的集成和 E2E 工作流，包括嵌入模型初始化。

使用 RUN_EMBEDDING_INTEGRATION=1，明确启用依赖网络/模型的测试套件。

发布策略

• 发布在本地进行，并通过 scripts/release-npm.sh 脚本执行。
• 支持的版本升级类型：patch、minor、major。
• 脚本会先运行依赖安装、pnpm check:all 和 pnpm ui:build，然后再修改版本文件。
• 只有在检查通过后，才会更新 package.json 和 server.json 中的版本；如果后续任何步骤失败，这些文件会自动还原。
• pnpm release:dry 会运行完整的发布检查，并执行 npm dry-run 发布，且始终还原版本文件。

项目结构

src/
├── bin/             # CLI subcommands (skills install)
├── chunker/         # Semantic text splitting
├── embedder/        # Transformers.js wrapper
├── errors/          # Error handling utilities
├── explainability/  # Keyword-based result explanations
├── flywheel/        # Feedback loop (pin/dismiss reranking)
├── hyde/            # Query expansion + HyDE (LLM-based)
├── parser/          # PDF, DOCX, HTML parsing
├── query/           # Advanced query syntax parser
├── reranker/        # Cross-encoder reranking (Transformers.js)
├── server/          # MCP tool handlers + remote transport
├── utils/           # Config, file helpers, process handlers
├── vectordb/        # LanceDB + hybrid search (boost + RRF)
└── web/             # Express server + REST API

web-ui/              # React frontend (Vite + Tailwind)

文档

• SECURITY.md：安全配置和最佳实践
• .env.example：完整的环境变量模板

许可证

MIT：可免费用于个人和商业用途。

致谢

使用 Model Context Protocol、LanceDB 和 Transformers.js 构建。

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