ai

1. 项目概述 #

RAG Lite 是一个基于 Flask 框架构建的轻量级检索增强生成（Retrieval-Augmented Generation, RAG）应用系统。该系统集成了文档管理、向量检索、智能问答等核心功能，支持多种大语言模型（LLM）和向量数据库，为企业和个人提供开箱即用的知识库问答解决方案。

1.1 核心特性 #

用户认证与权限管理 - 完整的用户注册、登录、会话管理功能
知识库管理 - 支持创建、编辑、删除知识库，支持自定义封面和描述
文档管理 - 支持 PDF、DOCX、TXT、MD 等多种格式文档上传、解析和向量化
智能检索 - 支持向量检索、关键词检索和混合检索三种模式
智能问答 - 基于知识库的智能问答，支持流式输出和 Markdown 渲染
灵活配置 - 支持多种 LLM 提供商（DeepSeek、OpenAI、Ollama）和 Embedding 模型
多存储后端 - 支持本地存储和 MinIO 对象存储
多向量数据库 - 支持 Chroma 和 Milvus 向量数据库

2. 技术架构 #

2.1 技术栈 #

Web 框架: Flask 3.1.2+
ORM: SQLAlchemy 2.0.45+
数据库: MySQL (通过 PyMySQL)
向量数据库: Chroma / Milvus
LLM 框架: LangChain 1.2.0+
文档解析: PyPDF, docx2txt
文本处理: jieba, sentence-transformers
存储: 本地文件系统 / MinIO

2.2 项目结构 #

rag-lite/
├── app/                          # 应用主目录
│   ├── blueprints/               # 蓝图（路由）模块
│   │   ├── auth.py              # 认证相关路由
│   │   ├── chat.py              # 聊天相关路由
│   │   ├── document.py          # 文档管理路由
│   │   ├── knowledgebase.py     # 知识库管理路由
│   │   ├── settings.py          # 系统设置路由
│   │   └── utils.py             # 工具路由
│   ├── models/                   # 数据模型
│   │   ├── base.py              # 基础模型类
│   │   ├── user.py              # 用户模型
│   │   ├── knowledgebase.py     # 知识库模型
│   │   ├── document.py          # 文档模型
│   │   ├── chat_session.py      # 会话模型
│   │   ├── chat_message.py      # 消息模型
│   │   └── settings.py          # 系统设置模型
│   ├── services/                 # 业务逻辑服务层
│   │   ├── base_service.py      # 基础服务类
│   │   ├── user_service.py      # 用户服务
│   │   ├── knowledgebase_service.py  # 知识库服务
│   │   ├── document_service.py  # 文档服务
│   │   ├── chat_service.py      # 聊天服务
│   │   ├── chat_session_service.py  # 会话服务
│   │   ├── rag_service.py       # RAG 服务
│   │   ├── retrieval_service.py # 检索服务
│   │   ├── vector_service.py    # 向量服务
│   │   ├── parser_service.py    # 文档解析服务
│   │   ├── settings_service.py  # 设置服务
│   │   ├── storage_service.py   # 存储服务
│   │   ├── storage/             # 存储后端实现
│   │   │   ├── base.py         # 存储基类
│   │   │   ├── factory.py      # 存储工厂
│   │   │   ├── local_storage.py # 本地存储
│   │   │   └── minio_storage.py # MinIO 存储
│   │   └── vectordb/            # 向量数据库实现
│   │       ├── base.py         # 向量数据库基类
│   │       ├── factory.py      # 向量数据库工厂
│   │       ├── chroma.py       # Chroma 实现
│   │       └── milvus.py       # Milvus 实现
│   ├── templates/                # HTML 模板
│   │   ├── base.html           # 基础模板
│   │   ├── home.html           # 首页
│   │   ├── login.html          # 登录页
│   │   ├── register.html       # 注册页
│   │   ├── kb_list.html        # 知识库列表
│   │   ├── kb_detail.html      # 知识库详情
│   │   ├── chat.html           # 聊天页面
│   │   └── settings.html       # 设置页面
│   ├── static/                  # 静态资源
│   ├── utils/                   # 工具函数
│   │   ├── auth.py             # 认证工具
│   │   ├── db.py               # 数据库工具
│   │   ├── logger.py           # 日志工具
│   │   ├── document_loader.py  # 文档加载器
│   │   ├── text_splitter.py    # 文本分割器
│   │   ├── embedding_factory.py # Embedding 工厂
│   │   ├── llm_factory.py      # LLM 工厂
│   │   ├── rerank_factory.py   # 重排序工厂
│   │   └── models_config.py    # 模型配置
│   ├── __init__.py              # 应用初始化
│   └── config.py                # 应用配置
├── chroma_db/                    # Chroma 向量数据库存储目录
├── storages/                     # 文件存储目录
├── logs/                         # 日志目录
├── volumes/                      # Docker 卷目录（Milvus/MinIO）
├── main.py                       # 应用启动入口
├── pyproject.toml                # 项目依赖配置
├── docker-compose.yml            # Docker Compose 配置
└── docs/                         # 项目文档

3. 快速开始 #

3.1 环境要求 #

Python 3.12+
MySQL 5.7+ 或 8.0+
（可选）Docker 和 Docker Compose（用于 Milvus/MinIO）

3.2 安装步骤 #

克隆项目

git clone <repository-url>
cd rag-lite

安装依赖

使用 uv 包管理器（推荐）：

uv sync

或使用 pip：

pip install -r requirements.txt

配置环境变量

在项目根目录创建 .env 文件：

# 应用配置
APP_HOST=0.0.0.0
APP_PORT=5000
APP_DEBUG=false
MAX_FILE_SIZE=104857600
SECRET_KEY=your-secret-key-here

# 日志配置
LOG_DIR=./logs
LOG_FILE=rag_lite.log
LOG_LEVEL=INFO
LOG_ENABLE_FILE=true
LOG_ENABLE_CONSOLE=true

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your-password
DB_NAME=rag-lite
DB_CHARSET=utf8mb4

# 存储配置
STORAGE_TYPE=local  # 'local' 或 'minio'
STORAGE_DIR=./storages

# MinIO 配置（当 STORAGE_TYPE='minio' 时使用）
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=rag-lite
MINIO_SECURE=false

# 向量数据库配置
VECTORDB_TYPE=chroma  # 'chroma' 或 'milvus'
CHROMA_PERSIST_DIRECTORY=./chroma_db

初始化数据库

创建 MySQL 数据库：

CREATE DATABASE `rag-lite` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

应用启动时会自动创建数据表。

启动应用

python main.py

应用将在 http://localhost:5000 启动。

3.3 Docker 部署（可选） #

如果需要使用 Milvus 向量数据库和 MinIO 存储，可以使用 Docker Compose：

docker-compose up -d

这将启动：

Milvus 向量数据库（端口 19530）
MinIO 对象存储（端口 9000, 9001）
etcd（Milvus 依赖）

4. 功能模块 #

4.1 用户认证 #

用户注册、登录、登出
基于 Session 的会话管理
密码哈希存储（安全）

4.2 知识库管理 #

创建、编辑、删除知识库
自定义知识库名称、描述和封面
配置文档分块参数（chunk_size, chunk_overlap）
知识库列表展示和搜索

4.3 文档管理 #

支持上传 PDF、DOCX、TXT、MD 格式文档
自动文档解析和文本提取
文档状态跟踪（pending, processing, completed, failed）
文档向量化和存储
文档删除和重新处理

4.4 智能检索 #

支持三种检索模式：

向量检索：基于语义相似度的向量检索
关键词检索：基于 BM25 算法的全文检索
混合检索：结合向量和关键词检索，支持权重配置

检索结果支持重排序（Rerank）优化。

4.5 智能问答 #

基于知识库的 RAG 问答
支持流式输出（Server-Sent Events）
Markdown 格式渲染
引用来源展示
普通聊天模式（不基于知识库）

4.6 系统设置 #

LLM 配置：支持 DeepSeek、OpenAI、Ollama
Embedding 配置：支持 HuggingFace、OpenAI、Ollama
检索配置：检索模式、阈值、TopN 等参数
提示词配置：系统提示词和查询提示词自定义

5. 配置说明 #

5.1 LLM 提供商配置 #

5.1.1 DeepSeek #

# 在系统设置中配置
LLM_PROVIDER=deepseek
LLM_MODEL_NAME=deepseek-chat
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.deepseek.com
LLM_TEMPERATURE=0.7

5.1.2 OpenAI #

LLM_PROVIDER=openai
LLM_MODEL_NAME=gpt-3.5-turbo
LLM_API_KEY=your-api-key
LLM_TEMPERATURE=0.7

5.1.3 Ollama #

LLM_PROVIDER=ollama
LLM_MODEL_NAME=llama2
LLM_BASE_URL=http://localhost:11434
LLM_TEMPERATURE=0.7

5.2 Embedding 模型配置 #

5.2.1 HuggingFace（默认） #

EMBEDDING_PROVIDER=huggingface
EMBEDDING_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2

5.2.2 OpenAI #

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL_NAME=text-embedding-ada-002
EMBEDDING_API_KEY=your-api-key

5.2.3 Ollama #

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL_NAME=nomic-embed-text
EMBEDDING_BASE_URL=http://localhost:11434

5.3 向量数据库配置 #

5.3.1 Chroma（默认） #

VECTORDB_TYPE=chroma
CHROMA_PERSIST_DIRECTORY=./chroma_db

5.3.2 Milvus #

VECTORDB_TYPE=milvus
# Milvus 连接信息在代码中配置

5.4 存储后端配置 #

5.4.1 本地存储（默认） #

STORAGE_TYPE=local
STORAGE_DIR=./storages

5.4.2 MinIO #

STORAGE_TYPE=minio
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=rag-lite
MINIO_SECURE=false

6. 使用指南 #

6.1 创建知识库 #

登录系统后，进入知识库管理页面
点击"新建知识库"
填写知识库名称、描述（可选）
上传封面图片（可选）
配置分块参数（可选，使用默认值）
保存知识库

6.2 上传文档 #

进入知识库详情页
点击"上传文档"
选择文件（支持 PDF、DOCX、TXT、MD）
等待文档处理完成（自动解析、分块、向量化）

6.3 开始问答 #

进入聊天页面
选择知识库（可选，不选择则为普通聊天）
输入问题并发送
系统将基于知识库内容生成答案
查看引用来源了解答案依据

6.4 配置系统设置 #

进入系统设置页面
配置 LLM 提供商和模型
配置 Embedding 模型
调整检索参数
自定义提示词模板
保存设置

7. 开发指南 #

7.1 代码结构说明 #

Blueprints: 处理 HTTP 请求，调用服务层
Services: 业务逻辑实现，数据操作封装
Models: 数据模型定义，SQLAlchemy ORM
Utils: 工具函数，工厂类，辅助功能

7.2 扩展开发 #

7.2.1 添加新的 LLM 提供商 #

在 app/utils/llm_factory.py 中注册新的提供商
实现创建 LLM 实例的函数
在系统设置中添加配置项

7.2.2 添加新的向量数据库 #

在 app/services/vectordb/ 中创建新的实现类
继承 BaseVectorDB 基类
实现所有抽象方法
在 factory.py 中注册

7.2.3 添加新的存储后端 #

在 app/services/storage/ 中创建新的实现类
继承 BaseStorage 基类
实现所有抽象方法
在 factory.py 中注册

8. API 文档 #

API 文档

主要 API 端点：

POST /auth/register - 用户注册
POST /auth/login - 用户登录
GET /auth/logout - 用户登出
GET /knowledgebase/list - 获取知识库列表
POST /knowledgebase/create - 创建知识库
POST /document/upload - 上传文档
POST /chat/ask - 发送问题（非流式）
GET /chat/stream - 流式问答
GET /settings - 获取系统设置
POST /settings/update - 更新系统设置

详细 API 文档请参考各模块文档。

9. 故障排除 #

9.1 常见问题 #

数据库连接失败
- 检查 MySQL 服务是否启动
- 验证 .env 中的数据库配置
- 确认数据库已创建
向量数据库连接失败
- Chroma: 检查 CHROMA_PERSIST_DIRECTORY 目录权限
- Milvus: 检查 Docker 容器是否运行，端口是否开放
文档处理失败
- 检查文件格式是否支持
- 查看日志文件了解详细错误
- 确认 Embedding 模型配置正确
LLM 调用失败
- 检查 API Key 是否正确
- 验证网络连接
- 查看 LLM 提供商服务状态

导航菜单