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

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

功能特性

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

快速开始

前置条件

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

检查 Ollama

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

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

安装步骤

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

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

   cd install
   

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:8b  # 较小模型，适合一般硬件
   OLLAMA_EMBEDDING_MODEL=qwen3-embedding:0.6b  # 较小嵌入模型
   # 可选：使用更大模型以获得更好效果（需要更强硬件）
   # OLLAMA_MODEL=qwen3:235b
   # OLLAMA_EMBEDDING_MODEL=qwen3-embedding:8b
   

   RAG服务配置:

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

3. 启动服务:

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

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

   • 配置管理界面: http://localhost:8001/config 或 http://localhost:8001/static/config/index.html （端口可通过 API_PORT 配置）
   • 智能问答界面: http://localhost:8001/chat （端口可通过 API_PORT 配置）
   • API 文档: http://localhost:8001/docs

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

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

   配置方式：

   • 数据库类型：配置 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

配置移植

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

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

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

数据源配置管理

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

配置界面访问

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

支持的数据源类型

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

• 点击"新增数据源"-"选择类型"-"选择数据库"

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

2. 文件夹类型 (folder)

• 点击"新增数据源"-"选择类型"-"文件夹"

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

3. Git代码库类型 (git)

• 点击"新增数据源"-"选择类型"-"Git代码库"

• Git代码库支持Git单仓库和Git服务器两种配置模式

• 模式1：Git仓库配置

  • Git仓库URL（必填）：Git代码库的URL地址
  • 分支（必填）：要同步的Git分支（默认main）
  • 协议：选择https或ssh协议
  • HTTPS Token：如果使用https协议，填写访问令牌
  • SSH密钥：如果使用ssh协议，填写SSH私钥
  • 点击"测试Git连接"，检查 Git 连接是否成功。

• 模式2：Git服务器模式配置

  • 模式选择：选择"服务器模式"启用多仓库管理
  • Git服务器主机（必填）：Git服务器的主机地址
  • Git服务器端口（必填）：Git服务器的端口（默认9418）
  • Git服务器用户名：SSH协议下的用户名
  • Git服务器密码：SSH协议下的密码
  • 仓库配置：添加多个仓库配置，每个仓库包含
    • 仓库名称：仓库的唯一标识
    • 仓库路径：仓库在服务器上的路径
    • 分支：要同步的Git分支（默认main）
  • 点击"测试Git连接"，检查 Git 服务器连接是否成功。

• 点击右上角"保存"按钮，保存Git仓库配置

1. 更新数据源配置

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

生产环境部署

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

注意：

• 确保宿主机上已安装 Docker 和 Docker Compose
• 根据机器架构，下载对应架构的镜像文件后并解压，目前支持 X86 64位和ARM 64架构。

X86 64位架构下载 V1.0.0.0.zip，包含镜像 chromadb.tar.gz、soffice.tar.gz、rag-api.tar.gz
ARM 64架构下载 V1.0.0.0-arm64.zip，包含镜像 chromadb-arm64.tar.gz、soffice-arm64.tar.gz、rag-api.tar.gz

解压后确保：

• 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. 运行docker-run.sh, 构建并启动服务
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/config 或 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
• 手动触发同步: 在配置管理界面中点击"同步"按钮

8. Git连接失败

错误: Git连接失败 或 Failed to connect to Git repository

解决:

• 确保 Git 仓库 URL 正确
• 检查网络连接是否正常
• 验证 Git 凭证（HTTPS Token 或 SSH 密钥）是否有效
• 确保目标 Git 仓库存在且可访问
• 查看详细错误信息: docker-compose logs rag-api | grep git

9. Git同步失败

错误: Git同步失败 或 Failed to sync Git repository

解决:

• 检查 Git 仓库是否有访问权限
• 验证本地磁盘空间是否充足
• 查看同步服务日志获取详细错误信息: 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 已安装
2. Ollama 服务已运行（可在主机或远程服务器），并安装了通用模型（例如：qwen3:235b）和嵌入模型（例如：qwen3-embedding:8b）
3. RAG-API的接口已开放访问（默认8001）

启动步骤：

# 0. 确保 .env 文件中的host配置准确
cp .env.zkxlocal .env

# 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

# 8. 如要调试，使用.vscode/launch.json 启动调试会话