# 塑化行业知识库智能客服系统

**Repository Path**: zhiops/xeagents

## Basic Information

- **Project Name**: 塑化行业知识库智能客服系统
- **Description**: 🥇🥇🥇XERAG 是一个面向塑化行业的 RAG（Retrieval-Augmented Generation，检索增强生成）知识库智能客服系统。系统基于 FastAPI + LangGraph + lancedb构建，集成本地/云端双模 LLM、多路召回检索、BGE Rerank 精排等核心 AI 能力，为塑化行业提供专业的智能问答、知识库管理、工单流转和运营报表等完整业务功能。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 塑化行业知识库智能客服系统（XERAG）

> 面向塑化行业的 RAG（Retrieval-Augmented Generation，检索增强生成）知识库智能客服系统。

---

## 项目简介

XERAG 是一个专为塑化行业打造的 AI Agent 智能客服与知识库管理平台。系统基于 **FastAPI + Vue3 + LanceDB** 构建，集成本地/云端双模 LLM、多路召回检索、BGE Rerank 精排、BM25 稀疏检索、文档智能分块等核心 AI 能力，为企业提供专业的智能问答、知识库管理、工作流编排、插件扩展和运营报表等完整业务功能。

## 核心特性

- **双模 LLM 推理**：支持云端 API（DeepSeek/DashScope 兼容 OpenAI 接口）与本地 GGUF 量化模型双活/降级切换
- **多路召回检索**：Dense 向量检索 + BM25 稀疏检索 + HyDE 假设文档生成 + RRF 倒数排名融合
- **BGE Rerank 精排**：支持 GGUF 与 Transformers 双格式重排模型，提升答案相关性
- **智能文档分块**：通用滑动窗口分块 + 塑化行业结构化分块（按章节标题/材料型号分割）
- **智能体编排**：可视化 DAG 工作流，支持 LLM / 检索 / 工具 / 条件分支节点
- **插件化工具**：外部 API 工具注册、测试、调用，支持 Bearer/API-Key 鉴权
- **权限管理体系**：RBAC 角色权限模型，JWT 鉴权 + Redis 单点登录控制
- **异步任务队列**：Celery + Redis 多队列隔离（rag_task / annotation_batch / export_task）
- **操作审计日志**：自动记录登录日志与操作日志，支持按模块隔离日志文件

## 技术栈

### 后端

| 层级 | 技术 |
|------|------|
| Web 框架 | FastAPI + Uvicorn |
| ORM / 数据库 | SQLAlchemy 2.0 + asyncmy + MySQL 8.0 |
| 缓存 / 任务队列 | Redis + Celery |
| 向量数据库 | LanceDB |
| Embedding / Rerank | BGE（GGUF / Transformers 双模式） |
| LLM | 本地 llama_cpp（GGUF）+ 云端 OpenAI 兼容接口 |
| 分词 / BM25 | jieba + rank_bm25 |
| 鉴权 | JWT + bcrypt |
| 配置管理 | python-dotenv |

### 前端

| 技术 | 说明 |
|------|------|
| Vue 3 | Composition API + `<script setup>` |
| Vite | 构建工具 |
| Element Plus | UI 组件库 |
| Pinia | 状态管理 |
| Vue Router 4 | 路由管理 |
| Axios | HTTP 客户端 |
| SCSS | 样式预处理器 |

## 项目结构

```
xeagents/
├── backend/                  # FastAPI 后端
│   ├── main.py               # 应用入口
│   ├── app/                  # 生命周期、中间件、异常、依赖注入
│   ├── api/v1/               # 接口控制器（sys / rag / agent）
│   ├── services/             # 业务服务层
│   ├── core/                 # 基础设施（DB/Redis/LLM/向量/检索/任务队列）
│   ├── models/               # SQLAlchemy ORM 模型
│   ├── schemas/              # Pydantic 数据模型
│   └── tasks/                # Celery 异步任务
├── frontend/                 # Vue3 前端
│   ├── src/
│   │   ├── api/              # API 接口封装
│   │   ├── views/            # 页面视图
│   │   ├── layout/           # 布局组件
│   │   ├── router/           # 路由配置
│   │   ├── store/            # Pinia 状态
│   │   └── styles/           # 全局样式
│   └── package.json
├── docs/                     # 项目文档
│   ├── 目录.md               # 后端架构详细文档
│   └── sql/                  # 数据库初始化脚本
├── .env                      # 环境变量（需自行配置）
├── docker-compose.yml        # 一键部署编排
└── README.md / README.en.md  # 项目说明
```

## 快速开始

### 1. 环境准备

- Python 3.10+
- Node.js 18+
- MySQL 8.0
- Redis 5.0+（推荐 6.0+，旧版 Redis 需配置 `protocol=2`）

### 2. 后端启动

```bash
# 进入后端目录
cd backend

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（复制后修改）
cp .env.example .env

# 初始化数据库（执行 docs/sql/rag_agent_system.sql）
mysql -u root -p rag_agent_system < ../docs/sql/rag_agent_system.sql

# 启动服务
python main.py
```

后端默认运行在 `http://127.0.0.1:8000`，API 文档地址：`http://127.0.0.1:8000/docs`

### 3. 前端启动

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端默认运行在 `http://127.0.0.1:5173`

### 4. 启动 Celery Worker

```bash
cd backend
celery -A core.task.queue_client worker -l info -Q rag_task,annotation_batch,export_task,default
```

## 使用说明

1. 访问前端页面，使用默认管理员账号登录（需提前在 `sys_user` 表中初始化）
2. 进入「知识库管理」创建知识库并上传塑化行业文档（PDF/MD/DOCX/TXT/XLSX/CSV）
3. 系统自动异步解析文档、分块、向量化并建立 BM25 索引
4. 进入「Agent管理」创建智能体，绑定知识库与工具插件
5. 在对话页面与智能体进行多轮问答，系统会自动检索知识库并生成专业回答

## 后端架构

```
HTTP 请求
  → CORS 中间件
  → 请求日志中间件
  → JWT 鉴权中间件
  → 全局异常处理器
  → API 控制器 (api/v1/)
      → @Log 操作日志记录
      → PermissionChecker 权限拦截
      → Service 业务层
          → DAO 数据访问层
          → ORM 模型
          → MySQL / Redis / LanceDB / LLM
  → ResponseUtil 统一响应
```

详细架构说明请参考：[docs/目录.md](docs/目录.md)

## 核心模块

| 模块 | 路径 | 说明 |
|------|------|------|
| 系统管理 | `api/v1/sys/` | 用户 / 角色 / 权限 / 部门 / 系统配置 / 日志 |
| RAG 知识库 | `api/v1/rag/` | 知识库 / 文档 / 分块 / 问答对 / 检索测试 |
| 智能体编排 | `api/v1/agent/` | 智能体 / 工作流 / 工具 / 对话 |
| 异步任务 | `tasks/` | 文档解析 / QA 生成 / 数据导出 |

## 开发指南

- 控制器只做参数校验，业务逻辑下沉到 Service
- Service 使用 `@classmethod`，第一个参数为 `AsyncSession`
- 数据库模型继承 `BaseModel`，统一逻辑删除字段 `is_deleted`
- 错误码按领域分段：`AUTH_1xxx` / `PERM_2xxx` / `RAG_6xxx` / `AGENT_8xxx`
- 操作日志通过 `@Log` 装饰器自动采集
- 新增 API 需在 `api/v1/__init__.py` 注册路由

## 参与贡献

1. Fork 本仓库
2. 新建 `feat/xxx` 或 `fix/xxx` 分支
3. 提交代码并编写清晰的 Commit Message
4. 新建 Pull Request

## 许可证

[MIT License](LICENSE)