总览
概述
相关源文件
本章引用的主要源码文件：
.github/workflows/release.yml.github/workflows/tests.ymlDockerfileDockerfile.depsREADME.mdREADME_ar.mdREADME_fr.mdREADME_id.mdREADME_ja.mdREADME_ko.mdREADME_pt_br.mdREADME_tr.mdREADME_tzh.mdREADME_zh.mdadmin/server/admin_server.pyapi/apps/__init__.pyapi/db/init_data.pyapi/ragflow_server.pyapi/settings.pyapi/utils/api_utils.pyconf/service_conf.yamldocker/.envdocker/README.mddocker/docker-compose-base.ymldocker/infinity_conf.tomldocker/service_conf.yaml.templatedocs/guides/manage_files.mddocs/quickstart.mdxdownload_deps.pyhelm/values.yamlpyproject.tomlrag/utils/redis_conn.pysdk/python/pyproject.tomlsdk/python/uv.locktest/testcases/test_web_api/test_system_app/test_apps_init_unit.pyuv.lock
目的与范围
RAGFlow 是一个开源的检索增强生成（RAG）引擎，它有效地将深度文档理解与智能体工作流能力相结合。其主要目标是将复杂的非结构化数据转化为高保真、可投入生产的 AI 系统，并具备强大的上下文基础与可解释性。README.md:76-78
RAGFlow 的功能
RAGFlow 提供了一个可投入生产的平台，具备以下能力：
- 使用基于深度学习的先进解析器，解析 PDF、DOCX、Excel 和 PPT 等多种格式的复杂文档。
- 应用智能的、基于模板的片段切分策略，将文档分割为有意义的片段。
- 为文本片段生成嵌入向量，并使用混合向量与关键词搜索后端进行索引。
- 支持基于引用的对话交互，减少大语言模型（LLM）的幻觉问题。
- 包含名为 "Canvas" 的可视化智能体工作流构建器，支持构建具有持久化记忆的多步骤 AI 应用。
- 支持与多种文档引擎、大语言模型（LLM）提供方集成，并支持从多个异构数据源进行同步。
这种端到端的设计适用于任何规模的企业，通过利用深度文档布局分析、表格提取和丰富的多模态特性，专注于"输入质量决定输出质量"的理念。README.md:112-122，pyproject.toml:4-4
来源： README.md:76-122，pyproject.toml:4-4
系统架构
RAGFlow 采用模块化的、面向微服务的三层架构，支持可扩展性、容错性和异步任务处理。该架构通过主要由 Redis Streams 中介的任务队列，将面向用户的 API 操作与密集的文档处理工作负载分离开来。这种设计增强了响应能力，并支持并行处理大规模文档入库工作流。
高层架构图
该图展示了：
- 客户端层：Web UI、Python SDK 和 HTTP API 客户端与 Quart API 服务器交互。
- API 编排层：Python Quart 服务器处理客户端请求，并与大语言模型（LLM）捆绑包和文档服务集成。Go 服务器补充了高性能的原生组件，MCP 服务器管理模型上下文协议通信。
- 服务逻辑层：核心业务服务，管理用户、文档、对话和大语言模型（LLM）交互。
- 工作层：任务执行器处理异步任务，如文档解析、嵌入向量生成和索引，通过 Redis Streams 消费任务。
- 处理引擎：专用引擎，如用于文档布局分析的 DeepDoc vision、用于基于图的检索增强的 GraphRAG，以及用于安全代码执行的沙箱执行器。
- 存储层：多语言持久化，包括关系型数据库、文档/向量存储和用于原始文件的对象存储。
来源： README.md:141-145，docker/.env:140-146，api/utils/api_utils.py:45-51
三层架构详解
RAGFlow 的设计将职责划分为不同的层级：
| 层级 | 描述 | 关键组件 |
|---|---|---|
| 1. 前端/API 层 | 处理用户请求、前端交互和对话编排。使用支持流式传输、CORS（跨域资源共享）、认证和模式校验的 Quart 异步 HTTP 服务器。 | api/ragflow_server.py 中的 API 服务器（Quart）、Python SDK、React Web UI。支持与 Go 服务器的混合代理模式（docker/.env:158-159） |
| 2. 异步任务层 | 将计算密集型任务（如文档解析、嵌入向量生成和索引）与同步 API 处理解耦。任务被提交到 Redis Streams 队列，并由 TaskExecutor 工作进程处理（rag/svr/task_executor.py）。 | 用于任务队列的 Redis Streams、TaskExecutor 工作进程、DeepDoc vision 引擎、GraphRAG、沙箱执行器。 |
| 3. 持久化层 | 使用适合不同类型数据的存储引擎：元数据、文档、向量、原始文件。 | 关系型数据库管理系统：通过 peewee ORM 使用的 MySQL/PostgreSQL（api/db/db_models.py）；文档存储：Elasticsearch、Infinity、OpenSearch、OceanBase；用于对象存储的 MinIO。 |
这种清晰的职责分离确保了高可用性，隔离了资源密集型操作，并支持每个层级独立扩展。
来源： pyproject.toml:5-8，docker/.env:13-159，README.md:134-139
核心组件与服务
自然语言概念到代码实体的映射
下图将 RAGFlow 的关键领域概念桥接到内部代码实体和包：
这突出了领域概念与代码子系统之间的对应关系，指导开发者更高效地浏览代码库。
来源： api/utils/api_utils.py:45-51，common/mcp_tool_call_conn.py:40-80，rag/svr/task_executor.py:1-80
应用入口点
| 组件 | 文件路径 | 描述 |
|---|---|---|
| Python API 服务器 | api/ragflow_server.py | 基于 Quart 的主要 HTTP RESTful API 服务器，处理客户端 API 调用并支持流式聊天。 |
| Go 服务器 | cmd/server_main.go | 实现高性能服务层和原生组件。以更低延迟处理搜索和用户服务。 |
| 管理服务 | admin/server/admin_server.py | 提供运维和监控接口的管理后台。 |
| MCP 服务器 | mcp/server/server.py | 实现模型上下文协议服务器，用于智能体工作流和工具集成。 |
来源： api/utils/api_utils.py:45-50，.github/workflows/tests.yml:132-139
关键特性
- 深度文档理解：应用深度学习模型，使用 DeepDoc vision 模块解析和理解复杂的文档布局，包括表格、文本段和图像。
Dockerfile:10-16，README.md:114-118 - 基于模板的片段切分：针对文档类型定制的多种片段切分模板，实现智能且可解释的文本切片。
README.md:120-124 - 基于引用的回答与减少幻觉：带有参考可视化与可追溯性的上下文答案。
README.md:125-129 - 多源兼容性：支持多种数据格式（Word、PowerPoint、Excel、图像、扫描文档、结构化数据、网页）。
README.md:130-133 - 自动化 RAG 工作流：完全编排的入库管线和嵌入向量工作流，可配置的大语言模型（LLM）和检索器模型，支持多召回与融合重排序。
README.md:134-140 - 智能体工作流与记忆：用于构建 AI 智能体的可视化工作流系统，支持多步骤推理、工具使用和持久化智能体记忆。
README.md:92-98 - 安全的代码执行：基于 gVisor 的沙箱化 Python/JS 代码执行环境，用于安全执行智能体组件。
README.md:155
来源： README.md:89-140，docker/.env:13-159，docs/quickstart.mdx:34-34
技术栈
后端
| 技术 | 用途 | 位置/参考 |
|---|---|---|
| Python >= 3.13 | 主要后端语言 | 代码库顶层 |
| Go | 高性能服务器层 | cmd/server_main.go |
| C++ | 原生分词器与组件 | internal/cpp（此处未完全列出） |
| Quart | 异步 HTTP 服务器框架 | api/ragflow_server.py |
| Peewee ORM | 关系型数据库 ORM | api/db/db_models.py |
| Redis（通过 Valkey） | 任务队列、缓存 | rag/utils/redis_conn.py |
| Elasticsearch / Infinity / OpenSearch / OceanBase | 文档向量存储 | 通过 docker/.env 配置，集成在 DocStore 相关模块中。 |
| MinIO | 原始文档和图像的对象存储 | 在 Docker 配置和任务执行器的使用中可见 |
前端
| 技术 | 用途 |
|---|---|
| React + Vite | Web UI 框架与构建 |
| 国际化（i18n） | 支持 10 种以上语言 |
来源： pyproject.toml:1-160，uv.lock:1-10，README.md:1-140
数据流：从文档到知识
以下步骤描述了从入库到查询响应的典型数据生命周期：
- 数据入库
- 用户上传的文件或从外部数据源（如 Confluence、Google Drive、Notion、Discord 和 S3）同步的文件。
README.md:94-94
- 用户上传的文件或从外部数据源（如 Confluence、Google Drive、Notion、Discord 和 S3）同步的文件。
- 对象存储
- 原始文件存储在 MinIO 对象存储中。元数据在关系型数据库中跟踪。
docker/.env:125-138
- 原始文件存储在 MinIO 对象存储中。元数据在关系型数据库中跟踪。
- 文档解析
- DeepDoc vision 模型分析文档布局，提取文本、表格、图像和结构。系统支持各种文档格式和扫描文档的 OCR。
Dockerfile:11-16
- DeepDoc vision 模型分析文档布局，提取文本、表格、图像和结构。系统支持各种文档格式和扫描文档的 OCR。
- 片段切分与嵌入向量生成
- 通过智能片段切分模板对文档进行分割。片段由配置的嵌入向量模型（大语言模型（LLM）或模型提供方）转换为嵌入向量。
README.md:120-124
- 通过智能片段切分模板对文档进行分割。片段由配置的嵌入向量模型（大语言模型（LLM）或模型提供方）转换为嵌入向量。
- 索引
- 嵌入向量和关键词数据存储在文档/向量存储中，如 Elasticsearch、Infinity 或 OceanBase。
docker/.env:13-20
- 嵌入向量和关键词数据存储在文档/向量存储中，如 Elasticsearch、Infinity 或 OceanBase。
- 检索与重排序
- 查询处理应用混合搜索（向量相似度 + BM25）和重排序，以返回有依据且相关的内容。
README.md:138-138
- 查询处理应用混合搜索（向量相似度 + BM25）和重排序，以返回有依据且相关的内容。
该管线异步编排，以最大化 API 响应能力和可扩展性。
来源： README.md:94-138，docker/.env:13-138，Dockerfile:11-16
总结
RAGFlow 是一个全面的、生产级的 RAG 引擎，采用清晰的模块化架构设计，将深度文档理解、多模态解析、嵌入向量生成和 AI 智能体工作流集成在一个可扩展的三层微服务结构中。其架构通过任务队列和后台工作进程，同时处理同步 API 交互和异步、计算密集型的文档入库与知识处理任务。该系统灵活且可扩展，支持多种存储后端、大语言模型（LLM）提供方和文档类型。生态系统包括强大的原生组件（Go 服务器、C++ 分词器），补充了其 Python 核心服务。
来源： 所有提供的源文件，主要见解来自 README.md:76-145，docker/.env:13-159，api/utils/api_utils.py:1-200，pyproject.toml:1-160，Dockerfile:1-130，.github/workflows/tests.yml:132-139