1. 为什么选择 RAGFlow 而不是自己拼一套 RAG 流水线1.1 从能跑到能交付之间的鸿沟我最早接触 RAG 是在 2023 年那时候团队要做一个内部知识库问答我的第一反应是这有什么难的——向量库选一个embedding 模型调一个检索 top-k 拼进 prompt完事。结果真到交付的时候问题一个接一个冒出来PDF 里的表格解析出来全是乱码扫描件根本读不出文字用户问第三季度的营收是多少这种需要跨页聚合的问题检索出来的片段永远是残缺的。那段时间我几乎把市面上能叫得出名字的 RAG 框架都试了一遍最后把 RAGFlow 留了下来原因很简单它是少数把文档解析当成一等公民来做的框架而不是把解析当成一个可有可无的预处理步骤。RAGFlow 的定位很明确它是一个基于深度文档理解Deep Document Understanding的 RAG 引擎。这句话翻译成人话就是它不只是把你的文档切块丢进向量库而是先想办法读懂文档的结构——标题层级、表格、图片、公式、页眉页脚然后再决定怎么切、怎么索引。这一点对于真实业务场景太重要了因为企业里的文档八成是 PDF、Word、Excel、PPT 这些非纯文本格式你如果解析这一关过不去后面检索再花哨都是空中楼阁。1.2 它到底解决了哪些别人没解决好的问题我把 RAGFlow 相对其他方案的核心差异总结成三点这三点也是我最终选它的理由。第一是模板化的分块策略。RAGFlow 内置了 General、QA、Resume、Manual、Table、Paper、Book、Laws、Presentation 等一堆分块模板每种模板对应不同的文档类型和切分逻辑。比如 Paper 模板会识别论文的摘要、章节、参考文献Table 模板会专门处理表格的行列关系。你不需要自己去写正则表达式调切分参数选对模板基本就能拿到可用的结果。第二是可视化的人工干预能力。文档解析完之后RAGFlow 提供了一个界面让你看到每个 chunk 是怎么切的切得不好可以手动调整甚至可以直接改 chunk 的内容。这一点在实际项目里救命——自动解析永远有搞不定的边角案例能人工兜底才是能交付的产品。第三是原生的 Agent 能力。从 0.8 版本之后RAGFlow 把 Agent 做进了主流程你可以把知识库检索、网页搜索、代码执行、大模型调用这些能力编排成一个工作流。这意味着你不需要再单独搭一套 LangChain 或者 Dify 来做编排知识库和 Agent 在同一个系统里数据流转和权限管理都省心很多。1.3 什么样的团队适合上 RAGFlow不是所有场景都值得上 RAGFlow。如果你的需求只是把几十个 Markdown 文件做成问答那用 LlamaIndex 写个脚本半小时就搞定了没必要上这么重的系统。RAGFlow 适合的是这几类场景文档量大且格式复杂几百上千份 PDF、扫描件、表格混在一起对解析质量要求高比如法律、金融、医疗这类不能容忍关键信息丢失的领域需要给非技术同事用的可视化界面以及需要把知识库和 Agent 编排结合起来做复杂任务的团队。反过来说如果你追求的是极致的轻量和可定制愿意自己写解析逻辑那 RAGFlow 的重可能会让你觉得束手束脚。它是一个产品化的框架产品化就意味着有约定、有取舍你得接受它的那套玩法。2. 部署前的环境盘点别让 Docker 在第一步就卡住你2.1 硬件与系统的最低门槛RAGFlow 官方给的资源要求是 CPU 4 核、内存 16GB、磁盘 50GB 起步。我实测下来这个配置只能算能跑起来真要处理几百份文档内存建议直接上 32GB磁盘用 SSD。原因在于 RAGFlow 的文档解析尤其是 OCR 和布局识别是吃内存的大户解析大 PDF 的时候内存峰值能冲到好几个 G内存不够会直接 OOM 把容器干掉。系统方面Ubuntu 22.04 LTS 是我最推荐的24.04 也能跑但偶尔会遇到依赖版本的小问题。如果你用的是 Windows强烈建议不要在 Windows 上直接装 Docker Desktop 跑 RAGFlow我踩过这个坑——文件挂载的性能损耗和路径大小写问题会让你怀疑人生。正确做法是在 Windows 上装个 WSL2然后在 WSL2 的 Ubuntu 里装 Docker或者干脆找台 Linux 机器。提示如果你的机器是 ARM 架构比如某些云服务器或者 M 系列芯片的 Mac部署前一定要确认镜像有对应的 ARM 版本否则会卡在拉镜像那一步。2.2 Docker 与 Docker Compose 的安装细节RAGFlow 是用 Docker Compose 编排的所以你需要 Docker Engine 和 Docker Compose 两个东西。在 Ubuntu 上我习惯用官方脚本装比 apt 源里的版本新也省得处理依赖冲突# 卸载可能存在的旧版本 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 添加软件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin装完之后有个必做的动作把当前用户加进 docker 组否则你每次敲 docker 命令都得加 sudosudo usermod -aG docker $USER newgrp docker这里有个新手经常踩的坑加完组之后必须重新登录或者执行newgrp docker才生效很多人加完组发现还是要 sudo就是因为没刷新会话。2.3 那些让人抓狂的 Docker 启动报错virtualization support not detected 这个报错我见过太多次了。它的本质是你的机器没有开启硬件虚拟化或者 Docker Desktop 拿不到虚拟化权限。在 Linux 服务器上进 BIOS 把 Intel VT-x 或 AMD-V 打开就行。在 Windows 上除了 BIOS 要开还得确认 Hyper-V 和 WSL2 都启用了。如果是云服务器有些低配机型本身就不支持嵌套虚拟化这种情况只能换机型。另一个高频问题是磁盘空间。Docker 默认把镜像和数据存在/var/lib/docker如果你的根分区小拉几个大镜像就满了。解决办法是改 Docker 的数据目录到一块大磁盘上编辑/etc/docker/daemon.json{ data-root: /data/docker }改完重启 Docker 服务注意迁移前先把原来的数据拷过去否则已有的镜像和容器会消失。3. 把 RAGFlow 拉起来从克隆到登录的完整链路3.1 获取源码与配置文件的取舍RAGFlow 的部署方式是先克隆仓库再用它自带的 docker-compose 文件启动。这里有个关键决策用哪个 compose 文件。仓库里通常有docker-compose.yml和docker-compose-base.yml之类的文件前者是完整版包含所有依赖服务后者是精简版。我的建议是第一次部署直接用完整版把 MySQL、Redis、MinIO、Elasticsearch 这些依赖都拉起来跑通之后再考虑精简。git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker克隆下来之后先别急着docker compose up。RAGFlow 的镜像版本和源码版本是要匹配的如果你直接拉 latest 镜像可能会遇到前后端版本不一致导致的诡异 bug。正确做法是看仓库里的docker/.env文件里面有个RAGFLOW_IMAGE变量指定了镜像的 tag。我一般会把它固定到一个明确的版本号比如infiniflow/ragflow:v0.15.0而不是用latest这样出了问题好回滚。3.2 启动过程中的资源拉取与等待启动命令很简单docker compose -f docker-compose.yml up -d但简单背后是漫长的等待。第一次启动要拉好几个 G 的镜像包括 Elasticsearch这个镜像本身就一个多 G、MySQL、Redis、MinIO还有 RAGFlow 自己的镜像。网络不好的话这一步能卡你半小时。我的经验是提前把镜像拉好或者配置国内镜像加速器。拉起来之后用docker compose ps看状态你会发现 Elasticsearch 和 RAGFlow 主服务启动特别慢。Elasticsearch 慢是因为它要初始化索引RAGFlow 慢是因为它要等所有依赖服务就绪。这时候别慌也别急着重启给它三五分钟。判断是否真的起来了看日志docker compose logs -f ragflow-server看到类似 Running on all addresses 或者 Application startup complete 的字样就说明服务起来了。3.3 首次登录与模型配置的必做项服务起来之后浏览器访问http://你的服务器IP:80默认端口是 80可以在.env里改。默认账号是admin密码在.env文件里的DOC_ENGINE附近能找到或者看官方文档第一次登录会强制你改密码。登录进去第一件事不是建知识库而是配模型。RAGFlow 本身不带大模型它需要你接入外部的 LLM 和 embedding 模型。这里我强烈建议用国内的模型服务比如智谱、通义、DeepSeek 这些一来网络稳定二来有免费额度可以先试。配置路径在右上角头像 - 模型提供商填 API Key 和 Base URL 就行。注意embedding 模型一旦选定建了知识库之后就不要随便换。因为不同 embedding 模型生成的向量维度不一样换了之后已有的向量全部作废得重新解析所有文档。这个坑我踩过一个几百份文档的知识库重新跑了一遍花了整整一个下午。4. 知识库配置解析质量的决定性因素4.1 分块模板的选择逻辑建知识库的时候RAGFlow 会让你选一个 chunk method分块方法。这个选择直接决定了后续检索的质量但很多人是随便选的。我把常见模板的适用场景整理成一张表你对着选就行模板名称适用文档类型核心特点General通用文本、混合内容按段落和标题切分最保险的默认选项QA问答对、FAQ 文档识别问答结构一问一答作为一个 chunkPaper学术论文识别摘要、章节、参考文献保留引用关系Manual产品手册、说明书识别步骤、注意事项保留层级结构Table表格为主的文档专门处理行列关系避免表格被切碎Laws法律法规识别条款编号按条款切分PresentationPPT 转出的文档按幻灯片页切分保留页面结构选模板的核心原则是文档长什么样就选什么。一份产品说明书你选 General它会把步骤和注意事项混在一起切检索出来的结果就很乱选 Manual它知道哪些是步骤哪些是警告切出来的 chunk 语义更完整。4.2 解析参数的调优经验选完模板还有一堆参数要调我挑几个最影响效果的说说。chunk token 数默认是 128 还是 256 我记不太清了但我的经验是中文文档建议设到 256 到 512 之间。设太小一个完整的语义单元被切碎检索出来上下文不全设太大一个 chunk 里混了好几个主题检索精度下降。这个值没有标准答案得拿你的真实文档试。delimiter分隔符默认是\n也就是按换行切。如果你的文档是那种一段话特别长的可以加上中文句号。作为分隔符让切分更细。layout recognize布局识别这个开关控制是否用视觉模型识别文档布局。开了之后表格、图片、多栏排版的处理会好很多但解析速度会明显变慢。我的建议是文档质量差扫描件、复杂排版就开文档本身就是规整的电子版就关。RAPTOR这是 RAGFlow 的一个特色功能开启后会对文档做层次化的摘要检索的时候能同时命中细节和全局。对于需要总结全文类问题的场景很有用但会额外消耗模型 token成本敏感的话慎开。4.3 解析结果的人工校验文档解析完之后一定要去 chunk 列表里抽查。我一般会随机点开十几个 chunk看三件事内容有没有乱码尤其是 PDF 里的特殊字符、表格有没有被切碎、标题和正文有没有被错误地合并。发现问题的处理方式有两种。轻度的直接在界面上编辑 chunk 内容改完保存就行。重度的比如整份文档解析得一塌糊涂就得回到解析配置调整参数重新解析。RAGFlow 支持对单个文档重新解析不用把整个知识库推倒重来这一点很人性化。提示解析是个耗时操作几百份文档可能要跑几个小时。建议先用十几份有代表性的文档试跑把参数调满意了再批量导入别一上来就把所有文档丢进去。5. Agent 后端接入让知识库真正动起来5.1 RAGFlow Agent 的能力边界RAGFlow 的 Agent 本质上是一个可视化的工作流编排器。你可以把知识库检索、大模型对话、条件判断、循环、代码执行这些节点拖到画布上连成一条流程。它和 Dify、Coze 那类产品的思路类似但优势在于知识库检索是原生集成的不需要额外配置。一个典型的 Agent 流程长这样用户输入问题 - 判断问题类型 - 如果是知识库相关问题就走检索节点 - 检索结果喂给大模型 - 大模型生成回答 - 返回给用户。如果问题需要实时信息就加一个网页搜索节点如果需要计算就加一个代码执行节点。5.2 通过 API 把 Agent 接入你的业务系统RAGFlow 的 Agent 做出来之后最终是要被你的业务系统调用的。它提供了 HTTP 和 Python SDK 两种接入方式。HTTP 方式最通用任何语言都能调curl -X POST http://你的服务器IP/api/v1/agents/你的agent_id/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API_KEY \ -d { question: 第三季度的营收是多少, stream: false, session_id: 可选的会话ID }API Key 在 RAGFlow 的 API 页面生成注意这个 Key 是和 Agent 绑定的不同 Agent 的 Key 不一样。session_id是可选的传了之后 RAGFlow 会维护多轮对话的上下文不传就是单轮问答。Python SDK 的用法更简洁from ragflow_sdk import RAGFlow rag RAGFlow(api_key你的API_KEY, base_urlhttp://你的服务器IP) agent rag.get_agent(你的agent_id) # 单轮 response agent.completion(第三季度的营收是多少) print(response) # 多轮 session agent.create_session() response agent.completion(第三季度的营收是多少, sessionsession) response agent.completion(那第四季度呢, sessionsession)5.3 接入过程中的几个真实坑坑一API 返回的流式数据解析。如果你用stream: true返回的是 SSE 格式的数据流每一行以data:开头。很多 HTTP 客户端默认会缓冲整个响应导致你拿不到流式效果。用 Python 的 requests 要加streamTrue用 fetch 要注意处理 chunk。坑二超时设置。RAGFlow 的检索加生成复杂问题可能要十几秒甚至更久。如果你的业务系统默认超时是 5 秒会大量报超时错误。建议把超时设到 60 秒以上或者用流式返回让用户先看到部分结果。坑三并发限制。RAGFlow 默认的并发能力有限如果你的业务量大需要调整.env里的 worker 数量并且给服务器加资源。我见过有人拿单机 RAGFlow 扛生产流量结果高峰期直接卡死这个教训要吸取。坑四Agent 里的模型配置和知识库的模型配置是分开的。知识库用的是 embedding 模型Agent 用的是对话模型两个都要配好缺一个都会报错。而且 Agent 里如果用了多个模型节点每个节点都要单独确认模型可用。6. 生产环境的稳定性与运维要点6.1 数据持久化与备份RAGFlow 的数据分散在好几个地方MySQL 存元数据MinIO 存原始文件和解析结果Elasticsearch 存向量索引Redis 存缓存。做备份的时候这几个都要覆盖只备份 MySQL 是不够的。我的做法是给这几个服务的 volume 目录做定期快照同时用mysqldump单独导一份 MySQL 数据。恢复的时候先恢复 volume再导入 MySQL 数据最后重启服务。注意 Elasticsearch 的索引恢复比较慢要有耐心。6.2 资源监控与扩容信号跑生产环境一定要监控几个指标容器内存使用率、Elasticsearch 的 JVM 堆内存、磁盘剩余空间。Elasticsearch 的堆内存如果长期在 80% 以上检索会变慢甚至 OOM这时候要么加内存要么调小堆大小。扩容的信号也很明确解析任务排队越来越长、API 响应时间持续上升、容器频繁重启。出现这些情况就该考虑加机器或者做水平扩展了。RAGFlow 本身支持多实例部署但要注意共享存储和数据库的配置。6.3 版本升级的注意事项RAGFlow 迭代很快几个月就是一个大版本。升级的时候千万别直接docker compose pull然后重启一定要先看 release notes确认有没有数据库 schema 变更。有 schema 变更的版本升级前必须备份数据库升级后可能要跑迁移脚本。我的习惯是先在测试环境升一遍把主要功能跑通再升生产。生产升级选在业务低峰期升级完立刻验证知识库检索和 Agent 调用是否正常。7. 我在实际项目里攒下的几条经验第一条别迷信自动解析。再好的解析引擎也有搞不定的文档尤其是那些排版奇葩的扫描件。我的做法是给每个知识库配一个解析质量负责人文档导入后人工抽查发现问题及时调整。这个投入是值得的因为解析质量直接决定了整个系统的上限。第二条embedding 模型的选择比 LLM 更重要。很多人把精力花在选哪个大模型上其实检索阶段如果召回的都是不相关的片段再强的 LLM 也救不回来。中文场景我推荐用 bge 系列或者智谱的 embedding实测召回质量比一些通用模型好不少。第三条Agent 的复杂度要克制。我见过有人把 Agent 画得跟迷宫一样十几个节点绕来绕去结果调试的时候根本不知道哪一步出了问题。我的原则是能用三个节点解决的就别用五个流程越简单越稳定出问题也越好定位。第四条给用户留反馈入口。RAGFlow 的对话界面支持点赞点踩这个数据非常宝贵。定期看用户点踩的回答能发现很多检索和解析的隐藏问题。我有个项目就是靠用户反馈发现某类文档的表格一直解析错误调整模板后效果立竿见影。最后分享一个排查问题的思路当 Agent 回答不对的时候先看检索出来的 chunk 对不对再看 LLM 的 prompt 有没有问题最后才怀疑模型本身。这个顺序能帮你快速定位问题出在检索层还是生成层避免瞎调参数。