RAGFlow 起好之后，真正的卡点往往不是部署，而是怎么用 HTTP 把它调起来：Base URL 该写哪个、token 放 header 还是 query、建数据集和上传文档是不是一个接口、检索返回为什么是空的。这篇按调用顺序把几个常用接口串一遍，顺带给一个从鉴权到检索的排查清单，照着做能自己定位大部分问题。
RAGFlow 装好之后，真正让人卡住的往往不是部署，而是怎么用 HTTP 把它调起来：Base URL 该写哪个、token 放 header 还是 query、建数据集和上传文档是不是一个接口、检索为什么返回空。这些问题里绝大多数不是模型问题，是请求写法问题。
下面按调用顺序把几个常用接口串一遍，从入口和鉴权开始，到建库、传文档、触发解析，再到检索和对话，最后给一套调不通时的排查顺序。照着走一遍，大部分问题能自己定位到是哪一层。
先定入口：Base URL 与鉴权怎么放
第一件事是分清两个入口。控制台/网页是一个端口，API 是另一个端口，脚本里必须用 API 那个。很多人拿浏览器能打开的地址去写脚本，结果一直连不上，就是因为把网页端口当成了 API 端口。
- Base URL
- API 服务的根地址，后面接固定前缀再接资源名，多一层少一层斜杠都会变成 404
- token
- 从页面 API 入口生成的一串密钥，和浏览器登录会话不是一回事
- 请求头
- 一般是 Authorization 里带 Bearer 加 token，不是校验用的 cookie
- 先跑一条最简单的列表类接口验证连通，别一上来就传文档
- 路径前缀要连斜杠一起拼对，末尾斜杠也要注意，两边不一致容易 404
- token 别拿浏览器里的 session cookie 去顶，两者不通用
- 具体路径前缀和端口写法各版本会有差异，到 ragflow-api-reference-dev 核对当次版本的写法
第二步：建数据集、传文档、触发解析
调用顺序是固定的：先建数据集拿到 dataset_id，后面的文档上传、切片、检索都要带上这个 id。漏了它，后面的请求要么报错要么查不到东西。这个顺序不能颠倒，也不建议跳过任何一步。
- 建数据集调创建接口，从返回体里取出 dataset_id 存下来，后面所有和这份数据相关的请求都要带上它
- 上传文档通常是 multipart 表单而不是 JSON，Content-Type 用错服务端会直接拒
- 触发解析上传成功只代表文件收下了，还要单独调解析/切片，并轮询状态直到跑完
- 校验可用解析跑完后再调一次检索，确认能召回，才算这一份数据真的可用了
轮询解析状态时给一个上限次数，别写成死循环。文件大或者队列忙的时候耗时会明显变长，但只要状态字段在往前走就说明没卡死。这里最容易犯的错是上传完立刻去检索，然后怀疑向量模型有问题，其实只是解析还没跑完。
第三步：检索与对话接口怎么带参数
检索类接口一般要传问题文本和 dataset 范围，可能还要带相似度阈值和返回条数。阈值设太高会一条都召不回，建议先放宽再逐步收紧，用同一批问题反复比对，看召回内容是不是真的相关。一上来就卡阈值，只会得到空结果。
| 参数类型 | 作用 | 取值建议 |
|---|---|---|
| 问题文本 | 检索的输入 | 用真实用户会问的句子，别用关键词堆叠 |
| dataset 范围 | 限定在哪份数据里查 | 必须先确认 id 有效且解析已完成 |
| 相似度阈值 | 过滤不相关片段 | 先放宽跑通，再按效果收紧 |
| 返回条数 | 控制召回量 | 按下游能处理的量给，不要一味拉满 |
对话类接口可以选择带知识库引用，注意返回结构里引用和正文是分开的字段，前端要分别取。如果接的是流式返回，要按分片解析，不能当成一个完整 JSON 去解；解析方式搞错，表现就是一直拿不到内容或者报解析错。
- 流式接口按分片处理，遇到结束标记再收尾
- 非流式接口直接当完整 JSON 解，别复用流式那套代码
- 返回体里引用字段和正文分开取，别只读正文
- 字段名和必填项会随版本变，以 ragflow-retrieval-api-token 的说明为准
调不通时的排查顺序
调不通不要东一榔头西一棒子，按固定顺序走：先看能不能连上端口，再看鉴权是否通过，再看资源 id 是否有效，最后才是参数和索引问题。这个顺序的好处是每一层都能排除掉一批可能，不会来回猜。
| 现象 | 优先怀疑 | 下一步动作 |
|---|---|---|
| 连不上、超时 | 端口或 Base URL 写错 | 换列表类接口从浏览器外单独试一次 |
| 401 未授权 | token 没带、失效或格式不对 | 检查请求头和 token 来源 |
| 404 | 路径前缀或资源 id 不对 | 核对前缀和 dataset_id 是否同一份数据 |
| 上传报错 | 体积超限或 Content-Type 不对 | 确认用的是表单上传，必要时分批传 |
| 检索返回空 | 解析没跑完，或阈值、范围选错 | 先查解析状态，再放宽阈值 |
检索空结果先查解析状态，再查阈值和 dataset 是否选对，别一上来就怀疑向量模型。把每次请求的路径、状态码、耗时记下来，出问题时能直接定位到是哪一层；接口延迟基线可以到 /tools/speed-test 量一遍做对照，这样后面变慢时你才知道是环境问题还是代码问题。
接到项目里之前要补的几件事
调通只代表能跑，接到正式项目里还要补几件事。超时要和重试分开设置：建数据集、上传、解析这类慢操作给足时间，检索类接口用短超时加有限重试，不要把两类操作套同一套参数。并发也别一上来就打满，上传和解析是重活，按队列分批更稳。
- token 放进环境变量，不要写死在代码和前端里
- 慢操作给长超时，快接口给短超时加有限重试
- 上传和解析按队列分批，避免同时打满
- 给关键调用加日志，至少记路径、状态码、耗时
如果这套接口要接到中转或代理后面走，链路本身的可信度和延迟是另一回事，和接口写法不是同一个问题。检索质量本身好不好，也另有专门的评法，本文只解决「调得通、调得稳」这一层。
下一步把自己的请求和站内整理好的接口示例逐条对照一遍，能很快看出路径前缀、鉴权和参数哪里对不上。→常见问题
ragflow 的 API 请求用 JSON 还是表单？
看接口。建数据集、检索、对话这类基本是 JSON；上传文档多半是 multipart 表单，里面同时带文件和 dataset_id 之类的字段。混用会直接吃 400 或 415，不确定时以 ragflow-api-reference-dev 里每个接口的参数说明为准。
为什么我上传了文档，检索接口却返回空？
最常见的原因是解析没跑完或者没触发。上传只是入库，还要单独发起解析并等状态变成完成，之后检索才能命中。其次检查 dataset_id 有没有传对、相似度阈值是不是设得太高。先去页面确认文档状态，再看检索参数。
token 放哪里，能放前端吗？
一般放在请求头里，形如 Bearer 加一串密钥。不要放进浏览器前端或客户端代码，任何人都能扒出来，等于把整个知识库开放了。放服务端环境变量里，由后端转发，需要的话在中间加一层校验。
