RAGFlow 后端技术架构分析

系统架构总览
Go 后端：服务入口与三层架构
Go 后端：Handler / Service / DAO
Go 后端：基础设施层
Python 后端：API 层
Python 后端：RAG 核心引擎
Python 后端：NLP 与检索
Python 后端：DeepDoc 文档解析
Python 后端：知识图谱与 RAPTOR
Python 后端：Agent 系统
Python 后端：记忆系统
Python 后端：MCP 集成
Python 后端：LLM 集成
核心数据流：文档解析
核心数据流：对话检索
核心数据流：Agent 执行
核心设计模式

1 系统架构总览

RAGFlow 采用 Python 后端 + Go 微服务的混合架构，Python 负责 RAG 核心（解析/分块/向量化/检索/对话/Agent），Go 负责 API 网关/任务调度/数据持久化。

┌──────────────────────────────────────────────────────────────────────┐ │ Go API Server (Gin :9384) │ │ Router → AuthMiddleware → Handler → Service → DAO → MySQL(GORM) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌─────────┐ │ │ │ User │ │ Document │ │ Chat │ │ Dataset │ │ LLM │ │ │ │ Tenant │ │ Chunk │ │ Session │ │ Search │ │ Provider│ │ │ │ File │ │ KB │ │ Memory │ │ Connector │ │ System │ │ │ └──────────┘ └──────────┘ └──────────┘ └───────────┘ └─────────┘ │ └──────────────────────────┬──────────────────────────────────────────┘ │ gRPC / HTTP ┌──────────────────────────┼──────────────────────────────────────────┐ │ Go Admin Server (:9383 + :9385 gRPC) │ │ Admin Handler → Admin Service → 16 DAOs │ │ Ingestion Manager (gRPC 双向流) ← Ingestion Workers │ └──────────────────────────┬──────────────────────────────────────────┘ │ Redis Stream ┌──────────────────────────┼──────────────────────────────────────────┐ │ Python RAG Engine (Quart) │ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ │ │ TaskExecutor │ │ DeepDoc │ │ Agent Canvas │ │ │ │ 文档解析 │ │ OCR+布局识别 │ │ DSL 工作流引擎 │ │ │ │ 分块/嵌入 │ │ 表格提取 │ │ 20+ 组件 / 20+ 工具 │ │ │ └──────┬──────┘ └──────┬───────┘ └───────────┬────────────┘ │ │ │ │ │ │ │ ┌──────▼────────────────▼───────────────────────▼────────────┐ │ │ │ NLP + 检索 (混合检索引擎) │ │ │ │ FulltextQueryer → Dealer → 向量+全文+RRF融合+Rerank │ │ │ │ KGSearch → 实体检索 → N-hop关系扩展 → 融合 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ GraphRAG │ │ RAPTOR │ │ Memory │ │ │ │ 实体/关系提取 │ │ 层次摘要 │ │ 四类记忆 │ │ │ │ 社区检测 │ │ GMM/AHC聚类 │ │ 遗忘策略 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └──────────────────────────────────────────────────────────────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ ES/Infinity │ │ MinIO/S3 │ │ Redis │ │ 向量+全文 │ │ 对象存储 │ │ 缓存+队列+锁 │ └──────────────┘ └──────────────┘ └──────────────┘

2 Go 后端：服务入口与三层架构 GO

三个独立可执行服务 + 一个 CLI 工具，采用 Handler → Service → DAO 三层架构。

server_main.go — API 主服务器

端口：9384（Gin HTTP）
启动流程：配置加载 → DB初始化(GORM, 30+表自动迁移) → LLM工厂导入 → DocEngine初始化(ES/Infinity) → Redis → Storage → 分词器 → 17个Service/Handler → Router → 心跳上报
优雅关闭：监听 SIGINT/SIGTERM/SIGQUIT

admin_server.go — 管理服务器

HTTP 端口：9383（Admin REST API）
gRPC 端口：9385（Ingestion Manager）
职责：用户管理、角色权限、服务监控、摄入任务调度
Ingestion Manager：gRPC 双向流，管理 Ingestor 节点注册与任务分配

ingestion_server.go — 摄入工作节点

通信：gRPC 双向流与 Admin 通信
核心结构：Ingestor — Connect → receiveLoop + heartbeatLoop + workerLoop
任务生命周期：QUEUED → RUNNING → COMPLETED/FAILED/CANCELED
重连机制：指数退避（1s → 30s）
心跳：每 5 秒发送（含任务状态、CPU/内存）

三层架构总览

Handler：Gin HTTP 处理，请求解析 + 响应格式化
Service：业务逻辑，编排 DAO + DocEngine + 缓存
DAO：GORM 数据访问，30+ 实体表 CRUD
统一响应：gin.H{"code":..., "data":..., "message":...}

3 Go 后端：Handler / Service / DAO GO

认证中间件 (AuthHandler)

AccessToken 验证：itsdangerous URLSafeTimedSerializer 签名验证（兼容 Python）
APIToken 验证：ragflow- 前缀的 Base64 Token
超级用户隔离：超级用户禁止访问普通 API
密码安全：RSA 公钥加密传输 + PBKDF2-SHA256 存储（兼容 Werkzeug）
上下文注入：user / user_id / email 注入 Gin Context

核心 Handler / Service / DAO 清单

领域	Handler	Service	DAO
用户	UserHandler	UserService	UserDAO
租户	TenantHandler	TenantService	TenantDAO, UserTenantDAO
文档	DocumentHandler	DocumentService	DocumentDAO
分块	ChunkHandler	ChunkService	DocEngine
知识库	KBHandler / DatasetsHandler	KBService / DatasetService	KbDAO
对话	ChatHandler / ChatSessionHandler	ChatService / ChatSessionService	ChatDAO, ChatSessionDAO
LLM	LLMHandler / ProvidersHandler	LLMService / ModelProviderService	LLMDAO, TenantLLMDAO
搜索	SearchHandler	SearchService	SearchDAO
文件	FileHandler	FileService	FileDAO
记忆	MemoryHandler	MemoryService	MemoryDAO
连接器	ConnectorHandler	ConnectorService	ConnectorDAO
系统	SystemHandler	SystemService	APITokenDAO

核心实体模型 (Entity)

实体	表名	关键字段
User	user	AccessToken, Email, Password(PBKDF2), IsActive, IsSuperuser, RoleID
Tenant	tenant	LLMID, EmbdID, ASRID, RerankID, ParserIDs, Credit
Knowledgebase	knowledgebase	TenantID, EmbdID, ParserID, SimilarityThreshold, VectorSimilarityWeight
Document	document	KbID, ParserID, TokenNum, ChunkNum, Progress, Status
Chat (Dialog)	dialog	LLMID, LLMSetting, PromptConfig, KBIDs, SimilarityThreshold
ChatSession	conversation	DialogID, Message(json), Reference(json)
TenantLLM	tenant_llm	TenantID, LLMFactory, APIKey, APIBase, MaxTokens, UsedTokens
File	file	ParentID, TenantID, Name, Type, Location
APIToken	api_token	TenantID, Token, DialogID, Source
Memory	memory	TenantID, MemoryType, StorageType, EmbdID, LLMID

4 Go 后端：基础设施层 GO

DocEngine 接口

可插拔引擎：Elasticsearch / Infinity
CreateChunkStore / InsertChunks / Search
CreateMetadataStore / InsertMetadata
IndexDocument / DeleteDocument / BulkIndex
单例模式，根据配置创建

Storage 接口

工厂模式：MinIO / AWS S3 / 阿里云 OSS
Put / Get / Remove / ObjExist
GetPresignedURL / BucketExists
Copy / Move 跨桶操作
运行时切换，线程安全

Redis 缓存

分布式锁：SetNX + Lua 脚本，SpinAcquire
令牌桶限流：Lua 脚本实现
Stream 消息队列：XAdd/XReadGroup
自增 ID：分布式 ID 生成器
原子操作：GetOrCreateKey / DeleteIfEqual

配置管理 (Viper)

service_conf.yaml 加载
环境变量覆盖（DOC_ENGINE, STORAGE_IMPL, DB_TYPE 等）
兼容 Python 配置格式
运行时变量：SecretKey 等，Redis 存储 + VariableWatcher 定期刷新

模型提供商管理

ProviderManager：从 conf/models/ 加载 50+ JSON 配置
Provider → Model → Features 多级结构
Features：多模态、推理能力（simple/budget/effort）
ModelDriver 接口：可插拔模型驱动

5 Python 后端：API 层 PY

ragflow_server.py — API 入口

框架：Quart（异步 Flask）
启动流程：init_settings() → init_web_db() → RuntimeConfig → GlobalPluginManager.load_plugins() → 后台线程(update_progress, Redis分布式锁) → Quart HTTP
20+ RESTful API 模块：chat / document / chunk / dataset / openai / agent / search / mcp / memory / connector / file / system / tenant / user / langfuse / bot / dify / plugin / stats / task

数据模型 (Peewee ORM)

支持 MySQL / PostgreSQL / OceanBase
RetryingPooledMySQLDatabase 自动重试连接池
MysqlDatabaseLock / PostgresDatabaseLock 分布式锁
migrate_db() 自动迁移
20+ ORM 模型：User, Tenant, Knowledgebase, Document, Task, Dialog, Conversation, UserCanvas, MCPServer, Memory, Search, Connector 等

数据服务层

每个模型对应一个 Service 类
LLMBundle：LLM 调用核心封装（租户模型配置 + Token 计费 + 异步调用）
联合服务：tenant_model_service / user_account_service / memory_message_service
API 服务：canvas_replica / dataset / document / file / memory

6 Python 后端：RAG 核心引擎 PY

13 种专用文档解析器 (rag/app/)

解析器	适用场景	核心特点
naive	通用文档	支持 PDF/DOCX/TXT/MD/HTML/Excel/EPUB/JSON，7 种 PDF 引擎（DeepDOC/MinerU/Docling/PaddleOCR/TCADP/OpenDataLoader/VisionParser）
book	书籍	按章节分块
laws	法律文件	按条款分块
paper	学术论文	结构化提取
manual	技术手册	按章节+表格
qa	Q&A 格式	问答对提取
table	表格数据	表格结构化
resume	简历	LLM 驱动字段提取
presentation	PPT	幻灯片解析
picture	图片	Vision LLM 描述
one	整文档	单块输出
audio	音频	ASR 转文字
email	邮件	邮件结构解析

TaskExecutor — 文档解析核心引擎

任务队列：Redis Stream 消费者组模式，支持多消费者并行
并发控制：LoopLocalSemaphore（任务/分块/嵌入/MinIO/知识图谱五级信号量）
任务类型：dataflow(Pipeline) / raptor(层次摘要) / graphrag(知识图谱) / mindmap / memory(记忆保存) / 默认(标准解析)

# 标准解析流程
do_handle_task():
绑定 Embedding 模型，获取向量维度
init_kb() - 初始化知识库索引
build_chunks() - 调用对应解析器分块
embedding() - 批量向量化（标题权重混合）
insert_chunks() - 插入 ES/Infinity
更新文档统计（分块数、Token 数）

7 Python 后端：NLP 与检索 PY

中文分词器 (rag_tokenizer.py)

基于 C++ 扩展的高性能分词
繁简转换、全角半角
细粒度分词
Go 端同步实现：rag_analyzer

FulltextQueryer (query.py)

全文检索查询构建器
中英文混合查询处理
同义词扩展（Redis/WordNet）
词权重计算（TF-IDF 变体）
输出 MatchTextExpr

Dealer — 混合检索引擎 (search.py)

向量检索：MatchDenseExpr，Embedding 相似度搜索
全文检索：MatchTextExpr，BM25/TF-IDF 关键词匹配
RRF 融合：Reciprocal Rank Fusion，合并向量和全文检索结果
Rerank 重排：可选的 Cross-Encoder 精排
结果过滤：已删除文档排除、相似度阈值过滤

# 检索核心流程
FulltextQueryer.question() → MatchTextExpr    # 全文查询
Dealer.get_vector()        → MatchDenseExpr   # 向量查询
dataStore.search()         → 混合检索          # 向量+全文+RRF
→ 结果过滤 → 可选 Rerank → 返回

8 Python 后端：DeepDoc 文档解析 PY

RAGFlowPdfParser — PDF 解析核心

OCR：PaddleOCR / Tesseract
布局识别：XGBoost 分类 + ONNX 模型推理
表格检测：表格结构识别
文本合并：智能段落合并
图表提取：Vision LLM 驱动图表描述

多引擎支持

DeepDOC（默认）：自研 OCR + 布局识别
MinerU：开源 PDF 解析引擎
Docling：IBM 开源文档解析
PaddleOCR：百度 OCR 引擎
TCADP：腾讯云文档解析
OpenDataLoader：开放数据加载器
VisionParser：视觉模型驱动解析

9 Python 后端：知识图谱与 RAPTOR PY

GraphRAG — 三级提取器

GeneralKGExt：完整知识图谱（实体+关系+社区）
LightKGExt：轻量级知识图谱
NerKGExt：命名实体识别

# General GraphRAG 流程
分批读取文档分块
→ GraphExtractor 提取实体和关系 (LLM)
→ 构建子图 (NetworkX)
→ graph_merge 合并子图
→ 可选 EntityResolution (编辑距离+LLM)
→ 可选 CommunityReportsExtractor (Leiden)
→ 向量化实体/关系 → 存入文档存储

RAPTOR — 层次摘要

经典策略：UMAP 降维 → GMM/AHC 聚类 → LLM 摘要 → 逐层构建
Psi 策略：余弦相似度排序 → 并查集合并树 → 分桶 → 自底向上摘要
聚类方法：GMM（BIC 选择最优 K）/ AHC（Ward + 树状图间隙）
数据结构：_PsiTreeNode + _PsiUnionFind

KGSearch — 知识图谱检索

继承 Dealer，增加图谱检索能力
query_rewrite()：查询改写（提取实体类型关键词）
实体检索 → N-hop 关系扩展 → 关系检索
与向量检索结果融合

10 Python 后端：Agent 系统 PY

Canvas — DSL 工作流引擎

DSL：JSON 格式工作流定义，包含组件、连接、全局变量
组件图：有向无环图（DAG），节点是组件，边是数据流
全局变量：sys.query / sys.user_id / sys.conversation_turns / sys.files / sys.history / sys.date
变量引用：{component_id@output_key} / {sys.query} / {env.var_name}

# Canvas.run() 执行流程
加载 DSL → 初始化组件实例
→ 设置全局变量 (query, user_id, files)
→ 按路径顺序执行组件 (_run_batch 并行同层)
→ Message 组件流式输出 + TTS
→ Categorize/Switch 分支路由
→ Iteration/Loop 循环
→ 支持任务取消 (Redis 标记)
→ 支持用户交互 (UserFillUp 暂停等待)

组件清单

Begin — 开始节点（对话/Webhook）
LLM — LLM 调用（System Prompt + 参数 + 引用 + 结构化输出）
Message — 消息输出（含 TTS）
Categorize — 分类路由
Switch — 条件分支
Iteration / Loop — 循环迭代
ExitLoop — 退出循环
FillUp — 用户输入表单
Invoke — 外部调用
Browser — 浏览器操作

20+ 内置工具

检索：retrieval (知识库检索)
搜索：Google / DuckDuckGo / Tavily / SearXNG / Wikipedia
学术：ArXiv / PubMed / Google Scholar
金融：AKShare / Tushare / 问财 / Yahoo Finance / 金十
开发：GitHub / Code Exec (沙箱)
数据：ExeSQL / Crawler
其他：DeepL 翻译 / 和风天气 / Email

沙箱执行环境

local — 本地 Docker 容器
e2b — E2B 云沙箱
aliyun_codeinterpreter — 阿里云代码解释器
ssh — SSH 远程执行
self_managed — 自管理沙箱

11 Python 后端：记忆系统 PY

四类记忆（位掩码）

bit 0 (1) = Raw — 原始消息
bit 1 (2) = Semantic — 语义知识（通用事实、定义、概念）
bit 2 (4) = Episodic — 情景知识（具体经历、事件）
bit 3 (8) = Procedural — 程序知识（流程、方法、步骤）

记忆服务

MessageService：ES/Infinity/OceanBase 存储消息
PromptAssembler：LLM 驱动记忆提取
FIFO 遗忘策略：pick_messages_to_delete_by_fifo
MsgTextQuery：中英文混合查询 + 同义词扩展
索引：memory_{uid}

12 Python 后端：MCP 集成 PY

MCP Server

暴露工具：ragflow_retrieval（支持 dataset_ids/document_ids/question/similarity_threshold）
传输协议：SSE (/sse) + Streamable HTTP (/mcp)
启动模式：self-host（单租户）/ host（多租户）
认证：AuthMiddleware，Bearer Token / API Key，OAuth 2.1

MCP Client

SSE 连接 MCP Server
调用 ragflow_retrieval 工具
MCPToolBinding：Agent 工具绑定
MCPToolCallSession：工具调用会话

13 Python 后端：LLM 集成 PY

6 种模型类型

Chat — 对话模型（OpenAI/LiteLLM/ReAct/Function Call）
Embedding — 嵌入模型（查询/文档编码分离）
Rerank — 重排模型（Jina/本地）
CV — 图像理解
OCR — 光学字符识别
TTS — 语音合成

LLMBundle

LLM 调用核心封装
租户模型配置管理
Token 计费追踪
异步调用支持
模型族策略（Qwen3/GPT-5/Kimi-K2.5 等）

FunctionToolSession

支持 Function Call 模式
支持 ReAct 模式
工具元数据自动生成 OpenAI 格式
50+ 模型提供商 JSON 配置

14 核心数据流：文档解析 GO+PY

文档上传 — Go API Server

DocumentHandler 接收上传 → FileService 存储（MinIO/S3/OSS）→ DocumentDAO 创建记录 → TaskDAO 创建解析任务

Gin Handler GORM MinIO

任务分发 — Redis Stream

Go 端写入 Redis Stream → Python TaskExecutor 消费者组读取 → LoopLocalSemaphore 并发控制

Redis Stream Consumer Group

文档解析 — DeepDoc

按文件类型选择解析器 → OCR + 布局识别(XGBoost/ONNX) + 表格提取 → 输出 sections + tables

DeepDoc PaddleOCR XGBoost

分块与 Token 化

naive_merge 分块 → tokenize_chunks 生成 token 化结果 → rag_tokenizer 中文分词

naive_merge rag_tokenizer

向量化与索引

Embedding 模型批量向量化（标题权重混合）→ insert_chunks 插入 ES/Infinity → 更新文档统计

Embedding ES/Infinity

可选后处理

GraphRAG（实体/关系提取 + 社区检测）/ RAPTOR（层次摘要）/ 记忆保存

GraphRAG RAPTOR Memory

15 核心数据流：对话检索 GO+PY

用户提问 — Go API / Python API

ChatHandler / chat_api 接收问题 → 加载 Dialog 配置（LLM 设置、Prompt、相似度阈值、知识库列表）

查询构建 — FulltextQueryer

中文分词（rag_tokenizer）→ 同义词扩展（Redis/WordNet）→ 词权重计算（TF-IDF）→ MatchTextExpr

混合检索 — Dealer

向量检索（MatchDenseExpr）+ 全文检索（MatchTextExpr）→ RRF 融合 → 结果过滤 → 可选 Rerank

可选知识图谱检索 — KGSearch

query_rewrite 查询改写 → 实体检索 → N-hop 关系扩展 → 与向量检索结果融合

LLM 生成回答

检索结果 + Prompt 模板 → LLM 生成回答（含引用标注）→ 流式输出 → 保存会话历史

16 核心数据流：Agent 执行 PY

加载 DSL — Canvas

从 UserCanvas 读取 DSL JSON → 初始化组件实例 → 设置全局变量（query, user_id, files）

组件执行 — DAG 遍历

Begin → LLM/Retrieval/Tool → Categorize/Switch 分支 → Message 输出 → _run_batch 并行同层组件

工具调用 — 20+ 内置工具 + MCP

LLM 生成 tool_calls → LLMToolPluginCallSession 执行 → retrieval/Google/Code Exec/ExeSQL 等 → MCP 工具

流式输出 + 记忆

Message 组件流式输出 + TTS → 记录历史/引用 → 可选记忆保存（LLM 提取 → 分类存储 → 遗忘策略）

17 核心设计模式

🔀 双语言混合架构

Go 负责 API 网关/认证/持久化/任务调度（高性能），Python 负责 RAG 核心/解析/检索/Agent（生态丰富）。通过 Redis Stream 和共享数据库协作，Token 签名/密码格式兼容 Python。

🔌 可插拔引擎

DocEngine 接口（ES/Infinity）、Storage 接口（MinIO/S3/OSS）、PDF 解析引擎（7种）、沙箱执行器（5种），工厂模式统一创建，运行时可切换。

📊 混合检索融合

向量检索 + 全文检索 + RRF 融合 + 可选 Rerank + 知识图谱检索。Dealer 统一编排多种检索策略，结果去重融合。

🏗️ 三层架构

Go 端 Handler → Service → DAO 严格分层，每个领域独立封装。Python 端 API → Service → DB Service 对应分层。

📝 DSL 驱动工作流

Agent Canvas 基于 JSON DSL 定义工作流，DAG 拓扑执行，组件间变量引用传递，支持分支/循环/迭代/工具调用。

🔒 多租户隔离

TenantID 贯穿所有数据模型，UserTenant 多对多关系。模型配置、Token 用量、文件存储均按租户隔离。

📡 分布式任务

Redis Stream 消费者组任务队列，LoopLocalSemaphore 多级并发控制，Ingestion Worker gRPC 双向流注册，心跳监控 + 指数退避重连。

🧠 多级知识增强

基础分块 → RAPTOR 层次摘要 → GraphRAG 知识图谱 → 记忆系统，四级知识增强层层递进，按需启用。

RAGFlow

目录