RAGFlow圣经(2)：RAGFlow 架构设计


ragflow/
├── 📁 api/                    # API网关和前端服务 (像图书馆的接待大厅)
│   ├── apps/                  # 各个业务模块的API接口
│   │   ├── conversation_app.py # 对话管理接口
│   │   ├── dataset_app.py     # 知识库管理接口
│   │   ├── document_app.py    # 文档管理接口
│   │   ├── file_app.py        # 文件上传接口
│   │   ├── llm_app.py         # 大模型配置接口
│   │   └── user_app.py        # 用户管理接口
│   ├── db/                    # 数据库操作层
│   │   ├── db_models.py       # 数据模型定义
│   │   └── services/          # 业务逻辑服务
│   ├── ragflow_server.py      # 主服务器入口
│   └── settings.py            # API服务配置
│
├── 📁 rag/                    # RAG核心引擎 (像图书馆的智能检索系统)
│   ├── app/                   # RAG业务逻辑
│   │   ├── retrieval.py       # 检索逻辑
│   │   ├── generator.py       # 生成逻辑
│   │   └── qa.py              # 问答处理
│   ├── flow/                  # 工作流管理
│   ├── llm/                   # 大模型适配器
│   │   ├── chat_model.py      # 对话模型封装
│   │   ├── embedding_model.py # 嵌入模型封装
│   │   └── rerank_model.py    # 重排序模型封装
│   ├── nlp/                   # 自然语言处理工具
│   │   ├── rag_tokenizer.py   # 分词器
│   │   └── search.py          # 搜索算法
│   └── utils/                 # 工具函数
│
├── 📁 deepdoc/               # 深度文档理解引擎 (像图书馆的文档分析中心)
│   ├── parser/               # 各种文档解析器
│   │   ├── excel_parser.py   # Excel解析器
│   │   ├── pdf_parser.py     # PDF解析器
│   │   ├── word_parser.py    # Word解析器
│   │   └── presentation_parser.py # PPT解析器
│   └── vision/               # 视觉理解模块
│       ├── layout_recognizer.py # 版面识别
│       ├── ocr.py               # 光学字符识别
│       └── table_recognizer.py  # 表格识别
│
├── 📁 agent/                 # Agent智能体系统 (像图书馆的AI助手)
│   ├── component/            # 智能体组件
│   │   ├── begin.py          # 开始节点
│   │   ├── retrieval.py      # 检索节点
│   │   ├── generate.py       # 生成节点
│   │   └── rewrite.py        # 重写节点
│   ├── tools/                # 外部工具集成
│   │   ├── bing_search.py    # 必应搜索
│   │   ├── google_search.py  # 谷歌搜索
│   │   ├── wikipedia.py      # 维基百科
│   │   └── arxiv.py          # 学术论文搜索
│   └── templates/            # 工作流模板
│
├── 📁 web/                   # 前端用户界面 (像图书馆的用户终端)
│   ├── src/
│   │   ├── components/       # React组件
│   │   ├── pages/            # 页面组件
│   │   ├── hooks/            # React Hooks
│   │   └── utils/            # 前端工具函数
│   ├── package.json          # 前端依赖配置
│   └── .umirc.ts            # UmiJS配置
│
├── 📁 docker/                # 容器化部署 (像图书馆的基础设施)
│   ├── docker-compose.yml        # 主服务编排
│   ├── docker-compose-base.yml   # 基础服务编排
│   ├── .env                       # 环境变量配置
│   ├── service_conf.yaml.template # 服务配置模板
│   └── nginx/                     # Nginx反向代理配置
│
├── 📁 conf/                  # 配置文件 (像图书馆的管理制度)
│   ├── service_conf.yaml    # 主服务配置
│   └── logging.yml           # 日志配置
│
├── 📁 sandbox/               # 代码执行沙箱 (像图书馆的安全实验室)
│   ├── executor_manager.py  # 执行器管理
│   └── runtime/              # 各语言运行时
│
├── 📁 test/                  # 测试代码
├── 📁 docs/                  # 项目文档
├── pyproject.toml            # Python项目配置
├── Dockerfile                # Docker镜像构建文件
└── README.md                 # 项目说明

2.1.3 分层架构设计 - 像盖楼一样层次分明

RAGFlow 的架构就像一栋设计精良的办公楼，每一层都有明确的功能定位：

2.1.4 云原生设计 - 为现代部署而生

现在的应用就像乐高积木，要能够灵活组装、随时拆换。RAGFlow 从设计之初就考虑了这些现代化需求：

容器化就像标准化的货柜：

所有服务都打包成 Docker 镜像，就像把货物装进标准货柜
不管是在开发环境、测试环境还是生产环境，都能一致地运行

配置外部化就像换衣服：

通过 docker/.env 和 conf/service_conf.yaml 灵活配置
同一套代码可以适应不同的运行环境

健康检查就像体检：

每个服务都有健康检查接口，系统能及时发现问题
不健康的服务会被自动重启或替换

2.2 实际架构分析 - 基于 Docker Compose 的现代化部署

理解 RAGFlow 架构最直观的方式就是分析它的 Docker Compose 配置。就像看一份现代化建筑的设计图纸，这些文件定义了构成 RAGFlow 系统的所有服务容器以及它们之间的依赖关系。

2.2.1 容器化架构总览

通过分析实际的 docker-compose.yml 和 docker-compose-base.yml 文件，我们可以看到 RAGFlow 的完整部署架构：

2.2.2 主要服务组件详解

让我们深入了解每个服务组件，就像详细了解一座现代化图书馆的各个部门：

🚀 ragflow-server （API 网关与前端服务）

这就像图书馆的接待大厅和客服中心，是用户与 RAGFlow 系统交互的唯一入口。

核心职责：

处理所有 HTTP 请求和 WebSocket 实时连接
用户身份认证和权限管理
提供 RESTful API 服务
前端静态资源服务

实际配置（根据 docker-compose.yml）：


ragflow:
  image: ${
   
   RAGFLOW_IMAGE} # 使用环境变量指定镜像版本
  container_name: ragflow-server
  ports:
    - ${
   
   SVR_HTTP_PORT}:9380 # 主 HTTP 服务端口
    - 80:80 # 标准 HTTP 端口
    - 443:443 # HTTPS 端口
    - 9382:9382 # MCP 服务端口
  volumes:
    - ./ragflow-logs:/ragflow/logs # 日志目录
    - ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf # Nginx 配置
    - ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template

代码结构：

api/ragflow_server.py - 主入口文件
api/apps/ - 各业务模块 API 接口
web/ - React 前端用户界面

📊 MySQL 8.0.39 （主数据库）

就像图书馆的主要目录系统，存储所有关键的结构化数据。

存储内容：用户账户、知识库元数据、文档元数据、对话历史、系统配置

实际配置：


mysql:
  image: mysql:8.0.39
  command: --max_connections=1000 --character-set-server=utf8mb4
  environment:
    - MYSQL_ROOT_PASSWORD=${
   
   MYSQL_PASSWORD}
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]

🔍 Elasticsearch 8.11.0 （检索引擎）

就像图书馆的智能检索系统，能够快速找到相关内容。

存储内容：文档分块文本、文本向量嵌入、全文检索索引、语义相似性检索索引

🟥 Redis/Valkey 8 （缓存系统）

就像图书馆的快速借阅区，存放经常被访问的热门信息。

存储内容：用户会话状态、API 访问频率限制、暂时计算结果缓存、分布式锁和任务队列

📰 MinIO （对象存储）

就像图书馆的大型仓库，存放所有的实体文件和多媒体资料。

存储内容：原始文档文件、处理后的文本文件、图片和多媒体文件、备份和导出数据

2.2.3 数据流转分析 - 一份文档的奇妙之旅

想象一下，当你在图书馆上传一份 PDF 文档时，它会经历一段怎样的奇妙之旅呢？让我们跟随一份文档的完整流程：

这个流程就像一本书在图书馆的完整生命周期：从进馆登记、分类编目、上架存放，到最终被读者查找和阅读。每一步都经过精心设计，确保信息能够被准确理解和快速检索。

2.3 核心模块深度剥析 - 深入各个专业部门

现在让我们走进 RAGFlow 的各个“专业部门”，看看它们是如何各司其职的。

2.3.1 📄 DeepDoc 深度文档理解引擎

这就像图书馆的专业文档分析师，能够理解各种复杂文档的结构和内容。

模块位置：deepdoc/ 目录

核心能力：

解析器	支持格式	核心功能
PDF 解析器	PDF	OCR 文字识别、版面分析、表格提取
Word 解析器	DOCX/DOC	样式保持、内嵌对象处理
Excel 解析器	XLSX/XLS	表格结构解析、数据类型推断
PPT 解析器	PPTX/PPT	幻灯片内容提取、图文结合

智能分块策略：

语义分块：按照语义逻辑切分，保持内容的完整性
结构分块：基于文档结构（标题、段落、表格）进行切分
动态分块：根据内容复杂度动态调整分块大小

2.3.2 🔍 RAG 检索增强生成引擎

这就像图书馆的智能检索系统和知识顾问，能够精准找到相关信息并综合生成答案。

模块位置：rag/ 目录

检索策略组合：

多维度检索算法：

(1) 关键词全文检索：传统 BM25 算法，快速匹配关键词

(2) 语义向量检索：基于 Embedding 的语义相似性匹配

(3) 混合检索：结合多种算法，取优补短

(4) 重排序机制：使用专门的排序模型优化结果

2.3.3 🤖 RAG 的Agent 智能体系统

这就像图书馆的专业研究员，能够根据复杂问题设计研究方案，调用各种工具和资源。

模块位置：agent/ 目录

工作流组件：

组件类型	功能描述	应用场景
开始节点	工作流入口，接收用户输入	所有工作流
检索节点	从知识库检索相关信息	知识问答
生成节点	调用大模型生成内容	文本生成
工具节点	调用外部 API 和工具	信息查询
条件节点	根据条件判断流程走向	复杂逻辑

可集成工具：

搜索引擎：Google、必应、百度等
学术资源：arXiv、学术搜索等
知识库：维基百科、百度百科等
计算工具：代码执行、数学计算等

2.3.4 🌐 Web 前端用户界面

这就像图书馆的现代化用户终端，提供直观友好的操作界面。

模块位置：web/ 目录

技术栈：

框架：React 18 + UmiJS 4
状态管理：Redux Toolkit + React Query
UI 组件：Antd 5.x
样式方案：Tailwind CSS
类型检查：TypeScript

核心功能模块：

功能模块	主要页面	核心特性
知识库管理	知识库列表、创建、设置	文档上传、分块预览、状态监控
文档管理	文档列表、详情、编辑	批量上传、解析进度、错误处理
对话问答	聊天界面、历史记录	流式响应、引用源显示、多轮对话
Agent 工作流	可视化编辑器、调试	拖拽式设计、实时执行、日志查看
系统管理	用户管理、模型配置	角色权限、API 配置、监控看板