diff --git a/.env.example b/.env.example index af1c18d..bb14c65 100644 --- a/.env.example +++ b/.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 配置 # ============================================ diff --git a/README.md b/README.md index 482b6f9..e572a43 100644 --- a/README.md +++ b/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