# local_rag_knowledge

**Repository Path**: xhyym/local_rag_knowledge

## Basic Information

- **Project Name**: local_rag_knowledge
- **Description**: 基于 FastApi+React 打造的一款完全支持内网本地部署的 rag 知识库，通体采用 Qwen3-0.6B 系列的嵌入、重排、VL、文本等模型。运行环境支持 CPU、GPU、MPS 等等加速。langchain 采用最新 1.2.7 版本进行研发，持续迭代中...
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 企业级多租户 RAG 知识库系统

<div align="center">

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/)
[![React](https://img.shields.io/badge/React-18+-61DAFB.svg)](https://reactjs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

基于 FastAPI + React 的企业级多租户 RAG（检索增强生成）系统  
支持智能文档管理、语义检索、实时向量化、WebSocket 推送

[功能特性](#功能特性) • [快速开始](#快速开始) • [架构设计](#架构设计) • [API 文档](#api-文档)

</div>

---

## 📖 项目简介

本系统是一个完整的企业级 RAG 解决方案，提供从文档上传、智能切分、向量化存储到语义检索、智能问答的全流程服务。采用多租户架构设计，支持个人、企业、团队三层租户体系，具备完善的权限控制和数据隔离机制。

### 核心亮点

- 🏢 **多租户架构**：三层租户体系（个人/企业/团队），完整的权限控制
- 📚 **智能文档处理**：支持 15+ 种文档格式，三种切分模式（语义/字符/父子）
- 🔍 **高效检索**：基于 Milvus 的向量检索 + Reranker 重排序
- ⚡ **实时通知**：WebSocket 实时推送向量化状态
- 🎯 **灵活配置**：每个文档独立配置加载器和切分策略
- 🔐 **安全可靠**：JWT 认证、数据隔离、权限控制


## 🎯 功能特性

### 多租户架构 🏢

- **三层租户体系**
  - 📱 个人租户：注册时自动创建，独立的知识库空间
  - 🏢 企业租户：超级管理员创建，支持成员管理和团队创建
  - 👥 团队租户：企业内部团队，独立的协作空间

- **权限控制**
  - 4 种角色：Owner、Admin、Member、Viewer
  - 14 种权限：知识库、文档、成员、团队、租户管理
  - 动态菜单：根据权限自动显示/隐藏功能

- **数据隔离**
  - MySQL：租户级别数据隔离
  - Milvus：向量数据按 tenant_id + knowledge_id + file_id 三层隔离
  - MinIO：对象存储按租户分桶

### 智能文档处理 📄

- **支持格式**（15+ 种）
  - 文本：TXT、Markdown、HTML、CSV、JSON
  - 文档：PDF、Word（.docx/.doc）、PPT（.pptx/.ppt）、Excel（.xlsx/.xls）
  - 多媒体：图片（OCR）、音频（Whisper 转录）

- **加载器选择**
  - PDF：PyPDF、PyMuPDF、PDFPlumber、UnstructuredPDF
  - Word：Docx2txt、UnstructuredWord
  - 其他：针对不同格式优化的专用加载器

- **三种切分模式**
  - **全文语义切分**：基于 BGE 模型的语义相似度切分
  - **全文字符切分**：自定义分隔符的字符级切分
  - **父子切分**：先父切分（语义/字符），再子切分，支持上下文检索


### 向量化与检索 🔍

- **向量化服务**
  - 异步向量化任务（BackgroundTasks）
  - WebSocket 实时推送状态（processing/completed/failed）
  - 自动重连机制（指数退避，最多 5 次）
  - 模型预加载（应用启动时初始化，避免重复加载）

- **检索优化**
  - 向量检索：Milvus COSINE 相似度检索
  - 重排序：Qwen3-Reranker 二次排序
  - 父文本去重：父子切分模式下自动去重
  - 多知识库检索：支持跨知识库检索

- **智能问答**
  - RAG 流程：检索 → 重排序 → 上下文构建 → LLM 生成
  - 流式输出：支持 SSE（Server-Sent Events）
  - 对话历史：支持多轮对话上下文

### 实时通知 ⚡

- **WebSocket 连接**
  - 自动连接：登录后自动建立 WebSocket 连接
  - 心跳保活：每 30 秒发送 ping 保持连接
  - 自动重连：连接断开后自动重连（指数退避）
  - 状态指示：实时显示连接状态（已连接🟢/重连中🟡/离线🔴）

- **向量化通知**
  - 开始处理：显示文档名称和知识库
  - 处理中：实时推送进度
  - 完成/失败：显示结果并自动刷新列表


## 🏗️ 架构设计

### 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                         前端层 (React)                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ 登录注册  │  │ 知识库   │  │ 文档管理  │  │ 智能问答  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ 租户管理  │  │ 成员管理  │  │ 团队管理  │  │ 权限控制  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTP/REST API + WebSocket
┌────────────────────────▼────────────────────────────────────────┐
│                      后端层 (FastAPI)                            │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    API 路由层                             │  │
│  │  auth • tenants • knowledge_bases • documents • query    │  │
│  │  conversations • websocket • admin                       │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                   业务逻辑层                              │  │
│  │  AuthService • TenantService • DocumentService           │  │
│  │  VectorizationService • QueryService • TextExtractor     │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                   模型管理层                              │  │
│  │  ModelManager (单例模式，预加载所有模型)                  │  │
│  │  • Qwen3-Embeddings  • Qwen3-Reranker  • Splitter       │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┬────────────────┐
        │                │                │                │
┌───────▼──────┐  ┌──────▼──────┐  ┌─────▼──────┐  ┌─────▼──────┐
│    MySQL     │  │   Milvus    │  │   MinIO    │  │  Qwen LLM  │
│  (关系数据)   │  │  (向量数据)  │  │ (对象存储)  │  │ (大模型)   │
│              │  │              │  │            │  │            │
│ • 用户信息   │  │ • 文档向量   │  │ • 原始文件 │  │ • 问答生成 │
│ • 租户关系   │  │ • 三层隔离   │  │ • 分桶存储 │  │ • 流式输出 │
│ • 权限数据   │  │ • COSINE检索 │  │            │  │            │
└──────────────┘  └─────────────┘  └────────────┘  └────────────┘
```


### 数据流架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      文档上传与向量化流程                         │
└─────────────────────────────────────────────────────────────────┘

用户上传文档
    │
    ├─→ 1. 上传到 MinIO (原始文件存储)
    │       └─→ 路径: tenant_{id}/kb_{id}/{uuid}.{ext}
    │
    ├─→ 2. 保存元数据到 MySQL
    │       ├─→ documents 表 (文档信息)
    │       └─→ document_parser_configs 表 (切分配置)
    │
    └─→ 3. 触发向量化任务 (BackgroundTasks)
            │
            ├─→ 3.1 从 MinIO 下载文件
            │
            ├─→ 3.2 使用指定加载器提取文本
            │       └─→ TextExtractor.load_document()
            │
            ├─→ 3.3 根据配置切分文档
            │       ├─→ 全文语义切分 (NativeSemanticSplitter)
            │       ├─→ 全文字符切分 (RecursiveCharacterTextSplitter)
            │       └─→ 父子切分 (两阶段切分 + MD5 hash)
            │
            ├─→ 3.4 生成向量 (Qwen3-Embeddings)
            │       └─→ 1024 维向量
            │
            ├─→ 3.5 存储到 Milvus
            │       └─→ 三层隔离: tenant_id + knowledge_id + file_id
            │
            └─→ 3.6 WebSocket 推送状态
                    ├─→ processing (开始处理)
                    ├─→ completed (完成)
                    └─→ failed (失败)

┌─────────────────────────────────────────────────────────────────┐
│                         检索与问答流程                            │
└─────────────────────────────────────────────────────────────────┘

用户提问
    │
    ├─→ 1. 生成查询向量 (Qwen3-Embeddings)
    │
    ├─→ 2. Milvus 向量检索 (COSINE 相似度)
    │       └─→ 返回 Top-K 候选文档 (默认 20)
    │
    ├─→ 3. Reranker 重排序 (Qwen3-Reranker)
    │       └─→ 精选 Top-N 最相关文档 (默认 5)
    │
    ├─→ 4. 父文本去重 (父子切分模式)
    │       └─→ 按 parent_id 去重，保留完整上下文
    │
    ├─→ 5. 构建 Prompt
    │       ├─→ 系统提示词
    │       ├─→ 检索到的上下文
    │       └─→ 用户问题
    │
    └─→ 6. LLM 生成答案 (Qwen3-0.6B)
            └─→ 流式输出 (SSE)
```


### 技术栈

#### 后端技术栈
| 技术 | 版本 | 说明 |
|------|------|------|
| Python | 3.12+ | 编程语言 |
| FastAPI | 0.115+ | Web 框架 |
| SQLAlchemy | 2.0+ | ORM 框架 |
| MySQL | 8.0 | 关系数据库 |
| Milvus | 2.6 | 向量数据库 |
| MinIO | Latest | 对象存储 |
| LangChain | 1.2.6 | LLM 应用框架 |
| Qwen3-Embeddings | 0.6B | 向量化模型 |
| Qwen3-Reranker | 0.6B | 重排序模型 |
| Qwen3 | 0.6B | 大语言模型 |
| BGE-Small | - | 语义切分模型 |

#### 前端技术栈
| 技术 | 版本 | 说明 |
|------|------|------|
| React | 18+ | UI 框架 |
| TypeScript | 5+ | 类型系统 |
| Ant Design | 5+ | UI 组件库 |
| Vite | 5+ | 构建工具 |
| React Router | 6+ | 路由管理 |
| Axios | 1+ | HTTP 客户端 |


## 🚀 快速开始

### 环境要求

- Python 3.12+
- Node.js 18+
- Docker & Docker Compose
- Conda（可选）
- 至少 8GB RAM
- 至少 20GB 磁盘空间

### 1. 克隆项目

```bash
git clone https://gitee.com/xhyym/local_rag_knowledge.git
cd local_rag_knowledge
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置以下关键参数：

```env
# 数据库配置
MYSQL_ROOT_PASSWORD=your_password
MYSQL_DATABASE=qwen_rag_db

# JWT 配置
JWT_SECRET_KEY=your_secret_key_here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440

# Milvus 配置
MILVUS_URI=http://localhost:19530
MILVUS_COLLECTION_NAME=rag_collection
MILVUS_DB_NAME=rag_db

# MinIO 配置
MINIO_ENDPOINT=localhost:5111
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=qwen-rag-bucket

# 模型配置
EMBEDDING_MODEL=Qwen/Qwen3-Embeddings-0.6B
RERANKER_MODEL=Qwen/Qwen3-Reranker-0.6B
SPLITTER_MODEL=BAAI/bge-small-zh-v1.5
LLM_API_BASE=http://localhost:10001/v1
```

### 3. 启动基础服务

```bash
docker-compose up -d
```

等待服务启动（约 1-2 分钟），检查状态：

```bash
docker-compose ps
```

### 4. 下载模型

从 ModelScope 下载模型到 `~/.cache/modelscope/hub/models/`：

```bash
# 使用 modelscope 命令行工具
pip install modelscope

# 下载 Embedding 模型
modelscope download --model Qwen/Qwen3-Embeddings-0.6B

# 下载 Reranker 模型
modelscope download --model Qwen/Qwen3-Reranker-0.6B

# 下载 Splitter 模型
modelscope download --model BAAI/bge-small-zh-v1.5

# 下载 LLM 模型
modelscope download --model Qwen/Qwen3-0.6B
```


### 5. 部署 Qwen LLM

**方式一：使用 vLLM（推荐）**

```bash
# 创建独立的 conda 环境（避免依赖冲突）
conda create -n vllm_qwen06b python=3.10
conda activate vllm_qwen06b

# Linux/Mac
bash deplo_vllm_qwen06b.sh

# Windows
deplo_vllm_qwen06b.bat
```

**方式二：使用 Ollama**

```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull qwen:0.6b

# 修改 .env 中的 LLM_API_BASE
LLM_API_BASE=http://localhost:11434/v1
```

### 6. 安装 Python 依赖

**使用 pip**：

```bash
pip install -r requirements.txt
```

**使用 Conda**：

```bash
conda env create -f environment.yml
conda activate local_rag_knowledge
```

### 7. 启动后端服务

```bash
# Linux/Mac
bash start.sh

# Windows
start.bat
```

后端服务将在 `http://localhost:10002` 启动。

### 8. 启动前端服务

```bash
cd frontweb
pnpm install  # 或 npm install
pnpm dev      # 或 npm run dev
```

前端服务将在 `http://localhost:5173` 启动。

### 9. 首次登录

访问 `http://localhost:5173`

**超级管理员登录**：
```
用户名：admin
密码：admin123
```

**普通用户注册**：
点击"注册"按钮，填写信息即可注册。


## 📸 功能展示

### 登录与注册
![登录页面](./images/首页介绍 1.png)
![登录页面](./images/首页介绍 2.png)
*支持企业名称 + 账户登录，自动创建个人租户*

### 知识库管理
![知识库列表](./images/功能 1.png)
*支持创建、删除知识库，按名称搜索，分页展示*

### 文档上传与配置
![文档上传](./images/文件上传预览功能.png)
*全屏弹窗配置文档加载器和切分策略*

### 文档列表与管理
![文档列表](./images/document-list.png)
*展示文档详细配置信息，支持向量化、删除操作*

### 实时向量化通知
![img.png](img.png)
*实时推送向量化状态，自动刷新列表*

### 智能问答
![智能问答](./images/chat.png)
*基于 RAG 的智能问答，支持流式输出*

### 成员管理
![团队多成员管理.png](images/%E5%9B%A2%E9%98%9F%E5%A4%9A%E6%88%90%E5%91%98%E7%AE%A1%E7%90%86.png)
*邀请成员、分配角色、管理权限*

### 团队管理
![团队管理](./i![企业下多团队管理.png](images/%E4%BC%81%E4%B8%9A%E4%B8%8B%E5%A4%9A%E5%9B%A2%E9%98%9F%E7%AE%A1%E7%90%86.png)mages/team-management.png)
*企业内创建团队，指定团队 Owner*


## 📚 使用指南

### 多租户使用流程

#### 1. 创建企业租户

#### 2. 创建团队（企业 Owner/Admin）

#### 3. 邀请成员（团队/企业 Owner/Admin）


#### 4. 上传文档
1. 进入"知识库"页面
2. 点击"上传文档"按钮
3. 选择知识库和文件
4. 配置加载器和切分策略
   - **加载器**：根据文件类型自动推荐
   - **切分模式**：
     - 全文语义切分：适合长文档，基于语义相似度切分
     - 全文字符切分：适合结构化文档，自定义分隔符
     - 父子切分：适合需要上下文的场景，两阶段切分
5. 点击"保存并上传"

#### 5. 向量化文档
1. 文档上传后状态为"待向量化"
2. 点击"向量化"按钮启动任务
3. 右上角显示实时通知
4. 完成后状态变为"已完成"

#### 6. 智能问答
1. 进入"智能问答"页面
2. 选择知识库
3. 输入问题
4. 系统自动检索相关文档并生成答案
5. 支持多轮对话


## 🔌 API 文档

### 服务端口

| 服务 | 端口 | 说明 | 访问地址 |
|------|------|------|---------|
| 后端 API | 10002 | FastAPI 服务 | http://localhost:10002 |
| API 文档 | 10002 | Swagger UI | http://localhost:10002/docs |
| 前端 Web | 5173 | Vite 开发服务器 | http://localhost:5173 |
| MySQL | 5100 | 数据库 | localhost:5100 |
| Milvus | 19530 | 向量数据库 | localhost:19530 |
| Attu | 5113 | Milvus 管理界面 | http://localhost:5113 |
| MinIO API | 5111 | 对象存储 API | http://localhost:5111 |
| MinIO Console | 5112 | MinIO 管理界面 | http://localhost:5112 |
| Qwen LLM | 10001 | 本地 LLM 服务 | http://localhost:10001 |

### 主要 API 端点

#### 认证相关
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出

#### 租户管理
- `GET /api/tenants/my` - 获取我的租户列表
- `POST /api/tenants/switch/{tenant_id}` - 切换租户
- `POST /api/tenants/teams` - 创建团队
- `GET /api/tenants/teams` - 获取团队列表

#### 知识库管理
- `GET /api/knowledge-bases` - 获取知识库列表
- `POST /api/knowledge-bases` - 创建知识库
- `DELETE /api/knowledge-bases/{kb_id}` - 删除知识库

#### 文档管理
- `POST /api/documents/upload` - 上传文档
- `GET /api/documents` - 获取文档列表
- `POST /api/documents/{doc_id}/vectorize` - 向量化文档
- `DELETE /api/documents/{doc_id}` - 删除文档

#### 智能问答
- `POST /api/conversations` - 创建对话
- `POST /api/conversations/{conv_id}/query` - 提问（流式输出）

#### WebSocket
- `WS /api/ws/{tenant_id}/{user_id}?token={token}` - WebSocket 连接


## 📁 项目结构

```
.
├── app/                          # 后端代码
│   ├── api/                      # API 路由
│   │   ├── auth.py               # 认证 API
│   │   ├── tenants.py            # 租户管理 API
│   │   ├── knowledge_bases.py    # 知识库 API
│   │   ├── documents.py          # 文档 API
│   │   ├── conversations.py      # 对话 API
│   │   ├── websocket.py          # WebSocket API
│   │   └── dependencies.py       # 依赖注入
│   ├── config/                   # 配置文件
│   │   └── config.py             # 应用配置
│   ├── db/                       # 数据库连接
│   │   └── milvus_db.py          # Milvus 操作封装
│   ├── models/                   # 数据模型
│   │   ├── user.py               # 用户模型
│   │   ├── tenant.py             # 租户模型
│   │   ├── knowledge_base.py     # 知识库模型
│   │   ├── document.py           # 文档模型
│   │   └── document_parser.py    # 文档解析配置模型
│   ├── qwen_models/              # Qwen 模型封装
│   │   ├── embeddigns_func.py    # Embedding 模型
│   │   ├── reranker_func.py      # Reranker 模型
│   │   └── native_semantic_splitter.py  # 语义切分器
│   ├── schemas/                  # Pydantic 模式
│   │   ├── user.py               # 用户模式
│   │   ├── tenant.py             # 租户模式
│   │   ├── document.py           # 文档模式
│   │   └── conversation.py       # 对话模式
│   ├── services/                 # 业务逻辑
│   │   ├── auth_service.py       # 认证服务
│   │   ├── tenant_service.py     # 租户服务
│   │   ├── document_service.py   # 文档服务
│   │   ├── vectorization_service.py  # 向量化服务
│   │   ├── query_service.py      # 查询服务
│   │   └── text_extractor.py     # 文本提取器
│   ├── utils/                    # 工具函数
│   │   ├── logger.py             # 日志工具
│   │   ├── minio_client.py       # MinIO 客户端
│   │   ├── model_manager.py      # 模型管理器
│   │   ├── websocket_manager.py  # WebSocket 管理器
│   │   └── security.py           # 安全工具
│   └── main.py                   # 应用入口
├── frontweb/                     # 前端代码
│   ├── src/
│   │   ├── components/           # React 组件
│   │   │   ├── MainLayout.tsx    # 主布局
│   │   │   ├── FileList.tsx      # 文档列表
│   │   │   ├── ChatAssistant.tsx # 智能问答
│   │   │   ├── WebSocketStatus.tsx  # WebSocket 状态
│   │   │   └── NotificationHandler.tsx  # 通知处理
│   │   ├── pages/                # 页面
│   │   │   ├── LandingPage.tsx   # 登录注册页
│   │   │   ├── TeamManagement.tsx  # 团队管理
│   │   │   └── MemberManagement.tsx  # 成员管理
│   │   ├── services/             # API 服务
│   │   │   ├── api.ts            # API 基础配置
│   │   │   ├── document.service.ts  # 文档服务
│   │   │   └── websocket.service.ts  # WebSocket 服务
│   │   ├── contexts/             # React Context
│   │   │   ├── AuthContext.tsx   # 认证上下文
│   │   │   ├── TenantContext.tsx # 租户上下文
│   │   │   └── WebSocketContext.tsx  # WebSocket 上下文
│   │   └── App.tsx               # 应用入口
│   └── package.json
├── migrations/                   # 数据库迁移脚本
├── images/                       # 功能展示图片
├── docker-compose.yml            # Docker 编排
├── requirements.txt              # Python 依赖
├── environment.yml               # Conda 环境
├── start.sh                      # 启动脚本（Linux/Mac）
├── start.bat                     # 启动脚本（Windows）
└── README.md                     # 项目文档
```


## 🔮 未来规划 (TODO)

### MCP (Model Context Protocol) 集成
- [ ] 支持 MCP 协议接入外部工具和服务
- [ ] 实现自定义 MCP 服务器
- [ ] 提供 MCP 工具市场
- [ ] 支持工具链编排

### Multi-Agent 交互
- [ ] 实现多智能体协作框架
- [ ] 支持 Agent 角色定义和任务分配
- [ ] Agent 间通信和协调机制
- [ ] 可视化 Agent 工作流编排
- [ ] 支持 Agent 记忆和学习

### 企业平台集成

#### 钉钉集成
- [ ] 钉钉机器人接入
- [ ] 钉钉文档库同步
- [ ] 钉钉审批流集成
- [ ] 钉钉消息推送
- [ ] 钉钉单点登录（SSO）

#### 飞书集成
- [ ] 飞书机器人接入
- [ ] 飞书云文档同步
- [ ] 飞书多维表格集成
- [ ] 飞书消息推送
- [ ] 飞书单点登录（SSO）

#### 企业微信集成
- [ ] 企业微信机器人接入
- [ ] 企业微信文档同步
- [ ] 企业微信审批流集成
- [ ] 企业微信消息推送
- [ ] 企业微信单点登录（SSO）

### 功能增强
- [ ] 支持更多文档格式（视频、代码等）
- [ ] 文档版本管理
- [ ] 知识图谱构建
- [ ] 智能标签和分类
- [ ] 文档摘要生成
- [ ] 多语言支持
- [ ] 移动端适配
- [ ] 数据分析和统计
- [ ] 审计日志
- [ ] 备份和恢复

### 性能优化
- [ ] Redis 缓存层
- [ ] 异步任务队列（Celery）
- [ ] 分布式部署支持
- [ ] 负载均衡
- [ ] CDN 加速
- [ ] 数据库读写分离


## 🛠️ 开发指南

### 添加新的文档加载器

1. 在 `app/models/document_parser.py` 中添加枚举值：

```python
class LoaderTypeEnum(str, Enum):
    YOUR_LOADER = "YourLoader"
```

2. 在 `app/services/text_extractor.py` 中实现加载逻辑：

```python
elif loader_type == LoaderTypeEnum.YOUR_LOADER:
    from langchain_community.document_loaders import YourLoader
    loader = YourLoader(file_path)
```

3. 在 `app/api/document_parsers.py` 中配置支持的文件类型：

```python
LOADER_CONFIGS = {
    "your_ext": [
        {"label": "Your Loader", "value": "YourLoader"}
    ]
}
```

### 添加新的切分策略

1. 在 `app/services/text_extractor.py` 中实现切分方法：

```python
@staticmethod
def _your_split_method(text: str, **kwargs) -> Tuple[List[str], List[Optional[str]], List[Optional[str]]]:
    # 实现切分逻辑
    chunks = your_split_logic(text)
    return chunks, [None] * len(chunks), [None] * len(chunks)
```

2. 在 `extract_and_split_with_config` 中添加分支：

```python
elif split_mode == 'your_mode':
    return TextExtractor._your_split_method(text, **config)
```

### 添加新的 API 路由

1. 在 `app/api/` 下创建新的路由文件
2. 在 `app/main.py` 中注册路由：

```python
from app.api import your_router
app.include_router(your_router.router, prefix="/api/your-path", tags=["Your Tag"])
```

### 前端开发

```bash
cd frontweb
pnpm dev
```

修改代码后自动热重载。


## 🔒 安全建议

### 生产环境部署

1. **修改默认密码**
   ```bash
   # 超级管理员密码
   # MySQL root 密码
   # MinIO 访问密钥
   # JWT Secret Key
   ```

2. **配置 CORS 白名单**
   ```python
   # app/main.py
   app.add_middleware(
       CORSMiddleware,
       allow_origins=["https://your-domain.com"],
       allow_credentials=True,
       allow_methods=["*"],
       allow_headers=["*"],
   )
   ```

3. **启用 HTTPS**
   - 配置 Nginx 反向代理
   - 申请 SSL 证书（Let's Encrypt）

4. **环境变量管理**
   - 使用 `.env` 文件管理敏感信息
   - 不要将 `.env` 提交到版本控制
   - 生产环境使用环境变量或密钥管理服务

5. **定期备份**
   - MySQL 数据库（每日备份）
   - MinIO 对象存储（增量备份）
   - Milvus 向量数据（定期快照）

### 性能优化建议

1. **数据库优化**
   - 配置合适的索引
   - 定期清理过期数据
   - 使用连接池
   - 读写分离

2. **缓存策略**
   - 启用 Redis 缓存
   - 缓存租户信息
   - 缓存用户权限
   - 缓存热门查询

3. **负载均衡**
   - 使用 Nginx 反向代理
   - 配置多个后端实例
   - 使用 CDN 加速静态资源

4. **监控告警**
   - 配置日志收集（ELK Stack）
   - 监控系统资源（Prometheus + Grafana）
   - 设置告警规则
   - 性能分析和优化


## ❓ 常见问题

### 1. 如何修改超级管理员密码？

**方法一：通过数据库**
```sql
-- 连接到 MySQL
mysql -u root -p qwen_rag_db

-- 更新密码（需要使用 bcrypt hash）
UPDATE users SET password_hash = '$2b$12$新的hash值' WHERE username = 'admin';
```

**方法二：通过 Python**
```python
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
new_hash = pwd_context.hash("your_new_password")
print(new_hash)
```

### 2. Milvus 连接失败

**检查日志**：
```bash
docker logs lm-milvus
```

**常见原因**：
- 磁盘空间不足
- 内存不足（建议至少 4GB）
- 端口被占用

**解决方案**：
```bash
# 重启 Milvus
docker-compose restart lm-milvus

# 检查端口
lsof -i :19530
```

### 3. 向量化失败

**检查模型是否加载**：
```bash
# 查看后端日志
tail -f app/logs/app.log
```

**常见原因**：
- 模型未下载或路径错误
- 内存不足
- Milvus 连接断开

**解决方案**：
- 确认模型路径正确
- 检查 Milvus 连接状态
- 查看详细错误日志

### 4. WebSocket 连接失败

**检查认证信息**：
- 确保已登录
- 检查 sessionStorage 中的 token

**检查后端日志**：
```bash
# 查看 WebSocket 连接日志
grep "WebSocket" app/logs/app.log
```

**常见原因**：
- Token 过期
- 认证信息不匹配
- 网络问题

### 5. 文档上传失败

**检查 MinIO 服务**：
```bash
docker logs lm-minio
```

**检查 Bucket**：
访问 http://localhost:5112，确认 bucket 已创建。

**常见原因**：
- MinIO 服务未启动
- Bucket 不存在
- 文件大小超限

### 6. 前端无法连接后端

**检查后端服务**：
```bash
curl http://localhost:10002/docs
```

**检查 CORS 配置**：
确保 `app/main.py` 中的 CORS 配置正确。

**检查防火墙**：
确保端口 10002 未被防火墙阻止。


## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

### 代码规范

- Python：遵循 PEP 8 规范
- TypeScript：遵循 ESLint 规则
- 提交信息：使用清晰的提交信息

### 报告问题

提交 Issue 时请包含：
- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 环境信息（操作系统、Python 版本等）
- 相关日志

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 📝 更新日志

### v2.1 (2026-01-28)
- ✅ 新增三种文档切分模式（语义/字符/父子）
- ✅ 实现 WebSocket 实时通知
- ✅ 优化模型加载机制（预加载，避免重复加载）
- ✅ 新增 Milvus 连接自动重连
- ✅ 优化文档列表展示（显示完整配置信息）
- ✅ 新增知识库名称搜索功能
- ✅ 修复多个 Bug

### v2.0 (2026-01-24)
- ✅ 完成多租户架构改造
- ✅ 新增超级管理员系统
- ✅ 实现三层租户体系（个人/企业/团队）
- ✅ 完整的权限控制系统
- ✅ 成员管理和邀请功能
- ✅ 租户级别数据隔离
- ✅ 前后端完整实现

### v1.0 (2025-12-01)
- ✅ 基础 RAG 系统
- ✅ 用户认证
- ✅ 知识库管理
- ✅ 文档上传和检索
- ✅ 智能问答

## 📧 联系方式

如有问题或建议，请：
- 提交 Issue：[GitHub Issues](https://github.com/your-repo/issues)
- 发送邮件：your-email@example.com

## 🙏 致谢

感谢以下开源项目：
- [FastAPI](https://fastapi.tiangolo.com/)
- [React](https://reactjs.org/)
- [Ant Design](https://ant.design/)
- [LangChain](https://www.langchain.com/)
- [Milvus](https://milvus.io/)
- [MinIO](https://min.io/)
- [Qwen](https://github.com/QwenLM/Qwen)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给个 Star！⭐**

Made with ❤️ by 作伴网络科技

</div>