3 · 系统架构（System Architecture）

系统架构

系统架构

相关源文件

本章引用的主要源码文件：

• admin/server/admin_server.py
• api/apps/__init__.py
• api/db/__init__.py
• api/db/db_models.py
• api/db/init_data.py
• api/db/services/dialog_service.py
• api/db/services/document_service.py
• api/db/services/file_service.py
• api/db/services/knowledgebase_service.py
• api/db/services/llm_service.py
• api/db/services/task_service.py
• api/db/services/user_service.py
• api/ragflow_server.py
• api/settings.py
• api/utils/api_utils.py
• cmd/server_main.go
• conf/service_conf.yaml
• docker/service_conf.yaml.template
• internal/admin/heartbeat.go
• internal/binding/rag_analyzer.go
• internal/common/status_message.go
• internal/cpp/Makefile
• internal/handler/datasets.go
• internal/handler/document.go
• internal/service/document.go
• internal/service/heartbeat_sender.go
• internal/tokenizer/tokenizer.go
• rag/nlp/search.py
• rag/raptor.py
• rag/svr/task_executor.py
• rag/utils/redis_conn.py
• test/testcases/test_web_api/test_system_app/test_apps_init_unit.py

目的与范围

本文档深入介绍 RAGFlow 的分层架构，描述 API 网关、服务层、工作层和存储层如何协同工作，以实现基于文档的对话式 AI 能力。关于具体实现细节：

• 核心应用服务和请求路由：参见核心应用服务
• 存储层设计和数据库选型：参见数据存储架构
• 异步任务处理：参见任务执行与队列系统
• 智能体和工具组件加载：参见组件动态加载
• 基于 Go 的原生服务层：参见Go 服务器与原生组件

前端架构请参见前端应用。大语言模型（LLM）集成模式请参见大语言模型（LLM）集成系统。文档处理管线请参见文档处理管线。

概述

RAGFlow 采用五层微服务架构，将客户端交互、API 路由、业务逻辑、异步处理和持久化存储的关注点分离。系统设计支持水平扩展，无状态的 API 服务器和分布式工作进程通过 Redis 支持的消息队列进行通信。

该架构遵循以下原则：

• 关注点分离：API 服务器处理同步请求，工作进程处理长时间运行的任务。
• 可插拔组件：文档存储（Elasticsearch、Infinity、OceanBase 或 OpenSearch）、解析器和大语言模型（LLM）提供商均可通过配置进行切换 api/db/services/document_service.py:31-33。
• 多租户：所有数据通过 tenant_id 进行作用域隔离，在 BaseModel 中实现行级安全性和关系映射 api/db/db_models.py:152-185。
• 异步处理：文档解析、嵌入向量生成和知识图谱构建作为后台任务运行，由 task_executor 管理 rag/svr/task_executor.py:122-128。

来源：api/db/db_models.py:152-185、rag/svr/task_executor.py:103-120、api/db/services/document_service.py:41-72。

五层架构

系统组件图

下图展示了基于 Python 的服务、Redis 任务队列和多语言存储层之间的关系。

来源：rag/svr/task_executor.py:145-151、api/db/services/document_service.py:41-72、api/db/db_models.py:72-74、api/db/services/llm_service.py:85-118、api/utils/api_utils.py:153-176。

核心执行流程

文档上传与任务入库

该流程将用户的文档上传请求桥接到异步后台处理系统。

来源：api/db/services/document_service.py:41-72、rag/svr/task_executor.py:103-120、api/db/services/task_service.py:74-143、api/ragflow_server.py:53-70。

各层核心组件

第1层：客户端层

为用户和外部系统提供接口。

来源：api/utils/api_utils.py:153-176。

第2层：API 网关

RAGFlow 支持多种代理方案，以平衡功能完整性和性能。

• Python 服务器：基于 Quart 构建，通过 ragflow_server.py 处理复杂的业务逻辑和智能体编排 api/ragflow_server.py:151-153。
• Go 服务器：针对高吞吐量的原生操作进行优化，包括分词器和搜索逻辑 cmd/server_main.go:1-20。
• 认证：通过 @validate_request 和工具层中的安全装饰器进行管理 api/utils/api_utils.py:153-176。

第3层：服务层

使用 peewee ORM 封装业务逻辑和数据库交互。

• DocumentService：编排文档元数据、状态跟踪和健康检查 api/db/services/document_service.py:41-110。
• KnowledgebaseService：管理数据集配置和存储引擎映射 api/db/services/knowledgebase_service.py:31-35。
• LLMBundle：大语言模型（LLM）操作的统一接口，包括聊天、嵌入向量和重排序，支持 Langfuse 追踪 api/db/services/llm_service.py:85-118。
• DialogService：管理聊天会话、检索增强生成（RAG）检索参数和互联网搜索集成 api/db/services/dialog_service.py:98-150。

第4层：工作层

通过 Redis 异步处理资源密集型任务。

• task_executor.py：主要工作进程，使用消费者组 SVR_CONSUMER_GROUP_NAME 从 Redis Streams 消费任务 rag/svr/task_executor.py:93, 132-133。
• 解析器工厂：根据文档配置动态选择解析器（例如 ParserType.NAIVE、ParserType.PAPER）rag/svr/task_executor.py:103-120。
• 任务类型：支持多种管线，包括 dataflow、raptor、graphrag 和 memory rag/svr/task_executor.py:122-128。

第5层：存储层

RAGFlow 使用系统配置中定义的多语言持久化策略。

来源：api/db/db_models.py:152-185、rag/nlp/search.py:38-41、rag/svr/task_executor.py:103-120、api/db/services/document_service.py:114-123。