xinli/rag-python/README.md

# RAG 知识库服务 (rag-python)

独立的 Python 知识库服务，提供文档解析、向量化和检索功能。

## 部署说明

此文件夹可以与 Java jar 包放在同级目录使用：

```
部署目录/
├── xinli-admin.jar          # Java 后端 jar 包
├── rag-python/              # Python RAG 服务
│   ├── app.py
│   ├── start.bat            # 启动脚本
│   ├── install.bat          # 安装脚本
│   ├── knowledge_docs/      # 知识库文档（放入文档）
│   ├── index_data/          # 索引数据（自动生成）
│   └── ...
└── ...
```

## 快速开始

### 1. 安装依赖

双击运行 `install.bat`，或手动执行：

```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 启动服务

双击运行 `start.bat`，或手动执行：

```bash
venv\Scripts\activate
python app.py
```

服务启动后访问: http://localhost:5000

### 3. 添加文档

有两种方式添加文档到知识库：

**方式一：直接放入文件夹**
- 将文档文件放入 `knowledge_docs` 文件夹
- 服务会自动检测并索引新文件

**方式二：通过 API 上传**
- 使用前端页面上传
- 或调用 `/api/documents/upload` 接口

## 功能特点

- 🔄 **自动索引**: 启动时自动扫描 `knowledge_docs` 文件夹并索引所有文档
- 📁 **文件监控**: 实时监控文件夹变化，自动处理新增/修改/删除的文件
- 🔍 **语义搜索**: 使用多语言向量模型，支持中文语义检索
- 📄 **多格式支持**: 支持 txt、md、pdf、docx 格式
- 💾 **持久化存储**: 索引数据保存到磁盘，重启后自动加载
- 🌐 **REST API**: 提供完整的 HTTP API，方便集成

## API 接口

### 健康检查
```
GET /api/health
```

### 文档管理

```
# 获取文档列表
GET /api/documents

# 上传文档
POST /api/documents/upload
Content-Type: multipart/form-data
file: <文件>

# 删除文档
DELETE /api/documents/<filename>
```

### 搜索

```
POST /api/search
Content-Type: application/json

{
  "query": "搜索内容",
  "top_k": 5
}
```

### 索引管理

```
# 获取统计信息
GET /api/stats

# 扫描文件夹（索引新文件）
POST /api/scan

# 重建索引
POST /api/rebuild
```

## 目录结构

```
rag-python/
├── app.py              # Flask 应用入口
├── config.py           # 配置文件
├── document_parser.py  # 文档解析器
├── text_splitter.py    # 文本分块器
├── vector_store.py     # 向量存储（FAISS）
├── knowledge_service.py # 知识库服务
├── file_watcher.py     # 文件监控
├── requirements.txt    # Python 依赖
├── install.bat         # 安装脚本
├── start.bat           # 启动脚本
├── knowledge_docs/     # 知识库文档目录（放入文档）
├── index_data/         # 索引数据目录（自动生成）
└── uploads/            # 上传临时目录（自动生成）
```

## 配置说明

编辑 `config.py` 修改配置：

```python
# 服务端口
PORT = 5000

# 文本分块大小
CHUNK_SIZE = 500
CHUNK_OVERLAP = 50

# 向量模型（支持中文）
EMBEDDING_MODEL = "paraphrase-multilingual-MiniLM-L12-v2"

# 检索返回数量
TOP_K = 5
```

## 与 Java 项目集成

Java 项目通过 HTTP 调用本服务的 API：

1. 确保 Python 服务已启动
2. Java 配置文件中设置:
   ```yaml
   rag:
     python:
       url: http://localhost:5000
       enabled: true
   ```
3. 前端知识库管理页面会自动检测服务状态

## 常见问题

### Q: 首次启动很慢？
A: 首次启动需要下载向量模型（约 500MB），请耐心等待。模型会缓存到用户目录。

### Q: 如何更换向量模型？
A: 修改 `config.py` 中的 `EMBEDDING_MODEL`，推荐使用支持中文的模型。

### Q: 索引数据在哪里？
A: 索引保存在 `index_data` 目录，包括 FAISS 索引和文档元数据。

### Q: 如何清空知识库？
A: 删除 `index_data` 目录下的文件，或调用重建索引 API。

### Q: 电脑重启后如何恢复？
A: 只需再次运行 `start.bat`，服务会自动加载已有索引。