MCP Rag Chroma Streamlit

集成MCP的RAG聊天助手-支持多格式文档

_通过 BINATI A分析_

使用Streamlit、LangChain和ChromaDB构建的生产就绪检索增强生成（RAG）应用程序。具有模型上下文协议（MCP）集成功能，可实现无缝工具调用，并支持包括OpenAI和Ollama在内的多个LLM提供商。

截图

UI Screenshot 1 UI Screenshot 2 UI Screenshot 3 UI Screenshot 4 UI Screenshot 5 UI Screenshot 6 UI Screenshot 7 UI Screenshot 8 UI Screenshot 9

特性

核心能力

• 多格式文档摄入：支持PDF、DOCX、TXT、HTML、PPT/PPTX、XLSX、ODT、MD、CSV、JSON和XML
• 向量数据库：ChromaDB与Ollama嵌入，用于高效的语义搜索
• 多个LLM提供商:

- OpenAI（GPT-4o、GPT-4o-mini、GPT-3.5涡轮增压） - Ollama（QWEN2.5，Callama3.2，Mistral，Phi3）

• MCP服务器集成：基于模块化工具的可扩展性架构
• 智能体：LangGraph驱动的代理，具有工具调用功能
• 并发处理：线程池文档处理可实现高性能
• 交互式用户界面：简洁、响应迅速的Streamlit界面，提供实时反馈

高级功能

• API错误时从OpenAI自动回退到Ollama
• 用于详细执行跟踪的调试模式
• 批处理数据库操作以获得最佳性能
• Ollama和MCP服务的健康检查
• 全面的错误处理和恢复
• 基于会话的聊天历史管理

建筑

┌─────────────────┐
│  Streamlit UI   │
│   (app_ui.py)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────────┐
│  LangChain      │◄─────┤  MCP Server      │
│  Agent          │      │  (server.py)     │
└────────┬────────┘      └──────────────────┘
         │                        │
         ▼                        ▼
┌─────────────────┐      ┌──────────────────┐
│  LLM Provider   │      │  API Utils       │
│ (OpenAI/Ollama) │      │ (api_utils.py)   │
└─────────────────┘      └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  ChromaDB        │
                         │  Vector Store    │
                         └──────────────────┘

技术栈

• 前端：流线型1.52+
• LLM框架：LangChain，LangGraph
• 向量数据库：ChromaDB 1.3+
• 嵌入：Ollama（nomic嵌入文本）
• LLM提供商OpenAI API，创建
• 主控程序：FastMCP 2.13+
• 文档处理：PyPDF2、python docx、python pptx、openpyxl、beautifulsoup4
• python: 3.13+

先决条件

1. Python 3.13或更高版本
2. 奥拉玛 （用于嵌入和/或本地LLM）

   # Install Ollama from https://ollama.ai

   # Pull required models
   ollama pull nomic-embed-text  # For embeddings
   ollama pull qwen2.5           # For local LLM (optional)

1. OpenAI API密钥 （可选，适用于OpenAI模型）
2. 紫外线 （Python包安装程序）

   pip install uv

安装

1.克隆存储库

git clone https://github.com/yourusername/mcp-rag-chroma-streamlit.git
cd mcp-rag-chroma-streamlit

2.创建虚拟环境

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

3.安装依赖项

# Using uv (recommended)
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt

4.配置环境变量

创建一个 .env 项目根目录中的文件：

# OpenAI Configuration (optional)
OPENAI_API_KEY=sk-your-openai-api-key-here

# DO NOT set OPENAI_API_BASE unless using a proxy
# OPENAI_API_BASE should be commented out for standard OpenAI usage

# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434

# Database Configuration (optional)
CHROMA_PATH=./chromadb
COLLECTION_NAME=document_collection

重要：如果您在OpenAI中看到身份验证错误，请确保 OPENAI_API_BASE 未设置或已注释掉。

用法

启动应用程序

1. 确保Ollama正在运行:

   ollama serve

1. 启动Streamlit应用程序:

   streamlit run app_ui.py

1. 访问用户界面：打开浏览器 http://localhost:8501

摄入文件

通过用户界面

1. 导航到侧边栏 “文档管理” 章节
2. 点击 “上载文档”
3. 输入文件路径、文件夹路径或URL
4. 点击 “摄入文件”

支持的来源

• 文件: /path/to/document.pdf
• 文件夹: /path/to/documents/ （处理所有支持的文件）
• 统一资源定位符: https://example.com/document.pdf

支持格式

PDF、DOCX、DOC、TXT、HTML、PPTX、PPT、XLSX、XLS、ODT、MD、CSV、JSON、XML

查询文档

1. 在聊天输入中键入您的问题
2. 点击 “发送” 或按Enter键
3. 代理人将：

- 从ChromaDB检索相关文档块 - 使用LLM生成上下文答案 - 显示来源和引用

查询示例

- "What is this document about?"
- "Summarize the key findings in the research paper"
- "What are the main points discussed in section 3?"
- "Find all mentions of [specific topic]"

MCP工具

MCP服务器(server.py)提供以下工具：

ingest_document(source: str)

从文件路径、文件夹或URL中获取文档。支持并发处理。

示例:

{"source": "/path/to/document.pdf"}
{"source": "https://example.com/file.docx"}
{"source": "/path/to/folder/"}

ingest_pdf(source: str) （遗产）

仅接受传统PDF格式。使用 ingest_document 相反。

retrieve(query: str, n: int = 5)

检索查询的前N个最相关的文档块。

示例:

{"query": "machine learning techniques", "n": 5}

db_info()

获取数据库统计信息，包括块计数、源和配置。

check_ollama()

验证Ollama服务健康状况和嵌入模型可用性。

clear_db()

清除矢量数据库中的所有数据并重新初始化。

配置

模型设置

在UI侧栏中调整或修改 app_ui.py:

# OpenAI
model_name = "gpt-4o-mini"  # gpt-4o, gpt-3.5-turbo
temperature = 0.7
max_tokens = 1024

# Ollama
model_name = "qwen2.5"  # llama3.2, mistral, phi3
base_url = "http://localhost:11434"

矢量数据库设置

在中配置 api_utils.py:

CHROMA_PATH = "./chromadb"
COLLECTION_NAME = "document_collection"
EMBED_MODEL = "nomic-embed-text"
CHUNK_SIZE = 1000
CHUNK_OVERLAP = 200
MAX_WORKERS = 4  # Concurrent document processing

故障排除

OpenAI身份验证错误（401）

错误: Error code: 401 - {'error': {'message': 'No cookie auth credentials found'}}

解决方案:

• 确保 .env 文件已存在 OPENAI_API_KEY=sk-...
• 评论或删除 OPENAI_API_BASE 如存在
• 验证API密钥在 platform.openai.com/api-keys

Ollama连接错误

错误: Cannot connect to Ollama

解决方案:

# Start Ollama service
ollama serve

# Verify models are installed
ollama list

# Pull missing models
ollama pull nomic-embed-text
ollama pull qwen2.5

MCP服务器错误

错误: Connection error with MCP server

解决方案:

• 确保 server.py 存在于项目根目录中
• 验证 uv 已安装： uv --version
• 检查Python环境是否已激活
• 使用侧栏“测试MCP连接”按钮测试MCP连接

文件摄取失败

错误: No supported document files found

解决方案:

• 验证文件路径是否正确且可访问
• 检查是否支持文件扩展名
• 确保文件权限允许读取
• 尝试绝对路径而不是相对路径

空响应

问题：代理未返回响应

解决方案:

• 确保文档已被接收（勾选“获取数据库统计信息”）
• 验证Olama嵌入物是否正常工作（“测试Olama”）
• 在侧边栏中启用调试模式以进行详细诊断
• 检查LangSmith跟踪（如果启用）

项目结构

mcp-rag-chroma-streamlit/
├── app_ui.py              # Main Streamlit application
├── server.py              # MCP server implementation
├── api_utils.py           # Vector DB and document processing utilities
├── main.py                # Alternative CLI entry point
├── requirements.txt       # Python dependencies
├── pyproject.toml         # Project metadata and dependencies
├── .env                   # Environment variables (create this)
├── chromadb/              # Vector database storage (auto-created)
└── README.md              # This file

发展

运行测试

# Test Ollama connectivity
ollama list

# Test MCP server directly
uv run server.py

# Test OpenAI API
python -c "from openai import OpenAI; print(OpenAI().models.list())"

调试模式

在UI侧栏“高级设置”下启用→ “显示调试信息”

显示器：

• MCP会话初始化详细信息
• 刀具装载信息
• 代理执行跟踪
• 响应提取方法

扩展功能

添加新的MCP工具 在 server.py:

@mcp.tool()
async def custom_tool(param: str) -> Dict[str, Any]:
    """Tool description for the agent"""
    # Implementation
    return {"status": "success", "data": "result"}

添加文档格式支持 在 api_utils.py:

SUPPORTED_EXTENSIONS.add('.new_format')

# Add extractor in document_to_chunks()
elif ext == '.new_format':
    # Custom extraction logic
    text = extract_custom_format(doc_path)

性能提示

1. 批量文档摄取：处理整个文件夹而不是单个文件
2. 调整块大小：较大的块（1500）用于一般文档，较小的块（500）用于结构化数据
3. 使用本地LLM：Ollama免费私人加工
4. 启用缓存：LangChain自动缓存重复查询
5. 增加工人：设置 MAX_WORKERS=8 实现更快的多文档处理

安全注意事项

• API密钥：从不承诺 .env 文件到版本控制
• 输入验证：在处理之前，所有文件路径都经过验证
• 沙箱：考虑在容器化环境中运行
• 速率限制：对生产部署实施速率限制

贡献

欢迎投稿！请按照以下步骤操作：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• LangChain LLM框架
• 色度数据库 用于矢量存储
• 奥拉玛 用于本地嵌入和LLM
• FastMCP 用于MCP服务器实现
• 溪流 漂亮的UI框架

支持

对于问题、疑问或贡献：

• 打开一个问题
• 检查现有问题是否存在类似问题
• 提供详细的错误消息和日志

路线图

• \[\]多用户会话管理
• \[\]云部署指南（AWS、GCP、Azure）
• \[\]高级组块策略（语义、递归）
• \[\]支持更多法学硕士提供者（Anthropic、Cohere）
• \[\]矢量数据库替代方案（松果体、Weaviate）
• \[\]文档版本控制和更新跟踪
• \[\]将聊天记录导出为PDF/Markdown
• \[\]用于编程访问的API端点

______________________________________________________________________

为重视模块化、性能和可扩展性的开发人员精心构建。