本地_RAG_mcp

Name: 本地_RAG_mcp
Author: ItsMistahJi

作者：ItsMistahJi2 星标更新：2025-05-28

安装使用来源：spider==github.com

项目介绍

local_RAG_mcp

这是我的尝试，创建一个本地RAG MCP服务器，用于与本地的.docx和.xlsx文件进行对话。

使用Ollama和MCP进行本地文档问答

该项目提供了一个基于Python的MCP代理，允许您使用Ollama进行本地语言模型推理，与您的本地Word（.docx）和Excel（.xlsx）文档进行对话，确保您的私有数据保留在您的机器上。

它使用LangChain社区组件进行文档加载、文本分割、嵌入和向量存储（ChromaDB），并通过mcp-sdk将其功能暴露为一组工具。

特性：

私有且本地化： 所有的处理、嵌入和语言模型推理都在本地通过Ollama完成。没有数据离开您的机器。
支持的文档类型： 目前支持Microsoft Word（.docx）和Excel（.xlsx）文件。（易于扩展到PDF、.txt等）
简单的索引： 一个专用的MCP工具扫描指定目录，处理文档，并构建可搜索的向量索引。
自然语言问答： 用自然语言询问有关您文档内容的问题。
MCP集成： 通过MCP工具暴露功能，可以使用MCP Inspector或mcp-cli。

工作原理

文档加载： 代理扫描指定的本地文件夹以查找支持的文档。
文本分块： 文档内容被分割成更小、更易管理的块。
嵌入： 每个块使用本地Ollama嵌入模型（例如，nomic-embed-text）转换成数值表示（嵌入）。
向量存储： 这些嵌入及其对应的文本块存储在本地的ChromaDB向量存储中。
查询（RAG - 增强检索生成）：
- 当您提问时，问题也会被嵌入。
- 系统会在向量存储中搜索与问题嵌入最相似的文档块。 相关块（上下文）与原始问题结合形成提示。
- 这个提示会被发送给本地的Ollama聊天模型（如llama3）来生成答案。

先决条件

Python： Python 3.9+
Ollama： 需要安装并运行Ollama。
- 安装：ollama.com
- 确保Ollama正在服务模型。您可以通过在终端中运行ollama list来测试这一点。
所需的Ollama模型：
- 拉取嵌入模型：ollama pull nomic-embed-text
- 拉取聊天模型：ollama pull llama3

安装

克隆仓库（或下载脚本）：

# 如果您创建了一个Git仓库：
# git clone https://github.com/ItsMistahJi/local_RAG_mcp
# cd local_RAG_mcp

创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

安装Python依赖项：
```
pip install -r requirements.txt
```

设置及使用

准备您的文档：
- 在server.py脚本所在的同一目录下创建一个名为docs_simple的文件夹（或在脚本中配置DOC_DIR）。
- 将您的.docx和.xlsx文件放入这个docs_simple文件夹中。
运行MCP代理脚本： 打开您的终端，导航到项目目录，并运行：
```
python server.py
```
脚本将启动，尝试连接到Ollama，然后等待MCP客户端连接（如MCP Inspector）。您将在该终端中看到日志输出。
使用MCP Inspector交互（推荐）：
- 下载并安装MCP Inspector。
- 打开MCP Inspector。
- 配置代理：
  - 如果代理没有自动检测到，您可能需要手动添加它。
  - 转到“文件”>“首选项”>“代理”（或类似部分）。
  - 点击“添加”或“+”图标。
  - 名称： 给它一个描述性的名称（例如，“我的本地RAG代理”）。
  - 命令： 输入运行脚本的完整命令：python /完整路径/to/your/server.py。
  - 传输： 选择stdio。
  - 保存配置。
- 连接并使用：
  - 回到主MCP Inspector窗口，在列表中找到您配置的代理。
  - 点击“连接”或旁边的播放图标。MCP Inspector将运行您的脚本。
  - 连接后，您将看到可用的工具：
    - initialize_and_index：首先运行此工具。它不需要参数。它将处理docs_simple中的文档，并在chroma_db_simple中创建本地向量数据库。检查代理终端日志以了解进度。
    - ask_question：索引完成后，使用此工具。它接受一个参数：
```
{
  "question": "关于这些文档的问题"
}
```
      代理将检索相关信息并生成答案。

使用mcp-cli交互（替代方法）： 确保您的Python脚本（server.py）尚未运行。mcp-cli将为每个命令启动它。

列出可用工具（可选检查）：

mcp tool list CompanyDocumentQA-Ollama --command "python server.py" --transport stdio

索引文档：

mcp tool call CompanyDocumentQA-Ollama initialize_and_index --command "python server.py" --transport stdio

(等待其完成。您将在终端中看到日志。)

提问：

m
mcp tool call CompanyDocumentQA-Ollama ask_question '{"question": "公司的年假政策是什么？"}' --command "python server.py" --transport stdio

脚本概述（`server.py`）

配置： 文件顶部的常量用于文档目录、ChromaDB路径、Ollama模型等。
辅助函数： 用于加载和分割文档、初始化Ollama组件。
initialize_and_index（MCP工具）：
- 加载.docx和.xlsx文件。
- 将它们分割成块。
- 使用Ollama生成嵌入。
- 将块和嵌入存储在一个持久的ChromaDB中。
ask_question（MCP工具）：
- 接受用户问题。
- 对问题进行嵌入。
- 从ChromaDB检索相关的文档块。
- 构建带有问题和上下文的提示。
- 从Ollama LLM获取答案。
主块： 设置日志记录，初始化Ollama组件，并在stdio上启动MCP代理服务器。

自定义及未来增强

更多文档类型： 在load_documents_from_directory中添加PDF（PyPDFLoader）、文本文件（TextLoader）等加载器。记得安装必要的包（如pypdf，unstructured）。
不同的模型： 更改EMBEDDING_MODEL_NAME和LLM_MODEL_NAME以使用其他Ollama模型。确保它们已本地拉取。
分块策略： 在RecursiveCharacterTextSplitter中实验chunk_size和chunk_overlap以获得更好的结果。
检索选项： 修改ask_question中的search_kwargs={"k": 3}以检索更多或更少的块。如有需要，探索其他检索模式。
提示工程： 在ask_question中优化提示模板以获得更好的LLM响应。
错误处理： 增强错误处理和用户反馈。
Web UI（例如，Streamlit/Gradio）： 将MCP代理或其核心逻辑包装在一个简单的Web UI中，以便非技术人员更容易访问，可能通过让UI调用MCP代理工具实现。

故障排除

“未找到Ollama”/连接错误：
- 确保Ollama正在运行（ollama serve或Ollama桌面应用）。
- 验证脚本中的OLLAMA_BASE_URL是否匹配您的Ollama设置（默认是http://localhost:11434）。
- 确保已拉取模型（nomic-embed-text，llama3）：ollama list。
“未找到文档”/“向量存储为空”：
- 再次检查脚本中的DOC_DIR路径，确保它指向正确的文件夹。
- 确保您的文档文件在该文件夹中并且具有支持的扩展名（.docx，.xlsx）。
- 运行initialize_and_index工具。检查终端日志以了解索引期间的错误。
mcp-cli问题：
- 确保正确安装了mcp-cli（pip install "mcp-cli[cli]"）。
- 使用完整的--command "python /path/to/script.py"和--transport stdio标志。
MCP Inspector看不到代理：
- 确保您已在MCP Inspector首选项中正确配置了代理，包括Python脚本的完整路径和stdio传输。
- 确保当MCP Inspector尝试启动它时，脚本尚未运行。