Rag Knowledge Base

RAG知识库

](https://pypi.org/project/rag-knowledge-base/)  

100%离线RAG存储和MCP服务器，用于查询本地文档知识库。专为大型语料库（5-10 GB+）的高质量检索而设计，具有GPU加速、混合搜索和跨编码器重新排序功能。

特性

核心

• 完全离线 --初始设置后不需要互联网
• 30+文件格式 --Markdown、PDF、DOCX、PPTX、XLSX、CSV、JSON、YAML、XML、HTML、RST、RTF、ODT/ODS/ODP、EPUB、图像（OCR）、源代码、日志和纯文本
• 多个RAG数据库 --创建、切换和管理独立的知识库
• 可共享的 --将RAG导出为单个 .rag 档案；在另一台机器上导入
• MCP服务器 --从VS Code Copilot、Claude Desktop或任何MCP客户端查询
• 网页用户界面 --用于搜索、状态和管理的NiceGUI仪表板
• 文件监视 --文件更改时的自动重新索引
• 跨平台 --Windows、macOS和Linux

搜索质量

• 混合搜索 --通过可配置的分数融合将向量相似性（余弦）与BM25关键字匹配相结合
• 交叉编码器重新排序 --第二阶段重新评级 cross-encoder/ms-marco-MiniLM-L-6-v2 为了精确
• 结构感知分块 --保留Markdown标题层次结构、PDF页面边界和代码函数/类边界
• 上下文前缀 --每个块都带有其文档标题和节路径，以提高嵌入质量
• 最小分数过滤 --自动过滤结果中的低相关性噪声
• MMR多样化 --最大边际相关性减少了结果中的冗余（可配置lambda）

索引性能

• GPU加速 --自动检测CUDA和Apple MPS；回落到CPU
• 并行文件解析 --具有可配置worker计数的多线程文档解析
• 批量嵌入 --大批量编码块（默认512）以获得最佳吞吐量
• 增量索引 --基于xxHash的文件清单以O（1）的代价跟踪变化；未更改的文件会立即跳过
• 调谐HNSW --可配置 ef_construction 和 M ChromaDB矢量索引参数

可靠性

• 取消 --合作取消长时间运行的索引；部分工作已安全清理，并在下次运行时重新索引
• 崩溃恢复 --锁文件检测和清单失效；如果检测到之前的崩溃，守护进程会在启动时自动运行增量重新索引
• 指标验证 — rag-kb verify 检查清单↔ 矢量存储一致性和孤立/无效文件报告

快速开始

从PyPI安装

pip install rag-knowledge-base

这安装了通过MCP进行索引、搜索和服务所需的一切，包括PDF、DOCX、PPTX、XLSX和RTF的解析器。

可选附加项

从源代码安装

pip install -e .

GPU支持： 在安装此软件包之前，请先使用CUDA安装PyTorch： ``bash pip install torch --index-url https://download.pytorch.org/whl/cu126 ``

创建并索引RAG

# Create a knowledge base pointing at your document folders
rag-kb create my-docs \
  --folders /path/to/docs /path/to/more/docs \
  --description "My documentation"

# Set as active
rag-kb use my-docs

# Index (auto-detects GPU, uses 14 parallel workers by default)
rag-kb index

# Re-run index any time — only changed files are processed
rag-kb index

通过MCP查询（VS代码副本）

# Start MCP server (stdio mode for VS Code)
rag-kb serve

添加到您的 .vscode/mcp.json:

{
  "servers": {
    "rag-knowledge-base": {
      "command": "rag-kb",
      "args": ["serve"]
    }
  }
}

通过MCP（HTTP）查询

# Start MCP server on HTTP
rag-kb serve --http --port 8080

Web仪表板

# Launch NiceGUI dashboard
rag-kb ui

分享RAG

# Export
rag-kb export my-docs --output my-docs.rag

# Import (on another machine)
rag-kb import my-docs.rag --name received-docs

支持的文件格式

CLI参考

使用 -v 对于详细输出： rag-kb -v index

MCP工具

当通过MCP连接时，可以使用以下工具：

配置

配置文件位置（取决于平台）：

• 窗户： %LOCALAPPDATA%\rag-kb\config.yaml
• macOS： ~/Library/Application Support/rag-kb/config.yaml
• Linux： ~/.local/share/rag-kb/config.yaml

# Embedding
embedding_model: paraphrase-multilingual-MiniLM-L12-v2
chunk_size: 1024
chunk_overlap: 128

# Search quality
reranking_enabled: true
reranker_model: cross-encoder/ms-marco-MiniLM-L-6-v2
hybrid_search_enabled: true
hybrid_search_alpha: 0.7        # 0.0 = pure BM25, 1.0 = pure vector
min_score_threshold: 0.15
mmr_enabled: true
mmr_lambda: 0.7                 # 0.0 = max diversity, 1.0 = max relevance

# Indexing performance
indexing_workers: 14             # parallel file-parsing threads
embedding_batch_size: 512        # texts per encode() call

# ChromaDB HNSW tuning
hnsw_ef_construction: 256
hnsw_m: 48

# File types to index
supported_extensions:
  - .md
  - .txt
  - .pdf
  - .docx
  - .pptx
  - .xlsx
  - .csv
  - .json
  - .yaml
  - .xml
  - .html
  - .htm
  - .rst
  - .rtf
  - .odt
  - .epub
  - .png
  - .jpg
  # ... see config for full list

# Server
host: 127.0.0.1
port: 8080

守护进程管理

守护进程是一个管理所有数据访问的后台进程。它在首次使用CLI时自动启动，并在空闲超时后关闭。

# Check daemon status
rag-kb daemon status

# View daemon logs
rag-kb daemon logs

# Follow logs in real-time (like tail -f)
rag-kb daemon logs -f

# Show last 100 lines
rag-kb daemon logs -n 100

# Restart the daemon
rag-kb daemon restart

# Stop the daemon
rag-kb daemon stop

崩溃恢复

如果索引中断（崩溃、断电、终止），守护进程会在下次启动时自动检测并恢复：

1. 锁定文件检测 一 .indexing_lock RAG数据库中的文件标记活动索引
2. 明显无效 --部分处理的文件已预先标记，因此 is_changed() 回报 True
3. 自动恢复 --如果检测到之前的崩溃，守护进程将在启动时运行增量重新索引

您还可以手动检查索引一致性：

# Verify manifest ↔ vector store consistency
rag-kb verify

# Repair by re-indexing
rag-kb index

建筑

Documents  ──►  Parsers (30+ formats)
                    │
                    ▼
             Structure-aware Chunker
             (headings / pages / functions)
                    │
                    ▼
             Embedding Model (CUDA / MPS / CPU)
             + Contextual Prefixes
                    │
                    ▼
             ChromaDB (HNSW cosine index)
                    │
          ┌─────────┼─────────┐
          ▼         ▼         ▼
       MCP Server  Web UI   CLI
          │
    ┌─────┼─────┐
    ▼     ▼     ▼
  Vector  BM25  Hybrid Fusion
    │           │
    ▼           ▼
  Cross-encoder Reranking
    │
    ▼
  Results

许可证

MIT许可证——见 许可证 了解详情。

所有依赖项都使用MIT、Apache 2.0或BSD许可证。