修改了readme和docker-run.sh env.example
This commit is contained in:
parent
7ab5afbdff
commit
a6413a76bc
64
.env.example
64
.env.example
|
|
@ -19,9 +19,6 @@ MAX_UPLOAD_SIZE_MB=5
|
|||
SOFFICE_HOST=localhost
|
||||
SOFFICE_PORT=8003
|
||||
|
||||
# 文件下载接口地址
|
||||
FILE_DOWNLOAD_BASE_URL=http://172.20.32.184:8000/api/file/open/downloadByIdentifier
|
||||
|
||||
# ============================================
|
||||
# ChromaDB 配置
|
||||
# ============================================
|
||||
|
|
@ -32,67 +29,6 @@ CHROMA_SERVER_HOST=localhost
|
|||
CHROMA_SERVER_PORT=8002
|
||||
CHROMA_COLLECTION_NAME=rag_collection
|
||||
|
||||
# ============================================
|
||||
# MySQL 配置
|
||||
# ============================================
|
||||
# MYSQL_HOST: MySQL 服务器地址（默认值，用于向后兼容）
|
||||
# - 使用 host 网络模式: localhost
|
||||
# - 远程服务器: 192.168.1.100 或 mysql.example.com
|
||||
# 注意: 如果使用 MYSQL_DATABASES_CONFIG，每个数据库配置可以指定自己的连接信息
|
||||
# 如果数据库配置中没有指定 mysql_host 等字段，则使用这里的默认值
|
||||
MYSQL_HOST=localhost
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_USER=root
|
||||
MYSQL_PASSWORD=your_password
|
||||
MYSQL_DATABASE=forgeplus
|
||||
|
||||
# 多数据库配置（可选）
|
||||
# 方式1: 使用配置文件（推荐）
|
||||
# MYSQL_DATABASES_CONFIG=./databases_config.json
|
||||
#
|
||||
# 在 databases_config.json 中，每个数据库配置可以：
|
||||
# 1. 使用默认连接（不指定 mysql_host 等字段）：使用上面 .env 中的 MYSQL_* 配置
|
||||
# 2. 使用独立连接（指定 mysql_host 等字段）：连接到不同的 MySQL 服务器
|
||||
#
|
||||
# 示例配置（database_config.json）:
|
||||
# [
|
||||
# {
|
||||
# "name": "db1",
|
||||
# "database": "database1",
|
||||
# "table_name": "documents",
|
||||
# "id_column": "id",
|
||||
# "content_column": "content",
|
||||
# "title_column": "title",
|
||||
# "comment": "使用 .env 中的默认 MySQL 连接配置"
|
||||
# },
|
||||
# {
|
||||
# "name": "db2_remote",
|
||||
# "database": "database2",
|
||||
# "table_name": "articles",
|
||||
# "id_column": "article_id",
|
||||
# "content_column": "body",
|
||||
# "title_column": "title",
|
||||
# "mysql_host": "192.168.1.100",
|
||||
# "mysql_port": 3306,
|
||||
# "mysql_user": "remote_user",
|
||||
# "mysql_password": "remote_password",
|
||||
# "comment": "使用独立的 MySQL 连接配置（不同的服务器）"
|
||||
# }
|
||||
# ]
|
||||
#
|
||||
# 方式2: 使用 JSON 字符串
|
||||
# MYSQL_DATABASES_CONFIG=[{"name":"db1","database":"database1","table_name":"documents","id_column":"id","content_column":"content","title_column":"title"}]
|
||||
|
||||
# ============================================
|
||||
# Ollama 配置
|
||||
# ============================================
|
||||
# OLLAMA_BASE_URL: Ollama 服务地址
|
||||
# - 使用 host 网络模式: http://localhost:11434
|
||||
# - 远程服务器: http://192.168.1.100:11434
|
||||
OLLAMA_BASE_URL=http://localhost:11434
|
||||
OLLAMA_MODEL=qwen3:1.7b
|
||||
OLLAMA_EMBEDDING_MODEL=qwen3-embedding:0.6b
|
||||
|
||||
# ============================================
|
||||
# RAG 配置
|
||||
# ============================================
|
||||
|
|
|
|||
388
README.md
388
README.md
|
|
@ -138,327 +138,36 @@ ollama pull qwen3-embedding:8b # Embedding模型，用于向量化
|
|||
- 支持文件附件内容解析
|
||||
|
||||
2. **文件夹类型 (folder)**
|
||||
- 支持本地文件夹
|
||||
- 支持远程文件夹（通过 SSH/SFTP）
|
||||
- 支持文件夹
|
||||
- 支持递归扫描
|
||||
- 支持文件过滤规则
|
||||
|
||||
#### 配置参数说明
|
||||
|
||||
#### 多列内容配置
|
||||
|
||||
如果你的数据库表中有多个列都需要参与检索，例如 `title`、`content`、`description`，你可以将这些列都配置为 `content_column`，系统会自动合并它们的内容用于向量化。
|
||||
若表中存在文件标识符列，如`file_identifiers`，要使系统能够解析并合并附件内容，则需要在`content_column`中新增文件标识符列，并配置 `file_column`。
|
||||
|
||||
**配置示例**:
|
||||
```json
|
||||
{
|
||||
"name": "db1",
|
||||
"database": "forgeplus",
|
||||
"table_name": "issues",
|
||||
"id_column": "id",
|
||||
"content_column": "title,content,description,file_identifiers",
|
||||
"file_column": "file_identifiers",
|
||||
"title_column": "title",
|
||||
"metadata_columns": "created_at,updated_at",
|
||||
"content_separator": "\n"
|
||||
}
|
||||
```
|
||||
|
||||
**工作原理**:
|
||||
1. 系统会从 MySQL 查询所有指定的 content 列
|
||||
2. 使用指定的分隔符（默认 `\n`）将多个列的内容合并
|
||||
3. 合并后的内容被用于向量化和存储到 ChromaDB
|
||||
4. 检索时使用合并后的完整内容进行相似度匹配
|
||||
|
||||
**注意事项**:
|
||||
- 列顺序：多个列会按照配置中的顺序合并
|
||||
- 空值处理：如果某个列为 NULL 或空字符串，会被跳过
|
||||
- 分隔符：选择合适的分隔符很重要，建议使用 `\n`（换行符）以保持可读性
|
||||
- 向后兼容：如果只指定一个列名（如 `"content_column": "content"`），行为与之前完全一致
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
RAG/
|
||||
├── api/ # FastAPI 应用
|
||||
│ ├── __init__.py
|
||||
│ └── main.py # API 主程序（包含配置管理端点）
|
||||
├── database/ # 数据库模块
|
||||
│ ├── __init__.py
|
||||
│ └── sync.py # MySQL 同步模块
|
||||
├── rag/ # RAG 核心模块
|
||||
│ ├── __init__.py
|
||||
│ ├── vector_store.py # 向量存储管理
|
||||
│ ├── document_processor.py # 文档处理
|
||||
│ └── rag_engine.py # RAG 引擎
|
||||
├── sync/ # 同步模块
|
||||
│ ├── __init__.py
|
||||
│ ├── base_sync.py # 同步基类
|
||||
│ ├── mysql_sync.py # MySQL 同步实现
|
||||
│ └── folder_sync.py # 文件夹同步实现
|
||||
├── static/ # 静态文件
|
||||
│ ├── config/ # 配置管理界面
|
||||
│ │ ├── index.html # 配置管理页面
|
||||
│ │ ├── style.css # 配置管理样式
|
||||
│ │ └── script.js # 配置管理脚本
|
||||
│ └── chat/ # 聊天界面
|
||||
│ ├── index.html
|
||||
│ └── style.css
|
||||
├── config.py # 配置管理
|
||||
├── db_utils.py # 数据库工具函数
|
||||
├── sync_service.py # 同步服务
|
||||
├── main.py # 程序入口（Docker 使用）
|
||||
├── requirements.txt # 依赖包
|
||||
├── Dockerfile # Docker 镜像定义
|
||||
├── docker-compose.yml # Docker Compose 配置
|
||||
├── .env.example # 环境变量示例
|
||||
├── data/ # 数据目录（SQLite 数据库、会话数据）
|
||||
└── README.md # 项目文档
|
||||
```
|
||||
|
||||
## API 接口
|
||||
|
||||
### 配置管理接口
|
||||
|
||||
#### 获取所有数据源配置
|
||||
```bash
|
||||
GET /folder-configs
|
||||
```
|
||||
|
||||
返回所有数据源配置的列表。
|
||||
|
||||
#### 获取特定数据源配置
|
||||
```bash
|
||||
GET /folder-configs/{config_id}
|
||||
```
|
||||
|
||||
获取指定 ID 的数据源配置详情。
|
||||
|
||||
#### 创建新数据源配置
|
||||
```bash
|
||||
POST /folder-configs
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "my_database",
|
||||
"type": "database",
|
||||
"database": "forgeplus",
|
||||
"table_name": "documents",
|
||||
"id_column": "id",
|
||||
"content_column": "title,content",
|
||||
"title_column": "title",
|
||||
"mysql_host": "localhost",
|
||||
"mysql_port": 3306,
|
||||
"mysql_user": "root",
|
||||
"mysql_password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新数据源配置
|
||||
```bash
|
||||
PUT /folder-configs/{config_id}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "my_database",
|
||||
"type": "database",
|
||||
"database": "forgeplus",
|
||||
"table_name": "documents",
|
||||
"id_column": "id",
|
||||
"content_column": "title,content",
|
||||
"title_column": "title",
|
||||
"mysql_host": "localhost",
|
||||
"mysql_port": 3306,
|
||||
"mysql_user": "root",
|
||||
"mysql_password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
#### 删除数据源配置
|
||||
```bash
|
||||
DELETE /folder-configs/{config_id}
|
||||
```
|
||||
|
||||
### 查询接口（检索 + LLM 生成）
|
||||
|
||||
```bash
|
||||
POST /query
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"query": "你的问题",
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
### 检索接口（仅检索，不生成）
|
||||
|
||||
```bash
|
||||
POST /retrieve
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"query": "你的问题",
|
||||
"top_k": 5
|
||||
}
|
||||
```
|
||||
|
||||
### 同步接口
|
||||
|
||||
```bash
|
||||
POST /sync
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"source_name": "my_database", // 可选，指定数据源名称
|
||||
"full_sync": false, // 是否全量同步
|
||||
"force": false // 是否强制重新处理
|
||||
}
|
||||
```
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
GET /health
|
||||
```
|
||||
|
||||
### 系统统计
|
||||
|
||||
```bash
|
||||
GET /stats
|
||||
```
|
||||
|
||||
完整 API 文档: http://localhost:8001/docs（端口可通过 `API_PORT` 配置）
|
||||
|
||||
## 系统架构
|
||||
|
||||
### 核心组件
|
||||
|
||||
1. **FastAPI** - Web框架，处理HTTP请求和流式响应
|
||||
2. **LlamaIndex** - RAG核心框架，负责文档索引和检索
|
||||
3. **ChromaDB** - 向量数据库，存储文档向量
|
||||
4. **Ollama** - 本地LLM服务，使用qwen3:1.7b模型（文本生成）和qwen3-embedding:0.6b模型（向量化）
|
||||
5. **MySQL** - 关系数据库，存储原始文档数据
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
MySQL数据库
|
||||
↓ (同步服务)
|
||||
文档处理与分块
|
||||
↓
|
||||
向量化 (Ollama Embedding)
|
||||
↓
|
||||
ChromaDB向量存储
|
||||
↓ (检索)
|
||||
LlamaIndex检索增强
|
||||
↓
|
||||
Ollama LLM生成
|
||||
↓
|
||||
FastAPI流式输出
|
||||
```
|
||||
|
||||
### 模块说明
|
||||
|
||||
#### 1. API层 (api/main.py)
|
||||
- **职责**: 处理HTTP请求，提供RESTful API接口
|
||||
- **主要功能**:
|
||||
- `/query` - 查询接口（支持流式和非流式）
|
||||
- `/retrieve` - 检索接口（仅检索，不生成）
|
||||
- `/sync` - 手动触发数据同步
|
||||
- `/health` - 健康检查
|
||||
- `/stats` - 系统统计信息
|
||||
|
||||
#### 2. 数据库层 (database/sync.py)
|
||||
- **职责**: 从MySQL读取文档数据
|
||||
- **主要功能**:
|
||||
- 连接MySQL数据库
|
||||
- 获取所有文档或增量文档
|
||||
- 支持按更新时间增量同步
|
||||
- 支持多数据库配置
|
||||
|
||||
#### 3. 同步层 (sync/)
|
||||
|
||||
**base_sync.py**
|
||||
- **职责**: 定义同步基类和接口
|
||||
- **主要功能**:
|
||||
- 定义抽象同步接口
|
||||
- 提供通用同步方法
|
||||
- 数据源存在性检查
|
||||
|
||||
**mysql_sync.py**
|
||||
- **职责**: MySQL 数据库同步实现
|
||||
- **主要功能**:
|
||||
- 从 MySQL 数据库获取文档
|
||||
- 支持多列内容合并
|
||||
- 支持文件附件内容解析
|
||||
- 增量和全量同步
|
||||
|
||||
**folder_sync.py**
|
||||
- **职责**: 文件夹同步实现
|
||||
- **主要功能**:
|
||||
- 从本地或远程文件夹获取文档
|
||||
- 支持 SSH/SFTP 连接
|
||||
- 递归扫描子文件夹
|
||||
- 文件过滤和忽略规则
|
||||
|
||||
#### 3. RAG核心层
|
||||
|
||||
**vector_store.py**
|
||||
- **职责**: 管理ChromaDB向量存储
|
||||
- **主要功能**:
|
||||
- 初始化ChromaDB客户端和集合
|
||||
- 添加/删除文档向量
|
||||
- 提供检索器（Retriever）
|
||||
|
||||
**document_processor.py**
|
||||
- **职责**: 处理文档转换和分块
|
||||
- **主要功能**:
|
||||
- MySQL文档转换为LlamaIndex Document
|
||||
- 文档分块处理
|
||||
- 元数据提取
|
||||
- 多列内容合并
|
||||
|
||||
**rag_engine.py**
|
||||
- **职责**: RAG查询和生成
|
||||
- **主要功能**:
|
||||
- 构建查询引擎
|
||||
- 流式和非流式查询
|
||||
- 集成Ollama LLM生成回答
|
||||
|
||||
#### 4. 同步服务 (sync_service.py)
|
||||
- **职责**: 协调数据源和ChromaDB之间的数据同步
|
||||
- **主要功能**:
|
||||
- 全量同步
|
||||
- 增量同步
|
||||
- 自动定时同步
|
||||
- 多数据源支持
|
||||
- 从SQLite数据库读取数据源配置
|
||||
|
||||
#### 5. 配置管理 (config.py)
|
||||
- **职责**: 管理系统配置和数据源配置
|
||||
- **主要功能**:
|
||||
- 从环境变量读取系统配置
|
||||
- 从SQLite数据库读取数据源配置
|
||||
- 提供配置访问接口
|
||||
|
||||
### 并发处理
|
||||
|
||||
#### 异步支持
|
||||
1. **FastAPI异步路由**: 所有API端点使用`async def`定义
|
||||
2. **异步生成器**: 流式响应使用`AsyncIterator`
|
||||
3. **线程池**: 同步操作（如非流式查询）使用`asyncio.to_thread`包装
|
||||
|
||||
#### 性能优化
|
||||
1. **连接池**: MySQL和ChromaDB使用连接池管理
|
||||
2. **向量索引**: ChromaDB自动创建向量索引加速检索
|
||||
3. **文档分块**: 大文档分块处理，提高检索精度
|
||||
4. **增量同步**: 只同步新增或更新的文档
|
||||
|
||||
## 生产环境部署
|
||||
|
||||
### 使用 Docker Compose（推荐）
|
||||
### 使用 Docker image (.tar.gz)文件部署
|
||||
|
||||
```bash
|
||||
# 1. 配置 .env 文件（复制 .env.example 并修改）
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件，配置 MySQL、Ollama 等连接信息
|
||||
|
||||
# 2. 构建并启动服务
|
||||
sudo bash docker-run.sh
|
||||
|
||||
# 3. 查看服务状态
|
||||
docker-compose ps
|
||||
|
||||
# 4. 查看日志
|
||||
docker-compose logs -f rag-api
|
||||
|
||||
# 5. 停止服务
|
||||
docker-compose down
|
||||
|
||||
# 6. 重启服务
|
||||
docker-compose restart rag-api
|
||||
```
|
||||
|
||||
### 使用 Docker Compose
|
||||
|
||||
```bash
|
||||
# 1. 配置 .env 文件（复制 .env.example 并修改）
|
||||
|
|
@ -490,29 +199,6 @@ docker-compose restart rag-api
|
|||
- **权限提示**: 确保宿主机上 `./data` 和 `./chroma_db_data` 目录可被 Docker 进程读写（通常 `chown` 或 `chmod` 为容器用户设置适当权限）。
|
||||
- **配置管理**: 所有配置统一在 `.env` 文件中管理，方便不同机器之间移植
|
||||
|
||||
### 配置移植
|
||||
|
||||
在不同机器之间移植时：
|
||||
|
||||
1. **复制配置文件**:
|
||||
```bash
|
||||
# 复制 .env 文件
|
||||
cp .env 新机器路径/.env
|
||||
|
||||
# 复制 databases_config.json（如果使用多数据库配置）
|
||||
cp databases_config.json 新机器路径/
|
||||
```
|
||||
|
||||
2. **修改配置**:
|
||||
编辑 `.env` 文件，修改相应的配置（如 MySQL 地址、密码等）
|
||||
|
||||
3. **启动服务**:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
所有配置都会自动从 `.env` 文件读取，无需修改 `docker-compose.yml`。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 容器无法连接 MySQL/Ollama
|
||||
|
|
@ -605,12 +291,7 @@ docker-compose restart rag-api
|
|||
|
||||
### 更换LLM模型
|
||||
|
||||
1. 修改`.env`中的`OLLAMA_MODEL`配置
|
||||
2. 或修改`rag/rag_engine.py`中的LLM初始化
|
||||
|
||||
### 自定义提示词
|
||||
|
||||
修改`rag/rag_engine.py`中的`qa_prompt`模板
|
||||
修改`.env`中的`OLLAMA_MODEL`配置
|
||||
|
||||
## 开发
|
||||
|
||||
|
|
@ -636,26 +317,9 @@ uv pip install -r requirements.txt
|
|||
# 3. 启动 ChromaDB 服务（必须）
|
||||
docker-compose up -d chromadb
|
||||
|
||||
# 4. 配置 .env 文件（确保使用 HttpClient 模式）
|
||||
# 在 .env 文件中设置：
|
||||
# CHROMA_SERVER_HOST=localhost
|
||||
# CHROMA_SERVER_PORT=8000
|
||||
# OLLAMA_BASE_URL=http://localhost:11434
|
||||
# MYSQL_HOST=localhost
|
||||
# ... 其他配置
|
||||
|
||||
# 5. 验证 ChromaDB 服务运行
|
||||
curl http://localhost:8002/docs
|
||||
|
||||
# 6. 启动 RAG API 服务
|
||||
python main.py
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- ChromaDB 必须通过 Docker 运行，因为系统已改为 HttpClient 模式
|
||||
- 如果不想使用 Docker，可以修改 `.env` 文件，注释掉 `CHROMA_SERVER_HOST`，系统会自动切换到本地文件模式（PersistentClient）
|
||||
- 确保 MySQL 和 Ollama 服务在配置的地址上运行
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
|
|
|
|||
Loading…
Reference in New Issue