RAGFlow 从入门到精通：完整学习教程

第一章：认识 RAGFlow

1.1 什么是 RAG？

在深入了解 RAGFlow 之前，我们需要先理解 RAG（Retrieval-Augmented Generation，检索增强生成）这个核心概念。

大语言模型（LLM）的固有局限

大语言模型虽然能力强大，但存在几个根本性的局限：

1. 知识截止日期：模型训练完成后，其知识就停留在训练数据的截止时间点，无法获取之后产生的新信息。例如，GPT-4 的知识截止日期是 2023 年，它无法知道 2024 年之后发生的事件。

2. 领域知识缺失：LLM 对你公司的内部文档、专有数据、机密信息一无所知。即使是最强大的通用模型，也无法回答"我们公司去年的营收是多少"这类内部问题。

3. 幻觉问题（Hallucination）：当 LLM 遇到不知道的问题时，它倾向于"编造"一个听起来合理的答案，而不是承认自己不知道。这种现象被称为"幻觉"，在医疗、金融、法律等对准确性要求极高的领域，幻觉可能带来严重的后果。

4. 难以更新和定制：重新训练或微调一个 LLM 需要大量的计算资源和时间，成本高昂，无法满足快速变化的信息需求。

RAG 的诞生与核心原理

RAG（Retrieval-Augmented Generation）正是为解决这些问题而生的。它的工作原理可以概括为经典的三步流程：

用户提问 → 第一步：检索（Retrieval）→ 第二步：增强（Augmented）→ 第三步：生成（Generation）→ 最终回答

第一步，检索（Retrieval）：当用户提出问题时，系统先从知识库（Knowledge Base）中检索出与问题最相关的文档片段。这个检索过程可以是基于关键词的全文检索（如 Elasticsearch），也可以是基于语义的向量检索（通过 Embedding 模型将文本转化为向量后计算相似度），或者两者结合的混合检索。

第二步，增强（Augmented）：将检索到的文档片段作为上下文（Context），与用户的问题一起拼接成一个结构化的 Prompt。这个 Prompt 通常包含三个部分：系统指令（System Instruction）、检索到的上下文、以及用户的问题。

第三步，生成（Generation）：将增强后的 Prompt 发送给大语言模型（LLM），由 LLM 基于提供的上下文生成准确的、有依据的回答。由于 LLM 在生成时"看到"了相关的参考资料，它不需要依赖自己的"记忆"来回答，大大降低了幻觉的产生。

这就好比你参加考试时允许翻书------LLM 不再只凭"记忆"回答问题，而是有据可查，回答的准确性和可信度都得到了显著提升。

RAG vs 微调（Fine-tuning）对比

理解了 RAG 之后，很多人会问：为什么不直接用微调（Fine-tuning）来让模型学习新知识？以下是 RAG 和微调的核心区别对比：

维度	RAG	微调（Fine-tuning）
知识更新	即时更新：只需更新知识库中的文档	需要重新训练，周期长、成本高
幻觉控制	强：回答基于检索到的上下文	弱：模型仍可能自由发挥
透明可追溯	是：每条回答都可追溯到原文	否：无法知道模型从哪里"学到"的信息
实施成本	低：无需训练，只需配置检索管道	高：需要 GPU 资源、训练数据、技术 expertise
适用场景	知识库问答、企业内部文档查询	改变模型的写作风格、行为模式、输出格式
推理速度	稍慢（增加检索步骤）	与普通 LLM 推理速度一致
对长文档的支持	天然支持：文档可被切块索引	受限于模型最大上下文长度

总的来说，RAG 和微调并非互斥关系，而是互补的。在实际应用中，很多企业同时使用两者：用 RAG 让模型访问最新的知识库，用微调让模型适应特定的输出风格和行为规范。

1.2 RAGFlow 是什么？

RAGFlow 是由 InfiniFlow 团队开发的一款开源 RAG 引擎，目前在 GitHub 上已获得超过 74,000 颗 Star，是 2025 年 GitHub 年度 Top 10 项目之一。它的核心定位是：基于深度文档理解，构建优越的 AI Agent 上下文层（Build a superior context layer for AI agents）。

与市面上其他 RAG 框架不同，RAGFlow 并不是一个简单的"文档切块 + 向量检索"的管道，而是一个端到端的、面向企业级场景的完整 RAG 解决方案。它提供了从文档解析、知识切分、向量化存储、智能检索、到 Agent 工作流编排的全链路能力，并且全程提供可视化操作界面，这意味着你不需要编写一行代码就能搭建起一个企业级的 RAG 系统。

RAGFlow 的发展历程（简要）

• 2024 年初：RAGFlow 首次开源，凭借其深度文档解析能力迅速获得关注
• 2024 年中：发布 Agent 工作流功能，支持可视化编排
• 2025 年初：Star 数突破 50,000，成为 GitHub 增长最快的开源项目之一
• 2025 年底：Star 数突破 74,000，入选 GitHub 年度 Top 10 项目
• 2026 年：持续迭代，增强 MCP 集成、AI Search 等企业级功能

1.3 RAGFlow 的核心优势

RAGFlow 之所以能在众多 RAG 框架（如 LangChain、LlamaIndex、QAnything、Dify 等）中脱颖而出，主要依靠以下几个核心优势：

深度文档理解（Deep Document Understanding）

这是 RAGFlow 的杀手锏。传统 RAG 系统处理 PDF 时往往只能提取纯文本，遇到表格、图片、复杂排版就束手无策。RAGFlow 内置了 DeepDoc 和 MinerU 两套文档解析引擎，能够智能识别文档中的标题层级、表格结构、图片内容、页眉页脚、公式等复杂元素，确保信息不丢失、不错乱。

具体来说，DeepDoc 和 MinerU 能够：

• 识别文档的版面结构（标题、正文、页眉、页脚、页码区域）
• 提取复杂表格（包括合并单元格、跨页表格）
• 识别并提取 LaTeX 数学公式
• 对扫描件进行 OCR 文字识别
• 识别图片并提取图片中的文字（OCR）
• 保持文档的层级结构和阅读顺序

模板化智能分块（Templated Chunking）

RAGFlow 提供了 11 种预设分块模板：General（通用）、Q&A（问答对）、Book（书籍）、Laws（法律法规）、Manual（产品手册）、Table（表格）、Paper（学术论文）、Resume（简历）、Picture（图片）、Tag（标签）、One（整文件）。每种模板针对不同的文档类型优化了分块策略，而不是简单粗暴地按固定字数切割。模板的选择直接影响检索效果------选对了模板，检索准确率可能从 60% 提升到 90% 以上。

可追溯的引用（Traceable Citations）

RAGFlow 的每一个回答都能追溯到原始文档的具体位置，用户可以点击查看原文出处，甚至高亮显示对应的文档段落。这在对准确性要求极高的企业场景（如法律、金融、医疗）中尤为关键。引用信息包括：文档名称、页码、具体的段落文本，以及该段落在原文中的位置。

可视化 Agent 工作流（Visual Agent Workflow）

RAGFlow 提供了基于画布（Canvas）的拖拽式 Agent 编排能力，你可以通过连线的方式组合 LLM 节点、检索节点、分类节点、工具节点等，构建出复杂的多轮对话、意图识别、多知识库路由等智能应用，全程无需编写代码。这大大降低了构建复杂 AI 应用的门槛。

混合检索与重排（Hybrid Search & Reranking）

支持全文检索（关键词匹配）、向量语义检索（语义相似度匹配）、以及混合检索（两者加权结合）三种策略。并可在检索后进行重排（Rerank）------先用轻量级方法召回大量候选结果，再用 Rerank 模型对候选结果进行深度相关性排序，确保最相关的结果排在前面。

广泛的模型兼容性

支持 OpenAI、Azure OpenAI、Anthropic Claude、阿里通义千问、百度文心一言、智谱 AI GLM、DeepSeek、Moonshot（月之暗面）、零一万物、Minimax、Cohere、Jina 等云端 API，以及 Ollama、LocalAI、LM-Studio、vLLM 等本地部署方案，覆盖了几十种 LLM 和 Embedding 模型提供商。任何兼容 OpenAI API 格式的服务都可以无缝接入。

MCP 协议支持

RAGFlow 支持 MCP（Model Context Protocol）标准协议，可以作为 MCP Server 被外部 AI 工具（如 Claude Desktop、Cursor、Qoder 等）调用，也可以在 Agent 工作流中通过 MCP Client 连接外部工具服务。这使得 RAGFlow 能够融入更广泛的 AI 工具生态。

1.4 与竞品的对比

特性	RAGFlow	LangChain	LlamaIndex	Dify
深度文档解析	✅ 独家 DeepDoc/MinerU	❌ 依赖外部解析器	❌ 依赖外部解析器	❌ 基础解析
可视化操作界面	✅ 完整 Web UI	❌ 代码为主	❌ 代码为主	✅ 完整 Web UI
可视化 Agent 工作流	✅ 拖拽式画布	❌ 代码编排	❌ 代码编排	✅ 可视化编排
模板化分块	✅ 11 种模板	❌ 需要自定义	⚠️ 基础分块策略	⚠️ 有限模板
引用溯源	✅ 精准定位到原文	❌ 需要自定义	⚠️ 基础引用	✅ 支持引用
MCP 协议	✅ 完整支持	❌ 不直接支持	❌ 不直接支持	❌ 不直接支持
部署复杂度	⚠️ 低到中（Docker 一键）	⚠️ 中（需要自行组装）	⚠️ 中（需要自行组装）	⚠️ 低（Docker）
二次开发灵活性	⚠️ 中（通过 API）	✅ 极高（代码级）	✅ 极高（代码级）	⚠️ 中（通过 API）

1.5 系统架构总览

RAGFlow 的整体架构可以分为以下几个层次，自下而上构成完整的 RAG 管道：

数据接入层

支持上传各种格式的文件（PDF、Word、Excel、PPT、TXT、Markdown、图片等），也支持通过 RESTful API 批量导入数据。文件上传后会被存储在 MinIO 对象存储中，元数据记录在 MySQL 数据库中。

文档解析层

由 DeepDoc 和 MinerU 两大解析引擎驱动。这一层负责：

• 文档格式转换：将各种文件格式统一转换为结构化的中间表示
• OCR 识别：对扫描件和图片进行光学字符识别
• 版面分析（Layout Analysis）：识别文档中的标题、正文、表格、图片等区域
• 表格提取：将表格区域转化为结构化的 HTML/Markdown 格式
• 公式识别：提取 LaTeX 数学公式

知识切分层

根据选定的分块模板（Chunk Method），将解析后的文档内容切分成语义合理的知识块（Chunk）。每个 Chunk 包含一段文本内容、在原文档中的位置信息（页码、坐标）、以及元数据（如所属章节、标签等）。

向量化与存储层

使用 Embedding 模型将知识块转化为高维向量（如 1024 维），存入向量数据库。RAGFlow 默认使用 Elasticsearch 或 Infinity 数据库作为向量存储引擎。同时保留知识的原文文本和元数据，用于全文检索和引用展示。

检索与重排层

接收用户查询，执行混合检索（向量检索 + 全文检索），对结果进行融合、去重、排序。如果配置了 Rerank 模型，还会对候选结果进行二次深度排序。

LLM 生成层

将检索结果与用户问题按照指定的 Prompt 模板拼接后，调用 LLM 生成最终回答。这一层还负责处理引用标注、流式输出、多轮对话上下文管理等。

Agent 编排层

提供基于 DAG（有向无环图）的工作流引擎，支持可视化编排各类节点（检索、生成、分类、工具调用、条件分支等），实现复杂的业务逻辑和智能应用。

API 与集成层

提供完整的 RESTful API，支持外部系统集成调用。同时提供 Python SDK 和 MCP Server 支持，方便开发者将 RAGFlow 的能力嵌入到自己的应用中。

第二章：环境准备与部署

2.1 系统要求

在部署 RAGFlow 之前，请确保你的环境满足以下最低要求：

硬件要求

配置项	最低要求	推荐配置
CPU	4 核	8 核及以上
内存	8 GB	16 GB+
磁盘空间	20 GB 可用	100 GB+（取决于文档量）
GPU（可选）	不强制要求	NVIDIA GPU 8GB+（运行本地模型时建议）
架构	x86_64	x86_64（暂不支持 ARM）

软件要求

软件	最低版本	说明
Docker	24.0.0+	容器运行环境
Docker Compose	v2.26.1+	Docker 编排工具
操作系统	Linux/macOS/WSL2	Windows 需通过 WSL2 运行

需要注意的是，RAGFlow 的文档解析和检索功能对 GPU 并非硬性要求，使用 CPU 即可正常运行。但如果你需要处理大量文档（日均解析 1000+ 页）或使用本地 LLM 模型（如通过 Ollama 部署 qwen2.5:7b 等），建议配备 GPU 以获得更好的性能。

2.2 Docker Compose 部署（推荐方式）

Docker Compose 是官方推荐的最简单部署方式，只需几条命令即可完成全部服务的启动。

第一步：克隆仓库

git clone https://github.com/infiniflow/ragflow.git
cd ragflow

如果你需要特定版本，可以切换到对应 tag，例如：

git checkout v0.25.0

建议使用稳定的 Release 版本而不是 main 分支的最新代码，因为 main 分支可能包含尚未充分测试的改动。

第二步：配置环境变量

进入 docker 目录，复制并编辑环境变量文件：

cd docker
cp .env.example .env

用文本编辑器打开 .env 文件，以下是关键配置项的详细说明：

# ===== 端口配置 =====
# RAGFlow Web 服务端口，默认 9380
SVR_HTTP_PORT=9380

# ===== 数据库引擎选择 =====
# 可选值：infinity 或 elasticsearch
# infinity：RAGFlow 自研的轻量级向量数据库，安装简单，适合中小规模（文档数 < 10,000）
# elasticsearch：成熟的企业级搜索引擎，适合大规模生产环境（文档数 > 10,000）
DOC_ENGINE=infinity

# ===== 存储配置 =====
# MinIO 对象存储的访问密钥（生产环境请修改默认值）
MINIO_USER=minio_admin
MINIO_PASSWORD=minio_admin

# MySQL 数据库密码（生产环境请修改默认值）
MYSQL_PASSWORD=ragflow

# ===== Redis 配置 =====
REDIS_PASSWORD=ragflow

# ===== Docker 镜像配置 =====
# 指定使用的 RAGFlow 镜像版本
RAGFLOW_IMAGE=infiniflow/ragflow:v0.25.0

# ===== 网络配置 =====
# 如果你的服务器需要配置 HTTP 代理才能访问外网，在此设置
HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,127.0.0.1

第三步：启动服务

docker compose -f docker-compose.yml up -d

首次启动会拉取所有必要的 Docker 镜像，包括：

• infiniflow/ragflow：RAGFlow 主服务镜像（约 2-3 GB）
• infiniflow/infinity：向量数据库镜像
• mysql:8.0：元数据数据库
• redis:7：缓存服务
• minio/minio：对象存储服务

这个过程可能需要几分钟到几十分钟不等，取决于你的网络速度。你可以通过以下命令查看拉取进度：

docker compose -f docker-compose.yml pull

第四步：验证服务状态

docker compose -f docker-compose.yml ps

所有服务都应处于 running 状态。正常状态下你会看到类似这样的输出：

NAME                    IMAGE                           STATUS   PORTS
ragflow-server          infiniflow/ragflow:v0.25.0      Up       0.0.0.0:9380->9380/tcp
infinity-ragflow        infiniflow/infinity:latest      Up       0.0.0.0:23817->23817/tcp
mysql-ragflow           mysql:8.0                       Up       3306/tcp
redis-ragflow           redis:7                         Up       6379/tcp
minio-ragflow           minio/minio                     Up       0.0.0.0:9000->9000/tcp

如果某个服务状态为 Exited 或 Restarting，可以使用以下命令查看日志排错：

docker compose logs ragflow-server

第五步：访问 Web 界面

打开浏览器，访问 http://localhost:9380（如果是在远程服务器上部署，替换为你的服务器 IP）。首次访问需要注册一个管理员账号------填写用户名、邮箱和密码即可完成注册。

2.3 Windows 环境下的特别注意事项

如果你是在 Windows 上部署，需要特别注意以下几点：

第一步：安装 WSL2

Windows 上的 Docker Desktop 依赖 WSL2（Windows Subsystem for Linux 2）。在 PowerShell（以管理员身份运行）中执行：

wsl --install

安装完成后重启电脑。然后运行 wsl --set-default-version 2 确保使用 WSL2。

第二步：配置 Docker Desktop 资源

打开 Docker Desktop → Settings → Resources，将内存（Memory）调整到 8192 MB（8 GB）或更高，CPU 调整到 4 核以上。

第三步：处理端口冲突

如果你本地已经有服务占用了 9380 端口（比如一些开发工具），可以在 .env 文件中修改端口：

SVR_HTTP_PORT=9390  # 改为其他端口

第四步：配置 Docker 镜像加速（国内用户）

国内用户拉取 Docker 镜像可能会较慢，建议配置镜像加速器。在 Docker Desktop 的 Settings → Docker Engine 中添加：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://mirror.ccs.tencentyun.com",
    "https://hub-mirror.c.163.com"
  ]
}

第五步：文件路径注意事项

WSL2 中的文件系统与 Windows 文件系统不同。建议将 ragflow 项目克隆到 WSL2 内部的文件系统中（如 /home/username/ragflow），而不是 Windows 的 C 盘，因为跨文件系统访问会有性能损失。

2.4 源码部署（开发者方式）

如果你想从源码构建和运行 RAGFlow（通常是为了二次开发或调试），步骤如下：

# 克隆仓库
git clone https://github.com/infiniflow/ragflow.git
cd ragflow

# 创建 Python 虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装 Python 依赖
pip install -r requirements.txt

# 启动基础服务（数据库、缓存等仍然推荐用 Docker）
cd docker
docker compose -f docker-compose-base.yml up -d

# 回到项目根目录，启动 RAGFlow 服务
cd ..

# 启动任务执行器
python rag/svr/task_executor.py &

# 启动 API 服务
python api/ragflow_server.py

源码部署的优势在于：

• 可以直接修改代码并进行调试
• 可以集成自定义的解析引擎或分块策略
• 可以使用最新的开发分支功能

但缺点是需要自行管理 Python 依赖和服务进程，没有 Docker 部署那么简单稳定。

2.5 Kubernetes 部署（生产环境）

对于需要在 Kubernetes 集群中部署的用户，RAGFlow 也提供了 Helm Chart 支持（需要自行从社区获取或根据 Docker Compose 配置自行编写 K8s 清单）。关键要点包括：

• 使用 PersistentVolume 存储 MySQL、MinIO、Elasticsearch 的数据
• 配置 Ingress 暴露 RAGFlow Web 服务
• 使用 ConfigMap 管理环境变量配置
• 为各个服务配置资源限制（Resource Limits）和健康检查（Health Check）

2.6 升级与版本管理

升级步骤：

# 1. 进入项目目录
cd ragflow/docker

# 2. 拉取最新代码
git pull

# 3. 更新镜像
docker compose pull

# 4. 重新启动服务
docker compose up -d

重要提醒：

• 在升级前务必备份数据库和文件存储
• 查看 Release Notes 了解是否有 Breaking Changes
• 对于生产环境，建议先在测试环境验证升级
• 大版本升级（如 v0.24.x → v0.25.x）可能需要执行数据迁移脚本

第三章：快速入门

3.1 注册与登录

首次访问 RAGFlow Web 界面时，你会看到登录/注册页面。

注册流程：

1. 点击页面上的"注册"按钮，进入注册页面
2. 填写用户名（建议使用英文或拼音，避免特殊字符）
3. 填写邮箱地址（用于密码找回和系统通知）
4. 设置密码（建议 8 位以上，包含字母和数字）
5. 点击"注册"按钮完成创建

登录流程：

1. 使用注册时的邮箱和密码登录
2. 登录成功后进入 RAGFlow 的主界面

用户体系说明：

• RAGFlow 支持多用户体系，每个用户有独立的知识库、对话、Agent 空间
• 管理员用户（Admin）拥有系统管理权限，可以管理用户、配置系统设置
• 普通用户只能管理自己的资源
• 不同的用户之间数据完全隔离

首次登录引导： 首次登录后，RAGFlow 会显示一个快速引导页面，建议按照引导步骤完成初始配置。

3.2 配置模型（至关重要的一步）

在使用 RAGFlow 的任何功能之前，你必须先配置好 LLM（大语言模型）和 Embedding（嵌入）模型。这是很多新手容易忽略的一步------如果没有可用的模型，后续的知识库解析、对话、Agent 功能都无法正常运行。

进入模型配置页面：

点击页面右上角的用户头像 → 在下拉菜单中选择"系统设置"（System Settings）→ 在左侧导航栏中选择"模型管理"（Models）。

模型配置界面概览：

模型管理页面分为三个主要区域：

1. LLM 模型列表：显示所有已配置的大语言模型
2. Embedding 模型列表：显示所有已配置的嵌入模型
3. Rerank 模型列表：显示所有已配置的重排模型（可选）
4. 添加模型按钮：用于添加新的模型配置

每种模型的状态通过指示灯显示：绿色表示连接正常，红色表示连接失败。

添加 LLM 模型的详细步骤

点击"添加模型"按钮，在弹出的对话框中选择你的模型提供商，然后填写相关信息。

场景一：使用 OpenAI API

适合有海外服务器或有 OpenAI API 访问权限的用户。

配置参数：

供应商：OpenAI
模型名称：gpt-4o（推荐） / gpt-4o-mini（性价比） / gpt-4-turbo
API Key：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Base URL：https://api.openai.com/v1（保持默认即可）

场景二：使用 DeepSeek API

DeepSeek 是目前国内性价比最高的 LLM API 服务之一，其最新版模型能力接近 GPT-4。

配置参数：

供应商：DeepSeek
模型名称：deepseek-chat（推荐） / deepseek-reasoner（推理模型）
API Key：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Base URL：https://api.deepseek.com/v1

关于 model name 的重要提示：DeepSeek API 中的模型名称会随版本更新而变化。根据 DeepSeek 官方文档，当前（2026 年）使用的模型名称可能是 deepseek-chat。如果连接失败，请在 DeepSeek 官方文档中确认最新的模型名称，或者在 Base URL 中添加 /chat/completions 等路径。如果遇到认证问题（401 错误），请检查 API Key 是否有效以及 API 地址格式是否正确。

场景三：使用 Ollama 本地模型

适合对数据隐私有要求、希望完全离线的场景。

前置条件：已在本机安装并运行 Ollama，且已拉取所需的模型。

配置参数：

供应商：Ollama
模型名称：qwen2.5:7b（或其他已拉取的模型名称）
API Base URL：http://host.docker.internal:11434

这里有一个关键细节：由于 RAGFlow 运行在 Docker 容器中，如果你在本机运行 Ollama，API 地址不能写 localhost 或 127.0.0.1，因为这两个地址在容器内部指向容器自己，而不是宿主机。正确的写法是使用 host.docker.internal 这个特殊域名，Docker 会自动将其解析为宿主机的 IP 地址。

在 Linux 环境下，如果 host.docker.internal 不生效，可以在 docker-compose.yml 中添加以下配置：

services:
  ragflow-server:
    extra_hosts:
      - "host.docker.internal:host-gateway"

或者在 Ollama 配置中允许所有来源的访问：

# 设置环境变量允许外部访问
export OLLAMA_HOST=0.0.0.0

场景四：使用 SiliconFlow（硅基流动）等兼容 OpenAI 格式的中转服务

SiliconFlow 提供了大量开源模型的 API 服务，且完全兼容 OpenAI API 格式。

配置参数：

供应商：OpenAI-API-Compatible
模型名称：Qwen/Qwen2.5-7B-Instruct（或平台上的其他模型名）
API Key：平台提供的 API Key
Base URL：https://api.siliconflow.cn/v1

添加 Embedding 模型的详细步骤

Embedding 模型负责将文本转化为向量，是知识库检索的基础。没有 Embedding 模型，知识库就无法正常工作。

配置方式与 LLM 类似：

使用内置 Embedding 模型（推荐）：

供应商：BAAI（北京智源人工智能研究院）
模型名称：bge-large-zh-v1.5

这是 RAGFlow 内置的 Embedding 模型，无需额外配置即可使用，对中文的支持效果非常好，推荐作为首选。

使用 Ollama 提供的 Embedding 模型：

供应商：Ollama
模型名称：bge-m3（或 nomic-embed-text）
API Base URL：http://host.docker.internal:11434

使用 OpenAI Embedding 模型：

供应商：OpenAI
模型名称：text-embedding-3-large（或 text-embedding-3-small）
API Key：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Base URL：https://api.openai.com/v1

配置验证

配置完成后，确保每个模型旁边的状态指示灯显示为绿色（已连接）。如果显示红色，请检查以下常见问题：

1. API Key 是否正确（注意不要多空格或少字符）
2. Base URL 是否正确（注意末尾的 /v1 路径）
3. 网络连接是否正常（容器能否访问到 API 地址）
4. 对于 Ollama，确认服务是否在运行（ollama list 检查）
5. API 速率限制是否被触发（某些免费 API 有调用次数限制）

3.3 创建第一个知识库

配置好模型后，我们就可以开始创建第一个知识库了。

步骤：

1. 点击左侧导航栏中的"知识库"（Datasets）进入知识库列表页面
2. 点击右上角的"创建知识库"按钮
3. 在弹出的对话框中填写以下信息：

知识库名称：给你的知识库起一个清晰的名字，例如"公司产品手册"、"技术FAQ"等。命名建议包含文档类型信息，方便后续管理。

描述（可选）：简要说明知识库的用途和包含的内容范围。好的描述能帮助其他用户理解知识库的用途。

Embedding 模型：选择你刚才配置的 Embedding 模型。注意：知识库创建后，Embedding 模型不能修改，因为已有向量数据是用该模型生成的，更换模型会导致向量维度不一致。

分块方法（Chunk Method）：选择适合你文档类型的模板。首次使用建议选"General"（通用），后续可以根据文档类型详细选择合适的模板。

解析器（Parser）：选择文档解析引擎。

• DeepDoc（默认）：速度快、资源消耗低，适合大多数标准文档
• MinerU：解析能力更强，尤其适合复杂排版文档，但速度较慢

其它高级设置：可以根据需要配置 Chunk Size（块大小）、Overlap（重叠率）等参数，首次建议保持默认。

4. 点击"确定"后，你的第一个知识库就创建好了

3.4 上传文件与解析

知识库创建完成后，接下来需要上传并解析文档。

上传文件：

1. 点击知识库名称进入知识库详情页
2. 点击"上传文件"（Upload）按钮
3. 选择你要上传的文档（支持多文件选择）
4. 文件开始上传，上传完成后会出现在文件列表中

RAGFlow 支持的文件格式非常丰富：

文件类型	格式	说明
文本文档	TXT, MD	纯文本和 Markdown 格式
Word 文档	DOCX, DOC	建议使用 DOCX，解析效果更好
Excel 表格	XLSX, XLS	表格内容会被提取为结构化数据
PPT 演示文稿	PPTX, PPT	提取幻灯片中的文字内容
PDF 文档	PDF	支持普通 PDF 和扫描件 PDF
CSV 数据	CSV	逗号分隔的数据文件
图片	PNG, JPG, JPEG, TIFF, BMP	结合 OCR 提取文字
邮件	EML	Outlook 邮件格式

解析文件：

1. 上传完成后，文件的状态显示为"未解析"（Unparsed）
2. 点击文件右侧的"解析"按钮（或勾选多个文件后点击"批量解析"）
3. RAGFlow 开始对文件进行解析和分块处理
4. 解析过程中，状态会变为"解析中"（Parsing）
5. 解析完成后，状态会变为"完成"（Completed），并显示绿色的对勾图标

解析过程的时间取决于以下因素：

• 文件大小：越大的文件解析时间越长
• 文件复杂度：纯文本文档解析最快，包含表格、图片的 PDF 较慢
• 解析引擎：DeepDoc 比 MinerU 快
• 系统资源：CPU 和内存资源越充足，解析速度越快

3.5 查看与调整分块结果

解析完成后，点击文件名可以查看解析和分块的结果。这是整个 RAGFlow 中最值得仔细了解的功能之一。

分块结果界面：

分块结果界面分为左中右三个区域：

• 左侧：知识块（Chunk）列表。每个知识块以卡片形式展示，包含文本片段、在原文中的位置（页码）、以及该块的元数据。
• 中间：选中的知识块的详细内容，支持编辑。
• 右侧：原始文档的预览（如果是 PDF 或图片），被当前知识块覆盖的区域会被高亮标注，方便你核对切分是否准确。

手动干预操作：

RAGFlow 允许你对分块结果进行人工干预，这是它区别于其他 RAG 框架的一大亮点：

• 编辑知识块：点击知识块的编辑按钮（铅笔图标），可以直接修改文本内容。这对于修正 OCR 错误、补充缺失信息非常有用。

  • 例如：OCR 将"深度学习"识别为"深度学 习"，你可以手动修正
  • 例如：表格解析后格式错乱，你可以手动调整

• 删除知识块：对于不需要或质量差的知识块，可以点击删除按钮移除。常见的需要删除的情况包括：

  • 封面、目录页的碎片
  • 页眉页脚等无关内容
  • 解析错误导致的内容混乱

• 添加知识块：你可以手动添加新的知识块，例如补充文档中没有但需要的说明信息。

• 重新解析：如果对分块结果整体不满意，可以调整分块参数后点击"重新解析"，系统会覆盖之前的结果。

这种"可干预"的设计是 RAGFlow 的一大亮点------它让你不完全依赖自动化算法，可以在关键环节进行人工校正，确保知识库的质量。

3.6 开始对话

知识库准备好后，就可以开始与 AI 对话了。

创建对话助手：

1. 点击导航栏中的"对话"（Chat）
2. 点击"创建对话"（Create Chat）按钮
3. 配置以下信息：
   • 对话名称：给这个对话助手起个名字，如"产品咨询助手"
   • 关联知识库：选择你刚才创建的知识库（可多选）
   • LLM 模型：选择用于生成回答的 LLM（如 deepseek-chat、gpt-4o 等）
   • 系统提示词（System Prompt）：定义助手的角色和行为

系统提示词示例：

你是一个专业的技术支持助手，请严格基于知识库中的内容回答用户的问题。
回答时请注意：
1. 如果知识库中有相关信息，请引用具体的内容和来源
2. 如果知识库中没有相关信息，请如实告知，不要编造答案
3. 回答应简洁、准确、有条理
4. 对于技术问题，提供具体的操作步骤和注意事项

开始提问：

在对话框输入你的问题，点击发送。RAGFlow 会：

1. 将你的问题发送到知识库进行检索
2. 在知识库中找出最相关的内容
3. 将检索到的内容作为上下文发送给 LLM
4. LLM 基于上下文生成回答
5. 回答以流式（Streaming）方式逐字显示

体验引用的魅力：

你会注意到回答的下方会显示引用的来源信息------包括文档名称、页码和具体的段落。点击引用链接可以查看原文和完整上下文。这是 RAGFlow 最核心的特性之一：每一个回答都可以追溯到原始文档，你可以随时验证 AI 回答的准确性。

第四章：知识库深度配置

4.1 分块模板（Chunk Method）详解

分块策略直接影响检索的准确性------切得太粗，检索精度低，用户问一个具体问题时可能找到含有大量无关内容的块；切得太细，语义可能不完整，LLM 无法获取足够的上下文来生成准确的回答。RAGFlow 提供了 11 种预设模板来适配不同场景。

选择分块模板的核心原则是：让每个知识块在语义上是一个完整的、独立的信息单元，同时块的大小适合 LLM 的上下文窗口。

General（通用）

适用场景：大多数普通文档，如会议纪要、通知、说明文档、博客文章、新闻稿等。

分块策略：智能识别文档的标题层级（H1、H2、H3...），按段落和语义边界进行分块。会尝试保持段落完整性，不会在段落中间切断。

使用建议：如果你不确定该选哪种模板，或者文档类型混杂，选 General 是最安全的选择。这是 RAGFlow 的"万能模板"。

最佳实践：对于 General 模板，建议将 Chunk Size 设置在 300-800 token 之间。如果文档内容高度结构化，可以适当调大；如果内容比较散乱，调小一些效果更好。

Q&A（问答对）

适用场景：FAQ（常见问题解答）文档、知识库问答集、帮助中心文档等。

分块策略：尝试识别文档中的"问题-答案"对结构，将每个问答对作为一个独立的知识块。能识别的常见格式包括：

• "问：... 答：..." 格式
• "Q: ... A: ..." 格式
• "问题：... 答案：..." 格式
• 连续的问号开头段落对

使用建议：如果你的文档本身就是 FAQ 格式，这个模板效果非常好。但如果你的文档不是问答格式，使用这个模板可能会导致分块结果混乱。

最佳实践：在使用 Q&A 模板前，建议先检查几页文档的格式是否符合"问题-答案"对的结构。如果格式不够规范，可以先用 General 模板解析，然后手工将相关段落整理为问答对。

Book（书籍）

适用场景：长篇书籍、电子书、教材、专著等。

分块策略：利用书籍的章（Chapter）、节（Section）、小节（Subsection）结构进行分块。每个章节或子章节作为一个知识块，保留完整的层级信息和上下文。

使用建议：如果文档有明确的目录结构和章节划分，Book 模板能很好地保留书籍的逻辑结构。RAGFlow 会利用 DeepDoc 解析出的标题层级信息来决定分块边界。

最佳实践：配合 Chunk Size 参数使用，一般书籍设置为 800-1500 token 比较合适。如果书籍中有大量代码或公式，建议适当减小。

Laws（法律法规）

适用场景：法律合同、规章制度、行业标准、政策文件等。

分块策略：按条款（Article）、章节（Chapter）、条目（Item）进行分块，保留条文编号（如"第一条"、"第 2.3 节"）和层级关系。

使用建议：法律文档的特点是结构层级明确、条款之间独立性较强。Laws 模板能确保每个条款作为一个独立的知识单元，在检索时精确命中。

最佳实践：对于法律文档，建议启用知识图谱功能，让系统自动抽取法律概念之间的引用关系。

Manual（产品手册）

适用场景：产品说明书、技术手册、操作指南、用户手册等。

分块策略：利用文档中的标题和编号体系进行智能分块。对于产品手册中常见的"步骤"、"警告"、"注意"等元素也会特别处理。

使用建议：产品手册通常包含大量操作步骤和注意事项，Manual 模板能够将这些结构化元素完整保留。

Table（表格）

适用场景：包含大量表格的文档，如财务报表、统计报告、产品规格表、对比表格等。

分块策略：将每个表格（或表格中的重要行）作为一个独立的知识块，保留表格的完整结构信息（表头、行、列关系）。

使用建议：如果你的文档中表格是核心信息载体（比如产品参数对比表），使用 Table 模板可以确保表格信息的完整性。普通文档中有少量表格的情况，使用 General 模板即可。

Paper（学术论文）

适用场景：学术论文、研究报告、技术白皮书等。

分块策略：按摘要（Abstract）、引言（Introduction）、方法（Methodology）、实验（Experiments）、结果（Results）、结论（Conclusion）等学术论文的标准章节结构分块。还会特别处理引用文献部分。

使用建议：对于学术文献，Paper 模板能保持论文的逻辑框架，使得检索时能精确找到论文的特定部分。

最佳实践：处理学术论文时，建议配合 RAPTOR 功能使用，对于需要理解论文整体贡献的问题效果更好。

Resume（简历）

适用场景：个人简历、履历表等。

分块策略：将教育背景、工作经验、专业技能、项目经历、证书资质等各个板块分别切分为独立知识块。还会识别姓名、联系方式等个人信息区域。

使用建议：如果你正在构建一个简历筛选系统，Resume 模板配合 Categorize 节点可以实现自动化的简历分类和候选人匹配。

Picture（图片）

适用场景：包含大量图片或扫描件的文档。

分块策略：结合 OCR 和图像理解技术，将图片中的文字和语义信息提取出来。对于纯图片文档（如扫描的票据、手写笔记等），会先进行 OCR 识别再将识别结果分块。

使用建议：如果文档主要是扫描件或图片，选择 Picture 模板。对于文字为主但包含插图的文档，使用 General 或对应的文本模板即可。

Tag（标签）

适用场景：有标签体系的结构化文档，如带有分类标签的知识库文章。

分块策略：识别文档中的标签信息，将相同标签下的内容归为一个知识块。

使用建议：如果你的文档已经有完善的标签体系（例如某些 Markdown 文档的 tag 字段），Tag 模板可以充分利用已有的分类信息。

One（整文件）

适用场景：短文档（如几段文字）、或你希望保留完整上下文的场景。

分块策略：将整个文件作为一个知识块，不做任何切分。

使用建议：适用于长度不超过 LLM 上下文窗口的短文档。如果文档很长（超过 LLM 上下文窗口），不建议使用 One 模板，因为 GPT 的上下文有限，长文档无法完整传入。

4.2 关键参数调优

在知识库设置中，有几个关键参数可以根据实际场景进行调优。这些参数直接影响检索质量和回答效果。

Chunk Size（块大小）

控制每个知识块的最大 token 数量。

• 默认值：通常在 500 左右
• 建议范围：300 到 2000 token
• 调优指南 ：
  • 文档内容越结构化（如有清晰的标题和段落），块大小可以设得越大
  • 文档内容越散乱，块大小应该设得越小
  • 对于简单的事实类知识（如产品规格），较小的块（300-500）更精确
  • 对于需要综合理解的知识（如技术原理），较大的块（800-1500）更能保持语义完整
  • 不要超过 LLM 的上下文窗口大小

实际案例：某公司在处理产品手册时，将 Chunk Size 从 500 调整为 1000 后，对于"产品性能对比"这类问题的回答质量明显提升，因为相关的技术参数不再被拆分到不同的块中。

Overlap（重叠率）

相邻知识块之间的重叠 token 数量或比例。

• 默认值：10% 到 25%
• 作用：避免语义在分块边界处被截断。例如，一个完整的段落刚好在分块边界处被切开，重叠机制能确保这个段落的结尾部分同时出现在下一个块的开头，保持语义的连续性。
• 调优指南 ：
  • 对于需要保持上下文连续的文档（如小说、故事），适当提高重叠率
  • 对于结构化强的文档（如条款、说明书），可以适当降低重叠率
  • 过高的重叠率会增加存储空间和检索成本（因为数据量变大了）
  • 一般建议 10-20%，不要超过 30%

Similarity Threshold（相似度阈值）

检索时，只有相似度高于该阈值的结果才会被返回和使用。

• 默认值：0.2 到 0.3
• 作用：这是一个过滤器，确保只使用与问题足够相关的知识块
• 调优指南 ：
  • 如果回答中出现过多不相关内容，可以适当提高这个值（如 0.4-0.5）
  • 如果经常出现"未找到相关信息"的提示，可以适当降低（如 0.1-0.15）
  • 对于精确查询（如"产品的价格是多少"），可以设高一些
  • 对于开放性查询（如"介绍一下这个产品"），可以设低一些

Vector Similarity Weight（向量相似度权重）

在混合检索中，控制向量语义相似度和全文检索关键词匹配的权重比例。

• 默认值：向量权重 0.3，关键词权重 0.7
• 作用：向量检索擅长理解语义（能理解同义词和近义表达），全文检索擅长精确匹配（能精确匹配关键词）
• 调优指南 ：
  • 如果文档中专业术语多、需要精确匹配关键词，提高关键词权重（如向量 0.2 + 关键词 0.8）
  • 如果文档中口语化表达多、需要理解语义，提高向量权重（如向量 0.6 + 关键词 0.4）
  • 大多数场景下使用默认值即可获得不错的效果

Top K

检索时返回的最相关结果数量，这些结果会被传递给 LLM 作为上下文。

• 默认值：1024（检索阶段返回较多候选，后续由 LLM 侧过滤）
• 对话侧 Top K：在对话设置中独立控制，一般建议 3 到 8 个
• 调优指南 ：
  • 对于简单的事实类问题，3-5 个结果通常够用
  • 对于需要综合分析的问题，可以尝试 5-10 个
  • 过多的结果会占用 LLM 的上下文窗口，增加 token 消耗
  • 过少的结果可能遗漏关键信息

4.3 高级功能：知识图谱（Knowledge Graph）

什么是知识图谱？

知识图谱是一种结构化的知识表示方式，它由"实体"（Entity）和"关系"（Relation）组成。例如，"张三 担任 CEO 于 某某公司"中，"张三"和"某某公司"是实体，"担任 CEO 于"是关系。

RAGFlow 中的知识图谱

RAGFlow 支持在知识库中自动构建知识图谱。启用后，系统会自动从文档中抽取实体和关系，构建出一张知识网络。

启用方式：

1. 进入知识库的设置页面
2. 找到"知识图谱"（Knowledge Graph）选项
3. 勾选"启用知识图谱"
4. 配置抽取参数（如实体类型、关系类型等）

知识图谱的价值：

1. 跨文档关联：知识图谱可以帮助系统理解不同文档中实体之间的关联关系
2. 多跳推理：支持"多跳"推理，例如从"A 公司属于 B 集团"和"B 集团的 CEO 是张三"推出"A 公司的 CEO 是张三"
3. 结构化展示：回答中可以展示知识图谱中的关系路径，增强回答的可信度

注意事项：

• 知识图谱的抽取依赖 LLM 的能力，会消耗额外的 API 调用量
• 对于结构不明确的文档，知识图谱的抽取效果可能有限
• 知识图谱会占用额外的存储空间
• 构建知识图谱需要额外的处理时间

4.4 高级功能：RAPTOR

什么是 RAPTOR？

RAPTOR（Recursive Abstractive Processing for Tree-Organized Retrieval）是一种层次化的文档索引方法。它会对知识块进行递归式的聚类和摘要，形成一棵"摘要树"。

RAPTOR 的工作原理：

1. 叶子节点：原始的知识块（经过分块后）
2. 中间节点：对叶子节点进行聚类后生成的摘要（层次 1）
3. 更高层次：对中间节点再次聚类和摘要（层次 2、3...）
4. 根节点：整个文档的总体摘要

RAPTOR 的价值：

在检索时，系统不仅可以在叶子节点（原始知识块）层面检索，还可以在中间节点（聚类摘要）层面检索。这对于需要"全局视角"的问题特别有效。

典型场景：

• 传统 RAG 检索"这份报告的主要结论是什么" → 很可能检索到某个具体段落
• 启用 RAPTOR 后检索"这份报告的主要结论是什么" → 能直接命中高层次的摘要节点

启用方式：在知识库设置中勾选"启用 RAPTOR"。

最佳实践：

• RAPTOR 适合长篇文档（如书籍、研究报告、综述论文）
• 对于短文档（如几页的备忘录），RAPTOR 带来的提升有限
• RAPTOR 会增加知识库的构建时间和存储空间
• RAPTOR 的摘要质量取决于 LLM 的能力

第五章：文档解析引擎

5.1 文档解析概述

文档解析是 RAGFlow 的基石。一个 RAG 系统的效果上限，很大程度上取决于文档解析的质量------如果解析阶段就丢失了关键信息，后续的检索和生成环节再怎么优化也无法弥补。

RAGFlow 提供了两套文档解析引擎：DeepDoc （默认）和 MinerU（增强）。两者各有优劣，适用于不同的场景。

5.2 DeepDoc 解析器

DeepDoc 是 RAGFlow 内置的默认文档解析引擎，也是使用最广泛的解析器。

核心能力：

1. 版面分析（Layout Analysis）：使用深度学习模型识别文档中的各种区域类型：

   • 标题区域（Title）：识别 1-6 级标题
   • 正文区域（Body Text）：识别普通段落
   • 表格区域（Table）：识别表格边界及内部结构
   • 图片区域（Figure）：识别图片及图表
   • 页眉页脚（Header/Footer）：识别并过滤页码、页眉页脚
   • 公式区域（Equation）：识别数学公式

2. 表格识别与提取：能够处理复杂的表格结构：

   • 合并单元格（行合并、列合并）
   • 跨页表格（表格在下一页继续）
   • 嵌套表格（表格中嵌套子表格）
   • 无边框表格（通过对齐关系推断表格结构）
   • 表格数据导出为 Markdown 或 HTML 格式

3. OCR 支持：对扫描件或图片格式的 PDF，DeepDoc 会调用 OCR 引擎（基于 PaddleOCR）提取文字。

4. 公式识别：支持 LaTeX 公式的识别和提取，可以识别行内公式和行间公式。

优点：

• 解析速度快，资源消耗低
• 对于大多数标准文档（Word 导出的 PDF、普通报告、网页等）效果良好
• 内置 OCR 支持，无需额外配置

局限：

• 对于复杂排版（多栏、不规则排版）效果一般
• 对于手写体文字识别效果有限
• 对于包含大量公式的学术论文，公式识别可能不够精确

5.3 MinerU 解析器

MinerU 是一个更强大的文档解析引擎，特别适合处理复杂排版的文档。

MinerU 相比 DeepDoc 的优势场景：

场景	DeepDoc	MinerU
标准报告/文档	✅ 优秀	✅ 优秀
多栏排版论文	⚠️ 一般	✅ 优秀
大量公式的学术文档	⚠️ 一般	✅ 优秀
复杂嵌套表格	⚠️ 一般	✅ 优秀
手写笔记扫描件	⚠️ 较差	✅ 较好
图表与正文混排	⚠️ 一般	✅ 优秀
解析速度	✅ 快	⚠️ 较慢
资源消耗	✅ 低	⚠️ 较高

MinerU 的特别能力：

• 精细化版面恢复：可以恢复文档的原始排版，包括字体大小、颜色、对齐方式等
• 高级表格分析：能处理更复杂的表格结构，识别表格中的文本样式（加粗、斜体等）
• 多列文档处理：能正确处理多栏排版的阅读顺序，不会出现"串栏"问题
• 图像理解：对图表进行更深度的分析，尝试理解图表含义

使用建议：

• 对于排版简单、内容规范的文档（如 Word 导出的 PDF），使用 DeepDoc 即可获得不错的效果
• 对于排版复杂、解析质量要求高的文档（如学术期刊论文、产品手册），建议使用 MinerU
• 如果 DeepDoc 解析结果不理想，可以尝试切换到 MinerU 重新解析

5.4 解析参数配置

在知识库设置或文件解析时，可以调整以下解析参数：

语言设置：指定文档的主要语言，帮助 OCR 和解析引擎选择更准确的模型。支持中文、英文、中英混合等。

OCR 配置：

• 启用/禁用 OCR（对于已经包含文本的 PDF 可以禁用 OCR 以加快速度）
• OCR 语言模型选择
• OCR 精度与速度的平衡（高精度模式较慢但识别更准）

公式识别：启用/禁用 LaTeX 公式识别。如果文档不包含公式，禁用可以加快解析速度。

表格增强：启用更精细的表格分析（类似 MinerU 的表格处理能力）。需要消耗更多资源。

5.5 解析结果的人工干预

无论使用哪个解析器，RAGFlow 都提供了完善的人工干预机制。在知识库的文件详情页面，你可以：

查看分块预览：每个知识块以卡片形式展示，包含文本内容和在原文中的位置标注。卡片上显示：

• 知识块的内容预览
• 所属页码
• 该块在文档中的顺序编号
• 该块的 token 数量

原文对照：右侧显示原始文档的页面，当前选中知识块覆盖的区域会被高亮标注。你可以通过这个对照功能快速判断：

• 分块位置是否合理
• 是否有内容遗漏
• OCR 是否准确

手动编辑知识块：点击任意知识块的编辑按钮（铅笔图标），可以修改其内容。常见的编辑场景：

• 修正 OCR 识别错误（如"0"被识别为"O"）
• 修正表格解析的格式错乱
• 补充被遗漏的文本内容
• 合并本应属于同一段但被错误分开的内容

增删知识块：

• 添加：点击"添加知识块"按钮，手动输入新的知识内容。适用于补充文档中没有的信息。
• 删除：选中不需要的知识块，点击删除按钮。适用于移除封面碎片、空白页、无关页眉页脚等。
• 合并：选中多个相邻的知识块，点击"合并"按钮将它们合并为一个更大的知识块。

重新解析：如果对解析结果整体不满意，可以：

1. 修改分块模板或参数
2. 更换解析引擎（如从 DeepDoc 切换到 MinerU）
3. 点击"重新解析"按钮
4. 之前的所有人工修改会被覆盖

5.6 解析质量评估标准

如何判断文档解析的质量？以下是一些评估标准：

完整性：文档中的所有内容是否都被正确提取？有没有遗漏的段落、表格、图片？

准确性：提取的文字是否有 OCR 错误？表格数据是否准确？

结构保持：文档的层级结构（标题嵌套关系）是否被正确识别？表格的行列关系是否保持？

阅读顺序：段落和内容的顺序是否与原文一致？多栏排版是否按正确顺序提取？

分块合理性：分块是否在语义完整的位置切分？有没有在段落中间切断？

第六章：模型配置详解

6.1 支持的 LLM 提供商

RAGFlow 支持广泛的 LLM 提供商，覆盖了国内外主流的 API 服务和本地部署方案：

提供商	接入方式	典型模型	适用场景
OpenAI	API	GPT-4o, GPT-4o-mini, o1, o3	通用场景，效果顶尖但价格较高
Azure OpenAI	API	GPT-4o, GPT-4o-mini	企业合规场景，数据不出 Azure
Anthropic	API	Claude 3.5 Sonnet, Claude 3 Opus	长上下文、安全敏感场景
DeepSeek	API	DeepSeek-Chat, DeepSeek-Reasoner	性价比首选，中文效果优秀
阿里通义千问	API	Qwen-Max, Qwen-Plus, Qwen-Turbo	中文场景，价格适中
百度文心一言	API	ERNIE-4.0, ERNIE-3.5-Turbo	中文场景，合规性好
智谱 AI	API	GLM-4, GLM-4-Air, GLM-3-Turbo	中文场景，开源友好
月之暗面 Moonshot	API	Moonshot-v1, Moonshot-v1-8k	长上下文场景（128K）
零一万物 Yi	API	Yi-Large, Yi-Medium	中文场景
Minimax	API	MiniMax-Text-01	中文场景，多模态
硅基流动 SiliconFlow	API	多种开源模型中转	国内访问开源模型
Ollama	本地	qwen2.5, LLaMA 3, Mistral	本地部署，数据隐私
LocalAI	本地	兼容多种模型	本地部署，兼容 OpenAI API
LM-Studio	本地	本地加载模型	本地部署，图形化操作
vLLM	本地	高性能推理	大规模部署，高吞吐量

此外，任何兼容 OpenAI API 格式的服务都可以通过"OpenAI-API-Compatible"提供商接入。这意味着理论上任何提供 OpenAI 兼容 API 的服务都能适配 RAGFlow。

6.2 Ollama 本地模型接入详解

Ollama 是在本地运行开源 LLM 的利器。以下是完整的接入流程：

第一步：安装 Ollama

# Linux 一键安装
curl -fsSL https://ollama.com/install.sh | sh

# macOS / Windows：从 https://ollama.com/download 下载对应平台的安装包

第二步：拉取模型

RAGFlow 中需要两类模型：LLM（对话生成用）和 Embedding（向量嵌入用）。

# 拉取 LLM 模型
# 推荐 qwen2.5，中文能力强，有 0.5B/1.5B/7B/14B/72B 多个规模可选
ollama pull qwen2.5:7b

# 拉取 Embedding 模型
# bge-m3 是多语言 Embedding 模型，支持中文，效果优秀
ollama pull bge-m3

第三步：确认 Ollama 服务运行中

# 查看已拉取的模型列表
ollama list

# 确认 Ollama 服务在运行（默认监听 127.0.0.1:11434）
# 如果需要远程访问，设置环境变量
export OLLAMA_HOST=0.0.0.0

第四步：在 RAGFlow 中添加模型

在 RAGFlow 的系统设置 → 模型管理页面，分别添加 LLM 和 Embedding 模型：

添加 LLM 模型：

• 供应商：选择 Ollama
• 模型名称：输入 qwen2.5:7b（注意要与 ollama list 中显示的名称完全一致）
• API Base URL：输入 http://host.docker.internal:11434（Docker 环境下）或 http://你的IP:11434

添加 Embedding 模型：

• 供应商：选择 Ollama
• 模型名称：输入 bge-m3
• API Base URL：同样输入 http://host.docker.internal:11434

关键技术细节：

为什么不能用 localhost 或 127.0.0.1？

因为 RAGFlow 运行在 Docker 容器内，容器的 127.0.0.1 指向容器自身的网络空间，而不是宿主机。host.docker.internal 是 Docker 提供的特殊 DNS 名称，它会自动解析为宿主机的 IP 地址。

在 Linux 系统上，如果 host.docker.internal 不生效（某些旧版本 Docker 不支持），可以在 docker-compose.yml 中手动添加：

services:
  ragflow-server:
    extra_hosts:
      - "host.docker.internal:host-gateway"

6.3 模型选择建议

不同场景对模型的要求不同，以下是推荐的模型搭配方案：

方案一：轻量级 / 本地离线方案

• LLM：Ollama + qwen2.5:7b
• Embedding：Ollama + bge-m3
• 适合场景：个人使用、数据隐私要求高的企业、硬件条件有限的场景
• 硬件要求：8GB 内存即可，推荐 16GB+
• 优势：完全离线、数据不出本机、无需 API 费用
• 劣势：模型能力受限于本地硬件，复杂问题的处理能力有限

方案二：性价比方案

• LLM：DeepSeek-Chat API
• Embedding：BAAI/bge-large-zh-v1.5（内置）
• Rerank：BAAI/bge-reranker-v2-m3（可选）
• 适合场景：大多数中小企业
• 成本：DeepSeek API 价格低廉（百万 token 约 1-2 元人民币）
• 优势：效果优秀、成本低、部署简单
• 劣势：需要联网、数据需经过 API

方案三：旗舰方案

• LLM：GPT-4o 或 Claude 3.5 Sonnet
• Embedding：OpenAI text-embedding-3-large
• Rerank：Cohere Rerank 或 Jina Reranker
• 适合场景：对回答质量要求极高的场景（如法律、医疗、金融）
• 优势：效果最好、最稳定
• 劣势：成本较高、需要海外 API 访问

方案四：混合方案

• LLM：本地 Ollama + 云端 API 做 fallback
• Embedding：bge-m3（本地）
• 适合场景：需要高可用性、对延迟敏感的场景
• 说明：RAGFlow 支持配置多个 LLM 作为 fallback，当主模型不可用时自动切换到备用模型

6.4 Rerank 模型配置

什么是 Rerank？

Rerank（重排）是检索后的一个优化步骤。它的工作流程是：

用户查询 → 初步检索（Embedding 向量检索或全文检索）→ 召回 Top N 候选
→ Rerank 模型对每个"查询-文档"对深度打分 → 重新排序 → 取 Top K 结果

与 Embedding 检索的区别在于：

• Embedding 检索：将查询和文档分别编码为向量，用余弦相似度快速匹配。速度很快，但精度有限。
• Rerank 模型：将查询和文档拼接在一起，用深层 Transformer 模型进行交互式匹配。速度较慢，但精度更高。

配置 Rerank 模型：

在系统设置 → 模型管理中，添加"Rerank"类型的模型：

供应商：BAAI（内置）
模型名称：bge-reranker-v2-m3

或：

供应商：Cohere
模型名称：rerank-english-v3.0（英文） / rerank-multilingual-v3.0（多语言）
API Key：Cohere API Key

或：

供应商：Jina
模型名称：jina-reranker-v2-base-multilingual
API Key：Jina API Key

启用 Rerank：

在对话（Chat）的高级设置中，找到"Rerank"选项，勾选启用。然后配置：

• Rerank Top K：经过 Rerank 后保留的结果数量（通常比检索阶段的 Top K 小）
• Rerank 阈值：只保留 Rerank 分数高于该阈值的结果

实践效果：在知识库文档量超过 100 份的场景下，启用 Rerank 通常能提升检索准确率 10-20%。文档量越大，Rerank 的效果越明显。

6.5 模型多级 Fallback 配置

RAGFlow 支持配置多个 LLM 作为 Fallback（备用）模型。当主模型不可用（如 API 故障、速率限制、网络问题）时，系统会自动切换到备用模型。

配置方式：

1. 在模型管理中添加多个相同类型的 LLM
2. 在对话或 Agent 的模型选择中，可以设置优先级列表
3. 系统会按优先级顺序尝试使用模型，直到成功为止

这个功能对生产环境特别重要，可以大大提高系统的可用性。

6.6 Embedding 模型的注意事项

选择 Embedding 模型时，有几个技术细节需要注意：

向量维度一致性：一个知识库一旦创建并选择了 Embedding 模型，就不能再更换。因为同一知识库中的所有向量必须使用同一个模型生成，否则向量维度不同，无法进行相似度计算。

中文 vs 英文 ：不同的 Embedding 模型对语言的支持不同。bge-large-zh-v1.5 是中文优化模型，text-embedding-3-large 是英文优化的通用模型。对于中文文档，强烈推荐使用中文优化的 Embedding 模型。

模型大小与效果 ：一般来说，更大的 Embedding 模型（向量维度更高）效果更好，但存储和检索成本也更高。bge-large-zh-v1.5 的维度是 1024，在效果和效率之间取得了良好的平衡。

第七章：对话与检索

7.1 创建对话助手

在 RAGFlow 中，对话（Chat）是用户与知识库交互的主要入口。一个对话助手相当于一个"知识问答机器人"，你可以为不同的场景创建不同的对话助手。

创建步骤：

1. 点击导航栏的"对话"（Chat）
2. 点击"创建对话"（Create Chat）按钮
3. 填写配置信息

配置项详解：

对话名称：给这个对话助手起一个有辨识度的名字，如"产品技术支持"、"HR 政策咨询"等。

关联知识库：选择一个或多个知识库作为检索源。选择多个知识库时，系统会从所有选中的知识库中检索相关信息。这对于需要跨部门、跨领域检索的场景非常有用。

• 注意：选择的知识库越多，检索的范围越大，但检索的精度可能会受到一定影响
• 建议：如果不同的知识库内容差异较大，可以考虑使用 Agent 的 Categorize 节点做路由

LLM 模型：选择用于生成回答的 LLM。这里的选择会直接影响：

• 回答的质量和风格
• 响应速度（不同模型的推理速度差异很大）
• 使用成本（API 调用费用）

系统提示词（System Prompt）：这是定义助手角色和行为的关键设置。一个好的系统提示词应该：

1. 定义角色：告诉 LLM 它扮演什么角色
2. 设定规则：规定回答的约束条件
3. 提供示例（可选）：给出期望的回答格式示例

系统提示词示例：

你是一个专业的技术支持助手，负责回答用户关于产品使用的问题。

回答规则：
1. 请严格基于知识库中的内容回答用户的问题
2. 如果知识库中有相关的参考信息，请在回答末尾附上引用来源（文档名称和页码）
3. 如果知识库中没有找到相关信息，请如实告诉用户"知识库中暂无相关信息"，不要编造答案
4. 回答要简洁明了，使用通俗易懂的语言
5. 对于操作步骤类问题，请用编号列表清晰地列出每一步
6. 如果用户的表述不够清晰，可以礼貌地请用户补充说明
7. 最后确认用户的问题是否已经解决

7.2 检索策略配置

在对话的高级设置中，你可以对检索策略进行精细调优。

检索模式（Retrieval Mode）：

RAGFlow 支持三种检索模式，每种模式各有优劣：

全文检索（Full-text Search）

• 原理：基于关键词匹配，类似传统搜索引擎（如百度、Elasticsearch）
• 优点：精确匹配关键词，速度快，对于专业术语和编号（如产品型号、法律条文编号）效果极好
• 缺点：无法理解同义词和语义相近的表述，例如搜索"计算机"不会匹配"电脑"
• 适用场景：精确查询、代码搜索、产品型号查询等

向量检索（Vector Search）

• 原理：将查询文本和文档都转化为向量（通过 Embedding 模型），计算向量的余弦相似度
• 优点：能理解语义，搜索"如何退货"能匹配到"退换货政策"相关的内容
• 缺点：对于精确匹配不敏感，可能遗漏关键词相同但语义不相关的内容
• 适用场景：模糊查询、开放式问题、语义理解要求高的场景

混合检索（Hybrid Search）

• 原理：同时执行全文检索和向量检索，将两者的结果按权重合并
• 优点：兼具有全文检索的精确性和向量检索的语义理解能力，是综合效果最好的模式
• 缺点：速度比单一模式稍慢，增加了一些系统开销
• 适用场景：大多数场景，推荐作为默认选择

推荐 ：大多数场景下选择混合检索模式。如果有特殊需求（如专门的代码检索），可以根据需要切换到全文检索模式。

检索参数：

Top K：控制从知识库中检索多少条候选结果传递给 LLM。

• 建议范围：3-8 条
• 调优：如果回答内容不够丰富，可以适当增加；如果回答中出现无关内容，可以适当减少

相似度阈值（Similarity Threshold）：只返回相似度高于该值的结果。

• 建议范围：0.2-0.5
• 调优：如果检索到的不相关内容较多，提高阈值；如果经常漏掉相关内容，降低阈值

Empty Response（空回复）：当检索不到相关内容时，系统应该如何回复。可以设置一个默认的回复模板，例如：

"抱歉，我在知识库中没有找到与您问题相关的信息。请尝试换一种方式描述您的问题，或联系人工客服获取帮助。"

7.3 引用与溯源

RAGFlow 的一大核心特性是"可追溯引用"（Traceable Citations）。这是它与普通 AI 对话工具（如 ChatGPT）最本质的区别之一。

引用显示方式：

当对话助手给出回答时，回答的末尾会自动附上引用来源。引用的格式为：

参考来源：
[1] 产品使用手册_v2.3.pdf - 第 12 页
[2] FAQ_常见问题.docx - 第 3 页

点击引用可以展开查看被引用的原文段落，方便你核实 AI 是否准确使用了文档中的信息。

引用的价值：

1. 验证准确性：你可以逐一核实 AI 回答中的每一个观点，看是否真的有文档支撑
2. 增强可信度：在向客户或同事展示 AI 的回答时，引用可以增加回答的可信度
3. 快速定位原文：如果你想进一步了解某个话题，可以直接从引用跳转到原文
4. 审计追溯：在企业合规场景下，可以审计 AI 的每一个回答是基于什么文档内容生成的

引用的技术原理：

RAGFlow 在生成回答时，会记录使用的每一个知识块（Chunk）的 ID。这些 ID 关联了文件信息、页码、以及段落在原文中的坐标位置。在展示时，系统会从这些元数据中提取文档名、页码等展示信息，并提供指向原文的链接。

7.4 多轮对话与上下文管理

RAGFlow 的对话助手支持多轮对话。用户可以在同一个对话窗口中连续提问，系统会自动维护对话上下文。

上下文管理的工作方式：

1. 第一轮：用户提问 → 系统检索知识库 → LLM 生成回答
2. 第二轮：用户在同一个对话中继续提问 → 系统将对话历史（第一轮的问答）加入上下文 → 结合新的问题检索知识库 → LLM 基于对话历史和检索结果生成回答
3. 第三轮及以后：以此类推

上下文窗口配置：

在高级设置中，你可以配置上下文参数：

• 上下文轮数：控制多少轮历史对话会被纳入 LLM 的输入。一般建议 3-5 轮，过多的历史会占用 LLM 的上下文窗口。
• 上下文长度：控制历史对话的最大 token 数。当历史对话过长时，系统会截断最早的部分。

多轮对话的典型交互：

用户：RAGFlow 支持哪些文件格式？
助手：RAGFlow 支持以下文件格式：
- 文档类：PDF、DOCX、DOC、XLSX、XLS、PPTX、PPT、TXT、MD、CSV
- 图片类：PNG、JPG、JPEG、TIFF、BMP
- 其他：EML

用户：其中哪种格式的解析效果最好？（这里的"其中"指代上一轮提到的文件格式）
助手：根据经验，PDF 格式的解析效果最好，尤其是直接由 Word 或设计工具生成的数字原生 PDF（而非扫描件）。
对于扫描件 PDF，需要使用 OCR 功能，解析质量取决于扫描清晰度。
DOCX 格式的解析效果也很好，因为它内部存储的是结构化数据。

7.5 Prompt 模板定制

除了系统提示词，RAGFlow 还允许你定制 LLM 的 Prompt 模板，精确控制 LLM 的输入格式。

Prompt 模板的结构：

一个典型的 RAG 问答 Prompt 模板包含以下部分：

System: [系统提示词]
Context: [检索到的知识库内容]
Question: [用户的提问]
Answer:

自定义模板变量：

RAGFlow 支持在 Prompt 中使用变量，常见的变量包括：

• {context}：检索到的知识库内容
• {question}：用户的提问
• {history}：对话历史
• {lang}：语言设置

通过自定义 Prompt 模板，你可以实现：

• 修改回答的格式和风格
• 添加额外的指令约束
• 实现结构化输出（如 JSON 格式）
• 控制引用的展示方式

第八章：Agent 工作流编排

8.1 什么是 Agent？

RAGFlow 中的 Agent 是一种基于 DAG（有向无环图）的智能工作流。与简单的"检索-生成"问答模式不同，Agent 可以实现更复杂的逻辑判断和多步骤处理。

Agent vs 对话助手的区别：

维度	简单对话助手	Agent 工作流
逻辑复杂度	单一"检索→生成"流程	多节点、多分支、条件判断
支持的操作	只能从知识库检索	可调用 API、执行代码、发送邮件等
分支路由	不支持	支持意图分类、条件分支
灵活性	固定流程	高度可自定义
使用门槛	低	中到高

Agent 的典型应用场景：

1. 智能客服：根据用户意图路由到不同的处理流程
2. 多知识库问答：根据问题领域从不同的知识库中检索
3. 数据查询助手：在工作流中调用外部 API 查询实时数据
4. 自动化报告生成：从多个数据源收集信息，汇总生成报告
5. 多步骤推理：将复杂问题分解为多个子问题，逐步求解

8.2 创建 Agent

创建步骤：

1. 点击导航栏的"Agent"（代理），进入 Agent 列表页面
2. 点击"创建 Agent"按钮
3. 选择一个预设模板或从空白开始

预设模板：

• 简单问答：一个基础的"检索 + 生成"工作流，相当于将对话助手可视化
• 客服助手：包含意图分类、多知识库路由的客服场景模板
• HR 助手：面向人力资源场景的多分支对话模板
• 通用搜索 Agent：结合网络搜索的增强问答模板

选择模板后，你会进入 Agent 编辑器界面------一个可视化的画布（Canvas），上面已经预置了对应的节点和工作流。

8.3 画布（Canvas）操作指南

Agent 编辑器提供了一个可视化的画布界面，让你通过拖拽、连线的方式来构建工作流。

界面布局：

画布编辑器分为三个主要区域：

1. 左侧节点面板：显示所有可用的节点类型
2. 中间画布区域：工作流的可视化编辑区
3. 右侧属性面板：显示选中节点的详细配置

基本操作：

操作	方法
添加节点	从左侧节点面板将节点拖拽到画布上
连接节点	从一个节点的输出端口拖拽到另一个节点的输入端口
删除节点/连线	选中后按 Delete 键，或右键选择删除
移动节点	拖拽节点标题区域调整位置
选择多个节点	按住 Shift 键点击多个节点，或拖拽框选
缩放画布	鼠标滚轮缩放，或使用右上角的缩放控件
平移画布	按住空格键加鼠标拖拽，或鼠标中键拖拽
查看节点属性	点击节点，右侧显示属性配置面板
运行调试	点击右上角的"运行"按钮，输入测试问题查看执行过程

8.4 节点类型详解

RAGFlow 提供了丰富的节点类型，每种节点负责工作流中的不同环节。

Begin（开始节点）

工作流的入口节点。用户的问题从这里进入工作流。

• 功能：接收用户的原始输入
• 输出：用户的输入文本
• 注意：每个 Agent 有且只有一个 Begin 节点，不可删除

Answer（回复节点）

工作流的出口节点。将最终结果返回给用户。

• 功能：将处理结果格式化后返回给用户
• 输入：需要回复给用户的内容
• 注意：一个 Agent 可以有多个 Answer 节点，不同分支可以有不同回复

Retrieval（检索节点）

从指定的知识库中检索与输入相关的内容。

配置参数：

• 关联知识库：选择要检索的知识库（可多选）
• 检索模式：全文检索、向量检索、混合检索
• Top K：返回的结果数量
• 相似度阈值：结果的相似度过滤阈值
• Rerank 配置：是否启用 Rerank 以及相关参数

使用技巧：如果需要从多个知识库检索，可以配置多个 Retrieval 节点分别检索不同的知识库。

Generate（生成节点）

调用 LLM 基于输入和上下文生成回答。

配置参数：

• LLM 模型：选择使用的模型
• System Prompt：系统提示词模板
• User Prompt：用户提示词模板
• 温度（Temperature）：控制 LLM 输出的随机性（0-1）
• 最大 Token 数：回答的最大长度

Categorize（分类节点）

使用 LLM 对用户输入进行意图分类。

配置示例：

类别1："技术问题"
  描述："用户询问关于产品使用方法、安装配置、故障排除等技术类问题"

类别2："商务咨询"
  描述："用户询问关于价格、合同、合作、订单等商务类问题"

类别3："闲聊"
  描述："用户进行非业务相关的闲聊或寒暄"

Categorize 节点根据分类结果为每个类别提供一个输出连线，实现工作流的分支路由。未匹配的输入从"其他"端口输出。

Message（消息节点）

向用户发送一条固定或模板化的消息，不经过 LLM 处理。

适用场景：发送预设回复（如"抱歉，请联系人工客服"）、触发提示信息、发送欢迎语等。

Relevant（相关性判断节点）

判断检索到的内容与用户问题是否相关。基于 LLM 的二分类器，输出"相关"或"不相关"。用于过滤低质量的检索结果。

RewriteQuestion（问题改写节点）

在多轮对话中，将用户的问题改写为语义完整、自包含的新问题。

示例：

原始问题：它的 Top K 参数有什么用？
改写后：RAGFlow 的 Retrieval 节点中的 Top K 参数有什么用？

Keyword（关键词提取节点）

从用户问题中提取关键词，用于全文检索或后续的搜索操作。

LLM 节点（通用）

通用的大语言模型调用节点，可以自由定义 System Prompt 和 User Prompt。适用于翻译、摘要、情感分析、格式转换等文本处理任务。

Iteration（迭代节点）

对一组输入数据逐一执行相同的子流程。例如对检索到的多个文档片段分别进行摘要处理。

HTTP Request（HTTP 请求节点）

在工作流中调用外部 HTTP API。

配置参数：请求方法（GET/POST等）、URL、请求头、请求体、超时设置。

Python Code（Python 代码节点）

在工作流中执行自定义 Python 代码，实现灵活的逻辑处理。

搜索工具节点

• Baidu（百度搜索）：调用百度搜索获取网络信息
• DuckDuckGo：调用 DuckDuckGo 搜索引擎，无需 API Key
• Wikipedia：从维基百科检索相关信息
• PubMed：从 PubMed 学术数据库检索论文

Email（邮件节点）

在工作流中发送邮件。配置 SMTP 服务器、收件人、主题、正文等。

8.5 典型工作流示例

示例一：基础 RAG 问答（入门级）

最简单的 RAG 流程，相当于把对话助手功能可视化：

Begin → Retrieval → Generate → Answer

工作流程：接收提问 → 从知识库检索 → 调用 LLM 生成回答 → 返回给用户。

示例二：带意图分类的多知识库路由（进阶级）

不同类别的问题从不同的知识库检索：

Begin → Categorize
  ├─ "技术问题" → Retrieval（技术知识库）→ Generate → Answer
  ├─ "商务咨询" → Retrieval（商务知识库）→ Generate → Answer
  └─ "闲聊" → Message("感谢交流！如有业务问题请随时提问。") → Answer

示例三：带相关性检查的高质量问答（进阶级）

确保只有相关的检索结果才会用于生成回答：

Begin → RewriteQuestion → Retrieval → Relevant
  ├─ "相关" → Generate → Answer
  └─ "不相关" → Message("抱歉，未找到与您问题相关的信息。") → Answer

示例四：结合网络搜索的增强 Agent（高级）

既使用内部知识库，又从互联网获取最新信息：

Begin → Categorize
  ├─ "内部知识" → Retrieval（内部知识库）→ Generate → Answer
  └─ "外部信息" → DuckDuckGo → LLM（整理搜索结果）→ Answer

示例五：智能客服系统（综合案例）

结合多种节点类型的完整客服工作流：

Begin → RewriteQuestion → Categorize
  ├─ "退换货" → Retrieval（退换货政策知识库）→ Generate → Answer
  ├─ "物流查询" → HTTP Request（调用物流API）→ LLM（格式化结果）→ Answer
  ├─ "产品咨询" → Retrieval（产品知识库）→ Generate → Answer
  ├─ "投诉建议" → Message("正在为您转接人工客服...") → Answer
  └─ "其他" → Retrieval（通用知识库）→ Generate → Answer

8.6 Agent 调试与发布

调试工作流：

1. 点击右上角的"运行"（Run）按钮
2. 输入测试问题，点击"开始运行"
3. 系统逐步执行工作流，高亮显示当前执行到的节点
4. 点击节点可以查看其输入和输出数据
5. 如果节点报错，会显示错误信息

调试技巧：

• 测试多种分类情况，确保分支路由正确
• 检查检索结果的质量
• 检查 LLM 生成的回答质量
• 测试边界情况：空输入、不相关问题、多轮对话等

发布工作流：

调试通过后，点击"发布"（Publish）按钮，Agent 上线。发布后可以通过对话界面或 API 调用 Agent。

版本管理： 支持查看历史版本和回滚到之前的版本。

第九章：API 开发指南

9.1 API 密钥获取

RAGFlow 提供了完整的 RESTful API，便于你将 RAGFlow 的能力集成到自己的应用中。

获取 API 密钥：

1. 在 RAGFlow Web 界面中，点击右上角用户头像
2. 选择"API"页面
3. 点击"创建 API Key"
4. 系统会生成一个以 ragflow- 开头的密钥
5. 复制并妥善保存密钥（密钥只显示一次，关闭后将无法再次查看）

API 权限说明：

• API Key 与创建它的用户账号绑定，拥有与该用户相同的权限
• 管理员用户创建的 API Key 拥有管理员权限
• 建议为不同的应用创建不同的 API Key，方便权限管理和审计

9.2 API 基础信息

基础 URL：

http://<your-ragflow-host>:9380/api/v1

请求头：

Authorization: Bearer ragflow-xxxxxxxxxxxxxxx
Content-Type: application/json

响应格式： 所有 API 响应遵循统一的格式：

{
  "code": 0,
  "message": "",
  "data": { ... }
}

• code：状态码，0 表示成功，非 0 表示失败
• message：错误信息（成功时为空字符串）
• data：响应的具体数据

错误码说明：

错误码	含义
0	成功
100	参数错误
101	认证失败（API Key 无效）
102	权限不足
103	资源不存在
104	资源冲突（如重复创建）
500	服务器内部错误

9.3 数据集（Dataset）API

数据集即知识库，是 RAGFlow 中的核心概念。

创建数据集：

POST /api/v1/datasets

请求体：

{
  "name": "产品手册",
  "description": "公司所有产品的使用手册",
  "embedding_model": "BAAI/bge-large-zh-v1.5",
  "chunk_method": {
    "name": "General",
    "chunk_token_num": 512
  }
}

响应：

{
  "code": 0,
  "data": {
    "id": "dataset_xxxxxxxxxxxx",
    "name": "产品手册",
    "status": "1",
    "chunk_count": 0,
    "created_at": "2026-06-01T10:30:00Z"
  }
}

获取数据集列表：

GET /api/v1/datasets?page=1&page_size=10

响应：

{
  "code": 0,
  "data": [
    {
      "id": "dataset_xxxxxxxxxxxx",
      "name": "产品手册",
      "description": "公司所有产品的使用手册",
      "chunk_count": 156,
      "status": "1",
      "created_at": "2026-06-01T10:30:00Z"
    }
  ],
  "total": 5
}

更新数据集：

PUT /api/v1/datasets/{dataset_id}

请求体：

{
  "name": "更新后的名称",
  "description": "更新后的描述"
}

删除数据集：

DELETE /api/v1/datasets/{dataset_id}

注意：删除数据集会同时删除其中的所有文件和知识块，此操作不可逆。

9.4 文件（Document）API

上传文件到数据集：

POST /api/v1/datasets/{dataset_id}/documents

使用 multipart/form-data 格式上传文件：

curl -X POST "http://localhost:9380/api/v1/datasets/dataset_xxx/documents" \
  -H "Authorization: Bearer ragflow-xxxxxxxxxxxxxxx" \
  -F "file=@/path/to/your/document.pdf"

批量上传文件：

curl -X POST "http://localhost:9380/api/v1/datasets/dataset_xxx/documents" \
  -H "Authorization: Bearer ragflow-xxxxxxxxxxxxxxx" \
  -F "file=@doc1.pdf" \
  -F "file=@doc2.docx"

获取文件列表：

GET /api/v1/datasets/{dataset_id}/documents?page=1&page_size=20

删除文件：

DELETE /api/v1/datasets/{dataset_id}/documents/{document_id}

触发文件解析：

POST /api/v1/datasets/{dataset_id}/chunks

请求体：

{
  "document_ids": ["doc_xxxx", "doc_yyyy"]
}

获取文件的分块结果：

GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?page=1&page_size=50

9.5 对话（Chat）API

创建对话：

POST /api/v1/chats

请求体：

{
  "name": "产品咨询助手",
  "dataset_ids": ["dataset_xxxx"],
  "llm": {
    "model_name": "deepseek-chat",
    "temperature": 0.7
  },
  "prompt": {
    "system": "你是一个专业的产品咨询助手，请基于知识库内容回答用户的问题。"
  }
}

发送消息（对话完成）：

POST /api/v1/chats/{chat_id}/completions

请求体：

{
  "question": "RAGFlow 支持哪些文件格式？",
  "stream": true
}

当 stream 为 true 时，响应会以 SSE（Server-Sent Events）格式流式返回：

data: {"content": "RAGFlow", "reference": null}
data: {"content": " 支持", "reference": null}
data: {"content": " 以下文件格式", "reference": null}
...
data: {"content": "", "reference": [{"doc_name": "产品手册.pdf", "page_num": 5}]}
data: [DONE]

获取对话历史：

GET /api/v1/chats/{chat_id}/sessions/{session_id}/messages?page=1&page_size=50

9.6 Agent API

创建 Agent 会话：

POST /api/v1/agents/{agent_id}/sessions

响应：

{
  "code": 0,
  "data": {
    "id": "session_xxxxxxxxxxxx"
  }
}

与 Agent 对话：

POST /api/v1/agents/{agent_id}/completions

请求体：

{
  "question": "你好，请问退货流程是怎样的？",
  "session_id": "session_xxxxxxxxxxxx",
  "stream": true
}

Agent 的对话流程与 Chat 类似，但会执行 Agent 画布上定义的完整工作流逻辑。

获取 Agent 列表：

GET /api/v1/agents?page=1&page_size=10

9.7 AI Search API

执行 AI 搜索：

POST /api/v1/search

请求体：

{
  "question": "2026年大语言模型的最新发展趋势",
  "dataset_ids": ["dataset_xxxx"],
  "search_engine": "bing",
  "stream": true
}

9.8 Python SDK 使用示例

RAGFlow 提供了 Python SDK（ragflow-sdk），方便 Python 开发者快速集成：

pip install ragflow-sdk

基础使用示例：

from ragflow_sdk import RAGFlow

# 初始化客户端
rag = RAGFlow(
    api_key="ragflow-xxxxxxxxxxxxxxx",
    base_url="http://localhost:9380"
)

# 创建数据集
dataset = rag.create_dataset(
    name="技术文档",
    embedding_model="BAAI/bge-large-zh-v1.5"
)

# 上传文件
dataset.upload_file(file_path="./docs/manual.pdf")

# 创建对话
chat = rag.create_chat(
    name="技术助手",
    dataset_ids=[dataset.id]
)

# 发送问题
response = chat.ask("如何配置网络？")
print(response.answer)
print(response.reference)  # 引用来源

流式对话示例：

chat = rag.get_chat(chat_id="chat_xxxxxx")
for chunk in chat.ask_stream("如何配置网络？"):
    print(chunk.content, end="", flush=True)

Agent 调用示例：

# 获取 Agent
agent = rag.get_agent(agent_id="agent_xxxxxx")

# 创建会话
session = agent.create_session()

# 发送消息
for chunk in agent.ask_stream(
    question="退货流程是怎样的？",
    session_id=session.id
):
    print(chunk.content, end="", flush=True)

注意事项：

• SDK 接口可能随版本更新而变化，建议参考 pip show ragflow-sdk 安装的具体版本对应的文档
• 生产环境中建议处理网络超时和重试逻辑
• 流式接口（stream=True）需要支持 SSE 的客户端

第十章：MCP 集成

10.1 什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是由 Anthropic 提出的一项开放标准协议，旨在为 AI 模型与外部工具、数据源之间建立统一的通信接口。

MCP 的核心概念：

• MCP Server：提供特定功能的服务器（如文件访问、数据库查询、API 调用等）
• MCP Client：使用 MCP Server 服务的客户端（如 Claude Desktop、RAGFlow Agent 等）
• 工具（Tool）：MCP Server 暴露的功能接口
• 资源（Resource）：MCP Server 提供的数据源

你可以把 MCP 理解为 AI 世界的"USB-C 接口"------只要工具实现了 MCP 协议，任何支持 MCP 的 AI 应用都能即插即用地调用它。

10.2 RAGFlow 作为 MCP Server

RAGFlow 可以作为 MCP Server 运行，让外部支持 MCP 的 AI 客户端直接调用 RAGFlow 的知识库检索能力。

配置方式：

在 MCP 客户端的配置文件中添加 RAGFlow 的 MCP Server 配置。

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "ragflow": {
      "command": "npx",
      "args": ["-y", "ragflow-mcp-server"],
      "env": {
        "RAGFLOW_API_KEY": "ragflow-xxxxxxxxxxxxxxx",
        "RAGFLOW_BASE_URL": "http://localhost:9380"
      }
    }
  }
}

MCP Server 提供的工具：

配置完成后，MCP 客户端会发现以下工具：

工具名称	功能	参数
search_knowledge_base	搜索知识库	query（搜索关键词）、dataset_ids（可选，指定知识库）
list_datasets	列出所有知识库	无
get_document_chunks	获取文档的分块	document_id

使用场景示例：

在 Claude Desktop 中配置好 RAGFlow MCP Server 后，你可以直接问 Claude："搜索我的产品知识库，看看 RAGFlow 支持哪些文件格式？"------Claude 会自动调用 RAGFlow 的 search_knowledge_base 工具来获取答案。

10.3 RAGFlow Agent 作为 MCP Client

在 RAGFlow 的 Agent 工作流中，你也可以通过 HTTP Request 节点或 Python Code 节点调用外部 MCP Server 提供的工具，使 Agent 能在对话过程中动态获取外部数据。

配置外部 MCP 工具：

1. 在 RAGFlow 系统设置中配置 MCP 工具连接信息
2. 在 Agent 工作流中添加相应的节点来调用 MCP 工具
3. 将 MCP 工具的返回结果用于后续的处理

典型集成场景：

• 文件系统集成：通过 MCP Server 访问本地文件系统，读取或写入文件
• 数据库集成：连接外部数据库，执行 SQL 查询
• 第三方 API 集成：通过 MCP Server 调用 GitHub、Slack、Notion 等 API
• 浏览器自动化：通过 MCP Server 控制浏览器，执行网页操作

10.4 实际集成示例

示例：在 Agent 工作流中结合 MCP 工具

Begin → Retrieval（内部知识库）→ HTTP Request（MCP 工具调用）
  → Generate（整合信息生成回答）→ Answer

在这个示例中，Agent 先检索内部知识库，然后通过 HTTP Request 节点调用外部 MCP Server 获取实时数据，最后将两者信息整合生成回答。

示例：RAGFlow 与 Cursor IDE 集成

如果你使用 Cursor IDE 进行开发，可以在 Cursor 的 MCP 配置中添加 RAGFlow，这样在编写代码时可以实时查询公司内部的技术文档和代码规范。

第十一章：AI Search 功能

11.1 什么是 AI Search？

AI Search 是 RAGFlow 对标 Perplexity、Bing Chat 等现代 AI 搜索引擎的功能模块。与普通的对话助手不同，AI Search 更侧重于面向开放域的信息检索场景。

AI Search 的核心能力：

1. 多源检索：同时从本地知识库和互联网检索信息
2. 信息整合：对检索结果进行去重、排序、整合
3. 报告生成：生成结构化的、带有引用的综合报告
4. 实时性：能获取互联网上的最新信息

AI Search vs 普通对话助手的区别：

维度	普通对话助手	AI Search
检索范围	本地知识库	本地知识库 + 互联网
信息时效性	取决于知识库更新频率	实时（可获取最新信息）
输出格式	对话式回答	结构化报告
适用场景	企业内部知识问答	信息调研、竞品分析、知识整理
引用来源	知识库文档	知识库文档 + 网页链接

11.2 配置搜索引擎 API

要使用 AI Search 功能，你需要先配置搜索引擎 API。

支持的搜索引擎：

搜索引擎	是否需要 API Key	说明
Bing Search	是	微软必应搜索，需在 Azure 申请 API Key
DuckDuckGo	否	无需 API Key，免费使用
Google Custom Search	是	Google 自定义搜索，需配置

配置 Bing Search API（推荐）：

1. 登录 Azure 门户（portal.azure.com）
2. 创建 Bing Search v7 资源
3. 获取 API Key 和 Endpoint
4. 在 RAGFlow 系统设置 → 搜索配置中填入 API Key

配置 DuckDuckGo（无需 API Key）：

在 RAGFlow 系统设置中直接选择 DuckDuckGo 作为搜索引擎即可使用，无需额外配置。

11.3 使用 AI Search

在 Web 界面中使用：

1. 点击导航栏中的"AI Search"（或"搜索"）
2. 输入你的搜索查询
3. RAGFlow 会同时从本地知识库和互联网检索信息
4. 生成一份综合性的搜索报告
5. 报告中的每条信息都会标注来源（知识库或互联网），并提供原始链接

搜索报告的结构：

一个典型的 AI Search 报告包含：

1. 摘要：对搜索结果的总体概述
2. 详细内容：按主题组织的信息，每个信息点附有引用
3. 来源列表：所有引用的完整列表，包括文档名称或网页链接

11.4 AI Search 的 API 调用

AI Search 支持通过 API 调用，便于集成到外部应用中：

POST /api/v1/search

请求体：

{
  "question": "2026年大语言模型的最新发展趋势",
  "dataset_ids": ["dataset_xxxx"],
  "search_engine": "bing",
  "stream": true
}

参数说明：

• question：搜索查询
• dataset_ids：指定检索哪些本地知识库（可选，不指定则只搜互联网）
• search_engine：搜索引擎类型（bing / duckduckgo）
• stream：是否流式返回

响应以流式方式返回搜索报告，包含 LLM 生成的综合回答和引用来源列表。

11.5 AI Search 的最佳实践

1. 明确指定知识库：如果搜索范围是特定的内部文档，明确指定 dataset_ids 可以提高检索精度
2. 结合本地和互联网：对于需要同时参考内部资料和外部信息的场景，同时使用知识库和搜索引擎
3. 使用高质量搜索引擎：Bing Search 的结果质量通常优于 DuckDuckGo
4. 验证引用：AI Search 的结果应按引用溯源，核实信息的准确性
5. 与 Agent 工作流结合：可以将 AI Search 作为 Agent 工作流中的一个节点使用

第十二章：实战案例

本章通过三个完整的实战案例，详细展示 RAGFlow 从需求分析到落地部署的全过程。每个案例都包含场景描述、方案设计、具体实施步骤、以及效果评估。

12.1 案例一：搭建企业内部知识库

12.1.1 场景描述

公司背景：某中型科技公司（约 500 人），拥有大量内部文档，包括：

• 产品技术文档（约 200 份 PDF，涵盖 5 大产品线）
• 内部操作手册（约 50 份 DOCX，涉及采购、财务、HR 等流程）
• 公司规章制度（约 30 份 PDF，包括员工手册、保密协议等）
• 常见问题 FAQ（约 100 条 Q&A，整理在 Excel 中）

痛点：

• 员工查找信息困难，经常需要问同事或翻阅大量文档
• 新员工入职后，需要花费大量时间学习各种文档
• 文档分散在不同的系统和文件夹中，缺乏统一的检索入口
• 重复性问题频繁出现，占用了技术团队大量的回答时间

目标：搭建一个统一的企业内部知识库 AI 问答系统，让员工能够通过自然语言提问快速获取所需信息。

12.1.2 方案设计

技术选型：

• 部署方式：Docker Compose 部署在内部服务器（Ubuntu 20.04，32GB 内存，8 核 CPU）
• LLM 模型：DeepSeek-Chat API（性价比高，中文效果好）
• Embedding 模型：BAAI/bge-large-zh-v1.5（内置，中文优化）
• Rerank 模型：BAAI/bge-reranker-v2-m3（可选，用于提升检索精度）
• 数据库引擎：Elasticsearch（预计文档数超过 10,000 个知识块）

知识库规划：

为了更好的分类管理和检索准确性，我们按文档类型创建多个知识库：

知识库名称	文档类型	分块模板	预计文档数
产品技术文档	PDF 产品手册	Manual	200
内部操作手册	DOCX 流程文档	General	50
规章制度	PDF 法律文档	Laws	30
常见问题 FAQ	Excel 问答	Q&A	100
培训材料	PDF/PPT 课件	General	80

12.1.3 实施步骤

第一步：部署 RAGFlow

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
cp .env.example .env
# 编辑 .env: DOC_ENGINE=elasticsearch
docker compose -f docker-compose.yml up -d

第二步：配置模型

登录 RAGFlow Web 界面，进入系统设置 → 模型管理：

1. 添加 LLM 模型：DeepSeek → deepseek-chat → 输入 API Key
2. 添加 Embedding 模型：BAAI → bge-large-zh-v1.5
3. 可选：添加 Rerank 模型：BAAI → bge-reranker-v2-m3

第三步：创建知识库并上传文档

根据规划逐一创建 5 个知识库，每个选择对应的分块模板。以产品技术文档为例：

1. 点击创建知识库，名称"产品技术文档"
2. 选择 Embedding 模型和 Manual 分块方法
3. 批量上传 200 份 PDF，点击批量解析

第四步：检查分块结果

解析完成后，抽查每个知识库的分块质量：

• 检查标题层级是否被正确识别
• 检查表格是否被完整提取
• 检查是否存在被错误切断的段落
• 手动修正明显的解析错误

第五步：创建对话助手

创建"综合知识助手"，关联所有 5 个知识库，使用 DeepSeek-Chat 模型。

系统提示词：

你是一个企业知识助手，请基于知识库内容回答员工的问题。
规则：
1. 严格基于知识库内容回答，不要编造
2. 回答时请附上引用来源（文档名称）
3. 如果问题涉及多个方面，请分点作答
4. 如果知识库中没有相关信息，请如实告知

第六步：集成到企业微信

通过 RAGFlow API 将对话助手集成到企业内部通信工具中。

12.1.4 效果评估与调优

上线后第 1 周：收集反馈

• 记录员工提问的类型分布
• 记录回答的准确率
• 记录未找到答案的问题

上线后第 2 周：优化调整

• 补充缺失的文档
• 调整分块参数（Chunk Size 从 512 调整为 768）
• 优化系统提示词
• 启用 Rerank 功能

效果指标（上线一个月后）：

• 回答准确率从 82% 提升至 93%
• 日均提问量约 150 次
• 首次回答满意度 89%
• 未找到率从 15% 降低至 7%
• 技术团队每周减少约 10 小时的重复性问答时间

持续运营：

• 每月更新一次知识库内容
• 每季度进行一次分块质量审查
• 根据员工反馈持续优化

12.2 案例二：智能客服系统

12.2.1 场景描述

业务背景：某电商平台（日订单量 5000+）需要建设一个智能客服系统。

常见问题类型：

1. 订单查询（30%）：订单状态、发货时间、物流追踪等
2. 退换货（25%）：退换货政策、流程、退款时间等
3. 产品咨询（20%）：产品参数、使用方法、推荐建议等
4. 售后投诉（15%）：质量问题、配送异常、服务不满等
5. 其他（10%）：账号问题、优惠活动、支付问题等

痛点：

• 人工客服团队 20 人，日均处理 300+ 咨询
• 高峰期咨询量翻倍，等待时间长
• 退换货和物流查询需要实时数据
• 客户满意度波动大

目标：建设智能客服 Agent，自动处理 70% 以上常见咨询，降低人工工作量 50% 以上。

12.2.2 方案设计

技术方案特点：

• 使用 Agent 工作流实现意图分类和多分支处理
• 退换货政策、产品信息使用知识库检索
• 物流查询通过 HTTP Request 调用物流 API 获取实时数据
• 投诉建议直接转接人工客服

LLM 选型：GPT-4o（效果优先）

Agent 工作流设计：

Begin
  → RewriteQuestion
    → Categorize
      ├─ 退换货咨询
      │   → Retrieval（退换货政策知识库）
      │     → Generate → Answer
      ├─ 物流查询
      │   → HTTP Request（调用物流API）
      │     → LLM（格式化结果）→ Answer
      ├─ 产品咨询
      │   → Retrieval（产品知识库）
      │     → Generate → Answer
      ├─ 投诉建议
      │   → Message（转人工通知）
      │     → HTTP Request（创建工单）→ Answer
      └─ 其他
          → Retrieval（通用知识库）
            → Generate → Answer

12.2.3 实施步骤

第一步：准备知识库

创建三个知识库：

1. 退换货政策知识库（Chunk Method: Laws）
2. 产品知识库（Chunk Method: Manual）
3. 通用知识库（Chunk Method: General）

第二步：配置 Categorize 节点

类别1：退换货咨询
描述：用户询问退换货、退款、售后保障、退货流程等问题

类别2：物流查询
描述：用户询问订单物流状态、配送时间、快递信息等问题

类别3：产品咨询
描述：用户询问产品参数、功能、使用方法、推荐建议等问题

类别4：投诉建议
描述：用户投诉产品质量、服务态度、配送问题等负面反馈

类别5：其他
描述：以上类别之外的咨询

第三步：调试与集成

测试每个分支：

• "我买的手机怎么还没发货？" → 物流查询分支
• "我要退货，衣服尺码不对" → 退换货咨询分支
• "你们服务太差了！" → 投诉建议分支

通过 API 集成到现有客服系统。

12.2.4 效果评估

上线运行一个月后的数据：

指标	实施前	实施后
日均处理咨询量	320 单	450 单
人工处理占比	100%	35%
平均响应时间	5 分钟	10 秒
客户满意度	4.2/5.0	4.4/5.0
人工客服工作量	20 人满负荷	13 人

各类问题的自动解决率：

• 订单查询：78%（物流 API 集成效果显著）
• 退换货咨询：85%（政策文档清晰）
• 产品咨询：72%（需要进一步丰富产品知识库）
• 投诉建议：0%（全部转人工，符合预期）
• 其他：55%

12.3 案例三：个人知识管理助手

12.3.1 场景描述

用户背景：AI 领域的研究者，需要管理海量学习资料，包括：

• 100+ 篇学术论文（PDF）
• 50+ 篇技术博客（Markdown）
• 个人学习笔记（Obsidian 导出）
• 书籍摘录和读书笔记

痛点：

• 文献太多，难以快速找到特定内容
• 需要跨文档整合信息
• 希望在完全离线的环境下使用
• 需要全局理解能力

目标：搭建完全离线的个人知识管理助手。

12.3.2 方案设计

技术选型：

• 部署：Docker Compose 在本地工作站（64GB 内存，RTX 4090 24GB）
• LLM：Ollama + qwen2.5:14b
• Embedding：Ollama + bge-m3
• Rerank：Ollama + bge-reranker-v2-m3
• 数据库：Infinity
• 特殊功能：启用 RAPTOR

知识库规划：

知识库名称	分块模板	启用 RAPTOR
学术论文	Paper	是
技术博客	General	否
学习笔记	General	是
书籍摘录	Book	是

12.3.3 实施步骤

第一步：部署 Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:14b
ollama pull bge-m3
ollama pull bge-reranker-v2-m3

第二步：部署 RAGFlow

使用 Docker Compose，配置 Ollama 为模型后端。

第三步：创建并优化知识库

创建 4 个知识库，启用 RAPTOR，上传资料后检查分块质量。

第四步：创建个人对话助手

系统提示词：

你是一个个人研究助手，帮助我管理和检索知识库。
能力：
1. 从论文、笔记、博客中检索相关信息
2. 整合多个来源的信息
3. 帮助我回忆之前看过的内容
要求：
1. 回答时标注信息来源
2. 利用 RAPTOR 摘要信息处理全局性问题
3. 如发现矛盾信息请指出

12.3.4 使用示例

精确检索： 用户：我看过一篇关于 Flash Attention 的论文，主要优化点是什么？ 助手检索到对应论文，清晰列出 Flash Attention 的核心优化点（tiling 技术、IO-Aware 计算、显存优化等），并标注来源。

全局综合分析： 用户：我最近读的论文中，关于 LLM 推理加速有哪些主要方法？ 助手整合 7 篇相关论文，按 KV Cache 优化、量化加速、投机解码三大方向分类总结，每项附论文来源和个人笔记心得。

跨笔记关联： 用户：我笔记里提到的"稀疏注意力"相关的论文有哪些？ 助手从论文库和笔记中关联出 Longformer、BigBird、Sparse Transformer 三篇论文，并引用实验记录中的数据和结论。

使用效果：

• 检索效率大幅提升（从 10 分钟翻文件夹到 10 秒内定位）
• RAPTOR 让总结类问题回答质量明显提升
• 离线运行，数据隐私有保障
• 自然语言交互，无需记忆文件结构

第十三章：性能优化与最佳实践

13.1 知识库质量优化

知识库的质量是 RAG 系统效果的基石。一个高质量的知识库，即使使用基础的检索策略，也能获得不错的效果；反之，一个质量差的知识库，即使使用最先进的检索算法，效果也有限。

文档预处理

在上传文档之前，对文档进行预处理能显著提升解析质量：

1. 清理噪音内容：

   • 移除页眉页脚中的水印、免责声明等重复内容
   • 移除封面和封底的装饰性页面
   • 清理文档中的批注、修订标记（对 Word 文档）
   • 去除空白页和重复页

2. 格式优化：

   • 将扫描件 PDF 转换为数字原生 PDF（如有条件）
   • 将 DOC 格式转换为 DOCX（DOCX 是结构化格式，解析效果更好）
   • 确保文档使用标准字体（特殊字体可能导致 OCR 识别困难）

3. 结构优化：

   • 确保文档使用规范的标题样式（Word 的 Heading 1/2/3，PDF 的书签）
   • 表格尽量使用标准表格格式，避免使用"假装是表格"的排版方式
   • 为图片添加适当的文字说明

选择合适的分块模板

这是最关键的一步。不要所有文档都用 General 模板，根据文档类型选择最合适的模板：

文档类型	推荐模板	效果提升
FAQ/问答集	Q&A	检索准确率提升 20-30%
法律合同/制度	Laws	条款检索精确度提升 40%+
学术论文	Paper	章节级检索准确度提升 25%
产品手册	Manual	操作步骤检索提升 30%
表格密集文档	Table	表格数据检索提升 50%+
简历	Resume	候选人信息提取提升 35%
长篇书籍	Book	章节上下文保持完善

人工审核分块结果

解析完成后，花 10-15 分钟检查分块结果：

• 修正明显的错误切分
• 删除无关内容（封面碎片、空白页等）
• 必要时合并被过度切分的知识块
• 特别注意检查表格和公式的提取是否完整

调整 Chunk Size

• 如果发现回答不够详细（LLM 得到的信息不够完整），适当增大 Chunk Size（如从 500 调整到 800）
• 如果发现回答中包含太多不相关内容，适当减小 Chunk Size（如从 500 调整到 300）
• 建议每次调整幅度为 20-30%，然后观察效果

13.2 检索效果优化

使用混合检索

大多数场景下，混合检索的效果优于纯全文检索或纯向量检索。混合检索结合了两者的优势：

• 全文检索确保精确匹配（产品型号、合同编号等）
• 向量检索确保语义理解（同义词、近义表达）

建议的设置：向量权重 0.3-0.5，关键词权重 0.5-0.7。

调优 Top K

问题类型	推荐 Top K	原因
事实类（"产品价格是多少？"）	3-5	结果少，精确性要求高
操作类（"如何配置网络？"）	5-8	需要完整步骤，但不要太多干扰
分析类（"对比 A 和 B 的优劣"）	8-10	需要多角度的信息
综合类（"报告的主要结论"）	5-8	需要关键信息点

启用 Rerank

如果 RAGFlow 版本支持，开启 Rerank 功能可以显著提升检索结果的相关性排序。Rerank 的效果在以下场景特别明显：

• 知识库文档数量超过 100 份
• 不同文档之间存在大量相似内容
• 需要高质量的排序结果

利用 RewriteQuestion 节点

在多轮对话场景中，用户的问题往往包含指代（如"它"、"这个"、"那个"）。RewriteQuestion 节点将问题改写为完整表述，能显著提升后续问题的检索效果。

启用该功能后，多轮对话的准确率通常能提升 15-25%。

13.3 生产环境部署建议

使用 Elasticsearch

对于大规模文档（超过 10,000 个文件或 50,000 个知识块），建议将 DOC_ENGINE 从 infinity 切换为 elasticsearch。Elasticsearch 在大规模数据下的性能和稳定性更好，支持分片和副本，适合生产环境。

切换方法：在 .env 文件中修改 DOC_ENGINE=elasticsearch，然后重新部署。

配置 HTTPS

在生产环境中，务必配置 HTTPS，保护 API 通信安全和用户数据隐私。

通过 Nginx 反向代理配置 HTTPS 的示例：

server {
    listen 443 ssl;
    server_name ragflow.yourcompany.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:9380;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

数据备份

定期备份以下数据：

1. MySQL 数据库：存储用户、知识库、对话等元数据
2. Elasticsearch/Infinity 索引：向量索引和全文索引
3. MinIO 对象存储：上传的原始文件

备份脚本示例：

#!/bin/bash
# MySQL 备份
docker exec mysql-ragflow mysqldump -u root -p${MYSQL_PASSWORD} ragflow > backup_mysql_$(date +%Y%m%d).sql

# MinIO 备份（使用 mc 工具）
docker exec minio-ragflow mc cp --recursive local/ragflow/ backup/

# 清理 7 天前的备份
find backup/ -name "*.sql" -mtime +7 -delete

监控与告警

使用 Docker 的日志和监控工具监控 RAGFlow 各服务的运行状态：

# 查看资源使用情况
docker stats

# 查看服务日志
docker compose logs --tail=100 -f ragflow-server

# 检查服务健康状态
curl http://localhost:9380/api/v1/health

对于生产环境，建议配置 Prometheus + Grafana 进行系统级监控。

水平扩展

RAGFlow 的各微服务组件支持水平扩展。在高并发场景下：

• 增加 ragflow-server 的实例数量，通过负载均衡分发请求
• 对 Elasticsearch 进行分片和副本配置
• 使用 Redis 集群提升缓存性能

13.4 常见问题与排错

文件解析失败

可能原因：

• 文件格式损坏或不完整
• PDF 文件加密或受密码保护
• 文档内容过于复杂（如多层嵌套表格）
• 解析引擎不支持的文件格式

解决方式：

1. 尝试用其他工具打开文件，确认文件是否完好
2. 移除 PDF 的密码保护
3. 尝试将 DOC 转换为 DOCX 后重新上传
4. 从 DeepDoc 切换到 MinerU 重新解析
5. 检查 RAGFlow 版本是否支持该文件格式

检索结果为空

可能原因：

• 相似度阈值设置过高
• Embedding 模型未正确配置或未连接
• 知识库中确实没有相关内容
• 文件解析尚未完成

解决方式：

1. 在对话设置中降低相似度阈值（如从 0.3 降低到 0.15）
2. 检查 Embedding 模型的状态是否为绿色
3. 确认知识库中已有解析完成的知识块
4. 尝试使用不同的表述重新提问

回答质量差

可能原因：

• 知识库分块不合理（太粗或太细）
• LLM 模型能力不足（如使用小型本地模型）
• 系统提示词设置不当
• 检索到的上下文不相关

解决方式：

1. 检查并优化分块参数
2. 尝试使用更强的 LLM 模型
3. 优化系统提示词，增加具体约束
4. 启用 Rerank 功能优化结果排序

回答中出现乱码或格式异常

可能原因：

• 文档编码问题（如使用 GB2312 编码的文本文件）
• OCR 识别错误
• 特殊字符（如 Emoji、数学符号）处理不当

解决方式：

1. 在分块结果中手动修正异常内容
2. 更换解析引擎（从 DeepDoc 切换到 MinerU）
3. 将文档转换为 UTF-8 编码后重新上传
4. 检查 LLM 模型的字符编码支持

Docker 容器启动失败

可能原因：

• 系统内存不足
• 端口被占用
• Docker 镜像拉取失败
• Docker Compose 文件语法错误

解决方式：

1. 使用 docker stats 检查系统资源
2. 使用 netstat -ano | findstr 9380（Windows）或 lsof -i:9380（Linux）检查端口占用
3. 配置 Docker 镜像加速器
4. 使用 docker compose config 检查配置文件的语法

Ollama 模型连接失败

可能原因：

• API 地址配置错误（使用了 localhost 而非 host.docker.internal）
• Ollama 服务未启动
• Docker 网络隔离无法访问宿主机
• 模型名称与实际拉取的不一致

解决方式：

1. 确认 Ollama 服务运行中（ollama list）
2. 使用 host.docker.internal 或宿主机实际 IP 作为 API 地址
3. 在 Linux 下使用 extra_hosts 配置或 network_mode: host
4. 确认模型名称与 ollama list 的输出完全一致

系统响应慢

可能原因：

• 文档解析任务过多，系统资源不足
• LLM 推理速度慢（尤其是本地模型）
• 网络延迟（调用云端 API）
• 检索的数据量过大

解决方式：

1. 分批处理文档解析任务
2. 对于本地模型，升级 GPU 或使用更轻量的模型
3. 对于云端 API，选择响应更快的模型
4. 优化 Top K 参数，减少不必要的检索量
5. 为 RAGFlow 分配更多系统资源（CPU、内存）

第十四章：进阶学习路线

当你掌握了本教程中的基础内容后，可以沿着以下方向继续深入学习和实践。

14.1 源码阅读

克隆 RAGFlow 的 GitHub 仓库，阅读核心模块的源码，理解其实现原理。

建议的阅读顺序：

1. api/ 目录：RESTful API 的实现，了解前后端交互方式

   • api/ragflow_server.py：主服务入口
   • api/apps/：各功能模块的路由和处理器

2. rag/ 目录：核心 RAG 逻辑

   • rag/nlp/：自然语言处理相关（分词、关键词提取等）
   • rag/llm/：LLM 调用封装
   • rag/naive/：基础 RAG 实现
   • rag/resume/：文档解析相关

3. agent/ 目录：Agent 工作流引擎

   • agent/canvas/：画布节点的定义和执行逻辑
   • agent/component/：各类节点的实现

4. deepdoc/ 目录：DeepDoc 文档解析引擎

   • deepdoc/parser/：各种文件格式的解析器
   • deepdoc/recognizer/：OCR 和版面分析

阅读源码的价值：

• 理解 RAGFlow 的核心实现原理
• 掌握文档解析、分块、检索等关键技术的实现细节
• 为二次开发和定制化修改打下基础
• 遇到 Bug 时能够快速定位和修复

14.2 二次开发方向

基于 RAGFlow 的 API 和 SDK，你可以进行以下方向的二次开发：

1. 自定义分块插件

如果你有特殊类型的文档，可以开发自定义的分块模板。继承 RAGFlow 的 ChunkMethod 接口，实现自己的分块逻辑。

2. 自定义解析引擎

对于特定类型的文档（如医疗影像报告、CAD 图纸等），可以开发自定义的解析引擎，替换默认的 DeepDoc 或 MinerU。

3. 集成到第三方平台

• 开发浏览器插件，让用户在浏览网页时直接查询知识库
• 开发 Slack / 企业微信 / 飞书 / 钉钉机器人
• 开发 VS Code / JetBrains IDE 插件，让开发者在编码时查询技术文档
• 集成到 WordPress / 钉钉文档 / 飞书文档等内容管理平台

4. 构建行业解决方案

• 法律行业：合同审查助手、法规检索系统
• 医疗行业：病历分析助手、医学文献检索
• 金融行业：报告分析助手、合规审查系统
• 教育行业：教学资源管理、智能问答系统
• 制造业：产品手册查询、故障诊断系统

14.3 社区参与

RAGFlow 是一个活跃的开源项目，参与社区是提升自己技术水平的好方式：

贡献方式：

1. 提交 Issue：在使用过程中遇到 Bug 或有功能建议，在 GitHub Issues 中提交
2. 参与讨论：在 Discussions 中参与技术讨论，回答其他用户的问题
3. 提交 Pull Request ：
   • 修复 Bug 或 typo（适合初次参与）
   • 改进文档和教程（文档贡献同样重要）
   • 添加新功能（需要深入了解代码）
4. 翻译：帮助翻译文档和界面到不同的语言
5. 分享案例：将你的使用案例和经验分享到社区

社区资源：

• GitHub 仓库：github.com/infiniflow/...
• 官方文档：ragflow.io/docs/
• 官方博客：ragflow.io/blog
• 微信/QQ 群：可在官网找到最新的社群信息

14.4 关注前沿

RAGFlow 的更新节奏很快，建议定期关注以下方向：

1. Agent 工作流

• 关注新的节点类型和功能更新
• 学习构建更复杂的多步骤工作流
• 探索 Agent 与其他系统的集成模式

2. MCP 协议集成

• 关注 MCP 生态的发展
• 学习如何将 RAGFlow 作为 MCP Server 接入更多 AI 工具
• 探索 Agent 中调用外部 MCP 工具的模式

3. 多模态支持

• 关注 RAGFlow 对图片、音频、视频等多模态内容的支持
• 学习如何处理和检索非文本内容

4. 性能优化

• 关注大规模知识库的检索优化技术
• 关注流式处理和实时更新的最佳实践

14.5 结合其他技术栈

将 RAGFlow 与其他 AI 和开发工具结合使用，构建更强大的应用：

1. RAGFlow + LangChain / LlamaIndex

在 LangChain 的 Agent 框架中，将 RAGFlow 作为一个检索工具节点调用，利用 LangChain 的工具调用和链式推理能力，结合 RAGFlow 的深度文档解析能力。

# 概念示例：在 LangChain 中调用 RAGFlow 作为检索工具
from langchain.agents import Tool
from ragflow_sdk import RAGFlow

rag = RAGFlow(api_key="xxx", base_url="http://localhost:9380")

def ragflow_search(query):
    chat = rag.get_chat("chat_id_xxx")
    result = chat.ask(query)
    return result.answer

tools = [
    Tool(
        name="RAGFlow Knowledge Base",
        func=ragflow_search,
        description="搜索公司内部知识库获取信息"
    )
]

2. RAGFlow + 自动化工具

结合 n8n、Zapier、Make 等自动化工具，将 RAGFlow 集成到工作流自动化中。例如，当有新的文档上传到云存储时，自动触发 RAGFlow 的解析和索引。

3. RAGFlow + 前端框架

使用 React / Vue / Svelte 等前端框架，基于 RAGFlow API 开发自定义的用户界面，满足特定的业务需求和品牌风格。

14.6 认证与评估

如果你想系统性地检验自己的学习成果，可以尝试以下方式：

1. 独立搭建一个完整的 RAG 系统

• 从零开始部署 RAGFlow
• 配置模型、创建知识库、上传文档
• 创建对话助手和 Agent 工作流

2. 参与开源贡献

• 修复一个 Issue 或提交一个 Pull Request
• 参与社区讨论和技术问答

3. 构建个人项目

• 选择一个你感兴趣的领域（如法律、医疗、教育）
• 使用 RAGFlow 构建一个完整的解决方案
• 将项目开源并分享到社区

4. 持续学习

• 订阅 RAGFlow 的 Release Notes
• 关注 AI 和 RAG 领域的最新研究进展
• 阅读相关的技术博客和论文

附录 A：常用命令速查

以下命令默认在 ragflow 项目根目录下执行（即 docker-compose.yml 文件所在的目录）。

基础管理命令

# 启动 RAGFlow 全部服务
docker compose up -d

# 停止 RAGFlow 全部服务
docker compose down

# 重启 RAGFlow 全部服务
docker compose restart

# 查看所有服务的运行状态
docker compose ps

# 查看指定服务的日志
docker compose logs ragflow-server
docker compose logs -f ragflow-server  # -f 表示持续跟踪日志

# 查看所有服务的日志
docker compose logs -f

# 查看服务资源使用情况
docker stats

部署与更新命令

# 拉取最新镜像（更新前执行）
docker compose pull

# 完全重新部署（会重建容器但不删除数据卷）
docker compose up -d --force-recreate

# 停止并删除所有容器和数据卷（⚠️ 会清除所有数据！）
docker compose down -v

# 查看配置是否正确
docker compose config

数据库相关命令

# MySQL 备份
docker exec mysql-ragflow mysqldump -u root -p${MYSQL_PASSWORD} ragflow > backup_$(date +%Y%m%d).sql

# MySQL 恢复
cat backup_20260101.sql | docker exec -i mysql-ragflow mysql -u root -p${MYSQL_PASSWORD} ragflow

# 查看 Elasticsearch 索引
curl http://localhost:9200/_cat/indices

# 查看 Elasticsearch 文档数
curl http://localhost:9200/ragflow*/_count

Ollama 相关命令

# 查看已拉取的模型列表
ollama list

# 拉取新模型
ollama pull qwen2.5:7b

# 删除模型
ollama rm qwen2.5:7b

# 查看 Ollama 服务状态
ollama ps

# 测试 Ollama 是否正常
curl http://localhost:11434/api/tags

文件操作命令

# 查看 RagFlow 文件存储（MinIO）
docker exec minio-ragflow mc ls local/ragflow/

# 进入容器内部
docker exec -it ragflow-server /bin/bash

# 查看容器日志
docker inspect ragflow-server

网络调试命令

# 测试容器能否访问宿主机
docker exec ragflow-server ping host.docker.internal

# 测试外部 API 连通性
docker exec ragflow-server curl -I https://api.deepseek.com

# 查看容器 IP
docker inspect ragflow-server | grep IPAddress

附录 B：配置文件详解

.env 文件完整配置项

# ===== 服务端口 =====
# RAGFlow Web 服务绑定端口
SVR_HTTP_PORT=9380

# ===== 数据库引擎 =====
# 可选：infinity（默认，轻量级）或 elasticsearch（生产环境推荐）
DOC_ENGINE=infinity

# ===== Elasticsearch 配置（仅 DOC_ENGINE=elasticsearch 时生效） =====
ES_HOST=es01
ES_PORT=9200

# ===== MySQL 配置 =====
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=ragflow

# ===== Redis 配置 =====
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=ragflow

# ===== MinIO 对象存储 =====
MINIO_ENDPOINT=minio:9000
MINIO_USER=minio_admin
MINIO_PASSWORD=minio_admin

# ===== Docker 镜像配置 =====
RAGFLOW_IMAGE=infiniflow/ragflow:v0.25.0

# ===== 网络代理（如需） =====
HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,127.0.0.1,.local

附录 C：参考资源

官方资源

• GitHub 仓库 ：github.com/infiniflow/...
  • 代码、Issues、Discussions、Release Notes
• 官方文档 ：ragflow.io/docs/
  • 安装指南、API 文档、功能说明
• 官方博客 ：ragflow.io/blog
  • 技术分享、版本更新、案例研究
• SDK（Python） ：pypi.org/project/rag...
  • Python 开发包

相关工具

• Ollama ：ollama.com
  • 本地运行和管理 LLM
• Docker Desktop ：www.docker.com/products/do...
  • Windows/macOS 上的 Docker 运行环境
• DeepSeek ：platform.deepseek.com
  • 国产高性价比 LLM API
• SiliconFlow ：siliconflow.cn
  • 国内开源模型 API 平台

学习资源

• RAG 技术概览 ：arxiv.org/abs/2005.11...
  • Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
• LangChain 教程 ：python.langchain.com/docs/tutori...
  • LangChain 的 RAG 实现教程
• 向量数据库入门 ：www.pinecone.io/learn/vecto...
  • 向量数据库基础概念

社区交流

• GitHub Issues：遇到 Bug 或技术问题可以在这里搜索和提问
• GitHub Discussions：功能讨论和最佳实践分享
• 官方社群：通过官网获取最新的微信群/QQ群信息