ragflow /api/v1/retrieval

本地 RAGFlow 跑起来了，知识库也建好了，结果一调检索接口就卡住：要么提示先去创建 API Token，要么连得上却拿不回结果，返回结构还跟文档对不上。这篇不讲 RAG 原理，也不重讲部署，只给一条排查顺序：Token 在哪创建、请求怎么发、报错按什么顺序定位，以及接进生产前要处理好的超时、并发、降级和日志。

本地 RAGFlow 跑起来了，知识库也建好了，结果一调检索接口就卡住：要么提示先去创建 API Token，要么连得上却拿不回结果，返回结构还跟文档对不上。这篇不讲 RAG 原理，也不重讲部署，只给一条排查顺序：Token 在哪创建、请求怎么发、报错按什么顺序定位，以及接进生产前要处理好的超时、并发、降级和日志。

整体思路是先分两类问题：一类是根本没拿到调用凭证，属于鉴权层；一类是凭证没问题但请求或返回不对劲，属于参数层和运行时层。先把最小请求打通，再往业务里加参数、加并发，出问题才有的查。调接口的时候手边备一份站内的模型与中转信息页面，方便对照你当前用的端点走哪条链路。

先解决「请先创建 API Token」这类鉴权报错

RAGFlow 的接口密钥一般是在系统设置里单独创建的，网页登录状态不能替代它。很多人卡在这一步，是因为浏览器里登录得好好的，就以为调用也能通。先分清手里拿到的是会话凭证还是接口密钥，这决定了报错到底该往哪查。

• 确认调用走的是 API 而不是网页会话，密钥通常在系统设置里单独生成，跟登录态是两套东西
• 请求头按官方口径带 Bearer 前缀，密钥里不要混入空格、换行或引号，从环境变量读而不是硬编码
• 拿到 401/403 时按「缺凭证、凭证错、凭证对但无该知识库权限」三档依次排除
• 密钥创建页点了没反应，多半是服务端还没就绪或反代没透传请求头，先确认容器健康再回页面重试

鉴权类报错的通用排查思路，可以对照站内那篇 401 排错来走，它把位置、请求头、域名这几个常见坑都列了。这里只强调一点：Token 创建失败和 Token 用错是两回事，先看报错发生在前端页面还是服务端返回，再动手。

请求怎么发：路径、参数与返回值对照

检索是 POST 语义，路径区分知识库级别和数据集级别。路径少一段、多一段都会表现成 404 或 405，这两种码看着像「服务没起来」，其实是路径写错了。先拿一个最小请求确认能通，再加参数。

必填项通常只有问题文本和数据集标识，召回条数、相似度阈值、重排开关属于可调项。可选项给错类型经常被静默忽略，表现就是「有返回但结果不对」，这类问题比报错更难查，因为服务端根本不报线索。

1. 第一步：打通最小请求只带问题文本和数据集标识发一次，确认状态码正常。不通就先查路径和方法，别急着调参数。
2. 第二步：用 curl 或接口工具验证命令行里跑通再写进业务代码，能省掉一半「是我代码错还是服务错」的来回。
3. 第三步：逐项加参数每加一个可调项就发一次，记下返回结构变化，避免一次加完对不上到底是哪个参数起的作用。

返回里的分块、分数、来源文档这些字段名，以你当前部署版本为准，写法可以参考站内召回可选字段说明。调试期统一用 curl 打通，比在业务代码里加日志快得多。

接进业务前的超时、并发与降级

打通不等于能上生产。检索受向量库和重排影响，读取耗时天然比普通接口长。把超时拆成连接和读取两段来看，读取段要给得比普通问答宽，具体档位怎么定，可以看站内超时设置清单里的分档思路。

• 连接超时给短一点，快速失败；读取超时给宽一点，因为检索和重排本身耗时
• 并发按你的部署规格和账号侧额度定，别按代码里能起多少线程定
• 被限流后要有退避而不是无限重试，退避策略参考站内限流与退避那篇
• 检索失败要有降级路径：降级到纯模型回答、返回缓存，或明确告诉用户这次没查到
• 批量任务和交互式请求分开排队，避免一次批量把检索通道打满

降级这块要提前想清楚：检索挂了是抛异常、编一个答案，还是老实说「这次没查到」。有资料就是有，没检索到就是没检索到，把这条写进接口约定里，比事后补救省事。

日志记什么、怎么判断改动是好是坏

日志不是记得越多越好，而是要能复盘「慢」和「空」这两类问题。每次检索至少留下几个关键字段，够你把一次异常请求还原成「问了什么、召回了什么、花了多久」。

字段的取舍可以参考站内日志字段清单，但有一条底线：不要把密钥和用户原文整个打进日志。日志能复盘就够了，不是备份数据用的。

改切片、调阈值、换嵌入模型之后，判断好坏要靠对照，不能凭感觉。用一组固定问题跑一遍，看命中率和答案有没有变好，小规模回归评测的方法站内有专门讲。线上表现和离线对不上时，先怀疑召回为空或切片错位，不要一上来就换模型。