企业官网建设流程全解析

做RAG落地这件事，我在团队里折腾了快两年。最早我们也是按网上教程东拼西凑：文档解析用一套开源库，向量库选一套，Embedding接一家API，最后再拿LangChain串起来。结果做Demo很顺利，一旦面对真实业务文档，就开始四处漏风：PDF里表格被切得稀碎，扫描件出来的全是乱码，用户问“这个流程在第几页有说明”模型根本答不上来。后来换到RAGFlow，才慢慢把文档解析、切分、召回、引用这些环节串成了一套真正能用的体系。

这篇文章不是官方文档的复读，而是我把RAGFlow从安装到实际项目跑通的系统性经验整理。它是什么、能解决什么问题、怎么部署、怎么选知识库类型、遇到坑怎么排，我会按自己踩过的路径一步步讲清楚。如果你正准备搭一个能落地的RAG知识库，或者已经在其他框架里被文档解析折腾到怀疑人生，这篇内容应该能帮你少走不少弯路。

1. 动手之前，先搞懂RAG到底卡在哪

很多人一上来就急着部署，忽略了理解RAG的内在瓶颈。我这两年踩出来的最大教训是：RAG项目十有八九不是死在模型不够强，而是死在“文档进来之后到答案出去之前”这一整条链路太糙。

1.1 我踩过的那几个典型瓶颈

第一个瓶颈是文档解析。常规RAG流程里，PDF进来之后往往就是按页码或固定长度切块，然后直接向量化。这个做法遇到排版本复杂的文档基本就废了：表格的行列关系丢了，图片里的文字被当成空白，标题和正文混在一起，最后召回的片段护士长读都读不通。你以为是模型理解能力差，实际是喂进去的料本身就是碎的。

第二个瓶颈是召回环节。纯粹的向量检索用余弦相似度找“语义相近”的片段，但语义相近不等于信息正确。比如用户问“退款到账要几天”，文档里可能存在十几处提到“退款”的地方，向量排名靠前的很可能是规则条目而不是答案所在的那个段落。没有关键词检索、没有重排模型去二次筛选，光靠向量TopK很容易被噪声淹没。

第三个瓶颈是引用不可验证。传统RAG返回的一堆片段，用户不知道它来自哪份文档、哪一页、哪个条款，出了问题没法复核。对内部知识库来说，不能给出可追溯的引用，业务方根本不敢把回答直接放出去。

第四个瓶颈其实是工程问题：组件之间版本兼容差，解析、向量化、检索、生成的参数散落在各个地方，出了问题排查成本极高。我们的第一版系统，经常是换一个Embedding模型就要重新调一遍切块大小，身心俱疲。

1.2 RAGFlow的解题思路：与其堆组件，不如做系统

RAGFlow打动我的不是某个单点功能，而是它把“文档解析—召回—重排—生成—引用”做成了完整闭环。用它的DeepDoc引擎做版面识别，能先还原文档结构再决定怎么切块；召回阶段同时支持向量检索和全文检索，再用rerank模型二次筛选；回答的每个引用都能回溯到原始Chunk，点开就能看到内容。

这套设计思路很接近一个真实的产品决策：要想让RAG在企业场景里可用，前端要处理非结构化文档的复杂性，后端要兼顾检索质量与可解释性。RAGFlow把这两件事在产品层面固化下来，你不用再为“PDF表格怎么提取”这类问题自己造轮子，这也是我这个系列教程最想强调的核心理念。

2. RAGFlow核心模块拆解：DeepDoc、双检索与知识图谱

想用好RAGFlow，不能只把它当成一个黑盒。它的价值集中在几个核心模块里，搞清楚每个模块的定位，你才知道参数该怎么调、流程该怎么配。

2.1 DeepDoc为什么是RAGFlow的“立身之本”

DeepDoc是RAGFlow自研的文档结构化解析引擎。和普通解析库最大的区别是，它先做版面分析，识别出标题、正文、表格、图片、页眉页脚，再按照文档类型选择合适的分块策略。

我在项目里最常用到的几个解析能力有四个。第一个是版面还原，对多栏PDF尤其有效，不会再出现左右栏文字交叉拼接的惨状。第二个是表格结构识别，DeepDoc能把表格抽取成相对结构化的形式，而不是把单元格内容当成一串流水文本。第三个是OCR兜底，扫描版PDF可以通过OCR把图像中的文字提取出来，再进入后续流程。第四个是领域模板，RAGFlow内置了paper、book、law、manual、presentation等几种解析模板，不同模板对章节层级和代码块的切分偏好不一样，选对模板能明显提升切块质量。

实操上的建议是：中文技术文档、规章制度这类材料，优先选“版面还原+手动配置模板”的方式；混合扫描件和电子版PDF的项目，务必打开OCR开关；对表格密集的文档，解析完一定要去Chunk列表里检查表格内容是否完整，不要直接信默认输出。

2.2 双检索和重排：召回不准的兜底方案

召回策略上，RAGFlow默认使用“向量检索+全文检索”的混合模式。向量检索负责语义相近，全文检索负责精确命中关键词。这个设计对中文场景尤其重要，比如查“合同编号A-2026-0815”这类精确串，向量检索经常顾左右而言他，但全文检索能直接命中原文字符。

混在一起之后，再用重排模型统一打一次分。重排的意义在于，初级检索允许召回更宽的候选集，重排阶段再做精细化排序，这样既不会因为TopK设太小的阈值而漏掉正确答案，也不会让一堆无关片段挤占高位。

调参上我习惯先保持默认，再根据效果微调。如果发现答非所问，就先调大候选数量，再观察重排后真实命中位置；中文场景下建议优先选择BGE等中文Embedding模型，英文通用模型应对中文文档效果普遍不理想。

2.3 知识图谱能力：和RAG知识库互补的另一套玩法

RAGFlow提供的知识图谱（KG）能力，是它区别于普通RAG壳子的重要一点。常规RAG知识库处理的是“一段一段的文本”，知识图谱处理的是“一个一个的实体和关系”。RAGFlow支持用户提前定义Ontology，也就是实体类型和关系类型，例如实体可以定义成“产品”“部门”“负责人”，关系可以定义成“隶属于”“负责”，然后系统从文档中抽取这些实体和关系，构建成图。

构建好图谱之后，问答阶段就可以借助图谱检索，把实体之间的关系链提供给大模型。举一个我做过的小例子：文档里写“张工负责RAGFlow平台的运维，而RAGFlow平台被财务部采购”，普通向量检索只能回答“谁负责RAGFlow”，而带知识图谱的RAG能回答“财务部采购的系统，运维负责人是谁”，因为它把两次关系跳转给串起来了。这个能力在处理多跳问答、关系型提问时优势特别明显。

不过我建议不要一上来就给所有文档开图谱。构建Ontology和抽取实体本身有成本，小规模文档库用不上；当你的问答场景里有明显的“谁、属于、负责、采购”这类关系词，再去配置图谱才有性价比。

2.4 Agent Workflow：让多个知识库协作起来

RAGFlow的Agent模块提供了一套可视化工作流，可以在画布上拖拽检索节点、LLM节点、知识图谱节点，把多个知识库甚至外部工具串成一条流水线。

我实际用过的一个场景是客服问答：用户问题先进产品FAQ知识库，如果检索得分低于阈值，再触发第二个工单处理知识库，最后统一由大模型把两轮结果整理成带引用的答复。这套流程写代码也不难，但Agent Workflow的好处在于可视化、可调试、可以给业务人员直接调整参数，不需要改代码重新发布。

在Agent里要特别注意“分支条件”的设置。让哪类问题走哪条分支，本质上是在模仿人工客服的判断过程，分支设得太粗会导致无用检索污染答案，设得太细则维护成本高。我的建议是先跑50个真实问题看失败分布，再决定要不要加分支。

3. 完整实操：从零部署一个RAGFlow知识库

这部分是新手最容易卡住的地方。RAGFlow的部署不算复杂，但有几个环境前提需要提前确认。我会按Linux服务器和Mac本机两种常见场景说明，并标注我实际遇到的问题。

3.1 环境准备和Docker部署（含Mac环境）

RAGFlow官方推荐用Docker Compose方式部署，它会把前后端服务、ES、MySQL、MinIO等一起编排起来。我强烈建议至少准备16GB内存，开发学习用8GB也能跑，但多容器同时启动会比较吃力。磁盘方面预留80GB以上，因为默认会带上镜像和向量缓存。

Linux部署基本就是三步：先确认已安装Docker和Docker Compose插件，再克隆RAGFlow源码仓库，然后进入源码目录执行docker compose up -d。部署前需要先看一下.env文件，确认接口端口是否和本机已有服务冲突。默认走80端口，如果你机器上已经跑了Nginx或其他Web服务，把映射端口改成比如28080再启动。

Mac上部署是一个高频问题。我自己的M系列芯片Mac用Docker Desktop跑RAGFlow是正常的，关键是把Docker Desktop的资源配额调高，尤其是内存，建议直接给到8GB以上。官方镜像已经支持ARM架构，不需要额外开兼容层，访问方式在Docker Desktop里映射出来的端口，浏览器打开localhost对应端口即可。如果你Mac上还同时跑着其他开发容器，注意总内存别超，否则整个Docker会进入假死状态，日志里全是OOM。

3.2 创建知识库、上传文档和解析配置

服务起来之后，注册账号登录，第一步就是创建知识库。RAGFlow的知识库类型默认是普通文档知识库，左侧也能创建知识图谱库。我建议先创建一个测试知识库，专门用来调解析参数。

上传文档之后进入配置页面，重点检查三项配置。第一是解析模板，常见文档选“通用”即可，论文选“论文”、法律文书选“法律”模板；第二是OCR开关，扫描件必须打开；第三是Chunk大小和重叠，中文环境下我习惯用512 Token左右作为默认值，特别短的条款类文档可以降到256，而长章节类文档可以提到768。Chunk太小会让上下文断裂，Chunk太大又会在向量检索时噪声变多，这个参数值得反复试。

配置完成之后点击解析，等解析结束不要急着问答。先去数据列表里看切分结果，RAGFlow的Chunk界面会直接展示每一段内容长什么样。这一步是我最看重的：如果文本乱序、表格丢失、标题没了，说明解析配置有问题，这时候调整解析策略的成本远低于事后补救。

3.3 调好检索参数，并验证问答效果

知识库解析完成后，进入对话测试页面，把“引用”按钮打开，回答里带的引用片段会直接显示内容。我每次测试都会先问几个和目标文档强相关的问题，逐个点开引用看是不是真的来自正确页面。

在知识库关联的Chat配置里，有几个参数值得关注：TopK的默认值通常可以先用，之后根据回答完整度调整；相似度阈值设太低会混入无关片段，太高又容易召回不到答案，通常在0.2到0.3之间起步比较稳。重排模型可以打开，如果配置了API就用API，也可以接本地Ollama跑一个较小的重排模型，对中文问答效果提升很明显。

如果一个问题的答案分布在不同文档里，建议不要试图靠一个超大Chunk解决，而是用Agent Workflow让多个知识库并行检索，最后让大模型做汇总。这样每段上下文都干净，最终回答质量反而更高。

4. 三种“知识库”怎么选型：文档库、知识图谱库与结构化数据库

热词里频繁出现“RAG知识库”和“结构化知识库”的区别，这是选型时必须想清楚的事。我工作中接触过不少团队，把结构化数据硬塞进向量库，结果统计类问题回答得一塌糊涂；也有团队把所有文档一股脑建图谱，最后维护成本压垮项目。

4.1 一张表看懂三者在能力上的区别

可以把RAG知识库、知识图谱库和结构化数据库的特点放在一起对比：

这张表不是我随便画出来的，每一条背后都是真实项目踩过的坑。很多团队把订单数据做成PDF再丢进RAG知识库，然后问“上月订单总额是多少”，模型只能猜，因为文档里根本没有做聚合计算。反过来，把规章制度强行转成本地数据库表，字段也定义不出来，因为文本里的语义关系本就不适合用字段表达。

4.2 场景判断方法：问三类问题，选对应方案

判断选型时，我通常让业务方先列出真实要问的问题，然后按类型归类。第一类是“某个规定是怎么写的”“这个操作步骤在手册哪里有说明”，这类适合文档型RAG知识库。第二类是“某某流程由谁负责，他属于哪个部门，与哪个系统相关”，这类适合知识图谱库。第三类是“库存还剩多少件”“最近三个月达标率是多少”，这类必须在结构化数据库里做聚合。

最麻烦的是三类问题混在一起。比如用户问“A系统最近的故障率是多少，对应的运维负责人是谁”，故障率是结构化计算，负责人是图谱关系，故障原因描述又藏在故障报告文档里。任何一个单一方案都答不全，这时候就轮到RAGFlow的Agent Workflow登场。

4.3 混合编排：RAGFlow里把多个库串成一条流程

RAGFlow支持在一个Agent流程中同时连接文档知识库、知识图谱库和文档解析结果。我的实践做法是：第一层用结构化查询节点，把能精确计算的字段先取出来；第二层用知识图谱节点，把实体之间的关系链拿到；第三层用文档知识库，把相关背景描述补全；最后统一交给大模型，按固定模板生成带引用的综合回答。

这种混合编排能解决单纯RAG知识库答不出来的问题，但也需要注意设计上的顺序：先取精确值，再做关系查询，再做语义检索，避免模糊检索把前面的精确结果给冲淡。流程顺序本身，比大模型的指令词更影响最终质量。

5. 常见问题排查与实操避坑记录

使用过程中踩过的坑，这里整理成一份速查表式的记录，也可以当成你排查问题时的参考手册。

5.1 解析环节的典型问题

解析出来是乱码或大量空行，十有八九是扫描版PDF没开OCR。在知识库配置里打开OCR后再重新解析，一般能解决。如果OCR开了但还是缺字，检查文档分辨率，太低的扫描件可以先做一次图像预处理。

表格错乱是解析里的高频问题。普通模板对复杂表格支持有限时，试试切换到适合带表格文档的模板，或者先在外部工具里把PDF转成Excel再上传。记住一个原则：不要让RAG系统去处理它天生不擅长处理的极端排版，能提前预处理就提前预处理。

还有一类问题是切分出来的Chunk里，标题和正文分家。这多半和解析模板选择有关，换成“论文”或“手册”等带结构意识的模板，再观察Chunk变化。如果还不行，手动调整切分配置里的“标题补充正文”之类的选项，让上层标题携带到子块中。

5.2 检索和问答环节的典型问题

问答答非所问，先不要怀疑大模型能力，去排查召回。把“引用”打开，看召回片段里到底有什么内容。如果片段相关但排序靠后，加大TopK或调整重排阈值；如果片段完全不沾边，优先检查和Embedding模型是否匹配中文场景，再检查知识库配置里的相似度阈值是不是设太高。

有一种情况我遇到好几次：文档库内容很多，但某个冷门问题怎么都召回不到。后来发现是Chunk太大，正确答案被淹没在长文本的中间位置。把Chunk调小一些、重叠调大一些之后，问题消失。这类问题靠脑测很难定位，逐条打开Chunk列表看最直观。

中文问答应优先选中文Embedding模型。默认模型如果是英文为主的通用模型，中文检索效果会明显打折，换成BGE系列或其他中文模型后，相似度分布的区分度会好很多。

5.3 部署与运行环境问题

启动后浏览器访问不了，先检查端口映射是否生效。容器起来了但界面打不开，大概率是预设端口已经被占用或者防火墙拦截，用docker compose ps看看实际映射情况。如果服务进程反复重启，多半是内存不足，给Docker多分配一些资源。

Mac环境下最容易遇到的是Docker Desktop的总资源配额不足。我在M系列芯片上部署时，8GB内存只能算及格线，同时跑多个容器时建议调到16GB。卷目录用本机路径代替容器内路径，备份和升级都方便，排查问题时看日志也更顺手。

5.4 RAG知识库到底能不能存图片？

这个问题的答案是：RAGFlow可以直接把图片文件纳入知识库，也可以通过PDF里的图片页面间接管理图片内容。普通RAG知识库主要索引的是图片中被OCR识别出来的文字，图片本身会保留在对象存储里供前端展示。

如果你的诉求是“用户问一句，系统返回相关图片”，那要看图片是否有文字信息。有文字的流程卡片、界面截图，靠OCR加文档知识库就能实现；没有文字内容的纯视觉图片，比如产品外观图，就需要引入图文向量模型或视觉语言模型来做匹配，这已经超出默认RAG系统的能力范围，需要单独扩展。

6. 给想系统学习RAGFlow的人一份最小行动清单

如果你是零基础，不建议按文档从头到尾啃。我试过更高效的方式：按目标拆成一个个小主题，每个主题亲手做一遍，再进入下一个。

6.1 一周主题式学习建议

第一天只部署，目标是把界面跑起来，不追求理解所有架构细节。第二天用一份排版规整的PDF建第一个知识库，重点看解析后的Chunk效果。第三天试扫描件，把OCR打开，对比开与不开的差别。第四天集中调检索参数，用同一批问题测试不同TopK和阈值下的回答差异。第五天把知识图谱玩一遍，建一个很小的Ontology跑通抽取流程。第六天用Agent Workflow串两个知识库，做一个带分支的问答流程。第七天把之前踩坑记录整理出来，作为团队内部手册。

这一周下来，你对RAGFlow的全貌会比碎片化看两个月文档扎实得多。而且这套流程不需要多少前置知识，会浏览器、会看日志、会改配置就能推进。

6.2 一点心得：把重心放在“解析+检索”而不是炫酷Agent

很多人学RAGFlow容易被眼花缭乱的Agent吸引，一上来就想做多智能体协同。但以我的项目经验来看，真实场景里决定成败的永远是前面两环：文档解析清不清晰、检索召回调没调准。Agent只是把已经可用的能力编排起来，基础不稳，流程越复杂失败率越高。

所以我的建议是，先用一个中小型知识库项目把“解析—召回—重排—引用”这条主链路跑通，让回答大部分时候能带出正确引用，再去研究Agent串流程。RAGFlow官方仓库里的Wiki也一直有更新，把快速开始、DeepDoc说明、知识图谱教程这几个页面排进你的学习计划，比我在这里列任何阅读清单都管用。

最后分享一个我自己反复用的方法：每次改完参数，固定问同一组问题，并且把回答截图保存。这样调优前后的效果对比一目了然，也方便回溯“到底哪次调整让效果变好了”。这套带版本感的实测习惯，比任何理论都更能帮你把RAGFlow用得顺手。