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 創建。現在它已經發展成為一個獨立的項目。 非常感謝上游貢獻者奠定的基礎，我在此基礎上進行了大量的迭代。 始終堅持本地優先的開發工具。