ragflow使用教程

很多人第一次打开 RAGFlow，界面点得动，但文档传进去问出来的答案不对，也不知道该怪切片、怪检索还是怪模型。这篇按「先跑通、再调好」的顺序，把建库、进料、切片、检索、问答这几步串成一条线，每一步都给出可检查的动作，顺带说清哪些情况不适用以及上线前要补的工程活。

很多人第一次打开 RAGFlow，界面点得动，文档也传进去了，但问出来的答案就是不对，然后开始瞎试：一会儿改提示词，一会儿换模型，折腾半天不知道问题出在哪。其实这类系统出问题的地方就那么几个：切片、检索、模型。这篇按「先跑通、再调好」的顺序，把建库、进料、切片、检索、问答这几步串成一条线，每一步都给出能检查的动作。

先把预期放正：RAGFlow 这类工具的价值是「让模型基于你给的资料回答」，不是「让模型变聪明」。如果资料本身乱、切片切得碎、召回片段压根没命中，后面模型再强也救不回来。所以下面每一步都有对应的验证点，走完一步确认一步，比一口气配完再回头找问题省事得多。

动手前先想清楚三件事

第一件是明确知识库要回答什么类型的问题。是查条款、查参数，还是查流程？这三种问题对切片粒度的要求完全不一样。条款类要求答案能精确落到某一句话，切片就得短而准；流程类往往需要前后文连着看，切片太短反而断章取义。想清楚问题类型，后面切片才有依据。

第二件是盘点手里文档的真实形态。原生 PDF、扫描件、表格、PPT，处理难度差得很远。扫描件要先做 OCR，表格密集的 PDF 直接解析出来经常是错位的，PPT 里大量信息藏在图里。先分类再动手，别一股脑全传进去指望系统自己搞定。

第三件是确定模型怎么来。对话模型和嵌入模型是两个独立的接入点，前者负责生成答案，后者负责把文本转向量做检索。这一步没定，后面全是空转。走官方还是走中转，可以先到 中转站导航（/sites） 看看各家情况，再决定要不要准备备用源。

建知识库：从空库到能进料

建库的第一原则是按「一批同类文档一个库」拆开。制度、产品手册、客服话术塞进同一个库，检索的时候它们互相干扰，召回结果永远不干净。一个库对应一类用途，后面调整切片参数、换嵌入模型也互不影响。

选嵌入模型时注意两个点：维度和语言支持。中文资料优先选在中文语料上表现稳的模型，具体哪些档位、当时的口径是什么，到 嵌入模型资料页（/embeddings） 核对当时的数字，别照着别人的旧配置抄。维度这个事不用太纠结，建完库之后换嵌入模型成本很高，所以宁可建之前多花点时间选。

• 解析方式按文档形态选：干净的文本类直接走默认解析，扫描件和图文混排要先做 OCR，可参考 PDF 清洗与 OCR 指南（/guides/pdf-ocr-doc-cleaning） 的清单
• 建完先别急着批量导入，拿一份最有代表性的文档做单篇试跑，确认解析出来的文本可读
• 同一类文档的命名保持规律，后面排查问题时能快速定位是哪一份出的问题
• 建库时就把库名和用途写清楚，管理多个库的时候你会感谢自己

第一次试跑怎么判断解析没问题

1. 传单篇挑一份内容最典型的文档单独上传，不要一次传十份。
2. 看解析结果打开解析后的文本预览，检查有没有乱码、段落是否被拆碎、表格是否错位。
3. 抽查关键段落找文档里你确定存在的一段话，在解析结果里搜一下，搜不到说明解析这关就挂了。
4. 确认切片生成看切片列表有没有正常生成，数量是否合理，切片内容是不是完整的句子。

上传与解析：文档进料阶段最容易翻车的地方

进料阶段的问题有个特点：当时看不出来，等到问答的时候才暴露。所以这个阶段的原则是「小批量、勤抽查」。传一批就看一批的解析日志，把有问题的文档挑出来单独处理，别攒到最后一起查。

扫描件走 OCR 之后务必人工抽查几页。OCR 识别错的字不会报错，但它会让后面的检索永远召不回正确的片段——因为用户搜的词和文档里存的那个错字对不上。这种问题非常隐蔽，等发现的时候往往已经传了几百页。

• 同一份文档重复上传前，先确认库里的去重策略，重复内容会挤占召回名额，把真正有用的片段顶出去
• 段落被拆碎是解析阶段的典型症状，表现为检索出来的片段读不通顺，遇到就回头看解析设置
• 上传后先别急着问问题，先把解析状态和切片列表过一遍，确认没有卡住的任务

切片与检索：问答答不准，八成卡在这

切片长度没有万能值。条款类要短而准，让每片只承载一个完整意思；叙述类可以长一点，保证上下文连贯。关键是：改完切片参数之后，必须用同一批问题做回归对比，不然你无法判断这次改动到底是变好还是变坏。

排查时要养成「分层看」的习惯。把问题直接打到检索层，先看召回的片段里有没有正确答案，再看模型是怎么组织的。这两件事分开排查，能立刻定位问题在哪一层。下面这个顺序建议照做。

1. 只测检索用原文里的原话去搜，看能不能召回对应片段。搜不到就是切片或嵌入的问题。
2. 换问法再搜用口语化的问法搜同一件事，看召回结果稳不稳。波动大说明检索还不够鲁棒。
3. 调召回条数召回条数先给个中等值，多了噪声大、少了漏信息，观察不同条数下召回内容的变化。
4. 加 rerank如果有 rerank 能力，先加 rerank 再调召回数量。顺序反了会白折腾，因为两者的作用会互相掩盖。

跑通问答：怎么判断是真跑通了

「问了一个问题，答得还行」不算跑通。真正跑通的标志是对一组固定问题都有稳定表现，包括那些文档里没有答案的问题。所以第一件事是准备一组基线问题，量不用大，但要覆盖两类：文档里明确写了的，和文档里不存在的。

对「文档里没有」的问题，正确的表现是拒答或者说不知道。如果它编出一个看起来很像那么回事的答案，说明要么阈值定得太松，要么提示词没要求它在找不到依据时收手。这种编造比答不出来危险得多，尤其在上线之后。

• 每个问题换两三种问法各问一遍，命中率波动太大说明切片或检索还不稳
• 把每轮问答的召回片段和最终答案都留档，后面调参才有对照
• 拒答率也要看：全部拒答说明阈值收太紧，什么都敢答说明太松
• 基线问题集不要只用一个人的问法，不同人的表述差异本身就是测试项

基线问题集样例结构

常见故障的排查顺序

出问题的时候最忌讳东改一下西改一下。下面这个顺序是按「从上游到下游」排的，照顺序走，能保证你在改某一环的时候，前面的环节已经确认没问题。

1. 先查检索答非所问时，先看召回片段里有没有正确内容。没有就停在这一步，别往下查。
2. 再查提示词与模型检索对了但答案跑偏，才去看提示词模板是否约束了回答范围，以及模型本身的能力边界。
3. 上传成功却搜不到按解析状态、切片是否生成、嵌入是否成功三步顺查，哪一步卡住就从哪一步修。
4. 整库变慢或报错先看服务资源和模型接口的连通性，用 测速工具（/tools/speed-test） 量一下延迟基线，区分是自己环境的问题还是上游接口的问题。

还有一个容易被忽略的点：文档更新之后，旧切片可能还留在库里。问答出现前后矛盾，先确认是不是同一份文档的新旧两个版本都在。这种问题表现为「答案看运气」，其实根子在重复数据。

从能用到敢用：上线前补的工程活

跑通演示和真正上线之间还隔着一层工程活。这一层不做，演示的时候好好的，一到真实使用就各种超时、断流、供应商挂掉。下面这几件属于「不做就会后悔」的。

• 给问答接口设超时和重试，流式场景还要处理断流，不能只写个正常路径就完事
• 把模型调用做成可切换的，某家接口挂了能降级到备用源，别让单一供应商绑死整条链路
• 记录每次请求的耗时、召回条数、token 消耗，出问题时这些字段是唯一线索
• 定期用固定问题集回归一遍，文档更新或换模型后尤其要跑，避免效果悄悄变差

选备用源的时候不要只看能不能通，要看它在你的实际使用时段稳不稳。可以到 价格追踪页（/price-watch） 看当时的行情，再到 可信度排名（/rankings） 看各家的稳定性记录，两边对一下再决定怎么配。具体数字以页面当时显示的为准，别拿几个月前的印象做决策。

RAG 系统的效果不是调出来的，是一层层排查出来的；上一层的错误不修，下一层怎么调都是白费。