内容
# RAG 知识库
[](https://pypi.org/project/rag-knowledge-base/)
[](https://pypi.org/project/rag-knowledge-base/)
[](https://opensource.org/licenses/MIT)
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 客户端查询
- **Web UI** — NiceGUI 仪表盘，用于搜索、状态和管理
- **文件监视** — 文件更改时自动重新索引
- **跨平台** — Windows、macOS 和 Linux
### 搜索质量
- **混合搜索** — 将向量相似性（余弦）与 BM25 关键词匹配相结合，通过可配置的分数融合
- **交叉编码器重新排序** — 第二阶段重新排序，使用 `cross-encoder/ms-marco-MiniLM-L-6-v2` 以提高精度
- **结构感知分块** — 保留 Markdown 标题层次结构、PDF 页面边界和代码函数/类边界
- **上下文前缀** — 每个块携带其文档标题和部分路径，以提高嵌入质量
- **最低分数过滤** — 自动从结果中过滤低相关性噪声
- **MMR 多样性** — 最大边际相关性减少结果中的冗余（可配置 lambda）
### 索引性能
- **GPU 加速** — 自动检测 CUDA 和 Apple MPS；回退到 CPU
- **并行文件解析** — 多线程文档解析，具有可配置的工作线程数
- **批量嵌入** — 在大批量（默认为 512）中编码块以优化吞吐量
- **增量索引** — xxHash-based 文件清单跟踪更改，成本为 O(1); 不变的 文件立即跳过
- **调谐 HNSW** — 可配置的 `ef_construction` 和 `M` 参数，用于 ChromaDB 的向量索引
### 可靠性
- **取消** — 长期运行的索引的合作取消；部分工作被安全清理并在下一次运行中重新索引
- **崩溃恢复** — 锁定文件检测和清单无效；守护进程在检测到以前的崩溃时自动运行增量重新索引
- **索引验证** — `rag-kb verify` 检查清单 ↔ 向量存储一致性并报告孤立/无效文件
## 快速开始
### 从 PyPI 安装
```bash
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]` | 以上所有 |
### 从源代码安装
```bash
pip install -e .
```
> **GPU 支持：** 在安装此软件包之前，请安装带有 CUDA 的 PyTorch：
> ```bash
> pip install torch --index-url https://download.pytorch.org/whl/cu126
> ```
### 创建和索引 RAG
```bash
# 创建一个指向文档文件夹的知识库
rag-kb create my-docs \
--folders /path/to/docs /path/to/more/docs \
--description "我的文档"
# 设置为活动状态
rag-kb use my-docs
# 索引（自动检测 GPU，默认为 14 个并行工作线程）
rag-kb index
# 重新运行索引 — 仅处理更改的文件
rag-kb index
```
### 通过 MCP（VS Code Copilot）查询
```bash
# 启动 MCP 服务器（用于 VS Code 的 stdio 模式）
rag-kb serve
```
添加到您的 `.vscode/mcp.json`：
```json
{
"servers": {
"rag-knowledge-base": {
"command": "rag-kb",
"args": ["serve"]
}
}
}
```
### 通过 MCP（HTTP）查询
```bash
# 在 HTTP 上启动 MCP 服务器
rag-kb serve --http --port 8080
```
### 网页仪表盘
```bash
# 启动 NiceGUI 仪表盘
rag-kb ui
```
### 分享 RAG
```bash
# 导出
rag-kb export my-docs --output my-docs.rag
# 导入（在另一台机器上）
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` |
| 网页 | `.html`, `.htm` |
| OpenDocument | `.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]` | 验证索引一致性（清单 vs 向量存储） |
| `rag-kb search QUERY [-n N]` | 搜索活动 RAG |
| `rag-kb status [--rag NAME]` | 显示索引状态和统计信息 |
| `rag-kb files [--rag NAME]` | 列出索引文件 |
| `rag-kb export NAME --output FILE` | 将 RAG 导出到 `.rag` 文件 |
| `rag-kb import FILE [--name NAME]` | 从 `.rag` 文件导入 RAG |
| `rag-kb serve [--http] [--port N]` | 启动 MCP 服务器 |
| `rag-kb ui [--port N]` | 启动网页仪表盘 |
| `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]` | 实时监控仪表盘（类似 htop for RAG） |
使用 `-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 健康信息 |
## 配置
配置文件位置（平台相关）：
- **Windows:** `%LOCALAPPDATA%\rag-kb\config.yaml`
- **macOS:** `~/Library/Application Support/rag-kb/config.yaml`
- **Linux:** `~/.local/share/rag-kb/config.yaml`
```yaml
# 嵌入式
embedding_model: paraphrase-multilingual-MiniLM-L12-v2
chunk_size: 1024
chunk_overlap: 128
# 搜索质量
reranking_enabled: true
reranker_model: cross-encoder/ms-marco-MiniLM-L-6-v2
hybrid_search_enabled: true
hybrid_search_alpha: 0.7 # 0.0 = 纯 BM25, 1.0 = 纯向量
min_score_threshold: 0.15
mmr_enabled: true
mmr_lambda: 0.7 # 0.0 = 最大多样性, 1.0 = 最大相关性
# 索引性能
indexing_workers: 14 # 并行文件解析线程
embedding_batch_size: 512 # 每个 encode() 调用中的文本数量
# ChromaDB HNSW 调整
hnsw_ef_construction: 256
hnsw_m: 48
# 要索引的文件类型
supported_extensions:
- .md
- .txt
- .pdf
- .docx
- .pptx
- .xlsx
- .csv
- .json
- .yaml
- .xml
- .html
- .htm
- .rst
- .rtf
- .odt
- .epub
- .png
- .jpg
# ... 参见完整列表
# 服务器
host: 127.0.0.1
port: 8080
```
## 守护进程管理
守护进程是一个后台进程，管理所有数据访问。它在第一次 CLI 使用时自动启动，并在空闲超时后关闭。
```bash
# 检查守护进程状态
rag-kb daemon status
# 查看守护进程日志
rag-kb daemon logs
# 实时跟踪日志（类似 tail -f）
rag-kb daemon logs -f
# 显示最后 100 行
rag-kb daemon logs -n 100
# 重启守护进程
rag-kb daemon restart
# 停止守护进程
rag-kb daemon stop
```
### 崩溃恢复
如果索引被中断（崩溃、电源损失、杀死），守护进程会在下一次启动时自动检测并恢复：
1. **锁定文件检测** — `.indexing_lock` 文件在 RAG 数据库中标记活动索引
2. **清单无效** — 部分处理的文件预先标记，以便 `is_changed()` 返回 `True`
3. **自动恢复** — 如果检测到以前的崩溃，守护进程会在启动时运行增量重新索引
您也可以手动检查索引一致性：
```bash
# 验证清单 ↔ 向量存储一致性
rag-kb verify
# 通过重新索引修复
rag-kb index
```
## 架构
```
文档 ──► 解析器（30+ 格式）
│
▼
结构感知分块器
（标题 / 页面 / 函数）
│
▼
嵌入式模型（CUDA / MPS / CPU）
+ 上下文前缀
│
▼
ChromaDB（HNSW 余弦索引）
│
┌─────────┼─────────┐
▼ ▼ ▼
MCP 服务器 网页 UI CLI
│
┌─────┼─────┐
▼ ▼ ▼
向量 BM25 混合融合
│ │
▼ ▼
交叉编码器重新排序
│
▼
结果
```
## 许可证
MIT 许可证 — 参见 [LICENSE](LICENSE) 获取详细信息。
所有依赖项都使用 MIT、Apache 2.0 或 BSD 许可证。
