[AI/RAG/源码解读] 源码深度解读报告之RAGFlow(知识库引擎)

📖 RAGFlow 源码深度解读报告

项目: infiniflow/ragflow
版本: v0.27.0（detached HEAD @ tag v0.27.0）
分析日期: 2026-08-25
源码路径: H:\Github\ragflow
分析方法: Git Repo Reader 五维阅读法

序

  • 定位：InfiniFlow 出品的开源 RAG 引擎，Apache 2.0，核心壁垒是 DeepDoc（OCR + 版面识别 + 表格结构识别）
  • 架构：Python（Quart API + RAG + DeepDoc）+ Go（Gin 后端，2188 文件，正从 Python 迁移中）双语言协同，React 前端
  • 核心模块：RAG 核心（检索 / 分块 / LLM 抽象）、Agent DAG 编排引擎（25 组件 + 26 工具）、DeepDoc 文档理解、GraphRAG、MCP 协议服务
  • 基础设施：MySQL + Redis/Valkey + MinIO + Elasticsearch/Infinity + NATS + 代码沙箱
  • 依赖：Python 180+ 依赖（LiteLLM 统一接入 100+ 模型），Go 75+ 直接依赖，重量级项目
  • 最低配置：4 核 CPU / 16GB RAM / 50GB 磁盘 / Python 3.13

Step 1: 定位（README）

项目简述

  • RAGFlow 是由 InfiniFlow 团队开发的开源检索增强生成（RAG）引擎，融合深度文档理解（DeepDoc）与 Agent 能力，为大语言模型构建高质量上下文层，提供适用于企业级的端到端 RAG 工作流。

解决的核心痛点

痛点 RAGFlow 的解法
非结构化文档解析困难（PDF/扫描件/复杂排版） DeepDoc 引擎：OCR + 版面识别 + 表格结构识别（TSR）
RAG 检索质量低、幻觉多 模板化分块 + 多路召回 + 融合重排序 + 可追溯引用
企业数据格式异构 支持 Word/Slides/Excel/TXT/图片/扫描件/结构化数据/网页
Agent 与 RAG 割裂 内置 Agent 工作流引擎 + 预构建模板 + MCP 协议支持
部署复杂 Docker Compose 一键部署，支持 CPU/GPU 双模式

与竞品的差异化

  • vs Dify / FastGPT: RAGFlow 更聚焦于深度文档理解和检索质量，DeepDoc 是其核心壁垒
  • vs LlamaIndex / LangChain: RAGFlow 是开箱即用的完整产品（含前端、API、文档管理），而非原始的开发框架
  • vs 纯向量数据库: RAGFlow 提供从文档摄入 → 解析 → 分块 → 嵌入 → 检索 → 生成的全链路

项目成熟度

  • 许可证: Apache 2.0（商用友好）
  • 最新版本: v0.27.0
  • Docker Pulls: 官方徽章显示持续增长
  • 最近更新: 2026-06-15（支持飞书/Discord/TG/Line 多聊天渠道）
  • 社区: Discord、X(Twitter)、GitHub Discussions
  • 云服务: cloud.ragflow.io 提供托管版

关键更新时间线（v0.27.0 前后）

日期 特性
2026-06-15 支持飞书、Discord、TG、Line 等多聊天渠道
2026-04-24 支持 DeepSeek v4
2026-03-24 OpenClaw 官方 Skill
2025-12-26 Agent Memory 记忆能力
2025-11-12 Confluence/S3/Notion/Discord/Google Drive 数据同步
2025-10-23 MinerU & Docling 文档解析
2025-10-15 可编排摄入管道（orchestrable ingestion pipeline）
2025-08-01 Agentic Workflow + MCP 协议
2025-05-23 Agent 代码执行器（Python/JavaScript）

Step 2: 用法（Examples / 典型调用链）

典型使用流程

RAGFlow 作为完整产品，典型使用链路为：

1. 注册/登录 → 创建知识库（Dataset）
2. 上传文档 → 自动解析（DeepDoc）→ 分块 → 嵌入 → 入库
3. 配置 LLM + Embedding 模型 + 检索参数
4. 创建对话助手（Assistant）/ Agent 工作流
5. 提问 → 检索 → 重排序 → LLM 生成 → 返回带引用的答案

API 调用方式

RAGFlow 提供 RESTful API（/api/v1/），核心接口包括：

  • 知识库管理: /api/v1/dataset（创建/列表/删除）
  • 文档上传: /api/v1/dataset/{id}/documents（上传 + 触发解析）
  • 文档管理: /api/v1/dataset/{id}/documents/{doc_id}（解析状态/分块查看）
  • 检索: /api/v1/retrieval（纯检索，不生成）
  • 对话: /api/v1/conversation（创建会话）+ /api/v1/completion（流式问答）
  • Agent: /api/v1/agent（Agent 工作流执行）

Python SDK

项目提供 sdk/python/ragflow_sdk，封装了上述 API 调用。典型代码：

from ragflow_sdk import RAGFlow

# 初始化客户端
client = RAGFlow(api_key="your_api_key", base_url="http://localhost:9380")

# 创建知识库
dataset = client.create_dataset(name="my_kb", embedding_model="BAAI/bge-large-zh-v1.5")

# 上传文档
with open("document.pdf", "rb") as f:
    doc = dataset.upload_documents(f)

# 等待解析完成后检索
results = dataset.retrieval(query="什么是RAG？", top_k=5)

# 创建对话并提问
conversation = client.create_conversation(agent_id="your_agent_id")
answer = conversation.chat(message="基于知识库回答问题")

Agent 工作流（可视化编排）

RAGFlow 的 Agent 采用组件化 DAG（有向无环图）架构，用户可通过前端画布拖拽编排：

[开始] → [分类] → [检索] → [LLM] → [结束]
                  ↓
              [代码执行] → [LLM]

核心组件（agent/component/）：

  • begin.py / iteration.py / loop.py — 控制流
  • llm.py — LLM 调用
  • invoke.py — 工具调用
  • retrieval.py（在 tools 中）— 知识库检索
  • code_exec.py — 代码执行（沙箱）
  • categorize.py / switch.py — 条件分支
  • variable_aggregator.py / variable_assigner.py — 变量操作
  • message.py — 消息处理
  • browser.py — 浏览器自动化

内置工具集（agent/tools/）

类别 工具
搜索 duckduckgo, google, tavily, searxng, wikipedia, googlescholar
学术 arxiv, pubmed
金融 akshare, tushare, yahoofinance, jin10, wencai
代码 code_exec（Python/JS 沙箱执行）
网页 crawler, browser
翻译 deepl
邮件 email
数据库 exesql
GitHub github
天气 qweather
知识库检索 retrieval

Step 3: 入口（CLI / Server）

双语言架构入口

  • RAGFlow v0.27.0 采用 Python + Go 双后端架构，正处于从 Python 向 Go 迁移的过程中：

Python 入口：api/ragflow_server.py

Python 入口：ragflow\api\ragflow_server.py

Python 版本要求： 3.13.x（不能低于，也不能高于）

启动流程:
1. init_root_logger()          — 初始化日志
2. settings.init_settings()    — 加载配置（service_conf.yaml）
3. init_web_db()               — 初始化 MySQL 表结构（peewee ORM）
4. init_web_data()             — 初始化基础数据
5. RuntimeConfig.init_env()    — 运行时环境配置
6. GlobalPluginManager.load_plugins() — 加载插件
7. 启动后台线程:
   - update_progress()         — 文档解析进度更新（Redis 分布式锁）
   - start_channel_server()    — 多聊天渠道服务（飞书/Discord/TG等）
8. app.run()                   — Quart ASGI 服务器启动
  • Web 框架: Quart（Flask 的异步版本，ASGI）
  • 认证机制: JWT + API Token + Beta Token 三重认证
  • 会话存储: Redis（flask-session）
  • 端口: 默认 9380（HTTP API），80（Nginx 反代 Web）

Go 入口：cmd/ragflow_server.go

Go 入口： ragflow\cmd\ragflow_server.go

Go 服务是 v0.27.0 中快速增长的新后端，基于 Gin 框架：

启动流程:
1. 加载配置（viper）
2. 初始化存储层（MySQL/GORM, Redis, MinIO, Elasticsearch/Infinity）
3. 初始化 NATS 消息系统（服务间通信）
4. 注册 HTTP 路由（router 包）
5. 启动各服务模块:
   - Agent 执行引擎（internal/agent）
   - 摄入服务（internal/ingestion）
   - 文档/分块/数据集服务（internal/service）
   - MCP 服务（internal/mcp）
   - 聊天渠道（internal/channels）
   - 管理后台（internal/admin）
6. Gin HTTP 服务器启动
  • Web 框架: gin-gonic/gin
  • ORM: GORM（MySQL）
  • 消息队列: NATS JetStream
  • 端口: 9384（Go HTTP），9383（Go Admin）

Go CLI 入口：cmd/ragflow-cli.go

提供命令行管理工具，用于运维操作。

任务执行器：rag/svr/task_executor.py

独立的后台任务执行进程，负责文档解析、分块、嵌入等异步任务：

启动方式: bash docker/entrypoint_task_executor.sh <worker_count> <queue_count>
职责:
- 从 Redis 任务队列消费文档处理任务
- 调用 DeepDoc 解析文档
- 执行分块（chunking）
- 调用 Embedding 模型向量化
- 写入 Elasticsearch/Infinity 向量库

Docker 部署入口

生产部署（Docker Compose）

cd ragflow/docker
git checkout v0.27.0

# CPU 模式
docker compose -f docker-compose.yml up -d

# GPU 模式（DeepDoc GPU 加速）
# sed -i '1i DEVICE=gpu' .env
# docker compose -f docker-compose.yml up -d

开发模式（源码启动）

# 1. 安装 uv 和 Python 依赖
pipx install uv
uv sync --python 3.13
uv run python3 ragflow_deps/download_deps.py

# 2. 启动基础服务
docker compose -f docker/docker-compose-base.yml up -d

# 3. 配置 hosts
# 127.0.0.1  es01 infinity mysql minio redis sandbox-executor-manager

# 4. 启动 Python 后端
source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

# 5. 启动前端
cd web && npm install && npm run dev

基础设施服务（docker-compose-base.yml）

服务 镜像 端口 用途
MySQL mysql:8.0.40 3306 元数据存储（用户/知识库/文档/对话）
Redis/Valkey valkey/valkey:8 6379 缓存/会话/任务队列/分布式锁
MinIO pgsty/silo 9000/9001 对象存储（原始文档/解析结果）
Elasticsearch elasticsearch 9200 全文检索 + 向量存储（默认）
Infinity infiniflow/infinity:v0.7.3 23817/23820/5432 向量数据库（可选替代 ES）
OpenSearch opensearch:2.19.1 9201 全文检索（可选）
NATS nats:2.14.2 4222/8222 Go 服务间消息通信（JetStream）
Sandbox Executor infiniflow/sandbox-executor-manager 9385 代码执行沙箱管理（Docker-in-Docker）
ClickHouse clickhouse-server 9000/8123 日志/分析存储（可选）
OceanBase oceanbase-ce:4.4.1 2881 分布式数据库（可选替代 MySQL）
TEI huggingface/text-embeddings-inference 6380 本地 Embedding 推理服务（可选）
Jaeger jaegertracing/jaeger 4317/16686 分布式追踪（可选）

配置文件

文件 用途
docker/.env 环境变量（端口/密码/镜像版本）
docker/service_conf.yaml.template 后端服务配置（LLM/Embedding/存储引擎）
conf/ 额外配置（80 个文件，含模型配置、分块模板等）

Step 4: 核心模块

整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                        Web 前端 (React)                          │
│                   web/ (1755 files)                              │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/WebSocket
┌──────────────────────────────▼──────────────────────────────────┐
│                    API 网关层 (Nginx :80)                        │
├──────────────────────────────────┬───────────────────────────────┤
│   Python 后端 (Quart :9380)     │   Go 后端 (Gin :9384)        │
│   api/ (162 files)               │   internal/ (2188 files)      │
│   ┌─────────────────────────┐    │   ┌─────────────────────────┐ │
│   │ RESTful API 路由        │    │   │ Agent 执行引擎          │ │
│   │ 认证/授权 (JWT/API Key) │    │   │ 摄入管道 (Ingestion)    │ │
│   │ 知识库/文档管理          │    │   │ 文档/分块/数据集服务    │ │
│   │ 对话/会话管理            │    │   │ MCP 服务                │ │
│   │ 聊天渠道集成             │    │   │ 聊天渠道                │ │
│   └─────────────────────────┘    │   └─────────────────────────┘ │
├──────────────────────────────────┴───────────────────────────────┤
│                     核心业务层                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
│  │ RAG 核心  │  │ Agent    │  │ DeepDoc  │  │ GraphRAG        │ │
│  │ rag/     │  │ agent/   │  │ deepdoc/ │  │ rag/graphrag/   │ │
│  │ (250)    │  │ (151)    │  │ (64)     │  │                 │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────────┘ │
├───────────────────────────────────────────────────────────────────┤
│                     数据存储层                                     │
│  MySQL(元数据) │ Redis(缓存/队列) │ MinIO(对象) │ ES/Infinity(向量)│
└───────────────────────────────────────────────────────────────────┘

模块一：RAG 核心（rag/，250 文件）

RAGFlow 的检索增强生成核心，包含以下子模块：

rag/nlp/ — 自然语言处理

文件 职责
search.py 全文检索查询构建（同义词扩展、分词、权重计算）
query.py 查询理解（意图识别、关键词提取）
term_weight.py 词权重计算（TF-IDF 变体）
synonym.py 同义词词典管理
delim.py 文本分隔符处理
rag_tokenizer.py 分词器封装
surname.py 中文姓氏处理（人名识别辅助）

rag/llm/ — 大模型抽象层

文件 职责
chat_model.py 对话模型统一封装（通过 LiteLLM 支持 100+ 模型）
embedding_model.py 嵌入模型封装（BGE/OpenAI/Cohere/Voyage 等）
rerank_model.py 重排序模型封装（Cohere Rerank / BGE Reranker）
cv_model.py 计算机视觉模型（多模态，图片理解）
ocr_model.py OCR 模型封装
tts_model.py 语音合成模型
sequence2txt_model.py 序列到文本模型（语音识别/字幕生成）
model_meta.py 模型元数据管理
tool_decorator.py LLM Function Calling 工具装饰器

设计亮点: 通过 LiteLLM 统一接入 OpenAI/Anthropic/Cohere/Groq/DeepSeek/通义千问/百度千帆/Google Gemini 等主流模型，开发者无需关心底层 API 差异。

rag/app/ — RAG 应用模板

针对不同场景预设的 RAG 应用模式：

文件 场景
naive.py 通用问答（最核心，处理文档解析+分块+检索+生成全流程）
qa.py 问答对管理
paper.py 学术论文阅读
book.py 书籍阅读
laws.py 法律条文检索
manual.py 产品手册
resume.py 简历解析
table.py 表格数据问答
picture.py 图片理解问答
presentation.py PPT 生成
audio.py 音频处理
email.py 邮件处理
tag.py 标签管理
one.py 单文档问答

rag/svr/ — 服务端进程

文件 职责
task_executor.py 任务执行器主进程（文档解析/分块/嵌入）
task_executor_limiter.py 任务执行限流
cache_file_svr.py 文件缓存服务
sync_data_source.py 数据源同步（Confluence/S3/Notion 等）
discord_svr.py Discord 聊天渠道服务

rag/graphrag/ — 图谱 RAG

基于知识图谱的检索增强，通过实体-关系抽取构建图谱，支持图谱推理问答。

rag/flow/ — RAG 流程编排

可配置的 RAG 处理流水线，支持自定义检索策略、重排序策略、生成策略。

模块二：Agent 框架（agent/，151 文件）

架构设计：组件化 DAG 引擎

RAGFlow 的 Agent 采用可视化 DAG 编排架构，每个节点是一个独立组件，通过连线定义数据流：

agent/component/
├── base.py              — 组件基类（定义输入/输出/执行接口）
├── begin.py             — 开始节点（接收用户输入）
├── llm.py               — LLM 调用节点
├── invoke.py            — 工具调用节点
├── categorize.py        — 分类节点（意图路由）
├── switch.py            — 条件分支节点
├── iteration.py         — 迭代循环节点
├── loop.py              — 循环节点
├── iterationitem.py     — 迭代项节点
├── loopitem.py          — 循环项节点
├── exit_loop.py         — 退出循环节点
├── code_exec.py         — 代码执行节点（Python/JS 沙箱）
├── browser.py           — 浏览器自动化节点
├── data_operations.py   — 数据操作节点
├── list_operations.py   — 列表操作节点
├── string_transform.py  — 字符串变换节点
├── variable_aggregator.py — 变量聚合节点
├── variable_assigner.py — 变量赋值节点
├── fillup.py            — 填充节点
├── docs_generator.py    — 文档生成节点
├── excel_processor.py   — Excel 处理节点
├── message.py           — 消息处理节点
└── canvas.py            — 画布管理（DAG 序列化/反序列化）

核心设计模式:

  • 组件基类 (base.py): 定义统一的 exec() 接口、输入/输出 schema、状态管理
  • DAG 执行引擎: 拓扑排序 + 依赖等待 + 并行执行
  • 变量传递: 节点间通过变量引用传递数据，支持模板字符串
  • 状态持久化: Agent 执行状态可暂停/恢复/调试

Agent 工具集（agent/tools/，26 个工具）

涵盖搜索、学术、金融、代码、网页、翻译、邮件、数据库等领域，每个工具实现统一的 BaseTool 接口。

Agent 模板（agent/templates/）

预构建的 Agent 工作流模板，用户可直接使用或在此基础上修改。

Agent 沙箱（agent/sandbox/）

  • 总结：代码执行安全沙箱，通过 sandbox-executor-manager 服务管理 Docker 容器，支持 Python 和 JavaScript 代码执行，限制内存（默认 256MB）和超时（默认 10s）。

  • RAGFlow 的沙箱机制是一个多层防御 + 可插拔 Provider 的代码执行系统，核心代码在 agent/sandbox/ 目录。我读完了全部关键实现，梳理如下。

整体架构（三层）
┌────────────────────────────────────────────────────────────┐
│ ① CodeExec 组件 (agent/tools/code_exec.py)                  │
│    Agent 工作流中的"代码执行"节点                            │
├────────────────────────────────────────────────────────────┤
│ ② Sandbox Client (agent/sandbox/client.py)                 │
│    统一入口，从系统配置读取 provider_type，路由到具体 Provider │
├────────────────────────────────────────────────────────────┤
│ ③ Provider 抽象层 (agent/sandbox/providers/)                │
│    self_managed │ local │ ssh │ e2b │ tenki │              │
│    aliyun_codeinterpreter │ ucloud_agent_sandbox           │
└────────────────────────────────────────────────────────────┘
默认实现：self_managed（Docker + gVisor）

这是生产默认方案，由独立的 sandbox-executor-manager 服务（端口 9385）承载，源码在 agent/sandbox/executor_manager/。

执行流程：

  1. 容器池预热：启动时按池大小（默认 3）预创建 sandbox_python_N 和 sandbox_nodejs_N 两组容器，放进队列复用
  2. 代码传输：main.py/main.js + runner.py/runner.js + args.json 通过 tar 管道注入容器工作目录
  3. 执行：docker exec 运行 runner，用 timeout 命令限时；代码通过结构化的 main(**args) 约定，返回结果用 __RAGFLOW_RESULT__: base64 标记封装在 stdout 中
  4. 收集产物：artifacts/ 目录下的文件（限制 10 个、每个 ≤10MB、仅限 png/jpg/svg/pdf/csv/json/html 白名单）取回，上传到 MinIO
  5. 清理：删除容器内任务目录和宿主机临时目录，容器归还队列
五层安全防御
层 机制 说明
① 系统调用隔离 gVisor (runsc) 用户态内核，拦截 / 限制 syscall，防容器逃逸（核心层）
② seccomp 白名单 seccomp-profile-default.json 可选，仅放行预定义 syscall，默认关闭（与部分依赖兼容性问题）
③ Docker 容器加固 见下 只读根文件系统、非 root、内存限额
④ 静态代码分析 AST / 正则 Python 用 SecurePythonAnalyzer（AST），JS 用正则，执行前拒绝危险模式
⑤ 资源限制 超时 / 内存 / 产物 timeout + OOM kill + 输出 / 文件大小上限
  • 容器加固细节（core/container.py）：
docker run -d \
  --runtime=runsc \
  --read-only \                        # 根文件系统只读
  --tmpfs /workspace:rw,exec,size=100M \  # 工作目录内存盘
  --tmpfs /tmp:rw,exec,size=50M \
  --user nobody \                      # 非 root 用户 (uid=65534)
  --memory 256m \                      # 内存上限
  [--security-opt seccomp=...]         # 可选

静态分析黑名单（services/security.py）：

  • Python 危险 import：os、subprocess、sys、shutil、socket、ctypes、pickle、builtins 等
  • Python 危险调用：eval、exec、open、__import__、compile、system、popen 等（含属性访问、lambda、列表 / 字典推导式变体）
  • JS 危险模式：child_process、fs、worker_threads、eval、Function、process.binding

错误分类：analyze_error_result 将失败细分为超时 (124)、OOM (137)、越权访问（Permission denied / Operation not permitted）、运行时错误等，供 Agent 下游节点处理。

可插拔 Provider

1 Provider = 沙箱执行后端的统一接口。

把「执行代码」这件事抽象成一套固定方法（initialize / create_instance / execute_code / destroy_instance / health_check），底下可以接不同的实现：

  • self_managed：本地 Docker + gVisor 容器池（默认）
  • local：直接起子进程
  • ssh：远程主机
  • e2b / tenki / aliyun / ucloud：云厂商托管沙箱

上层 CodeExec 组件只认接口、不认实现—— 不管代码是在本地容器还是阿里云上跑，调用方式完全一样。

Provider 就是「可插拔的沙箱执行后端」，解耦了「谁能执行代码」和「代码怎么执行」这两个问题。

2 除默认的 self_managed 外，还有：

  • local：直接本地子进程（preexec_fn 设 RLIMIT_CPU/AS/FSIZE/NOFILE），非沙箱边界，需 SANDBOX_LOCAL_ENABLED 显式开启
  • ssh：远程主机执行
  • e2b / tenki / aliyun_codeinterpreter / ucloud_agent_sandbox：第三方 / 云厂商托管沙箱

3 配置存储在系统设置表（sandbox.provider_type），通过 reload_provider() 热切换。

关键设计点
  • 容器复用而非每次新建：池化 + 队列分配，执行完清理任务目录后归还，性能好
  • 只读根 + tmpfs：代码无持久写盘能力，防磁盘耗尽
  • 网络未隔离：容器可联网（JS 示例用了 axios 请求 GitHub），这属于可执行代码的能力边界
  • Go 侧并行实现：go.mod 中也有 ucloud-sandbox-sdk-go、tenki-sdk-go/sandbox、e2b-go-sdk 等，说明 Go 后端同样接入了沙箱能力

RAGFlow 沙箱 = 「gVisor 系统调用隔离 + Docker 加固容器 + 静态代码审查」三层防御的容器池执行引擎，对外暴露统一的 Provider 抽象以支持自建或云厂商多种实现。

Agent 插件（agent/plugin/）

GlobalPluginManager 支持动态加载第三方插件，扩展 Agent 能力。

模块三：DeepDoc 深度文档理解（deepdoc/，64 文件）

DeepDoc 是 RAGFlow 的核心技术壁垒，负责将非结构化文档转化为可检索的结构化内容。

deepdoc/vision/ — 视觉理解

能力 说明
OCR 文字识别（支持中英文，基于 ONNX Runtime 推理）
版面识别 10 类版面元素：Text/Title/Figure/Figure caption/Table/Table caption/Header/Footer/Reference/Equation
表格结构识别（TSR） 5 类标签：Column/Row/Column header/Projected row header/Spanning cell
表格自动旋转 扫描件表格方向检测（0°/90°/180°/270°），基于 OCR 置信度选最优角度

deepdoc/parser/ — 文档解析器

格式 解析器 输出
PDF PdfParser（最复杂） 文本块（页码+坐标）+ 表格（图片+自然语言重述）+ 图片（标题+图内文字）
DOCX DocxParser 段落+表格+图片
Excel ExcelParser 工作表+单元格数据
PPT PptParser 幻灯片+文本+图片

PDF 解析关键技术:

  1. 基于 pdfplumber 提取文本和坐标
  2. 调用视觉模型进行版面分析
  3. 表格区域调用 TSR 模型识别结构
  4. 图片区域提取标题和图内文字
  5. 输出带坐标的结构化内容，供后续分块使用

deepdoc/server/ — DeepDoc 独立服务

DeepDoc 可作为独立微服务部署（deepdoc_oss Docker 镜像），通过 HTTP API 提供文档解析能力，端口 9390。

模块四：Go 后端（internal/，2188 文件）

v0.27.0 中 Go 代码量已远超 Python，是项目的主要发展方向。采用清晰的分层架构：

internal/handler/ — HTTP 处理器

基于 Gin 的 RESTful API 处理器，包含：

  • agent.go — Agent 执行 API（含调试、上传、下载、Webhook）
  • auth.go — 认证 API
  • api_token.go — API Token 管理
  • 以及数据集、文档、对话等业务处理器

internal/service/ — 业务服务层

子模块 职责
dataset/ 知识库管理
document/ 文档管理
chunk/ 分块管理
file/ 文件管理
nlp/ NLP 服务（分词/关键词）
nav/ 导航服务
graph/ 图谱服务
wikisearch/ Wiki 搜索

internal/agent/ — Go 版 Agent 引擎

  • canvas/ — DAG 画布管理
  • tool/ — 工具执行
  • audio/ — 音频处理
  • retrievalbridge/ — 检索桥接（连接 Python 检索服务）

internal/ingestion/ — 文档摄入管道

  • service/ — 摄入服务
  • knowledge_compile/ — 知识编译（文档→分块→嵌入的完整管道）

internal/engine/ — 存储引擎抽象层

支持多种向量/全文检索引擎的统一抽象：

引擎 目录 特点
Elasticsearch elasticsearch/ 默认，全文+向量混合检索
Infinity infinity/ InfiniFlow 自研向量数据库
OpenSearch （通过 ES 兼容） AWS 开源搜索
ClickHouse clickhouse/ 列式分析数据库
OceanBase oceanbase/ 分布式关系数据库
Redis redis/ 缓存/向量
NATS nats/ 消息系统
SereneDB serenedb/ 时序数据库

internal/storage/ — 对象存储抽象

统一 S3/MinIO/Azure Blob/Google Cloud Storage/OSS 等对象存储接口。

internal/mcp/ — MCP 协议服务

实现 Model Context Protocol 服务端，支持 SSE 和 Streamable HTTP 传输，允许外部 MCP Client 调用 RAGFlow 能力。

internal/channels/ — 多聊天渠道

飞书、Discord、TG、Line、微信、Slack 等即时通讯平台的消息接入。

internal/dao/ — 数据访问层

基于 GORM 的数据库操作封装。

internal/entity/ — 数据实体定义

数据库模型和 API 数据结构。

internal/router/ — 路由注册

Gin 路由集中注册，管理所有 API 端点。

internal/tokenizer/ — 分词器

Go 版文本分词实现。

internal/syncer/ — 数据同步

Confluence/S3/Notion/Discord/Google Drive 等数据源的定时同步。

internal/admin/ — 管理后台

系统管理 API（用户管理、模型配置、系统监控）。

模块五：API 层（api/，162 文件）

api/apps/ — Quart 应用

  • __init__.py — Quart 应用初始化、认证中间件、路由自动注册
  • restful_apis/ — RESTful API 路由（按业务模块分文件）
  • services/ — API 服务层
  • auth/ — 认证相关（登录/注册/OAuth）

认证机制详解 (api/apps/__init__.py):

  1. JWT 认证: 通过 itsdangerous.URLSafeTimedSerializer 签名的 access_token
  2. API Token 认证: 数据库存储的 API Key（APIToken 表）
  3. Beta Token 认证: 内测用户专用 Token
  4. Session 回退: 无 Authorization 头时，从 Redis Session 中恢复用户

api/db/ — 数据库层

  • db_models.py — peewee ORM 模型定义
  • services/ — 数据服务（UserService/DocumentService/LLMBundle 等）
  • joint_services/ — 联合服务（跨表查询）
  • runtime_config.py — 运行时配置管理

api/channels/ — 聊天渠道

Python 版多渠道消息接入（与 Go 版并存，逐步迁移中）。

api/utils/ — 工具函数

JSON 编码、API 响应封装、命令注册等。

模块六：公共层（common/，105 文件）

跨模块共享的工具和配置：

  • settings.py — 全局配置加载
  • constants.py — 常量定义（状态码/枚举）
  • token_utils.py — Token 计数
  • file_utils.py — 文件操作
  • log_utils.py — 日志工具
  • config_utils.py — 配置工具
  • mcp_tool_call_conn.py — MCP 工具调用连接管理
  • versions.py — 版本管理

模块七：前端（web/，1755 文件）

基于 React 的单页应用，提供：

  • 知识库管理界面（文档上传/解析进度/分块查看）
  • Agent 画布编辑器（可视化 DAG 编排）
  • 对话界面（流式输出/引用展示）
  • 模型配置界面
  • 系统管理界面

Step 5: 依赖与技术栈

Python 技术栈（必读）

核心依赖（按功能分类）

类别 关键依赖 版本约束 用途
Web 框架 Quart (传递依赖) 异步 ASGI Web 框架（Flask 异步版）
flask-cors 6.0.2 跨域支持
flask-login 0.6.3 用户登录管理
flask-session 0.8.0 会话管理（Redis 后端）
quart-auth 0.11.0 Quart 认证
quart-cors 0.8.0 Quart 跨域
quart-schema 0.23.0 API Schema 验证
LLM 接入 litellm 1.84.0 统一 100+ LLM API（核心）
anthropic 0.76.0 Claude 模型
cohere 5.6.2 Cohere 模型/重排序
groq ≥0.30.0 Groq 推理
mistralai ≥2.7.2 Mistral 模型
google-genai ≥1.41.0 Google Gemini
dashscope 1.25.11 阿里通义千问
qianfan 0.4.6 百度千帆
volcengine 1.0.194 火山引擎
voyageai 0.2.3 Voyage 嵌入
ollama ≥0.5.0 本地模型
replicate 0.31.0 Replicate 模型平台
zai-sdk ≥0.2.3 ZAI 模型
Agent 框架 langgraph 1.2.0 Agent 状态图编排
mcp ≥1.28.1 Model Context Protocol
browser-use ≥0.11.1 浏览器自动化
agentrun-sdk ≥0.0.51 Agent 运行 SDK
nest-asyncio ≥1.6.0 异步嵌套支持
RAG/检索 elasticsearch-dsl 8.12.0 Elasticsearch ORM
infinity-sdk 0.7.3 Infinity 向量数据库
infinity-emb ≥0.0.66 Infinity 嵌入
ranx 0.3.20 信息检索评估/融合
rapidfuzz 3.14.5 模糊字符串匹配
opensearch-py 2.7.1 OpenSearch 客户端
pyobvector 0.2.22 OceanBase 向量
NLP spacy 3.8.14 工业级 NLP
langdetect 1.0.9 语言检测
en/zh/de/fr/es/pt/ja-core-web-sm 3.8.x 多语言 spaCy 模型
文档解析 pdfplumber 0.11.10 PDF 解析（核心）
python-docx ≥1.1.2 DOCX 解析
python-pptx ≥1.0.2 PPT 解析
mammoth ≥1.11.0 DOCX→HTML
tika 2.6.0 Apache Tika 文档解析
pypandoc ≥1.16 Pandoc 文档转换
pypdf ≥6.15.0 PDF 操作
extract-msg ≥0.39.0 Outlook MSG 解析
python-calamine ≥0.4.0 Excel 解析（Rust 绑定）
markdown ≥3.8.1 Markdown 渲染
markdownify ≥1.2.0 HTML→Markdown
html-text 0.6.2 HTML 文本提取
readability-lxml ≥0.8.4 网页正文提取
OCR/视觉 onnxruntime 1.23.2 ONNX 推理（CPU）
onnxruntime-gpu 1.23.2 ONNX 推理（GPU）
opencv-python 4.10.0.84 图像处理
opencv-python-headless 4.10.0.84 无界面 OpenCV
数据库 peewee ≥3.17.1 ORM（核心）
mysql-connector-python ≥9.0.0 MySQL 驱动
psycopg2-binary ≥2.9.11 PostgreSQL 驱动
pyodbc ≥5.2.0 ODBC 驱动
sqlglotrs 0.9.0 SQL 解析（Rust）
缓存/队列 valkey 6.0.2 Redis 兼容客户端
对象存储 minio 7.2.4 MinIO/S3 客户端
opendal ≥0.45.0 统一对象存储抽象
boto3 ≥1.28.0 AWS SDK
mypy-boto3-s3 1.40.26 S3 类型提示
搜索/爬虫 crawl4ai ≥0.9.2 网页爬虫
duckduckgo-search ≥7.2.0 DuckDuckGo 搜索
tavily-python 0.5.1 Tavily 搜索
selenium-wire 5.1.0 Selenium 带抓包
webdriver-manager 4.0.1 浏览器驱动管理
feedparser ≥6.0.11 RSS/Atom 解析
金融数据 akshare ≥1.15.78 A股/财经数据
yfinance 0.2.65 Yahoo Finance
tushare (工具内) Tushare 财经数据
学术 arxiv 2.1.3 arXiv 论文
scholarly 1.7.11 Google Scholar
pubmed (工具内) PubMed 文献
代码执行 ucloud-sandbox ≥1.4.2 沙箱执行
mini-racer ≥0.12.4 JavaScript 执行（V8）
消息/通知 aiosmtplib ≥5.1.1 异步 SMTP
flask-mail ≥0.10.0 邮件发送
discord-py 2.3.2 Discord Bot
python-TG-bot ≥21.0 TG Bot
line-bot-sdk ≥3.0.0 Line Bot
wechatpy ≥1.8.18 微信公众号
slack-sdk 3.37.0 Slack Bot
lark-oapi ≥1.2.0 飞书开放平台
alibabacloud-dingtalk ≥2.0.0 钉钉
可观测性 langfuse ≥4.0.1 LLM 可观测性
安全 pycryptodomex 3.20.0 加密算法
captcha ≥0.7.1 验证码生成
其他 beartype ≥0.20.0 运行时类型检查
json-repair 0.60.1 JSON 修复（LLM 输出容错）
demjson3 3.0.6 宽松 JSON 解析
ormsgpack ≥1.6.0 高性能 MessagePack
reportlab ≥4.4.1 PDF 生成
xgboost 1.6.0 梯度提升（分类/排序）
graspologic (git) 图分析/可视化
cn2an 0.5.22 中文数字转换
xpinyin 0.7.6 中文转拼音
word2number 1.1 英文数字转换
roman-numbers 1.0.2 罗马数字转换

Python 依赖统计

  • 直接依赖数量: ~180+ 个（含注释掉的可选依赖）
  • 复杂度评级: 重量级（依赖数 > 30，且有大量跨领域子依赖）
  • Python 版本: ≥3.13,❤️.14（强制使用 3.13）
  • 包管理: uv（现代 Python 包管理器，替代 pip/poetry）

安全治理

pyproject.toml 中通过 [tool.uv] constraint-dependencies 主动约束了大量传递依赖的 CVE 修复版本，包括：

  • pyasn1 ≥0.6.4（CVE-2026-30922 等）
  • urllib3 ≥2.7.0（CVE-2026-44431/44432）
  • lxml ≥6.1.1（CVE-2026-41066）
  • nltk ≥3.10.0（CVE-2025-14009 CRITICAL 等）
  • protobuf ≥5.29.6（CVE-2026-0994）
  • orjson ≥3.11.6（CVE-2025-67221）

Go 技术栈

核心依赖

类别 关键依赖 版本 用途
Web 框架 gin-gonic/gin v1.12.0 HTTP 框架（核心）
gorilla/websocket v1.5.3 WebSocket 支持
数据库 gorm.io/gorm v1.25.7 ORM（核心）
gorm.io/driver/mysql v1.5.2 MySQL 驱动
go-sql-driver/mysql v1.7.0 原生 MySQL 驱动
lib/pq v1.10.9 PostgreSQL 驱动
jackc/pgx/v5 v5.10.0 PostgreSQL 高级驱动
denisenkom/go-mssqldb v0.12.3 SQL Server 驱动
glebarez/sqlite v1.11.0 SQLite 驱动
缓存/消息 redis/go-redis/v9 v9.18.0 Redis 客户端
nats-io/nats.go v1.52.0 NATS 消息客户端
nats-io/nats-server/v2 v2.14.3 内嵌 NATS 服务端
搜索/向量 elastic/go-elasticsearch/v8 v8.19.1 Elasticsearch 客户端
infiniflow/infinity-go-sdk (replace) Infinity 向量数据库
对象存储 minio/minio-go/v7 v7.0.99 MinIO/S3 客户端
aws/aws-sdk-go-v2 v1.41.3 AWS SDK（S3/STS）
cloud.google.com/go/storage v1.63.0 Google Cloud Storage
AI/Agent cloudwego/eino v0.9.14 字节跳动 Agent 框架
google.golang.org/genai v1.54.0 Google Gemini SDK
pkoukk/tiktoken-go v0.1.8 Token 计数
browserbase/stagehand-go/v3 v3.21.0 浏览器自动化
alibabacloud-go/agentrun-20250910/v5 v5.8.4 阿里云 Agent 运行
LuxorLabs/tenki-sdk-go/sandbox v0.7.0 沙箱执行
ucloud/ucloud-sandbox-sdk-go (latest) UCloud 沙箱
eric642/e2b-go-sdk v0.1.3 E2B 沙箱
文档处理 ledongthuc/pdf (latest) PDF 解析
xuri/excelize/v2 v2.11.0 Excel 处理
signintech/gopdf v0.36.1 PDF 生成
yfedoseev/pdf_oxide/go v0.3.67 PDF 处理（Rust 绑定）
yfedoseev/office_oxide/go v0.1.8 Office 文档处理
gomarkdown/markdown (latest) Markdown 解析
yuin/goldmark v1.4.13 Markdown 渲染
配置 spf13/viper v1.18.2 配置管理
日志 go.uber.org/zap v1.27.1 高性能日志
gopkg.in/natefinch/lumberjack.v2 v2.2.1 日志轮转
可观测性 go.opentelemetry.io/otel v1.44.0 OpenTelemetry
go.opentelemetry.io/otel/sdk v1.44.0 OTel SDK
安全 golang-jwt/jwt/v5 v5.3.0 JWT 认证
golang.org/x/crypto v0.53.0 加密库
JSON goccy/go-json v0.10.6 高性能 JSON
json-iterator/go v1.1.12 JSON 解析
kaptinlin/jsonrepair v0.4.8 JSON 修复
工具 google/uuid v1.6.0 UUID 生成
cespare/xxhash/v2 v2.3.0 哈希
zeebo/xxh3 v1.0.2 XXH3 哈希
cenkalti/backoff/v5 v5.0.3 退避重试
pkg/errors v0.9.1 错误处理
gonum.org/v1/gonum v0.17.0 数值计算/矩阵
nikolalohinski/gonja v1.5.3 Jinja2 模板引擎（Go 版）
gojianfan (latest) 简繁转换
larksuite/oapi-sdk-go/v3 v3.9.9 飞书 SDK
open-dingtalk/dingtalk-stream-sdk-go v0.0.5 钉钉 SDK

Go 依赖统计

  • 直接依赖数量: ~75 个
  • 间接依赖数量: ~150+ 个
  • 复杂度评级: 重量级
  • Go 版本: 1.26.4
  • 模块名: ragflow

前端技术栈

  • 框架: React（1755 个源文件）
  • 构建: 标准前端工具链
  • 核心功能: 知识库管理、Agent 画布编辑器、对话界面、模型配置

技术栈综合评估 （必读）

维度 评估
技术方向 AI / RAG / Agent / 文档理解
后端语言 Python（API/RAG/DeepDoc）+ Go（Agent/Ingestion/Service，迁移中）
前端 React SPA
核心数据库 MySQL（元数据）+ Elasticsearch/Infinity（向量+全文）
缓存/队列 Redis/Valkey + NATS JetStream
对象存储 MinIO（S3 兼容）
LLM 接入 LiteLLM 统一层（100+ 模型）
复杂度 重量级（Python 180+ 依赖，Go 75+ 直接依赖）
部署方式 Docker Compose（生产）/ 源码（开发）
可观测性 Langfuse（LLM 追踪）+ OpenTelemetry（Go）+ Jaeger（可选）

速读结论

综合评分

维度 评分 说明
文档清晰度 ⭐⭐⭐⭐ README 详尽，多语言支持，官方文档站完善；但代码内部注释偏少
上手难度 ⭐⭐⭐ Docker 一键部署友好；但源码开发环境复杂（Python 3.13 + uv + 多服务）
代码质量 ⭐⭐⭐⭐ 架构分层清晰，双语言协同；Python 侧部分模块耦合较高，Go 侧较新且规范
技术前沿性 ⭐⭐⭐⭐⭐ 紧跟 RAG/Agent/MCP 前沿，支持 GraphRAG、DeepDoc、代码沙箱、多渠道
项目活跃度 ⭐⭐⭐⭐⭐ 版本迭代快（月更），社区活跃，商业公司背书（InfiniFlow）
生产就绪度 ⭐⭐⭐⭐ 已有云服务和企业用户；但 v0.x 版本号暗示 API 可能变动

核心优势（必读）

  1. DeepDoc 文档理解是最大壁垒——OCR + 版面识别 + TSR 的组合在开源 RAG 项目中独树一帜
  2. Agent + RAG 深度融合——不是简单拼接，而是通过 DAG 编排让检索成为 Agent 的一个可配置节点
  3. 多存储引擎支持——Elasticsearch/Infinity/OpenSearch/OceanBase/ClickHouse 灵活选择
  4. 企业级特性——多租户、API Key、权限管理、审计、多聊天渠道集成
  5. 双语言演进——Python 快速迭代 + Go 高性能服务，正在向 Go 迁移以提升性能

潜在风险/不足（必读）

  1. 依赖极重——Python 180+ 依赖，安装体积大，版本冲突风险高
  2. 资源消耗大——最低 16GB RAM + 50GB 磁盘，Elasticsearch 本身就是资源大户
  3. 双语言维护成本——Python 和 Go 功能重叠，迁移过程中可能存在不一致
  4. v0.x 版本——API 稳定性未做正式承诺，升级可能有 breaking change
  5. ARM64 支持不完善——Docker 镜像仅 x86，Apple Silicon 用户需自行构建

适合场景（必读）

  • ✅ 企业级知识库问答（文档密集型场景）
  • ✅ 复杂格式文档解析（PDF/扫描件/表格/论文）
  • ✅ 需要 Agent 工作流的 RAG 应用
  • ✅ 私有化部署的企业级 AI 问答系统
  • ✅ 多渠道客服机器人（飞书/钉钉/微信等）

不适合场景（必读）

  • ❌ 轻量级个人项目（资源消耗过大）
  • ❌ 仅需简单向量检索（用 Chroma/Qdrant 更轻量）
  • ❌ ARM64 服务器生产部署（官方不支持）
  • ❌ 对 API 稳定性要求极高的场景（v0.x 版本）
  • ❌ 离线环境且无法下载 HuggingFace 模型（DeepDoc 依赖模型下载）

源码结构速查表（必读）

ragflow/
├── api/                    # Python API 服务 (Quart)
│   ├── ragflow_server.py      # Python 入口
│   ├── apps/                   # Quart 应用 + 路由
│   ├── db/                     # 数据库层 (peewee ORM)
│   ├── channels/               # 聊天渠道
│   └── utils/                  # 工具函数
├── agent/                  # Agent 框架
│   ├── component/              # DAG 组件 (25个)
│   ├── tools/                  # 内置工具 (26个)
│   ├── templates/              # 预构建模板
│   ├── sandbox/                # 代码沙箱
│   ├── plugin/                 # 插件管理
│   └── canvas.py               # 画布/DAG 管理
├── rag/                    # RAG 核心
│   ├── nlp/                    # NLP 处理
│   ├── llm/                    # LLM 抽象层
│   ├── app/                    # RAG 应用模板 (15种场景)
│   ├── svr/                    # 服务进程 (task_executor)
│   ├── graphrag/               # 图谱 RAG
│   ├── flow/                   # 流程编排
│   ├── prompts/                # Prompt 模板
│   └── utils/                  # 工具函数
├── deepdoc/                # 深度文档理解
│   ├── vision/                 # OCR/版面识别/TSR
│   ├── parser/                 # PDF/DOCX/Excel/PPT 解析
│   └── server/                 # 独立解析服务
├── internal/               # Go 后端 (2188 files)
│   ├── handler/                # HTTP 处理器 (Gin)
│   ├── service/                # 业务服务层
│   ├── agent/                  # Go 版 Agent 引擎
│   ├── ingestion/              # 文档摄入管道
│   ├── engine/                 # 存储引擎抽象 (8种)
│   ├── storage/                # 对象存储抽象
│   ├── mcp/                    # MCP 协议服务
│   ├── channels/               # 多聊天渠道
│   ├── dao/                    # 数据访问层 (GORM)
│   ├── entity/                 # 数据实体
│   ├── router/                 # 路由注册
│   ├── admin/                  # 管理后台
│   ├── syncer/                 # 数据同步
│   ├── tokenizer/              # 分词器
│   └── common/                 # 公共工具
├── cmd/                    # Go 入口
│   ├── ragflow_server.go       # Go HTTP 服务入口
│   └── ragflow-cli.go          # CLI 工具入口
├── web/                    # React 前端 (1755 files)
├── common/                 # 公共模块 (Python)
├── conf/                   # 配置文件 (80 files)
├── docker/                 # Docker 部署
│   ├── docker-compose.yml      # 主服务编排
│   ├── docker-compose-base.yml # 基础设施服务
│   ├── .env                    # 环境变量
│   └── service_conf.yaml.template  # 服务配置模板
├── sdk/                    # 官方 SDK
│   └── python/ragflow_sdk/     # Python SDK
├── mcp/                    # MCP 服务
├── memory/                 # Agent 记忆模块
├── test/                   # 测试 (499 files)
├── tools/                  # 独立工具项目
├── example/                # 示例
├── docs/                   # 文档 (143 files)
├── helm/                   # Kubernetes Helm Chart
├── pyproject.toml          # Python 项目配置 (uv)
├── go.mod / go.sum         # Go 模块配置
├── Dockerfile              # 主镜像构建
├── Dockerfile_base         # 基础镜像
├── Dockerfile_deepdoc_oss # DeepDoc 独立服务镜像
├── LICENSE                 # Apache 2.0
└── README.md               # 项目说明

报告生成时间: 2026-08-25 | 基于 RAGFlow v0.27.0 源码分析
分析方法: Git Repo Reader 五维阅读法（定位→用法→入口→核心模块→依赖）

Y 推荐文献

X 参考文献

posted @ 2026-08-27 01:59  数据知音  阅读(20)  评论(0)    收藏  举报