RAG API - 本地化检索增强系统

一个基于 LlamaIndex、ChromaDB 和 Ollama 的本地化 RAG（检索增强生成）系统，提供流式 API 接口供其他平台调用。

功能特性

• 🔍 智能检索: 使用 LlamaIndex 和 ChromaDB 实现高效的向量检索
• 💾 数据同步: 自动同步 MySQL 数据库数据到 ChromaDB 向量库
• 🌊 流式输出: 基于 FastAPI 的流式响应，支持实时对话
• 🤖 本地 LLM: 集成 Ollama 本地部署的大模型
• ⚡ 高并发: 支持多用户同时访问
• 🔄 自动同步: 支持定时自动同步和手动触发同步
• 🐳 Docker 部署: 使用 Docker Compose 一键部署
• ⚙️ 统一配置: 所有配置统一在 .env 文件中管理，方便不同机器之间移植

快速开始

前置条件

1. Docker 和 Docker Compose 已安装
2. MySQL 数据库已安装并运行（可在主机或远程服务器）
3. Ollama 服务已安装并运行（可在主机或远程服务器），且已下载以下模型（可以替换为其他模型）：
   • qwen3:235b - LLM模型（用于文本生成）
   • qwen3-embedding:8b - Embedding模型（用于向量化）

检查 Ollama

# 检查 Ollama 是否运行
curl http://localhost:11434/api/tags

# 下载所需的模型（如果未下载）
ollama pull qwen3:235b              # LLM模型，用于文本生成
ollama pull qwen3-embedding:8b    # Embedding模型，用于向量化

安装步骤

1. 克隆或进入项目目录:

   cd 项目目录
   

2. 配置环境变量:

   # 复制环境变量示例文件
   cp .env.example .env
   
   # 编辑 .env 文件，配置以下参数：
   

   必须配置的参数:

   # ChromaDB 配置（Docker 模式，使用 host 网络）
   CHROMA_SERVER_HOST=localhost
   CHROMA_SERVER_PORT=8002
   
   # Ollama 配置（使用 host 网络模式）
   OLLAMA_BASE_URL=http://localhost:11434
   OLLAMA_MODEL=qwen3:235b
   OLLAMA_EMBEDDING_MODEL=qwen3-embedding:8b
   

   RAG服务配置:

   # API 端口（默认 8001）
   API_PORT=8001
   
   # 同步配置
   SYNC_INTERVAL=300  # 同步间隔（秒）
   AUTO_SYNC=true     # 是否启用自动同步
   

3. 启动服务:

   # 构建并启动所有服务（ChromaDB + RAG API）
   # docker-compose 会自动读取 .env 文件中的配置
   docker-compose up -d
   
   # 查看日志
   docker-compose logs -f rag-api
   

4. 访问配置管理界面: 服务启动后，可以通过以下方式访问配置管理界面：

   • 配置管理界面: http://localhost:8001/static/config（端口可通过 API_PORT 配置）
   • API 文档: http://localhost:8001/docs
   • 健康检查: http://localhost:8001/health
   • 系统统计: http://localhost:8001/stats

5. 配置数据源: 在配置管理界面中，您可以：

   • 添加新的数据源（数据库或文件夹）
   • 编辑现有数据源配置
   • 删除不需要的数据源
   • 查看数据源的同步状态

   配置方式：

   • 数据库类型：配置 MySQL 数据库连接信息、表名、字段映射等
   • 文件夹类型：配置文件夹路径、SSH 连接信息等

配置说明

环境变量配置

所有配置参数都统一在 .env 文件中管理，包括：

• API 配置: API_HOST, API_PORT, API_TITLE, API_VERSION
• ChromaDB 配置: CHROMA_SERVER_HOST, CHROMA_SERVER_PORT, CHROMA_COLLECTION_NAME
• Ollama 配置: OLLAMA_BASE_URL, OLLAMA_MODEL, OLLAMA_EMBEDDING_MODEL
• RAG 配置: EMBEDDING_DIMENSION, CHUNK_SIZE, CHUNK_OVERLAP, TOP_K
• 同步配置: SYNC_INTERVAL, AUTO_SYNC

配置移植

在不同机器之间移植时，只需：

1. 复制 .env 文件到新机器
2. 修改相应的配置（如 Ollama 地址、端口等）
3. 启动服务: docker-compose up -d

所有配置都会自动从 .env 文件读取，无需修改 docker-compose.yml。

数据源配置管理

系统提供 Web 界面来管理所有数据源配置，支持以下类型：

配置界面访问

访问配置管理界面：http://localhost:8001/static/config/index.html

支持的数据源类型

1. 数据库类型 (database)

   • 支持 MySQL 数据库
   • 可配置多个数据库和表
   • 支持多列内容合并
   • 支持文件附件内容解析

2. 文件夹类型 (folder)

   • 支持文件夹
   • 支持递归扫描
   • 支持文件过滤规则

生产环境部署

使用 Docker image (.tar.gz)文件部署

# 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

# 1. 配置 .env 文件（复制 .env.example 并修改）
cp .env.example .env
# 编辑 .env 文件，配置 MySQL、Ollama 等连接信息

# 2. 构建并启动服务
docker-compose up -d --build

# 3. 查看服务状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f rag-api

# 5. 停止服务
docker-compose down

# 6. 重启服务
docker-compose restart rag-api

配置说明

• 网络模式: 使用 host 网络模式，容器可以直接访问宿主机上的服务（MySQL、Ollama）
• 端口: RAG API 使用 8001 端口（可通过 API_PORT 配置），ChromaDB 使用 8000 端口
• 数据持久化: ChromaDB 数据存储在 ./chroma_db_data 目录
  • 会话/SQLite 持久化: API 会将会话数据存储在 ./data/sessions.db，请在使用 Docker Compose 时把宿主机的 ./data 目录挂载到容器内（示例 docker-compose.yml 已包含该挂载）。
  • 权限提示: 确保宿主机上 ./data 和 ./chroma_db_data 目录可被 Docker 进程读写（通常 chown 或 chmod 为容器用户设置适当权限）。
• 配置管理: 所有配置统一在 .env 文件中管理，方便不同机器之间移植

常见问题

1. 容器无法连接 MySQL/Ollama

错误: Connection refused 或 Failed to connect

解决:

• 确保 MySQL 和 Ollama 服务正在运行
• 检查配置管理界面中的数据库连接信息是否正确
• 使用 host 网络模式时，应使用 localhost 访问宿主机服务

2. 端口冲突

错误: Address already in use

解决:

• 检查端口是否被占用: netstat -tlnp | grep 8001
• 修改 .env 文件中的 API_PORT 配置

3. 同步失败

错误: No documents found 或 Sync failed

解决:

• 检查数据源配置是否正确（通过配置管理界面）
• 验证数据库或文件夹连接信息
• 查看容器日志: docker-compose logs rag-api

4. 容器启动失败

错误: 容器不断重启

解决:

• 查看详细日志: docker-compose logs rag-api
• 检查 .env 文件中的环境变量配置是否正确
• 确保所有必需的服务（MySQL、Ollama）都已启动

5. 配置管理界面无法访问

错误: 404 Not Found 或 Connection refused

解决:

• 确认 RAG API 服务已启动: docker-compose ps
• 检查端口配置是否正确: API_PORT=8001
• 尝试访问: http://localhost:8001/static/config/index.html

6. 数据源配置保存失败

错误: Failed to save configuration

解决:

• 检查配置名称是否已存在
• 验证必填字段是否都已填写
• 查看浏览器控制台和服务器日志获取详细错误信息
• 确保 SQLite 数据库文件有写入权限

7. 同步服务未自动启动

错误: 配置保存后没有自动开始同步

解决:

• 检查 .env 文件中的 AUTO_SYNC=true 配置
• 查看同步服务日志: docker-compose logs rag-api | grep sync
• 手动触发同步: 在配置管理界面中点击"同步"按钮

性能优化建议

1. 调整配置参数

根据实际需求调整 .env 中的参数：

• CHUNK_SIZE: 文档分块大小（默认1024）
• CHUNK_OVERLAP: 分块重叠（默认200）
• TOP_K: 检索文档数量（默认5）
• SYNC_INTERVAL: 同步间隔（默认300秒）

2. 数据库优化

• 为 MySQL 表的 updated_at 字段创建索引
• 定期清理 ChromaDB 中的过期数据
• 监控向量数据库大小

扩展性

添加新数据源

1. 在database/目录创建新的同步模块
2. 实现类似MySQLSync的接口
3. 在sync_service.py中集成

更换LLM模型

修改.env中的OLLAMA_MODEL配置

开发

本地开发（可选）

如果需要本地开发（不使用 Docker 运行 rag-api，但仍需要 Docker 运行 ChromaDB）：

前置条件：

1. Docker 已安装（用于运行 ChromaDB）
2. MySQL 服务已运行（可在主机或远程服务器）
3. Ollama 服务已运行（可在主机或远程服务器）

启动步骤：

# 1. 创建虚拟环境
uv venv --python 3.13.9
source .venv/bin/activate # Windows: venv\Scripts\activate

# 2. 安装依赖
uv pip install -r requirements.txt

# 3. 启动 ChromaDB 服务（必须）
docker-compose up -d chromadb

# 5. 验证 ChromaDB 服务运行
curl http://localhost:8002/docs

# 6. 启动 RAG API 服务
python main.py