内容
# 🚀 ChatXWiki
**使用RAG + Weaviate + MCP + FastAPI的AI知识助手**
ChatXWiki是一个检索增强生成（RAG）系统，它会自动索引XWiki页面，将其嵌入到Weaviate数据库中，并提供一个智能聊天助手，可以从任何XWiki页面访问。RAG管道会从XWiki页面中检索最相关的文档块，并将它们作为上下文提供给LLM，以便在生成响应之前。通过将模型建立在您自己的文档中，ChatXWiki确保响应准确、上下文感知，并根据您的组织的知识生态系统量身定制。
它结合了：
- **MCP Server** → 提供检索工具
- **封装MCP客户端与FastAPI** → 处理RAG + LLM推理
- **Weaviate Vector DB** → 存储嵌入式文档块
- **XWiki摄入管道** → 提取、分割、嵌入、存储所有XWiki内容
- **浮动聊天窗口** → 直接嵌入到XWiki中的JavaScript UI
- **Docker Compose** → 所有服务的复制部署
---
## 📌 功能
- 🔍 跨所有XWiki页面的语义搜索
- 📚 全自动矢量摄入和块生成
- 🤖 使用OpenAI GPT模型的RAG驱动LLM回答
- 🧩 MCP Server工具：`retrieve_top_k_chunks`
- 🌐 FastAPI端点：`/ingest`和`/rag_query`
- 💬 浮动聊天窗口出现在每个XWiki页面
- 👑 管理员专用“重建知识库”按钮（Velocity脚本）
- 🐳 使用Docker Compose一键部署
---
## 🏗️ 架构概述
---
## 📁 项目结构
```text
项目根目录/
│
├── docker-compose.yml
├── README.md
│
├── mcp/
│ ├── services.sh
│ ├── Dockerfile
│ ├── ingest_wiki_pages.py # XWiki → Weaviate 摄入（FastAPI）
│ ├── mcp_server.py # MCP Server 暴露检索工具
│ ├── mcp_client.py # 基于MCP的RAG客户端（FastAPI）
│ ├── requirements.txt
│ ├── .env
│
└── xwiki_integration/
├── ChatXWiki_UI.js # 浮动聊天窗口
└── injest_knowledgebase_button.vm # Velocity 脚本，用于管理员专用按钮
```
---
## ⚙️ 组件
### 🔹 1. MCP Server
实现主要的检索工具：`retrieve_top_k_chunks`
该工具：
- 使用OpenAI嵌入用户查询
- 在Weaviate中搜索最近的邻居
- 返回包含顶部K个块的结构化JSON
---
### 🔹 2. MCP Client + FastAPI
运行一个FastAPI服务，暴露以下API：
| 端点 | 描述 |
|------------------|-------------|
| **POST /rag_query** | 运行完整的RAG管道 → 检索 + LLM推理 |
在内部，FastAPI MCP客户端：
- 通过**SSE**与MCP服务器连接
- 调用MCP服务器工具`retrieve_top_k_chunks`
- 为RAG构建上下文
- 使用**LangChain + OpenAI GPT**模型生成最终答案
---
### 🔹 3. XWiki 摄入系统
`ingest_wiki_pages.py`：
1. 爬取所有XWiki空间
2. 加载每个页面的`WebHome`元数据 + wiki内容
3. 清洁和提取文本
4. 分割成RAG块（LangChain）
5. 使用OpenAI生成嵌入
6. 写入Weaviate矢量数据库（v4 API）
触发方式：
- FastAPI端点`/ingest`
- XWiki中管理员专用的按钮
---
### 🔹 4. Weaviate 矢量数据库
在集合**DocumentChunk**中存储嵌入的XWiki块：
- `content`
- `parent_id`
- `fullName`
- `title`
- `chunk_index`
- `url`
- `creator`
- `last_modified`
- `vector`（OpenAI嵌入）
---
### 🔹 5. 浮动聊天窗口（JavaScript）
`ChatXWiki_UI.js`添加：
- 一个可拖动的浮动聊天窗口
- 跨所有页面的持久UI
- 调用FastAPI：POST /rag_query
添加方式：
XWiki → 管理 → 外观 → JavaScript扩展
---
### 🔹 6. Velocity 脚本（管理员按钮）
`injest_knowledgebase_button.vm`提供：
- 一个按钮：**重建知识库**
- 发送POST请求到FastAPI `/ingest`
- 重建XWiki → Weaviate中的所有嵌入
---
## 🚀 运行ChatXWiki
### **步骤1：启动所有服务**
docker compose up -d
启动：
- XWiki
- PostgreSQL
- Weaviate
- MCP Server
- FastAPI RAG服务
- FastAPI 摄入服务
### **步骤2：安装和配置XWiki**
访问：
http://localhost:8080
完成：
- 设置向导
- 创建管理员用户
- 安装标准XWiki风格
### **步骤3：添加管理员专用知识重建按钮**
1. 在XWiki中创建一个新的**管理员专用页面**。
2. 打开页面并点击**编辑 → 源代码**模式。
3. 将`injest_knowledgebase_button.vm`的整个内容粘贴到编辑器中并保存页面。
这将添加一个“重建知识库”按钮，只有管理员才能看到。单击时，它会触发`/ingest` API端点并重建Weaviate中的ChatXWiki矢量索引。
### **步骤4：添加浮动聊天窗口**
前往：
`XWiki → 管理 → 外观 → JavaScript扩展`
添加新的扩展：
- 粘贴`ChatXWiki_UI.js`的内容
- 选择这些选项：使用此扩展 → 在此Wiki上；解析内容 → 否；缓存 → 长
- 点击保存 → 聊天窗口全局显示。
### **步骤5：开始聊天！**
用户流程：
聊天窗口
→ FastAPI
→ MCP客户端
→ MCP服务器
→ Weaviate
→ LLM（OpenAI）
→ 响应返回到UI
## 🧪 **测试API**
触发摄入
`curl -X POST http://localhost:9000/ingest`
## 🔐 **环境变量**
示例.env：
```
OPENAI_API_KEY=插入您的密钥
OPENAI_EMBEDDING_MODEL=${OPENAI_EMBEDDING_MODEL:-text-embedding-3-small}
OPENAI_LLM=${OPENAI_LLM:-gpt-5.1}
MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN:-supersecrettoken}
WEAVIATE_URL=http://weaviate:8000
WEAVIATE_GRPC_PORT=50051
WEAVIATE_CLASS=${WEAVIATE_CLASS:-DocumentChunk}
MCP_SERVER_PORT=8050
```
## 🤝 **贡献**
欢迎提交拉取请求！
对于重大更改，请先打开一个问题。
## 📜 **许可证**
MIT许可证
