很多人装完 RAGFlow 就卡住了：文档传上去解析不出内容、检索答非所问、换个环境重来一遍又跑不起来。这篇按实际动手顺序走一遍——从环境准备、Docker 拉起服务，到建知识库、调切片与检索参数，再到验证效果。每一步都会说清「怎么判断这一步算过了」，以及哪些情况下这套做法不适用。
很多人装完 RAGFlow 就卡住了：文档传上去解析不出内容、检索答非所问、换个环境重来一遍又跑不起来。这篇按实际动手顺序走一遍——从环境准备、Docker 拉起服务，到建知识库、调切片与检索参数，再到验证效果。每一步都会说清「怎么判断这一步算过了」，以及哪些情况下这套做法不适用。
先说明一个前提：下面讲的是「自己部署一套完整服务」的路径。如果你只是想先摸摸 RAGFlow 的解析和问答手感，别急着上部署，先找个能跑起来的最小环境把流程走通，再决定要不要正式搭。判断要不要正式搭的标准很简单——你是要长期往里喂资料，还是只试一次。
先把环境跑起来：Docker 部署要点
部署前值得花十分钟确认三件事，容器起不来九成卡在这三样上：机器内存与磁盘余量够不够、要用的端口有没有被别的服务占、能不能拉通镜像源。这三项每一项都可以在部署前单独验证，不要等报了错再回头查。
- 内存与磁盘：解析大文档和跑向量检索都吃资源，先看当前余量再决定要不要加盘
- 端口占用：把要用的几个端口先查一遍，被占了就换，别等启动失败才发现
- 镜像源连通性：先单独拉一个小镜像试一下，能拉通再开始整套部署
- 目录权限：挂载的本地目录要保证容器里的进程能读写，权限不对会表现为「起来了但不工作」
拉起服务之后，怎么算「起来了」？不是看到容器状态是 Running 就算数。要看两件事：服务日志里没有反复重启、没有持续报错刷屏；页面能正常打开并登录进去。这两条都满足，才算这一步过了。
真出问题的排查顺序很重要：先看容器状态与日志，再看端口映射，最后才看挂载目录权限。顺序反过来的话，你会先花很久去检查权限，结果发现根因是端口被占，白折腾。
建知识库：从上传到切片
建库之前先想清楚三件事：准备喂什么格式的资料、按什么维度切、切多粗。这三项基本决定了后面检索能到什么水平，等到问答不准再回头改，成本会高很多。资料格式越规整，后面越省事。
- 先传少量样本别一上来就把全部资料倒进去。先挑几篇有代表性的文档上传，跑通解析再批量补
- 看解析结果重点核对页数对不对、表格有没有被拆散、扫描件有没有识别出文字；这一步不过关，后面全是白费
- 调切片粒度太碎会把一句话拆开，太粗会把好几件事塞进同一块；依据是你自己的问答能不能命中完整答案
- 确认有效再扩容样本跑顺了再考虑要不要继续往库里加资料，避免一开始就堆一堆解析不了的文件
如果原始文档本身是扫描件或者排版很乱，切片怎么调都救不回来，得先做清洗这一步。这类前置处理站内已经有一篇专门讲，先按那篇把文档整理干净再回来建库。
让它答得准：检索参数与提问方式
检索不准，先分清是「压根没召回到」还是「召回了但排错序」。这两种病因不一样：前者要动切片和关键词策略，后者得看是不是需要加一层重排。分不清就乱调参数，只会越调越乱。
| 现象 | 先怀疑什么 | 先动哪一步 |
|---|---|---|
| 提问答不出来，换种问法就有了 | 召回到了但排序靠后 | 试加一层重排，或看检索条数是不是太小 |
| 换几种问法都答不出来 | 根本没召回到 | 回头检查切片粒度和关键词覆盖 |
| 答案沾边但不完整 | 切片太碎 | 先把切片调粗一点再看 |
| 答案串了别的内容 | 切片太粗 | 拆细，让每块只讲一件事 |
处理同类问题有一套固定的排查动作：换一种提问方式试、把问题里的专有名词去掉试、单独测一个你已知答案的小问题。三步做完，基本能定位到是召回问题还是排序问题。
- 切片粒度、向量模型、检索条数是三个互相牵制的旋钮
- 一次只动一个，动完记录变化
- 如果同时动两个以上，你永远说不清是哪一步起的作用
- 记录里至少写清：改了什么、验收集表现怎么变
还有一种情况要认清：如果知识库里根本没有答案，再调参数也不会变好。这时候该做的是补资料，不是继续拧参数。判断方法很简单——拿一个你确定库里没有的问题去问，如果它硬编了一个答案，那就是资料缺口问题。
验收与迭代：怎么判断这套库能用了
上线前准备一批有标准答案的问题当验收集，覆盖三类：简单事实、跨段落归纳、查不到答案。跑一遍再决定上不上线。没有验收集就直接对外用，等于把问题留给用户去发现。
重点看两类失败：明明有答案却答不出来、库里没有答案却硬编一个。后者比前者危险得多，上线前必须处理，宁可让它回答「不知道」，也不能让它编。
- 验收集
- 一批有标准答案的问题，覆盖简单事实、跨段落归纳、查不到答案三类
- 危险失败
- 库里没有答案却硬编一个，比答不出来更需要优先处理
- 变更记录
- 每次改切片或参数，记下改了什么、验收集表现怎么变
- 判断基准
- 向量模型与部署方案的选择，到站内页面看当时的数字，别照抄别人的参数
上线之后，每次调整都留记录。改了切片、换了配置、动了检索条数，都要记下来验收集的表现变化。下次出问题的时候，这份记录就是你唯一能回溯的东西。向量模型的价格与效果对比可以到站内向量模型页面核对，部署方案的横向对比可以看向量数据库与检索方案的汇总页，按当时的数字决定，不要照抄别人的参数。
下一步搭完之后，容器部署的横向方案、向量模型与检索组件的当下对比，站内都有汇总页，按自己机器条件和资料类型挑，比照抄别人的配置稳。→常见问题
RAGFlow 知识库搭好后，为什么检索总是答不准？
先分清是召回问题还是排序问题。如果是文档压根没被切进候选，调切片粒度或换提问方式；如果是候选里明明有却排到了后面，考虑加一层重排。另外要确认解析那步是不是把关键内容弄丢了，扫描件和复杂表格最容易出这个问题。一次只改一个变量，改完把结果记下来。
用 Docker 部署 RAGFlow，容器一直起不来怎么办？
按顺序查：先看容器状态和日志里有没有反复重启，再看端口是不是被别的服务占了，最后看挂载目录的权限对不对。绝大多数启动失败都在这三样里。另外确认机器内存和磁盘余量够不够，资源不够时服务会起来又挂掉，看起来像配置问题其实是硬件不够。
知识库里的文档要多久重新解析一次？
看你的资料更新频率，没有固定周期。判断依据是：检索结果开始出现明显过时的答案，或者源文档已经改过一轮了，就该重新跑一遍解析和入库。更新时建议先在验收集上跑一次对比，确认新版本没把原来能答对的问题弄坏，再正式替换。
