RAGFlow 学习教程

发表于 2026-03-24 更新于 2026-05-17 分类于 Agent 阅读次数：本文字数： 5.8k 阅读时长 ≈ 21 分钟

《RAGFlow 学习手册》

文档核心说明

本文档是基于 RAGFlow 最新稳定版（v0.16+）的标准化学习资料，整合了多轮技术会话的核心内容，去重重构后形成符合学习认知的完整知识体系。

适用人群：RAG 技术学习者、RAGFlow 运维人员、企业架构师、业务系统集成开发者
覆盖模块：基础入门认知、环境部署配置、Web 端核心功能、Python SDK 开发、底层技术原理、企业级项目落地全流程

一、基础入门认知

1.1 RAGFlow 核心定位

RAGFlow 是一款基于深度文档理解的开源 RAG（检索增强生成）引擎，支持各类复杂格式文档的智能解析与问答，可快速搭建企业级知识库与对话助手，核心优势是解决传统 RAG 工具文档解析能力弱、幻觉率高的痛点。

1.2 支持的复杂文档格式

RAGFlow 基于自研 DeepDoc 深度文档理解引擎，原生支持8 大类、23 + 种主流及专业复杂格式的全结构化智能解析，完整覆盖：

格式大类	核心支持的格式与能力
PDF 全场景	原生可复制 PDF、扫描件 / 影印件 PDF、复杂表格 PDF、公式类 PDF、图文混排 PDF、加密 / 超大体积 PDF
办公文档	Word、Excel、PPT、WPS 系列、ODF 开源办公格式、RTF
图片 / 扫描件	JPG/PNG/TIFF/HEIC 等主流图片，支持 OCR 识别、表格 / 公式提取、多模态理解
专业领域文档	法律合同、学术论文 / LaTeX、简历、技术源码 / Markdown、电子书、电子邮件
其他格式	网页 / HTML、字幕 / 会议转写文本、压缩包（自动解压解析）

二、环境部署与初始化

2.1 前置环境要求

配置项	最低要求	推荐生产配置
操作系统	Linux(Ubuntu 22.04+)/macOS	Ubuntu 22.04 LTS
CPU	8 核	16 核 +
内存	8GB	32GB+（大文档 / 多并发场景建议 64GB）
磁盘	50GB+ SSD	200GB+ 高速 SSD
依赖	Docker 20.10+、Docker Compose v2+	最新稳定版 Docker 引擎

系统内核参数调整（必须执行）

RAGFlow 依赖 Elasticsearch，需调整内存映射参数，否则服务会启动失败：

# 临时生效（重启后失效）
sudo sysctl -w vm.max_map_count=262144

# 永久生效
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2.2 单机一键部署（POC / 测试环境）

步骤 1：克隆官方仓库

1 2	git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker

步骤 2：自定义环境配置

1
2
3

cp .env.example .env
# 可修改端口、镜像版本、内存配置等
vim .env

步骤 3：启动服务

# CPU版本（绝大多数场景适用）
docker compose -f docker-compose.yml up -d

# GPU加速版本（需NVIDIA显卡+驱动+CUDA环境）
# docker compose -f docker-compose-gpu.yml up -d

步骤 4：访问 Web 界面

访问地址：http://\<你的服务器IP\>（若修改了端口，需加上端口号）
默认管理员账号：admin，默认密码：admin，首次登录强制修改密码。

2.3 生产级集群部署架构

正式项目必须使用高可用集群架构，避免单点故障，核心架构如下：

Text

┌─────────────────────────────────────────────────────────────────────┐
│                        负载均衡层（Nginx/Ingress）                  │
│  （HTTPS加密、请求转发、限流熔断、IP白名单、WAF防护）              │
├─────────────────────────────────────────────────────────────────────┤
│                        应用服务层（多副本）                          │
│  API Server 3副本、Controller 2副本（任务调度）                     │
├─────────────────────────────────────────────────────────────────────┤
│                        任务执行层（弹性扩容）                        │
│  Worker节点（文档解析/向量化/检索/LLM推理），按业务量弹性扩缩容    │
├─────────────────────────────────────────────────────────────────────┤
│                        中间件层（高可用集群）                        │
│  Redis集群、MinIO分布式集群                                        │
├─────────────────────────────────────────────────────────────────────┤
│                        存储层（高可用集群）                          │
│  PostgreSQL主从集群、ES/Milvus集群（向量+全文检索）                │
└─────────────────────────────────────────────────────────────────────┘

生产环境组件配置参考

组件	最低生产配置	高并发场景推荐配置
API Server	2 核 4G，2 副本	4 核 8G，3 + 副本
Worker 节点	4 核 8G，2 节点	8 核 16G，4 + 节点，GPU 加速
PostgreSQL	2 核 4G，SSD，主从架构	4 核 8G，SSD，一主两从
Elasticsearch/Milvus	4 核 8G，SSD，3 节点集群	8 核 16G，高速 SSD，3 + 节点集群
Redis	2 核 4G，3 节点主从集群	4 核 8G，集群模式
MinIO	2 核 4G，分布式集群	4 核 8G，多节点分布式集群

2.4 系统初始化配置

1. API Key 获取

登录 RAGFlow Web 界面
点击左侧菜单栏 「系统设置」→「API 密钥」
点击「生成新的 API 密钥」，复制保存密钥（仅显示一次，丢失需重新生成）

2. 大语言模型（LLM）配置

RAGFlow 本身不内置大模型，需配置第三方 LLM 接口，支持 OpenAI、通义千问、文心一言、DeepSeek、Ollama 本地模型等：

点击左侧菜单栏 「系统设置」→「模型管理」
选择对应的模型厂商，填入 API Key、Endpoint 等信息，点击「测试连接」
测试通过后，点击「保存」，并设置默认聊天模型。

3. 嵌入模型配置

嵌入模型用于文档向量化，直接影响检索精度，一个知识库（数据集）只能使用一个嵌入模型，一旦选定并解析文档后，无法修改：

同路径「模型管理」→「嵌入模型」
选择内置模型，或配置第三方 API 嵌入模型，中文场景优先使用BAAI/bge\-large\-zh\-v1\.5。

三、Web 端核心功能使用

3.1 知识库（数据集）管理

知识库是文档管理、向量存储的核心单元，用于统一管理文档、索引与配置。

1. 创建知识库

点击顶部导航 「知识库」，点击右上角 「+ 新建」
填写知识库名称，选择语言
核心配置：
- 嵌入模型：选择提前配置好的嵌入模型（选定后不可修改）
- 分块方法（模板）：根据文档类型选择，核心模板如下：
  | 分块模板 | 适用文档类型 | 核心特点 |
  |----------|--------------|----------|
  | General | 通用文档、常规报告、网文 | 通用智能分块，适配大多数场景 |
  | Q&A | 问答对、FAQ、Excel 题库 | 按问答对拆分，精准匹配问题 |
  | Laws | 法律合同、法规条款 | 精细切分，保留条款完整性和逻辑 |
  | Manual | 产品手册、技术文档、操作指南 | 按章节 / 步骤拆分，保留层级结构 |
  | Table | 财务报表、Excel 表格、数据清单 | 强化表格识别与抽取，保留表格语义 |
  | Paper | 学术论文、期刊文献 | 识别摘要、章节、参考文献、公式 |
  | Resume | 简历文档 | 结构化解析，提取个人信息、经历等字段 |
点击「保存」，完成知识库创建。

2. 知识库权限与管理

支持「私有 / 团队 / 公开」三级权限，可指定用户 / 用户组的访问权限
支持按业务线 / 部门拆分知识库，避免所有文档混在一个库中导致检索混乱

3.2 文档上传与智能解析

1. 上传文档

进入创建好的知识库，点击 「+ 添加文件」，支持：

本地文件上传：支持 PDF、Word、Excel、PPT、图片、扫描件等数十种格式
网页抓取：输入 URL，自动爬取网页内容
批量上传：支持多文件同时上传，单文件最大支持 GB 级

2. 解析配置与执行

上传完成后，可对单个文件设置解析规则：
- 扫描件 / PDF 图片：开启「OCR 识别」
- 表格密集型文档：开启「表格抽取」
点击文件后的「播放」按钮，开始单文件解析；或点击「全部解析」，批量处理所有文件
等待解析完成，进度条变绿即为成功。

3.3 分块精细化管理

RAGFlow 核心优势是分块可视化与可干预，可大幅降低问答幻觉，提升准确率：

解析完成后，点击文件名，进入「切片」页面
可查看所有自动拆分的文本块，核心操作：
- 双击文本块，可手动修改内容、补充关键词、修正识别错误
- 可拆分 / 合并文本块，调整分块粒度
- 可删除无效、冗余、错误的文本块
- 可为关键文本块设置权重，提升检索优先级
修改完成后，点击「保存」，自动更新向量索引。

3.4 检索测试与对话助手

1. 检索测试

文档构建完成后，进入「检索测试」页面，输入测试问题，可查看检索到的相关文本块、相似度得分，验证检索精度。

2. 创建对话助手

知识库就绪后，可创建专属对话助手，实现基于知识库的智能问答：

点击顶部导航 「助手」，点击右上角 「+ 新建」
基础配置：填写助手名称，关联知识库，选择聊天模型
高级配置：
- 系统提示词：限定助手的回答风格、范围、规则，例如你是公司制度问答助手，仅基于提供的知识库内容回答，禁止编造信息，答案需标注引用来源
- 模型参数：温度设置为0.1-0.3，降低幻觉，提升答案稳定性
点击「保存」，即可进入聊天界面，测试基于知识库的问答，答案会自动关联原文引用，支持点击溯源。

四、Python SDK 开发与集成

4.1 SDK 安装与初始化

1. 安装 SDK

1	pip install ragflow-sdk

2. 初始化客户端

from ragflow_sdk import RAGFlow

# 本地部署版初始化
client = RAGFlow(
    api_key="你的RAGFlow API Key",
    base_url="http://你的RAGFlow服务IP/域名",
    timeout=60,  # 单次请求超时时间（秒）
    max_retries=3  # 请求失败自动重试次数
)

# 测试连接
try:
    datasets = client.list_datasets(page_size=1)
    print("RAGFlow 连接成功！")
except Exception as e:
    print(f"连接失败：{e}")

4.2 知识库全生命周期管理

1. 创建知识库

# 完整参数创建
dataset = client.create_dataset(
    name="财务报表知识库",
    description="公司2023-2025年财务报表、审计报告",
    embedding_model="BAAI/bge-large-zh-v1.5@BAAI",
    permission="me",
    chunk_method="table",
    parser_config={
        "chunk_token_num": 512,
        "delimiter": "\\n",
        "layout_recognize": True
    }
)
print(f"知识库创建成功，ID：{dataset.id}")

2. 查询与更新知识库

# 列出所有数据集
all_datasets = client.list_datasets(page=1, page_size=30)

# 更新知识库配置
dataset.update({
    "name": "公司财务知识库",
    "permission": "team"
})

# 删除知识库
client.delete_datasets(ids=["数据集ID1"])

4.3 文档与分块管理

1. 上传与解析文档

# 上传文档
file_path = "./员工手册.pdf"
dataset.upload_documents([
    {
        "display_name": "2025版员工手册.pdf",
        "blob": open(file_path, "rb").read()
    }
])

# 同步解析文档
docs = dataset.list_documents()
doc_ids = [doc.id for doc in docs]
parse_results = dataset.parse_documents(document_ids=doc_ids)

2. 分块精细化管理

# 获取目标文档
doc = dataset.list_documents(name="2025版员工手册.pdf")[0]

# 手动添加分块
chunk = doc.add_chunk(
    content="公司年假有效期为自然年1月1日至12月31日，未休年假可延期至次年3月31日，逾期清零",
    important_keywords=["年假", "有效期", "延期", "清零"]
)

# 更新分块
chunk.update({
    "content": "修改后的分块内容",
    "important_keywords": ["年假", "有效期", "延期规则"]
})

4.4 检索与对话能力调用

1. 知识库检索

# 执行检索
retrieve_result = client.retrieve(
    question="年假可以延期到什么时候？",
    dataset_ids=["数据集ID1"],
    page_size=10,
    similarity_threshold=0.2
)

# 遍历检索结果
for chunk in retrieve_result:
    print(f"相似度：{chunk.similarity}")
    print(f"来源文档：{chunk.document_name}")
    print(f"分块内容：{chunk.content}")

2. 聊天助手与多轮对话

# 获取助手
assistant = client.list_chats(name="企业制度问答助手")[0]

# 创建会话
session = assistant.create_session(name="员工咨询会话1")

# 流式对话
print("助手回复：", end="", flush=True)
full_content = ""
for message in session.ask(
    question="年假最多可以申请多少天？",
    stream=True
):
    new_content = message.content[len(full_content):]
    print(new_content, end="", flush=True)
    full_content = message.content

3. OpenAI 兼容接口

RAGFlow 提供完全兼容 OpenAI 格式的接口，可直接使用 OpenAI SDK 无缝切换：

from openai import OpenAI

client = OpenAI(
    api_key="你的RAGFlow API Key",
    base_url="http://你的RAGFlow服务地址/api/v1/chats_openai/<聊天助手ID>"
)

completion = client.chat.completions.create(
    model="model",
    messages=[{"role": "user", "content": "年假可以延期到什么时候？"}]
)
print(completion.choices[0].message.content)

五、底层核心技术原理

5.1 端到端全流程架构

RAGFlow 采用前后端解耦的微服务架构，将 RAG 全流程拆解为独立可扩展的服务模块，通过消息队列解耦重型任务，实现高并发、高可用的生产级部署。

1. 索引构建（文档入库）流程

graph LR
    A[用户上传文档/URL抓取] --> B[API服务接收请求]
    B --> C[文件存入MinIO + 元数据写入PostgreSQL]
    C --> D[Controller创建解析任务，推入Redis任务队列]
    D --> E[Worker节点获取任务，调用DeepDoc引擎]
    E --> F[文档深度解析与结构化]
    F --> G[智能语义分块]
    G --> H[调用嵌入模型，文本块向量化]
    H --> I[向量+原文+元数据写入向量/全文数据库]
    I --> J[索引构建完成，等待检索调用]```

#### 2\. 查询问答（用户对话）流程

```mermaid
graph LR
    A[用户输入问题] --> B[API服务接收请求]
    B --> C[查询预处理与增强]
    C --> D[调用同一嵌入模型，问题向量化]
    D --> E[多路混合检索召回]
    E --> F[检索结果融合]
    F --> G[重排序Rerank精排]
    G --> H[Prompt工程与上下文组装]
    H --> I[调用LLM大模型执行推理生成]
    I --> J[答案校验与后处理]
    J --> K[返回最终答案给用户]```

### 5\.2 核心模块：DeepDoc 深度文档理解引擎

DeepDoc 是 RAGFlow 自研的核心差异化模块，解决了传统 RAG 工具 “文档解析丢失语义、结构、多模态信息” 的核心痛点，实现了**像人一样 “阅读” 文档**的视觉驱动解析能力。

#### 底层技术架构

```mermaid
graph TD
    A[输入文档/PDF/图片] --> B[页面渲染与统一预处理]
    B --> C[视觉版面分析]
    C --> C1[基于YOLOv8+LayoutLM的区域定位]
    C --> C2[区域分类：标题/正文/表格/图片/公式]
    C --> C3[阅读顺序还原：多栏排版/跨页内容逻辑拼接]
    C --> D[分区域专项解析]
    D --> D1[文本区域：原生文本提取+OCR兜底]
    D --> D2[表格区域：Table-Transformer结构识别]
    D --> D3[公式区域：公式定位+LaTeX语法生成]
    D --> D4[图片区域：OCR提取+多模态图文描述生成]
    D --> E[结构化内容融合]
    E --> F[输出带层级结构、空间位置、语义关联的高保真文本]```

### 5\.3 智能分块技术原理

RAGFlow 摒弃了传统 “按固定字符数硬拆分” 的方式，采用**基于文档结构与语义单元的模板化智能分块**：

1. **场景化分块模板**：针对不同文档类型设计专属分块逻辑，从根源保证语义完整性

2. **语义边界识别**：通过嵌入模型计算相邻文本的语义相似度，在语义发生跳转的位置自动拆分

3. **跨页内容拼接**：自动识别并拼接跨页面的完整段落、表格，解决 PDF 分页导致的语义断裂问题

4. **全流程可干预**：分块结果可视化展示，支持人工拆分、合并、修改、权重标注

### 5\.4 混合检索与重排序引擎原理

RAGFlow 采用 \\*\\*“多路召回 \- 融合排序 \- 精排去重” 的三级漏斗架构 \\*\\*，核心原理：

1. **混合检索加权融合**：双路并行检索，兼顾语义理解与精确匹配，通过加权公式实现结果融合：

    ```Plain Text
    最终得分 = α × 向量检索归一化得分 + (1-α) × 全文检索归一化得分

重排序（Rerank）精排：先通过低成本的向量 + 全文检索快速召回 Top-100 候选，再通过高算力的 Cross-Encoder 重排模型，对用户问题与每个候选分块做深度语义交互打分，精准判断真实相关性
MMR 去冗余：剔除高度重复的内容，保证最终送入 LLM 的上下文既精准又信息全面

5.5 微服务与任务调度引擎

核心组件协同：
- API Server：基于 FastAPI 构建的请求入口，负责用户认证、请求接收
- Controller：系统的 “大脑”，负责解析 RAG 工作流，将完整流程拆解为独立任务，推入 Redis 任务队列
- Worker 节点：任务执行单元，从 Redis 队列中获取任务，执行文档解析、分块、向量化等具体操作，支持横向扩展
- Redis：核心消息队列与缓存中间件，实现任务的异步分发、状态管理
DAG 工作流引擎：所有 RAG 流程都被抽象为 DAG 有向无环图，支持可视化拖拽编排，支持条件分支、循环、失败重试等逻辑

六、企业级项目落地全流程

6.1 需求评估与方案设计

1. 业务场景适配性判断

高适配场景（核心优势场景）	低适配 / 不建议场景
企业内部制度 / 流程 / 手册智能问答	强实时动态数据查询
智能客服 / 售后 FAQ 问答	纯逻辑推理 / 复杂数学计算
法律合同 / 法规条款 / 合规审核	强主观判断的决策类场景
制造业设备维保 / 工艺规范 / 故障排查	纯开放闲聊 / 情感陪伴
金融投研 / 财报解读 / 行业研报分析	单一场景、文档量少于 10 份
教育行业教辅资料 / 知识点 / 题库智能答疑	涉密级别过高、无法数字化的文档

2. 量化指标定义

避免模糊需求，必须定义可量化的验收指标：

业务指标：员工制度查询效率提升 80%、客服标准化问题自动解决率≥70%
技术指标：文档解析成功率≥98%、检索召回率≥90%、问答准确率≥95%、幻觉率≤2%
非功能需求：合规要求、高可用 SLA≥99.9%、细粒度权限管控

6.2 知识体系构建与数据治理

80% 的 RAG 项目效果问题，都源于数据治理不到位，核心操作：

文档标准化预处理：
- 格式统一：优先使用可编辑的 PDF/Word 格式，扫描件提前做高清化处理
- 内容清洗：去除水印、冗余内容，统一术语，过滤过期、作废的文档
- 合规校验：去除涉密、敏感信息，做数据脱敏
知识库拆分原则：
绝对禁止把所有文档放到一个大知识库中，按业务线 / 部门、文档类型、权限粒度拆分，同一个业务域的知识库使用同一个嵌入模型。
知识全生命周期管理：
- 增量更新：对接企业文档系统，实现文档自动同步更新
- 版本管理：保留历史版本，自动下线失效版本
- 定期复盘：每月梳理用户提问日志，补充未覆盖的知识点

6.3 主流场景落地方案

1. 企业内部智能知识助手

落地步骤：梳理制度文档→按部门拆分知识库→配置专属助手→对接企业微信 / OA
效果参考：常规制度问题自动解决率 87%，HR 重复答疑工作量降低 65%
集成示例：企业微信机器人对接，零代码快速落地

2. 智能客服与售后问答系统

落地步骤：梳理产品手册 / FAQ→按产品线拆分知识库→配置客服助手→对接在线客服系统
效果参考：客服问题自动化解决率从 34% 提升至 67%，平均响应时间从 120 秒降至 15 秒

3. 法律合规与合同审查助手

落地步骤：梳理法规 / 合同模板→使用 Laws 分块模板→开启知识图谱→对接合同管理系统
效果参考：合同初审时间从 2 小时缩短至 10 分钟，合规风险检出率提升 80%

4. 制造业设备维保助手

落地步骤：梳理设备手册 / 维修记录→按设备型号拆分知识库→对接 MES 系统
效果参考：设备故障平均处理时间从 4 小时缩短至 40 分钟，停机时间降低 50%

6.4 上线前测试与优化

1. 多维度测试体系

功能测试：验证全流程功能无 bug
效果测试：构建标准化测试集，量化评估召回率、准确率、幻觉率
性能测试：模拟并发，验证响应时延、稳定性
安全测试：验证权限、渗透、合规性

2. 效果优化方法论

检索优化：使用中文优化的嵌入模型，开启 Rerank 重排序，调整检索参数
幻觉抑制：优化 Prompt 约束，降低模型温度，开启引用溯源
解析优化：核心文档人工校验分块，修正识别错误

6.5 生产运维与避坑指南

1. 全链路监控与备份

搭建 Prometheus+Grafana 监控面板，监控系统、业务、效果指标
定时备份核心数据，异地存储，建立高可用容灾机制

2. 企业落地避坑指南

坑 1：盲目追求大模型，忽略数据治理：80% 的精力放在数据治理上，数据是根基，模型只是放大器
坑 2：一个大库存所有文档，检索混乱：按业务线拆分知识库，避免噪声干扰
坑 3：一次上传文档后就不管了，知识过时：建立增量更新机制，定期清理过期内容
坑 4：POC 单机部署，直接上线生产：生产环境必须使用集群部署，保证高可用
坑 5：敏感行业使用公网 API，合规风险：私有化部署，对接本地模型，数据不出内网
坑 6：忽略权限管控，数据泄露：设置细粒度权限，操作全程留痕
坑 7：为了 RAG 而 RAG，脱离业务目标：以业务目标为核心，先落地 MVP 验证价值

核心知识点速览

RAGFlow 是基于深度文档理解的开源 RAG 引擎，核心优势是复杂文档解析能力与低幻觉率
一个知识库只能使用一个嵌入模型，选定后无法修改，需提前规划
中文场景优先使用BAAI/bge\-large\-zh\-v1\.5嵌入模型，业务场景将 LLM 温度设置为 0.1-0.3
80% 的 RAG 项目效果问题源于数据治理，文档标准化、分块优化是核心
禁止将所有文档放到一个知识库，按业务线 / 部门拆分，避免检索混乱
检索采用 “多路召回 - 融合排序 - 精排去重” 的三级架构，开启 Rerank 可大幅提升精准度
敏感行业必须私有化部署，对接本地模型，保证数据全链路不出内网
建立知识全生命周期管理，实现文档自动增量更新，避免知识过时
生产环境必须使用集群部署，建立监控、备份、容灾机制，保证高可用
落地要以业务目标为核心，先落地 MVP 验证价值，再逐步扩展功能