181 lines
4.2 KiB
Markdown
181 lines
4.2 KiB
Markdown
# 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`，服务会自动加载已有索引。
|