企业官网建设流程全解析

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、Q&A、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 a+r /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 命令都得加 sudo：

sudo 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，它会把步骤和注意事项混在一起切，检索出来的结果就很乱；选 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_url="http://你的服务器IP") agent = rag.get_agent("你的agent_id") # 单轮 response = agent.completion("第三季度的营收是多少？") print(response) # 多轮 session = agent.create_session() response = agent.completion("第三季度的营收是多少？", session=session) response = agent.completion("那第四季度呢？", session=session)

5.3 接入过程中的几个真实坑

坑一：API 返回的流式数据解析。如果你用stream: true，返回的是 SSE 格式的数据流，每一行以data:开头。很多 HTTP 客户端默认会缓冲整个响应，导致你拿不到流式效果。用 Python 的 requests 要加stream=True，用 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 有没有问题，最后才怀疑模型本身。这个顺序能帮你快速定位问题出在检索层还是生成层，避免瞎调参数。