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

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

功能特性

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

快速开始

前置条件

Docker 和 Docker Compose 已安装
MySQL 数据库已安装并运行（可在主机或远程服务器）
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模型，用于向量化

安装步骤

（安装包在install文件夹，解压使用）

克隆或进入项目目录:
```
cd install
```

配置环境变量:

# 复制环境变量示例文件
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     # 是否启用自动同步

启动服务:

# 构建并启动所有服务（ChromaDB + LibreOffice + RAG API）
# docker-compose 会自动读取 .env 文件中的配置
docker-compose up -d

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

访问配置管理界面: 服务启动后，可以通过以下方式访问配置管理界面：
- 配置管理界面: http://localhost:8001/config （端口可通过 API_PORT 配置）
- 智能问答界面: http://localhost:8001/chat （端口可通过 API_PORT 配置）
- API 文档: http://localhost:8001/docs
配置数据源: 在配置管理界面中，您可以：
- 添加新的数据源（数据库或文件夹）
- 编辑现有数据源配置
- 删除不需要的数据源
- 查看数据源的同步状态
配置方式：
- 数据库类型：配置 MySQL 数据库连接信息、表名、字段映射等
- 文件夹类型：配置文件夹路径、SSH 连接信息等

配置说明

环境变量配置

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

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

配置移植

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

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

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

数据源配置管理

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

配置界面访问

访问配置管理界面：http://localhost:8001/config

支持的数据源类型

**数据库类型 (database)**（目前仅支持 MySQL 数据库）

点击”新增数据源”-“选择类型”-“选择数据库”

数据库源配置界面

数据库连接配置
- 主机地址（必填）：MySQL 数据库主机地址
- 端口（必填）：MySQL 数据库端口
- 用户名（必填）：MySQL 用户名
- 密码（必填）：MySQL 密码
- 点击”测试连接”，检查数据库连接是否成功。
- 点击”获取数据库列表”，获取所有数据库
数据库配置
- 点击”选择数据库”，选中需要配置的数据库
- 点击”获取表列表”
- 点击”选择表”，选中对应的数据表
- 点击”获取表结构”，配置ID列、内容列、标题列、更新时间列（建议选择，以加速数据同步效率）
- 点击右上角”保存”按钮，保存数据库配置

文件夹类型 (folder)

点击”新增数据源”-“选择类型”-“文件夹”

文件夹源配置界面

文件夹配置
- 填写要同步文档所在的文件夹路径
SSH连接配置
- 主机地址（必填）：要同步的文件夹所在的 SSH 主机地址
- 端口（必填）：SSH 端口（默认 22）
- 用户名（必填）：SSH 用户名
- 密码（必填）：SSH 密码
- 点击”测试SSH连接”，检查 SSH 连接是否成功。
点击右上角”保存”按钮，保存文件夹配置

更新数据源配置

点击左侧数据源列表中的数据源
修改配置后点击保存，后台会自动删除原来同步的数据并重新同步

生产环境部署

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

注意： - 确保宿主机上已安装 Docker 和 Docker Compose - chromadb.tar.gz、soffice.tar.gz、rag-api.tar.gz 这三个文件必须存在于一个目录下 - .env 文件必须存在于该目录下（按照下面的步骤通过.env.example 生成并修改） - static/ 文件夹必须存在于该目录下 - docker-run.sh 脚本必须存在于该目录下 - nltk/ 文件夹必须存在于该目录下，用于存储 NLTK 数据

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

常见问题

1. 容器无法连接 Ollama

错误: Connection refused 或 Failed to connect

解决:

确保 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 文件中的环境变量配置是否正确
确保所有必需的服务（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 中的过期数据
监控向量数据库大小

扩展性

添加新数据源

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

更换LLM模型

修改.env中的OLLAMA_MODEL配置

开发

本地开发（可选）

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

前置条件：

Docker 已安装
Ollama 服务已运行（可在主机或远程服务器），并安装了通用模型（例如：qwen3:235b）和嵌入模型（例如：qwen3-embedding:8b）
RAG-API的接口已开放访问（默认8001）

启动步骤：

# 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

# 4. 启动 LibreOffice 服务（必须）
docker-compose up -d soffice-service

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

# 6. 验证 LibreOffice 服务运行
curl http://localhost:8003/health

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