Rag Chat

Xantus-集成MCP的私人RAG聊天系统

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

*考虑隐私•可通过MCP扩展•多提供商AI支持*

特性 • 快速开始 • 建筑 • MCP集成 • 配置 • API 参考

______________________________________________________________________

目录

• 概述
• 特性
• 建筑
• 快速开始

- 先决条件 - 安装 - 首次运行

• MCP集成
• 配置

- 环境变量 - 提供商设置 - RAG调谐

• 用法

- 流线型UI - API终点 - Python客户端

• 发展
• 故障排除
• 常见问题解答
• 许可证

______________________________________________________________________

概述

Xantus是一个 隐私第一 RAG系统允许您使用人工智能与文档聊天。与纯云解决方案不同，Xantus可以运行 完全本地化 或者使用云提供商——由您选择。

是什么让Xantus与众不同？

• 隐私第一：所有数据都保留在本地AI的系统中
• 可扩展：用于外部工具的MCP（模型上下文协议）集成
• 多个用户界面：流式接口+支持OpenAI的API
• 多供应商：支持Ollama、OpenAI、Anthropic等
• 模块化：轻松交换LLM、嵌入、向量存储
• 生产准备就绪：依赖注入、正确的错误处理、日志记录

______________________________________________________________________

特性

核心功能

• 文档聊天：上传PDF、DOCX、TXT、Markdown并与他们聊天
• 语义搜索：使用ChromaDB或Qdrant进行RAG驱动的检索
• 多个接口:

- 为终端用户提供干净的Streamlit UI - 用于集成的RESTful API - 面向开发人员的Python SDK

• 灵活的AI后端:

- 本地：Ollama（隐私优先） - 云：OpenAI，人类学 - 混合：云LLM+本地嵌入

高级功能

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

______________________________________________________________________

建筑

Xantus建立在现代模块化架构之上：

┌─────────────────────────────────────────────────────────┐
│                        User                             │
└────────────┬────────────────────────────┬───────────────┘
             │                            │
    ┌────────▼────────┐          ┌────────▼─────────┐
    │  Streamlit UI   │          │   API Clients    │
    │  (Port 8501)    │          │   (curl, SDK)    │
    └────────┬────────┘          └────────┬─────────┘
             │                            │
             └────────────┬───────────────┘
                          │
                 ┌────────▼─────────┐
                 │   FastAPI Server │
                 │   (Port 8000)    │
                 └────────┬─────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
   ┌──────▼──────┐ ┌──────▼───────┐ ┌────▼─────┐
   │ Chat Service│ │Ingest Service│ │   MCP    │
   └──────┬──────┘ └──────┬───────┘ │ Service  │
          │               │         └────┬─────┘
          │               │              │
   ┌──────▼───────────────▼──────────────▼─────┐
   │        Dependency Injection Container     │
   │  (LLM • Embeddings • Vector Store • MCP)  │
   └────────────────────┬──────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌────▼────┐    ┌─────▼─────┐   ┌───▼────┐
   │   LLM   │    │ Embeddings│   │ Vector │
   │Provider │    │  Provider │   │ Store  │
   └─────────┘    └───────────┘   └────────┘
   │Ollama   │    │HuggingFace│   │Chroma  │
   │OpenAI   │    │  Ollama   │   │Qdrant  │
   │Anthropic│    │  OpenAI   │   └────────┘
   └─────────┘    └───────────┘
                                   ┌──────────┐
                                   │MCP Server│
                                   │TypeScript│
                                   └──────────┘
                                   │Calculator│
                                   │FileSystem│
                                   │TextProc  │
                                   └──────────┘

技术栈

项目结构

xantus/
├── .env.example                  # Environment variable template
├── .gitignore                    # Git ignore patterns
├── config.yaml                   # Main configuration file
├── requirements.txt              # Python dependencies
├── setup_mcp.sh                 # MCP setup automation
├── start_api.sh                 # API server startup script
├── start_ui.sh                  # UI startup script
│
├── xantus/                       # Main application package
│   ├── __init__.py
│   ├── main.py                  # FastAPI application entry
│   ├── container.py             # Dependency injection setup
│   │
│   ├── api/                     # API endpoints
│   │   ├── chat_router.py       # /v1/chat/completions
│   │   ├── ingest_router.py     # /v1/ingest/*
│   │   └── embeddings_router.py # /v1/embeddings
│   │
│   ├── services/                # Business logic
│   │   ├── chat_service.py      # RAG-powered chat
│   │   ├── ingest_service.py    # Document processing
│   │   └── mcp_service.py       # MCP tool orchestration
│   │
│   ├── components/              # Component factories
│   │   ├── llm/
│   │   │   └── llm_factory.py   # LLM provider factory
│   │   ├── embeddings/
│   │   │   └── embedding_factory.py
│   │   └── vector_store/
│   │       └── vector_store_factory.py
│   │
│   ├── models/                  # Data models
│   │   └── schemas.py           # Pydantic request/response models
│   │
│   └── config/                  # Configuration
│       └── settings.py          # Settings management with Pydantic
│
├── ui/                          # User interface
│   └── streamlit_app.py         # Streamlit chat application
│
├── mcp-servers/                 # MCP integration (git submodules)
│   └── mcp-starter-template-ts/ # TypeScript MCP server
│       ├── dist/                # Compiled JavaScript
│       │   └── start.js         # Entry point
│       └── src/                 # TypeScript source
│           └── tools/           # Tool implementations
│
├── data/                        # Data directory (gitignored)
│   └── vector_store/            # Persisted vector embeddings
│
└── docs/                        # Documentation
    ├── MCP_INTEGRATION.md       # MCP technical guide
    ├── README_MCP.md            # MCP quick start
    └── SETUP_COMPLETE.md        # Setup summary

______________________________________________________________________

快速开始

先决条件

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

安装

步骤1：克隆存储库

# Clone with MCP submodules
git clone --recurse-submodules https://github.com/onamfc/rag-chat
cd xantus

# OR if you already cloned without submodules:
git submodule update --init --recursive

第二步：创建虚拟环境

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate     # Windows

步骤3：安装Python依赖项

pip install -r requirements.txt

步骤4：设置MCP（可选但推荐）

# This will:
# - Initialize MCP submodules
# - Install npm dependencies
# - Build TypeScript MCP server
./setup_mcp.sh

步骤5：配置环境变量

# Copy the example file
cp .env.example .env

# Edit .env and add your API keys (if using cloud providers)
# For Anthropic:
XANTUS_LLM__API_KEY=sk-ant-api03-your-key-here

# For OpenAI:
# XANTUS_LLM__API_KEY=sk-your-openai-key-here

步骤6：配置设置

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

选项A：完全本地（隐私优先）

llm:
  provider: ollama
  model: llama3.2

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

mcp:
  enabled: true  # Enable MCP tools

选项B：云驱动（人工智能）

llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key: null  # Read from .env

embedding:
  provider: huggingface  # Keep embeddings local
  model: BAAI/bge-small-en-v1.5

mcp:
  enabled: true

选项C:OpenAI

llm:
  provider: openai
  model: gpt-4
  api_key: null  # Read from .env

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

首次运行

启动API服务器

# Option 1: Using the startup script
./start_api.sh

# Option 2: Manual start
python -m xantus.main

# The API will be available at http://localhost:8000
# API docs at http://localhost:8000/docs

您应该看到：

INFO - Starting Xantus application...
INFO - Loaded settings with LLM provider: anthropic
INFO - Dependency injection container initialized
INFO - Starting server on 127.0.0.1:8000

启用MCP后，您还将看到：

INFO - Starting MCP server 'mcp-starter-template': node mcp-servers/...
INFO - Loaded 4 tools from 'mcp-starter-template': ['calculate', 'filesystem', 'text-processing', 'weather']

启动UI（在新终端中）

# Activate venv again
source venv/bin/activate

# Start Streamlit
streamlit run ui/streamlit_app.py

# The UI will open in your browser at 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/)提供：

MCP架构

User Question
     ↓
Xantus retrieves document context (RAG)
     ↓
Sends to Claude with available MCP tools
     ↓
Claude decides to use a tool (e.g., calculator)
     ↓
Xantus forwards tool call to MCP server (TypeScript)
     ↓
MCP server executes tool and returns result
     ↓
Claude incorporates result into answer
     ↓
User gets comprehensive response

启用/禁用MCP

在 config.yaml:

mcp:
  enabled: true  # Set to false to disable MCP

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

添加更多MCP服务器

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

mcp:
  enabled: true
  servers:
    # Your custom tools
    - name: "my-tools"
      command: "node"
      args: ["mcp-servers/mcp-starter-template-ts/dist/start.js"]

    # Database access
    - name: "postgres"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]

    # Web search
    - name: "brave-search"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-brave-search"]

MCP文件

对于完整的MCP设置和定制：

• 快速开始: README_MCP.md

______________________________________________________________________

配置

环境变量

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

# ===== LLM API Keys =====
# For Anthropic (double underscore for nested config!)
XANTUS_LLM__API_KEY=sk-ant-api03-your-key-here

# For OpenAI
# XANTUS_LLM__API_KEY=sk-your-openai-key-here

# ===== Embedding API Keys (optional) =====
# XANTUS_EMBEDDING__API_KEY=sk-your-key-here

# ===== Override Other Settings =====
# Format: XANTUS_
__=value
# Examples:
# XANTUS_LLM__TEMPERATURE=0.5
# XANTUS_RAG__SIMILARITY_TOP_K=10
# XANTUS_SERVER__PORT=8001

重要：使用 双下划线 (__)用于嵌套配置！

提供商设置

Ollama的本地设置

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

1. 启动Ollama:

   ollama serve

1. 拉模型:

   ollama pull llama3.2        # For chat
   ollama pull nomic-embed-text # For embeddings

1. 配置 config.yaml:

   llm:
     provider: ollama
     model: llama3.2
     api_base: http://localhost:11434  # Default

   embedding:
     provider: ollama
     model: nomic-embed-text

拟人设置

1. 获取API密钥: https://console.anthropic.com/

1. 添加到 .env:

   XANTUS_LLM__API_KEY=sk-ant-api03-your-key-here

1. 配置 config.yaml:

   llm:
     provider: anthropic
     model: claude-sonnet-4-20250514
     api_key: null  # Read from environment
     temperature: 0.7
     max_tokens: 4096

   embedding:
     provider: huggingface  # Use local for cost savings
     model: BAAI/bge-small-en-v1.5

OpenAI设置

1. 获取API密钥: https://platform.openai.com/api-keys

1. 添加到 .env:

   XANTUS_LLM__API_KEY=sk-your-openai-key-here

1. 配置 config.yaml:

   llm:
     provider: openai
     model: gpt-4-turbo-preview
     api_key: null

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

RAG调谐

微调检索 config.yaml:

rag:
  # Number of relevant chunks to retrieve
  similarity_top_k: 5

  # Size of text chunks (characters)
  chunk_size: 1024

  # Overlap between chunks (prevents context loss)
  chunk_overlap: 200

  # Enable advanced reranking (requires additional setup)
  enable_reranking: false

调整指南:

• 大块 （1024-2048）：更适合长篇内容
• 小块 （512-1024）：更适合具体事实
• 更高的top_k （8-10）：上下文更多，但速度较慢
• 下顶_k （3-5）：速度更快，但可能会错过上下文
• 重叠：建议使用chunk_size的15-20%

矢量存储配置

vector_store:
  provider: chroma  # or qdrant

  # Path to persist vector data
  persist_path: ./data/vector_store

  # Collection name
  collection_name: xantus_documents

服务器配置

server:
  host: 127.0.0.1  # Change to 0.0.0.0 for network access
  port: 8000

  # CORS settings
  cors_enabled: true
  cors_origins:
    - "*"  # Be more restrictive in production!

______________________________________________________________________

用法

流线型UI

使用Xantus的最简单方法：

1. 启动API （终端1）：

   ./start_api.sh

1. 启动UI （终端2）：

   ./start_ui.sh
   # OR
   streamlit run ui/streamlit_app.py

1. 导航至 http://localhost:8501

1. 上传文件 通过侧边栏

1. 聊天 和你的文件！

特性:

• ✅ 文档上传进度
• ✅ 文档管理（列表/删除）
• ✅ 聊天历史记录
• ✅ 上下文切换（是否使用RAG）
• ✅ 健康监测

API终点

健康检查

curl http://localhost:8000/health

答复：

{
  "status": "healthy",
  "version": "0.1.0",
  "components": {
    "llm": "anthropic",
    "embedding": "huggingface",
    "vector_store": "chroma"
  }
}

聊天完成（与RAG）

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are the main findings in the report?"}
    ],
    "use_context": true,
    "stream": false
  }'

答复：

{
  "id": "chat-123abc",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "claude-sonnet-4-20250514",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Based on the documents, the main findings are..."
    },
    "finish_reason": "stop"
  }]
}

上传文档

curl -X POST http://localhost:8000/v1/ingest/file \
  -F "file=@/path/to/document.pdf"

答复：

{
  "status": "success",
  "document_id": "doc_abc123",
  "chunks_created": 42
}

列出文件

curl http://localhost:8000/v1/ingest/documents

删除文档

curl -X DELETE http://localhost:8000/v1/ingest/documents/doc_abc123

生成嵌入

curl -X POST http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": "Text to embed", "model": "default"}'

Python客户端

import requests

# Start a session
session = requests.Session()
api_url = "http://localhost:8000"

# Upload a document
with open("document.pdf", "rb") as f:
    response = session.post(
        f"{api_url}/v1/ingest/file",
        files={"file": f}
    )
    print(f"Uploaded: {response.json()}")

# Chat with RAG
response = session.post(
    f"{api_url}/v1/chat/completions",
    json={
        "messages": [
            {"role": "user", "content": "Summarize the key points"}
        ],
        "use_context": True,
        "stream": False
    }
)

result = response.json()
print(result["choices"][0]["message"]["content"])

______________________________________________________________________

发展

项目理念

1. 隐私第一：默认为本地，支持云
2. 模块化：易于更换任何组件
3. 简洁：最小抽象
4. 类型安全：到处都是双关语
5. 生产就绪：正确的DI、错误处理、日志记录

添加新的LLM提供程序

1. 添加到设置 (xantus/config/settings.py):

   provider: Literal["ollama", "openai", "anthropic", "your-provider"]

1. 执行工厂 (xantus/components/llm/llm_factory.py):

   def _create_your_provider_llm(config: LLMConfig) -> LLM:
       return YourProviderLLM(
           model=config.model,
           api_key=config.api_key,
           temperature=config.temperature
       )

1. 更新工厂调度:

   elif config.provider == "your-provider":
       return _create_your_provider_llm(config)

添加新的矢量存储

类似的过程 xantus/components/vector_store/vector_store_factory.py

代码的风格

# Format code
black xantus/

# Lint
ruff check xantus/

# Type check
mypy xantus/

测试

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

______________________________________________________________________

故障排除

常见问题

1.“无法连接到Ollama”

解决方案：确保Olama正在运行

ollama serve

2.“ValueError:需要Anthropic API密钥”

解决方案：检查您的 .env 文件：

# Correct (double underscore!):
XANTUS_LLM__API_KEY=sk-ant-...

# Wrong (single underscore):
XANTUS_LLM_API_KEY=sk-ant-...

3.“导入错误：没有名为'xantus'的模块”

解决方案：确保你在正确的目录中

cd xantus
python -c "import xantus; print('OK')"

4.“MCP服务器未启动”

解决方案：构建MCP服务器

./setup_mcp.sh
# OR manually:
cd mcp-servers/mcp-starter-template-ts
npm install
npm run build

5.“端口8000已在使用中”

解决方案：终止现有进程或更改端口

# Kill existing
pkill -f "python.*xantus"

# OR change port in config.yaml:
server:
  port: 8001

6.“矢量存储错误”

解决方案：清除并重新创建

rm -rf data/vector_store
mkdir -p data/vector_store
# Restart server, re-upload documents

调试模式

启用详细日志记录：

# In xantus/main.py
import logging
logging.basicConfig(level=logging.DEBUG)

______________________________________________________________________

常见问题解答

Q： 我的数据会离开我的机器吗？ A： 仅当您使用云提供商（OpenAI/Anthropic）时。有了Olrama+HuggingFace，一切都保持在当地。

Q： 哪个更快——本地还是云？ A： 云（OpenAI/Anthropic）通常更快。本地（Ollama）取决于您的硬件。

Q： 我可以使用多个文档吗？ A： 是的！上传任意数量。它们都在矢量存储中被索引。

Q： 文档的最大尺寸是多少？ A： 没有硬性限制，但处理较大的文档需要更长的时间。

Q： 我可以删除文档吗？ A： 是，通过API /v1/ingest/documents/{doc_id} 或流式UI。

Q： 是否支持流媒体？ A： 是的！集 "stream": true 在聊天完成请求中。

Q： 什么LLM是最好的？ A.

• 最佳品质：克劳德·十四行诗4，GPT-4
• 最佳本地：拉玛3.2，米斯特拉尔
• 最佳平衡：克劳德·海库，GPT-3.5涡轮增压

Q： 如何添加身份验证？ A： 在中添加FastAPI中间件 xantus/main.py 用于API密钥或OAuth。

______________________________________________________________________

额外资源

• MCP快速入门: README_MCP.md
• API文档: http://localhost:8000/docs（运行时）
• LlamaIdex文档: https://docs.llamaindex.ai/
• FastAPI文档: https://fastapi.tiangolo.com/
• 简化文档: https://docs.streamlit.io/

______________________________________________________________________

贡献

欢迎投稿！该项目旨在：

• 易于理解
• 易于扩展
• 有据可查

请随意：

• 添加新提供者
• 优化用户界面
• 增强MCP工具
• 修复bug
• 改进文档

______________________________________________________________________

许可证

本项目按原样提供，用于教育和研究目的。

______________________________________________________________________

内置：

• 快速API -现代异步web框架
• Llama索引 -RAG框架
• 溪流 -数据应用框架
• 色度数据库 -矢量数据库
• 奥拉玛 -本地LLM运行时
• 模型上下文协议 -工具集成

______________________________________________________________________

由以下材料制成❤️ 对于开源社区

⬆ 返回页首