Xantus - 私有RAG聊天系统与MCP集成

<div align="center">

一个用于与您的文档进行聊天的生产就绪型RAG（检索增强生成）系统

注重隐私 • 通过MCP扩展 • 多提供商AI支持

功能 • 快速开始 • 架构 • MCP集成 • 配置 • API参考

</div>

---

目录

• 概述
• 功能
• 架构
• 快速开始
  • 前提条件
  • 安装
  • 首次运行
• MCP集成
• 配置
  • 环境变量
  • 提供商设置
  • RAG调整
• 使用
  • Streamlit界面
  • API端点
  • Python客户端
• 开发
• 故障排除
• 常见问题解答
• 许可证

---

概述

Xantus是一个注重隐私的RAG系统，它允许您使用AI与文档进行聊天。与仅限云的解决方案不同，Xantus可以完全本地运行或使用云提供商——由您选择。

Xantus有何不同？

• 注重隐私：所有数据都保留在您的系统中，使用本地AI
• 可扩展性：通过MCP（模型上下文协议）集成外部工具
• 多种用户界面：Streamlit界面 + 兼容OpenAI的API
• 多提供商支持：支持Ollama、OpenAI、Anthropic等
• 模块化：轻松更换LLMs、嵌入式向量存储
• 生产就绪：依赖注入、适当的错误处理、日志记录

---

功能

核心功能

• 文档聊天：上传PDF、DOCX、TXT、Markdown文件并与其对话
• 语义搜索：使用ChromaDB或Qdrant进行RAG驱动的检索
• 多种用户界面：
  • 供最终用户的干净Streamlit界面
  • 供集成使用的RESTful API
  • 供开发者的Python SDK
• 灵活的AI后端：
  • 本地：Ollama（注重隐私）
  • 云：OpenAI、Anthropic
  • 混合：云LLM + 本地嵌入式向量存储

高级功能

• MCP集成：连接外部工具（计算器、文件系统、数据库）
• ⚙可配置：YAML + 环境变量
• 多种向量存储：ChromaDB、Qdrant
• RAG调整：调整块大小、重叠、top-k检索
• 安全：通过环境变量管理API密钥
• 可扩展：异步API，具有适当的依赖注入

---

架构

Xantus建立在一个现代、模块化的架构之上：

┌─────────────────────────────────────────────────────────┐
│                        用户                             │
└────────────┬────────────────────────────┬───────────────┘
             │                            │
    ┌────────▼────────┐          ┌────────▼─────────┐
    │  Streamlit UI   │          │   API客户端    │
    │  (端口8501)    │          │   (curl, SDK)    │
    └────────┬────────┘          └────────┬─────────┘
             │                            │
             └────────────┬───────────────┘
                          │
                 ┌────────▼─────────┐
                 │   FastAPI服务器 │
                 │   (端口8000)    │
                 └────────┬─────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
   ┌──────▼──────┐ ┌──────▼───────┐ ┌────▼─────┐
   │ 聊天服务│ │导入服务│ │   MCP    │
   └──────┬──────┘ └──────┬───────┘ │ 服务  │
          │               │         └────┬─────┘
          │               │              │
   ┌──────▼───────────────▼──────────────▼─────┐
   │        依赖注入容器     │
   │  (LLM • 嵌入式向量存储 • 向量存储 • MCP)  │
   └────────────────────┬──────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌────▼────┐    ┌─────▼─────┐   ┌───▼────┐
   │   LLM   │    │ 嵌入式向量存储│   │ 向量存储 │
   │提供商 │    │  提供商 │   │ 存储  │
   └─────────┘    └───────────┘   └────────┘
   │Ollama   │    │HuggingFace│   │Chroma  │
   │OpenAI   │    │  Ollama   │   │Qdrant  │
   │Anthropic│    │  OpenAI   │   └────────┘
   └─────────┘    └───────────┘
                                   ┌──────────┐
                                   │MCP服务器│
                                   │TypeScript│
                                   └──────────┘
                                   │计算器│
                                   │文件系统│
                                   │文本处理│
                                   └──────────┘

技术栈

组件	技术	目的
后端	FastAPI + Python 3.10+	高性能异步API
RAG框架	LlamaIndex	文档索引和检索
用户界面	Streamlit	用户友好的聊天界面
配置	Pydantic + YAML	类型安全设置
依赖注入	Injector	清晰的依赖注入
向量数据库	ChromaDB / Qdrant	语义搜索
MCP	模型上下文协议	外部工具集成

项目结构

xantus/
├── .env.example                  # 环境变量模板
├── .gitignore                    # Git忽略模式
├── config.yaml                   # 主配置文件
├── requirements.txt              # Python依赖项
├── setup_mcp.sh                 # MCP设置自动化
├── start_api.sh                 # API服务器启动脚本
├── start_ui.sh                  # 用户界面启动脚本
│
├── xantus/                       # 主应用包
│   ├── __init__.py
│   ├── main.py                  # FastAPI应用程序入口
│   ├── container.py             # 依赖注入设置
│   │
│   ├── api/                     # API端点
│   │   ├── chat_router.py       # /v1/chat/completions
│   │   ├── ingest_router.py     # /v1/ingest/*
│   │   └── embeddings_router.py # /v1/embeddings
│   │
│   ├── services/                # 业务逻辑
│   │   ├── chat_service.py      # RAG驱动的聊天
│   │   ├── ingest_service.py    # 文档处理
│   │   └── mcp_service.py       # MCP工具编排
│   │
│   ├── components/              # 组件工厂
│   │   ├── llm/
│   │   │   └── llm_factory.py   # LLM提供商工厂
│   │   ├── embeddings/
│   │   │   └── embedding_factory.py
│   │   └── vector_store/
│   │       └── vector_store_factory.py
│   │
│   ├── models/                  # 数据模型
│   │   └── schemas.py           # Pydantic请求/响应模型
│   │
│   └── config/                  # 配置
│       └── settings.py          # 使用Pyd
│
├── ui/                          # 用户界面
│   └── streamlit_app.py         # Streamlit聊天应用程序
│
├── mcp-servers/                 # MCP集成（git子模块）
│   └── mcp-starter-template-ts/ # TypeScript MCP服务器
│       ├── dist/                # 编译JavaScript
│       │   └── start.js         # 入口点
│       └── src/                 # TypeScript源代码
│           └── tools/           # 工具实现
│
├── data/                        # 数据目录（git忽略）
│   └── vector_store/            # 持久化向量嵌入
│
└── docs/                        # 文档
    ├── MCP_INTEGRATION.md       # MCP技术指南
    ├── README_MCP.md            # MCP快速入门
    └── SETUP_COMPLETE.md        # 设置总结

---

快速开始

前提条件

• Python 3.10+（检查：python --version）
• Node.js 18+（用于MCP集成，检查：node --version）
• Git（用于克隆子模块）
• （可选）Ollama（用于本地AI）

安装

第一步：克隆仓库

# 克隆带有MCP子模块
git clone --recurse-submodules https://github.com/onamfc/rag-chat
cd xantus

# 或者如果您已经克隆但没有子模块：
git submodule update --init --recursive

第二步：创建虚拟环境

# 创建虚拟环境
python -m venv venv

# 激活它
source venv/bin/activate  # Linux/Mac
# 或者
venv\Scripts\activate     # Windows

第三步：安装Python依赖项

pip install -r requirements.txt

第四步：设置MCP（可选但推荐）

# 这将：
# - 初始化MCP子模块
# - 安装npm依赖项
# - 构建TypeScript MCP服务器
./setup_mcp.sh

第五步：配置环境变量

# 复制示例文件
cp .env.example .env

# 编辑.env并添加您的API密钥（如果使用云提供商）
# 对于Anthropic：
XANTUS_LLM__API_KEY=sk-ant-api03-your-key-here

# 对于OpenAI：
# XANTUS_LLM__API_KEY=sk-your-openai-key-here

第六步：配置设置

编辑config.yaml以选择您的提供商：

选项A：完全本地（注重隐私）

llm:
  provider: ollama
  model: llama3.2

embedding:
  provider: huggingface
  model: BAAI/bge-small-en-v1.5

mcp:
  enabled: true  # 启用MCP工具

选项B：云驱动（Anthropic）

llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: null  # 从.env读取

embedding:
  provider: huggingface  # 保持嵌入式向量存储本地
  model: BAAI/bge-small-en-v1.5

mcp:
  enabled: true

选项C：OpenAI

llm:
  provider: openai
  model: gpt-4
  api_key: null  # 从.env读取

embedding:
  provider: openai
  model: text-embedding-3-small
  api_key: null

首次运行

启动API服务器

# 选项1：使用启动脚本
./start_api.sh

# 选项2：手动启动
python -m xantus.main

# API将在http://localhost:8000可用
# API文档在http://localhost:8000/docs

您应该看到：

INFO - 正在启动Xantus应用程序...
INFO - 加载了LLM提供商：anthropic的设置
INFO - 依赖注入容器已初始化
INFO - 在127.0.0.1:8000启动服务器

启用MCP时，您还将看到：

INFO - 正在启动MCP服务器'mcp-starter-template'：node mcp-servers/...
INFO - 从'mcp-starter-template'加载了4个工具：['calculate', 'filesystem', 'text-processing', 'weather']

启动用户界面（在新终端中）

# 再次激活虚拟环境
source venv/bin/activate

# 启动Streamlit
streamlit run ui/streamlit_app.py

# 用户界面将在浏览器中的http://localhost:8501打开

上传文档并聊天！

1. 单击侧边栏中的“上传文档”
2. 选择PDF、TXT、DOCX或Markdown文件
3. 等待处理（您会看到进度）
4. 就您的文档提问！

示例问题：

• “这份文档的主要主题是什么？”
• “总结关键要点”
• “计算第3节提到的总收入”（使用MCP计算器）
• “与../reports/2023.pdf中的文件进行比较”（使用MCP文件系统）

---

MCP集成

MCP（模型上下文协议）允许Claude在回答问题时使用外部工具。

可用的工具有哪些？

您的TypeScript MCP服务器（在mcp-servers/mcp-starter-template-ts/中）提供了：

工具	功能	示例用途
计算器	数学运算	“计算Q1-Q4收入总和”
文件系统	读/写/列出文件	“与去年的报告在../reports/中进行比较”
文本处理	字数统计、情感分析、大小写转换	“分析客户反馈的情感”
天气	天气数据（模拟）	“检查活动规划的天气”

MCP架构

用户问题
     ↓
Xantus检索文档上下文（RAG）
     ↓
发送给Claude，附带可用的MCP工具
     ↓
Claude决定使用一个工具（例如，计算器）
     ↓
Xantus转发工具调用到MCP服务器（TypeScript）
     ↓
MCP服务器执行工具并返回结果
     ↓
Claude将结果整合到答案中
     ↓
用户获得全面的回答

启用/禁用MCP

在config.yaml中：

mcp:
  enabled: true  # 设置为false以禁用MCP

  servers:
    - name: "mcp-starter-template"
      command: "node"
      args: ["mcp-servers/mcp-starter-template-ts/dist/start.js"]

添加更多MCP服务器

您可以连接多个MCP服务器：

mcp:
  enabled: true
  servers:
    # 您的自定义工具
    - name: "my-tools"
      command: "node"
      args: ["mcp-servers/mcp-starter-template-ts/dist/start.js"]

    # 数据库访问
    - name: "postgres"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]

    # 网络搜索
    - name: "brave-search"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-brave-search"]

MCP文档

有关完整的MCP设置和定制：

• 快速入门：README_MCP.md

---

配置

环境变量

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

# ===== LLM API密钥 =====
# 对于Anthropic（双下划线用于嵌套配置！）
XANTUS_LLM__API_KEY=sk-ant-api03-your-key-here

# 对于OpenAI
# XANTUS_LLM__API_KEY=sk-your-openai-key-here

# ===== 嵌入式API密钥（可选）=====
# XANTUS_EMBEDDING__API_KEY=sk-your-key-here

# ===== 覆盖其他设置 =====
# 格式：XANTUS_<SECTION>__<KEY>=值
# 示例：
# XANTUS_LLM__TEMPERATURE=0.5
# XANTUS_RAG__SIMILARITY_TOP_K=10
# XANTUS_SERVER__PORT=8001

重要：对于嵌套配置，请使用双下划线（__）！

提供商设置

使用Ollama进行本地设置

1. 安装Ollama：https://ollama.com/download

2. 启动Ollama：

   ollama serve
   

3. 拉取模型：

   ollama pull llama3.2        # 用于聊天
   ollama pull nomic-embed-text # 用于嵌入式向量存储
   

4. 配置 config.yaml：

   llm:
     provider: ollama
     model: llama3.2
     api_base: http://localhost:11434  # 默认
   
   embedding:
     provider: ollama
     model: nomic-embed-text
   

Anthropic设置