AI导哈

RAG文档索引服务

一个高性能的RAG模型上下文协议(MCP)服务器，支持自动文档索引、智能组织和多格式文档处理，适用于知识管理和信息检索场景。

  • by justinlime
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 justinlime/easy_mcp_rag

使用说明

简易MCP RAG🚀

使用Qdrant的RAG高性能模型上下文协议（MCP）服务器。专为UV/UVX构建，支持CPU/GPU和HTTP传输。

✨ 特性

  • 🔍 自动文档索引 -扫描目录并索引所有文档
  • 📁 智能组织 -每个子目录都成为自己的可搜索数据集
  • 🛠️ 动态MCP工具 -为每个集合自动生成工具
  • 📄 多格式支持 -PDF、DOCX、CSV、XLSX、TXT、Markdown等
  • ⚡ GPU加速 -可选CUDA/MPS支持，可实现更快的嵌入
  • 🌐 HTTP传输 -以HTTP服务器或stdio运行
  • 📦 UV/UVX就绪 -只需一个命令即可安装并运行
  • 📊 详细日志记录 -详细的查询跟踪和监控

🚀 快速开始

使用UVX安装（推荐）

直接从GitHub运行，无需安装：

uvx --from git+https://github.com/yourusername/easy_mcp_rag.git easy_mcp_rag --data-dir ./documents

使用UV进行安装

# Install from GitHub
uv pip install git+https://github.com/yourusername/easy_mcp_rag.git

# Or clone and install locally
git clone https://github.com/yourusername/easy_mcp_rag.git
cd easy_mcp_rag
uv pip install -e .

📋 先决条件

  1. 启动Qdrant （使用Docker）：
docker run -p 6333:6333 qdrant/qdrant
  1. 准备你的文件:
documents/
├── legal_docs/
│   ├── contract.pdf
│   └── terms.docx
├── research/
│   ├── paper1.pdf
│   └── notes.txt
└── data/
    └── analysis.csv

💻 用法

基本用法（stdio）

# With UVX
uvx --from git+https://github.com/yourusername/easy_mcp_rag.git easy_mcp_rag --data-dir ./documents

# With UV
uv run easy_mcp_rag --data-dir ./documents

# After installation
easy_mcp_rag --data-dir ./documents

HTTP模式

easy_mcp_rag --data-dir ./documents --transport http --http-port 8000

GPU加速

# Auto-detect GPU
easy_mcp_rag --data-dir ./documents --device auto

# Force CUDA (NVIDIA GPU)
easy_mcp_rag --data-dir ./documents --device cuda

# Force MPS (Apple Silicon)
easy_mcp_rag --data-dir ./documents --device mps

# Force CPU
easy_mcp_rag --data-dir ./documents --device cpu

高级配置

easy_mcp_rag \
  --data-dir ./documents \
  --qdrant-host localhost \
  --qdrant-port 6333 \
  --device cuda \
  --embedding-model all-mpnet-base-v2 \
  --chunk-size 1024 \
  --chunk-overlap 100 \
  --top-k 10 \
  --batch-size 64 \
  --verbose \
  --force-reindex

🔧 配置选项

标志 描述 默认值
--data-dir 包含文档子目录的目录 必需
--qdrant-host Qdrant服务器主机 localhost
--qdrant-port Qdrant服务器端口 6333
--device 设备：自动、cpu、cuda、mps auto
--transport 传输类型：stdio，http stdio
--http-host HTTP服务器主机 0.0.0.0
--http-port HTTP服务器端口 8000
--embedding-model 句子转换模型 all-MiniLM-L6-v2
--chunk-size 文本块大小（字符） 512
--chunk-overlap 块重叠（字符） 50
--top-k 每次搜索的结果 5
--batch-size 嵌入批量大小 32
--verbose 启用详细日志记录 False
--log-level 日志级别 INFO
--force-reindex 强制重新索引所有文档 False

🎯 MCP客户端配置

Claude Desktop/Cline/其他MCP客户端

添加到MCP客户端配置中：

{
  "mcpServers": {
    "rag-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/easy_mcp_rag.git",
        "easy_mcp_rag",
        "--data-dir",
        "/path/to/your/documents",
        "--device",
        "auto",
        "--verbose"
      ]
    }
  }
}

使用HTTP传输

{
  "mcpServers": {
    "rag-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/easy_mcp_rag.git",
        "easy_mcp_rag",
        "--data-dir",
        "/path/to/your/documents",
        "--transport",
        "http",
        "--http-port",
        "8000"
      ]
    }
  }
}

🛠️ 运作原理

  1. 扫描 -查找数据目录中的所有子目录
  2. 负载 -从所有支持的文件类型中提取文本
  3. 块 -将文档拆分为重叠的块
  4. 嵌入 -生成向量嵌入（CPU或GPU）
  5. 索引 -存储在Qdrant中（每个子目录一个集合）
  6. 服务 -为每个集合创建MCP工具

示例

documents/
├── legal_docs/      → Creates "legal_docs_search" tool
├── research/        → Creates "research_search" tool
└── data/            → Creates "data_search" tool

📄 支持的文件类型

类别 扩展
文本 .txt, .md, .py, .js, .json, .xml, .html, .css
PDF .pdf
Word .docx, .doc
电子表格 .csv, .xlsx, .xls

🎨 嵌入模型

根据您的需求进行选择：

型号 尺寸 速度 质量 用例
all-MiniLM-L6-v2 384 ⚡⚡⚡ 好 默认，快速
all-MiniLM-L12-v2 384 ⚡⚡ 更好 平衡
all-mpnet-base-v2 768 ⚡ 最佳 质量

🐛 故障排除

Qdrant连接失败

# Check if Qdrant is running
curl http://localhost:6333

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant

未检测到GPU

# Check PyTorch GPU support
python -c "import torch; print(torch.cuda.is_available())"

# Install with GPU support
uv pip install -e ".[gpu]"

内存不足

# Use smaller model
--embedding-model all-MiniLM-L6-v2

# Reduce batch size
--batch-size 16

# Use CPU
--device cpu

📊 日志记录

启用详细日志记录以查看详细信息：

easy_mcp_rag --data-dir ./documents --verbose

输出包括：

  • ✅ 工具访问事件
  • 🔍 查询详细信息
  • 📈 结果计数
  • 🎯 相关性得分
  • 📁 源文件

例子：

2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Tool accessed: legal_docs_search
2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Query: contract terms
2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Results returned: 5
2024-01-20 10:30:15 - easy_mcp_rag.server - DEBUG - Result 1: score=0.8542

🔐 安全说明

  • HTTP模式暴露网络上的服务器
  • 使用 --http-host 127.0.0.1 仅限本地访问
  • 考虑生产部署的身份验证

📝 发展

# Clone repository
git clone https://github.com/yourusername/easy_mcp_rag.git
cd easy_mcp_rag

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Lint
ruff src/

🤝 贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 提交拉取请求

📜 许可证

MIT许可证-请参阅许可证文件

🙏 鸣谢

内置：

相关 MCP