基于 Clean Architecture 的检索增强生成(RAG)系统,集成文档向量化、知识图谱构建与大模型问答能力。后端采用 Python(Flask + ChromaDB + DeepSeek),前端采用 React 19 + Ant Design。

本项目分为**后端(Python)和前端(Node.js)**两部分,运行前请确认以下软件已安装:

前往官网 https://python.org/downloads 下载并安装 Python 3.11。

安装时务必勾选 「Add Python to PATH」。

安装完成后验证:

python --version
# 预期输出:Python 3.11.x

uv 是高性能的 Python 包管理工具,用于替代 pip + venv。

Windows(PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后验证:

uv --version

在项目根目录(rag/)执行:

cd rag
uv venv --python 3.11
# 将在当前目录下创建 .venv 文件夹

Windows:

.venv\Scripts\activate

Linux / macOS:

source .venv/bin/activate

激活成功后,命令行前缀会显示 (.venv)。

虚拟环境激活后,执行:

uv pip install -r requirements.txt

依赖较多,首次安装约需 3 ~ 10 分钟,请耐心等待。

在项目根目录 .env 文件中,写入 API Key:

DEEPSEEK_API_KEY=your_api_key_here

将 your_api_key_here 替换为真实的 DeepSeek API Key。

本项目使用 FastEmbedEmbeddings 进行文档向量化,底层模型为:

• 模型名称:BAAI/bge-small-en-v1.5(ONNX 量化版)
• 模型大小:约 130 MB
• 缓存目录:rag/llm_model/(自动创建)
• 向量数据库:ChromaDB,数据持久化在 rag/db/ 目录

首次启动后端时,程序会自动从 HuggingFace 下载模型并缓存到本地。后续启动直接读取本地缓存,无需重复下载。

前往 https://nodejs.org 下载并安装 LTS 版本(18 或以上)。

安装完成后验证:

node --version
npm --version
# 预期:node v18.x.x 或更高,npm 9.x.x 或更高

进入前端目录并安装依赖:

cd rag/frontend
npm install
# 首次安装约需 2 ~ 5 分钟

在项目根目录(rag/),确保虚拟环境已激活,执行:

python main.py

启动成功后终端显示:

 * Running on http://0.0.0.0:8080

后端监听端口 8080,debug 模式,支持多线程并发。

新开一个终端窗口,进入前端目录:

cd rag/frontend
npm start

启动成功后浏览器将自动打开:

http://localhost:3000

前端开发服务器支持热重载。

rag/
├── Backend/ 后端源代码(Clean Architecture)
│ ├── Application/ 应用层(用例、技能、上下文管理)
│ ├── Domain/ 领域层(实体与公共模型)
│ ├── Infrastructure/ 基础设施层
│ └── Web/ Web 接口层
├── frontend/ 前端源代码(React 19 + Ant Design)
├── docs/ 项目文档
├── db/ SQLite 数据库 + ChromaDB 向量库(自动创建)
├── llm_model/ 向量化模型缓存(自动创建)
├── uploads/ 用户上传文件(自动创建)
├── tests/ 测试用例
├── requirements.txt Python 依赖清单
├── main.py 后端启动入口
└── .env 环境变量配置(需手动创建)当前给了一个示例

安装 uv 后重新打开终端,或手动将 uv 安装路径加入 PATH 环境变量。

检查网络是否能访问 huggingface.co,或配置国内镜像:

# Windows 临时设置
set HF_ENDPOINT=https://hf-mirror.com
# 然后再次运行
python main.py

后端默认 8080,前端默认 3000。如端口冲突,分别修改:

• 后端:main.py 第 8 行的 port=8080
• 前端:
  1. 在 frontend/ 目录下新建 .env 文件,写入 PORT=3001
  2. 同步修改 frontend/src/setupProxy.js 第 14 行 url 中的 8080 为新端口

确认已激活虚拟环境(命令行前缀显示 (.venv)),再重新执行安装命令。

文件导入后,后端会执行:文档切片 → 提取信息三元组 → 构建知识图谱。该过程需要一定时间,请等待构建完成后再进行检索。

• 后端:Python 3.11、Flask、ChromaDB、FastEmbed、DeepSeek LLM
• 前端:React 19、Ant Design、TailwindCSS
• 架构:Clean Architecture(领域驱动设计)
• 数据存储:SQLite + ChromaDB 向量库 + JSON 知识图谱