从部署 RAGFlow 开始，配置模型、创建数据集、解析文档，再创建一个能够引用资料回答问题的 Chat Assistant，完整跑通一次知识库问答。
RAGFlow 入门：它是怎样把文档变成知识库的
RAGFlow 不只是一个“上传文档后就能聊天”的工具。这篇是我的第一篇 RAGFlow 学习笔记，主要记录它在知识库问答中的位置，以及一份原始文档从解析、切片到被检索和引用的完整过程。
前段时间，公司内部搭建了一套专业知识平台：员工从统一的聊天页面提问，系统再到内部资料中查找答案。真正参与过这套系统以后，我才发现，所谓“让大模型阅读公司文档”，远不只是上传几个 PDF 那么简单。
文档里的标题、表格和页码能不能识别，切片会不会把一句完整的话拆开，用户换一种说法还能不能找到同一段内容，回答后能不能指出资料来源，这些问题都会影响最后的效果。
我也正是在这个过程中接触到 RAGFlow。这篇先不急着研究复杂参数，我想从最基本的问题开始：RAGFlow 到底在整套知识问答系统中做了什么，以及一份文档是怎样变成可检索知识的。
先把 RAG 这件事说清楚
大模型在训练完成以后，并不知道公司刚刚发布的制度、产品手册和业务流程。即使模型知道一些通用知识，也不能保证它说出的内容和公司当前资料一致。
RAG 是 Retrieval-Augmented Generation 的缩写，也就是“检索增强生成”。它并不要求大模型把公司资料重新训练一遍，而是在回答问题之前，先从知识库中找到相关内容，再把这些内容和用户问题一起交给大模型。
我以前对 RAG 的理解偏向中间的“向量检索”，真正做过以后才意识到，检索只是其中一段。原始文档能不能被正确解析，往往在更早的时候就决定了效果上限。
如果表格被抽成一堆顺序错乱的文本，后面的 Embedding 和 Rerank 再好，也很难还原出正确答案。
RAGFlow 的位置
RAGFlow 官方文档把它定义为一个基于深度文档理解的开源 RAG 引擎。我现在更愿意把它理解成位于原始资料和大模型之间的知识处理层。
这里有一个很重要的边界：RAGFlow 不是大模型本身。
它需要连接 Chat Model、Embedding Model，必要时还会使用 Rerank Model 和视觉模型。RAGFlow 负责把文档处理好、把相关知识找出来，再调用配置好的模型完成回答。
我对几个模型角色的理解
- Chat Model：理解问题，并根据上下文组织答案；
- Embedding Model：把文档和问题变成可比较的向量；
- Rerank Model：对初步召回的内容重新排序；
- Vision Model：辅助理解图片、扫描件和复杂页面。
它们不是“越多越好”，而是分别解决不同环节的问题。
部署前先看资源
RAGFlow 不是只有一个 Web 服务。默认 Docker Compose 还会带起文档引擎、数据库、对象存储和缓存等依赖，所以它对机器资源的要求明显高于一个普通管理后台。
本文实验环境
本文以 RAGFlow v0.26.0 的 Docker 部署方式为参照。官方当前给出的最低参考是 4 核 CPU、16 GB 内存、50 GB 磁盘，并要求 Docker 24.0.0 及以上、Docker Compose 2.26.1 及以上。
RAGFlow 更新比较快，真正部署时还需要回到 Quickstart 和 Configuration 核对当前版本。
默认环境中的几个服务各有用途：
这张图也解释了一个现象：页面可以打开，不代表整套服务已经可用。MySQL、Redis、MinIO 或文档引擎有任何一个没准备好，都可能表现为登录异常、上传失败或者文档一直无法完成解析。
用 Docker Compose 跑起来
官方推荐使用 Docker。为了让实验可以重复，我会固定到一个明确的稳定标签，而不是直接跟随 nightly。
步骤 1：拉取代码并固定版本
git clone https://github.com/infiniflow/ragflow.git cd ragflow git switch --detach v0.26.0步骤 2：检查
vm.max_map_countElasticsearch 需要足够的内存映射区域。在 Linux 上可以先检查：
sysctl vm.max_map_count sudo sysctl -w vm.max_map_count=262144临时修改在重启后会失效，正式环境还需要写入系统配置。Windows + WSL2 和 macOS 的处理方式不同，官方 Quickstart 中都有对应说明。
步骤 3：检查部署配置
cd docker我至少会检查
.env中的镜像版本、端口、MySQL、MinIO、Redis 和文档引擎密码。示例密码可以用于本地实验，正式环境不能原样带上生产。步骤 4：启动服务
docker compose up -d docker compose ps docker compose logs -f我会先等主要服务完成初始化，再打开页面。刚启动就访问，前端有时只会给出一个比较笼统的网络异常。
RAGFlow 的配置主要分布在三个位置：
| 文件 | 我理解的职责 |
|---|---|
.env | 镜像、端口、资源限制以及依赖服务的环境变量 |
service_conf.yaml.template | RAGFlow API、任务执行器和后端服务连接配置 |
docker-compose.yml | 容器、网络、挂载和启动关系 |
我第一次接触时很容易把所有配置都归到 .env。后来排查过几次才发现，先分清“容器怎样启动”和“RAGFlow 启动后怎样连接后端”，看配置会清楚很多。
配置模型
RAGFlow 启动后，我先进入模型供应商设置，配置 Chat Model 和 Embedding Model。对于第一次实验，Rerank 可以后加，先把最短路径跑通。
如果模型也运行在 Docker 中，需要注意：容器里的 localhost 指向容器自己，不是宿主机。模型部署在宿主机时，可以根据系统使用 host.docker.internal 或宿主机在容器网络中的地址；模型在另一个容器时，通常应该使用 Compose 服务名。
一个容易被忽略的限制
一个数据集开始用某个 Embedding Model 解析文件后，就不能随意改成另一个 Embedding Model。不同模型产生的向量不在同一个空间里，不能直接混在一起比较。
如果必须更换，稳妥的做法是新建数据集并重新解析。
创建第一份数据集
为了后面几篇能够连起来，我给这次学习准备了一套脱敏资料：
- 一份产品使用手册；
- 一份售后处理流程；
- 一份包含型号和参数的 Excel；
- 一份常见问题说明。
这些文档格式不同，正好可以观察 RAGFlow 对普通段落、步骤和表格的处理差异。
步骤 1：创建 Dataset
先选择 Embedding Model，再选择合适的 Chunk Method。第一遍可以从
General开始，不需要一上来就调整所有参数。步骤 2：上传并解析文件
上传成功只是把文件保存下来，还需要点击解析。解析过程会完成版面识别、文本提取、切片、Embedding 和索引。
步骤 3：检查 Chunk
我会重点看标题有没有跟正文分离、表格有没有错列、步骤有没有从中间切断，以及来源页码是否还在。
步骤 4：执行 Retrieval Test
在创建聊天助手之前，先直接测试检索。这里如果找不到正确片段，Chat Model 通常也救不回来。
步骤 5：创建 Chat Assistant
关联数据集、选择 Chat Model，设置系统提示词和“没有检索到答案时”的回复，再开启引用。
第一次问答，我先看引用
第一次提问时，我不会只看答案是否通顺，而是先检查三件事：
- 命中的 Chunk 是不是来自正确文档；
- Chunk 是否真的包含回答依据；
- 引用能不能回到对应文档和位置。
一段读起来很自然的回答，并不一定来自知识库。对于内部制度、产品参数这类内容，能够核对来源，比语言是否漂亮更重要。
我对 RAGFlow 特点的第一轮认识
跑完这一遍以后，我觉得 RAGFlow 最有价值的并不是“自带一个聊天页面”，而是下面几个特点：
- 文档处理是可见的：能看到 Chunk，不必把解析过程当成黑盒；
- 复杂文档是主要目标：PDF、表格、图片和演示文稿都在支持范围内；
- 检索可以单独验证：回答不对时，可以先把检索和生成拆开；
- 引用有完整链路：答案可以关联到文档和具体片段；
- 模型可以替换：Chat、Embedding、Rerank 并不绑定某一家供应商；
- 能力可以 API 化：知识问答不一定只能使用 RAGFlow 自带页面。
这也让我重新理解了 RAG 系统：真正可靠的知识问答，不是给大模型多塞几段文字，而是建立一条可以检查、可以调整、可以追溯的知识链路。
下一篇我会继续拆开文档解析、Chunk、混合检索和 Rerank，看看答案不准时究竟应该从哪里开始调整。