AI导哈

离线RAG知识库

一个完全离线的RAG存储和MCP服务器，用于查询本地文档知识库，支持多种文件格式和高效检索。

  • by yohasacura
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 yohasacura/rag-knowledge-base

使用说明

RAG知识库

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的解析器。

可选附加项

额外 安装命令 它添加了什么
web pip install rag-knowledge-base[web] NiceGUI网络仪表板
ocr pip install rag-knowledge-base[ocr] 图像OCR（Surya、RapidOCR）
api pip install rag-knowledge-base[api] OpenAI/Voyage嵌入API
monitoring pip install rag-knowledge-base[monitoring] 系统指标（psutil）
all pip install rag-knowledge-base[all] 以上所有

从源代码安装

pip install -e .

GPU支持： 在安装此软件包之前，请先使用CUDA安装PyTorch：

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

支持的文件格式

类别 扩展
文件 .md, .markdown, .txt, .text, .pdf, .docx, .pptx, .rst, .rest, .rtf, .epub
电子表格 .xlsx, .xls, .csv, .tsv
数据 .json, .jsonl, .yaml, .yml, .xml, .xsl, .xslt, .xsd, .svg, .rss, .atom
Web .html, .htm
开放文档 .odt, .ods, .odp
图像（OCR） .png, .jpg, .jpeg, .gif, .bmp, .tiff, .tif, .webp, .ico, .heic, .heif
代码 .py, .js, .mjs, .cjs, .jsx, .ts, .tsx, .java, .c, .h, .cpp, .cxx, .cc, .hpp, .hxx, .cs, .go, .rs, .rb, .php, .swift, .kt, .kts, .scala, .m, .mm, .r, .R, .lua, .pl, .pm, .sh, .bash, .zsh, .fish, .ps1, .psm1, .bat, .cmd, .sql, .dart, .ex, .exs, .erl, .hrl, .hs, .ml, .mli, .fs, .fsx, .clj, .cljs, .groovy, .gradle, .vim, .el, .zig, .v, .nim, .tf, .hcl, .proto, .graphql, .gql, .vue, .svelte, .toml, .ini, .cfg, .conf, .env, .properties, .makefile, .cmake, .dockerfile
日志 .log

CLI参考

命令 描述
rag-kb create NAME --folders ... 创建新的RAG数据库
rag-kb list 列出所有RAG数据库
rag-kb use NAME 设置活动RAG
rag-kb delete NAME [-y] 删除RAG数据库
rag-kb detach NAME 从源文件中分离RAG（只读模式）
rag-kb attach NAME 将分离的RAG重新附加到其源文件
rag-kb index [--rag NAME] [--workers N] 索引文档（并行、增量）
rag-kb cancel-index 取消正在运行的索引操作
rag-kb verify [--rag NAME] 验证索引一致性（清单与向量存储）
rag-kb search QUERY [-n N] 搜索活动RAG
rag-kb status [--rag NAME] 显示索引状态和统计信息
rag-kb files [--rag NAME] 列出索引文件
rag-kb export NAME --output FILE 将RAG导出到a .rag 文件
rag-kb import FILE [--name NAME] 从a导入RAG .rag 文件
rag-kb serve [--http] [--port N] 启动MCP服务器
rag-kb ui [--port N] 启动web仪表板
rag-kb config 显示当前配置
rag-kb download-models [--output DIR] 预下载ML模型以供离线/捆绑使用
rag-kb models list|info|download|delete 管理嵌入/重新链接模型
rag-kb daemon status|stop|restart|logs 管理后台守护进程
rag-kb stats [CATEGORY] 显示详细的指标和监控统计数据
rag-kb monitor [--interval N] 实时监控仪表板（如RAG的htop）

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

MCP工具

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

工具 说明
search_knowledge_base 混合搜索，可选交叉编码器重新排序
get_document_content 从特定文档中检索所有块
list_indexed_files 列出所有带有元数据的索引文件
get_index_status 当前索引状态和统计信息
reindex 触发活动RAG的重新索引
cancel_indexing 取消正在运行的索引操作
verify_index_consistency 检查清单↔ 向量存储一致性
list_rags 列出所有可用的RAG数据库
switch_rag 切换活动RAG数据库
create_rag 创建新的RAG知识库
delete_rag 永久删除RAG数据库
export_rag 将RAG导出到可共享文件
import_rag 从共享文件导入RAG
detach_rag 从源文件中分离/重新附加RAG
list_models 列出可用的嵌入/重新链接模型
get_model_info 获取模型的详细信息
get_monitoring_metrics 获取全面的监控仪表板
get_indexing_history 获取最近的索引运行历史记录
get_search_stats 获取最近的搜索查询性能统计数据
get_embedding_stats 获取最近的嵌入批处理性能统计数据
get_vector_store_details 获取详细的矢量存储/ChromaDB健康信息

配置

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

  • 窗户： %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许可证。

相关 MCP