xinli/rag-python

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，或手动执行：

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

2. 启动服务

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

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 修改配置：

# 服务端口
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 配置文件中设置:

   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，服务会自动加载已有索引。