装好 RAGFlow 之后把一批 PDF 丢进知识库、提问却答非所问，通常不是模型不行，而是解析和分块这两步没做对：解析决定文字有没有被正确取出来，分块决定答案有没有被完整装进一个片段。这两步做错，后面换再大的模型、加 rerank 也补不回来。建议的顺序是先把容器、端口、模型这些前置条件验证掉，再用一份两页 PDF 看解析质量，按文档类型调分块参数，最后用检索测试反向确认命中片段，然后拿第二份同类文档复用同一组参数。

先别急着换模型：本地知识库答非所问，多数情况出在解析和分块。做法是先用一份两页 PDF 验证表格、标题有没有被拆散，再按段落型或条款型文档分别调分块长度与重叠，最后在检索测试里看命中片段是否完整。容器、端口、模型这些前置条件要先验证掉，否则会把环境问题误判成解析问题。分块参数改完必须重新解析，只改配置不重跑，旧分块仍在库里生效。

确认容器起来了、访问端口能打开、模型已接通

这一步的目的很单纯：把环境问题和解析问题分开。容器没起全、端口没映射对、embedding 模型没接通，症状同样是「检索不到东西」，但它跟解析无关，先排掉能省很多时间。

docker compose ps
docker logs -f ragflow-server `--tail` 200
# 服务名以你实际的 compose 文件为准，可能叫 ragflow-server、ragflow 等

看容器状态时重点确认三类服务都在 running：Web/API 服务、向量库或检索引擎、以及依赖的数据库或缓存。日志里如果反复出现连接被拒、端口占用、初始化超时，先解决再往下走。接着用浏览器打开映射出来的访问端口，能正常登录、能看到知识库列表，才算 Web 层通了。

然后进模型设置页，需要确认的字段通常是：模型类型（对话模型、嵌入模型、重排模型分别配置）、API Base 地址、API Key、模型名称、以及最大 token 之类的限额。判定可以开始建库的标准可以看三条：配置能保存不报错；模型列表里嵌入模型显示可用或测试通过；新建知识库时下拉框里能选到那个嵌入模型。这三条任意一条不满足，先修环境，不要动解析参数。

上传一份两页 PDF，看解析结果里表格和标题有没有被拆散

不要一上来丢几百份文档，那样出了问题也不知道是哪一份、哪一页。用一份两页、包含一个标题层级和一个小表格的 PDF 做样本最合适。

操作路径通常是：进入知识库（数据集）→ 添加文件或上传本地文件 → 选中刚上传的 PDF → 点击该文件对应的解析、运行或开始解析按钮 → 等待状态从待解析变成已完成 → 打开分块或解析结果视图查看。

解析结果页要看的字段：分块总数、每一块的文本内容、原文标题有没有单独成块、表格有没有保持成结构化的行列表格、扫描件有没有被 OCR 识别成文字。三种情况的差别值得单独观察：带边框的表格，在没开表格识别时往往被当作普通文本流，按行或按单元格拆散，甚至跨块；多栏排版的页面，可能按视觉顺序混排，导致左右两栏的文字串到一段里；扫描件和图片型 PDF，如果没有开启 OCR，解析出来是空的或只有零星字符，这时候检索测试必然什么都找不回来。

如果样本页本身解析就是乱的，先别调分块长度，回到解析方法和 OCR、布局识别这些开关上找原因。

按文档类型调分块长度和重叠，别用一套参数打天下

分块参数一般在解析方法里配置，常见字段是：分块方法或解析模板（General、Q&A、Laws、Paper 之类）、分块长度（按 token 或字符计）、分隔符、重叠长度、以及布局识别开关。不同模板的默认行为不同，选错模板比调错数值影响更大。

段落型文档（说明文、手册、技术文档）的思路是让一个语义段落尽量落在一个块里：分块长度可以给得大一些，重叠给得小一些，分隔符用换行或空行，让自然段成为边界。条款型文档（合同、法规、SOP、规章制度）反过来：每一条本身就是完整语义单元，分块长度要小一些，尽量按条款编号切，重叠适度加大，避免「适用条件」和「处理结果」被切到相邻两块里，检索时只召回半句。

数值上没有通用最优解，可以先按「一段完整论述能装下、一条条款不被切断」这个标准试一组值，再去检索测试里验证。改完分块参数后有一个必须动作：回到数据集里对相关文档重新解析或重新分块。只改配置不重跑，旧的切块结果还在库里，检索行为不会有任何变化，这一点最容易被忽略。

在检索测试里输入问题，看命中片段是不是你以为的那一段

检索测试的作用是反向验证分块，而不是验证模型。入口通常在知识库或数据集页面里的检索测试、召回测试或类似按钮，输入一个你在原文里明确知道答案位置的问题，设置好召回条数（top N）和相似度阈值后执行。

读结果时看两样东西：召回片段的内容和它们的相似度分数。分数只适合在同一批结果内部做相对比较，不适合拿来当绝对标准；真正要判断的是命中片段里有没有完整答案。几种典型情况和对应的回改方向：

• 命中片段里只有答案的前半句或后半句，说明分块边界正好切在答案中间，回改分块长度或重叠，通常是把重叠加大或把长度调小。
• 命中片段内容是对的但排序靠后，可以考虑加 rerank，或者把分块调小一些，让答案集中在一段里、减少无关文字干扰。
• 相关内容完全没被召回，且原文里确实有，多半是解析阶段就丢了——表格被拆散、扫描件没 OCR，回到上一步处理解析，别继续调分块。
• 召回了大量高度相似但都不含答案的片段，通常是分块过长、一段里塞了太多主题，把长度调小或换更贴合的分隔符。

换第二份同类文档复用同一组参数，比对两次的命中情况

一份文档上跑通不代表参数可复用，所以第二步要拿同类型的第二份文档，用完全相同的解析方法和分块参数再走一遍，看看命中情况是否稳定。建议维护一张简单的参数记录表，字段至少包括：文档类型、解析方法或模板、分块长度、重叠长度、分隔符设置、召回条数、测试问题、命中片段位置、片段是否含完整答案。

两次对比的方法是把同一个测试问题分别跑在两份文档上，比较三件事：命中的是不是同一层级的内容（比如都命中某个条款、某个小节），命中片段是否是完整语义单元，以及片段在原文中的相对位置是否稳定。如果第一份命中的是完整条款、第二份命中的是被切断的半句，说明这组参数对版式更敏感，需要往更保守的方向调重叠。

允许的偏差：两份文档排版不同，分块总数、每块的字符数、相似度分数都不会一致，这属于正常。判断标准不是数值一致，而是答案是否稳定地完整落在被召回的那个片段内。如果这一点稳定成立，这组参数就可以在这类文档上继续用；如果不成立，只针对该类文档单独调整，不要为了迁就个别文档把全局参数改掉。