ragflow api documentation

你准备在 Java 后端接 RAGFlow 的接口，可能是要做知识库上传、检索问答或者把结果拼进自己的服务。文档看完还是不确定请求怎么组、文件怎么传、流式怎么接、报错该从哪查。这篇按调用方式到 Java 落地的顺序讲一遍，重点放在参数结构、鉴权方式、超时与异常处理这些真正决定能不能上线的细节上。

你准备在 Java 后端接 RAGFlow 的接口，可能是做知识库上传、检索问答，或者把结果拼进自己的服务。文档翻完还是不确定请求怎么组、文件怎么传、流式怎么接、报错该从哪查。这篇按调用方式到 Java 落地的顺序讲一遍，重点放在参数结构、鉴权方式、超时与异常处理这些真正决定能不能上线的细节上。模型能力、参数上限这类会变的东西，到站内模型资料库页面核对当时的说明。

先明确一件事：接口本身会随部署形态和版本调整，别照着某一份静态文档硬编码。正确做法是先用最短链路跑通，把请求和响应结构固化到自己的 DTO 里，再用回归用例兜住后续变化。

先搞清 RAGFlow API 的调用形态

RAGFlow 的接口大致分三类：知识库与文档管理、检索召回、对话补全。这三类请求体结构差异不小，管理类偏表单与文件，检索类偏一组查询参数，对话类则是消息数组加上若干可选开关。写代码前先把每类的必填字段列出来，缺哪个会直接返回参数错误。

鉴权位置

通常在请求头里带 token 或 api key，逐个接口确认是否都需要带，漏带一般直接返回未授权状态码

同步返回

一次性把完整结果给你，适合文档列表、知识库信息这类小响应

流式返回

边生成边吐字，适合对话场景，Java 侧要按块读而不是等整个 body

版本前缀

接口路径前缀取决于你的部署方式，先确认自己的服务入口再写常量

• 先确认你是直连官方还是走自建部署，两者的入口地址和鉴权细节可能不同
• 把三类接口的请求示例各抓一份真实响应存下来，作为 DTO 生成依据
• 检查响应里是否有统一的错误包装字段，有的话先解出错误码再看业务字段
• 别把 baseUrl 写死在业务类里，抽成配置项，换环境时只改配置

Java 侧怎么发请求：客户端选型与代码骨架

客户端选型看你的调用模式。同步为主、不想加依赖的用 JDK 自带的 HttpClient；需要成熟连接池和拦截器生态的用 OkHttp；本来就是 Spring 技术栈、且要处理流式响应的，WebClient 更顺手。关键是别在业务代码里 new 客户端，统一封一层。

请求体建议建 DTO 而不是手拼 Map。字段名和嵌套层级是最容易出错的地方，尤其是对话接口里的消息数组和检索接口里的过滤条件。用 DTO 加序列化注解，编译期就能发现拼写问题，比运行时靠日志猜强得多。

public class RagFlowClient { private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build(); private final String baseUrl; private final String token; public String postJson(String path, String jsonBody) throws Exception { HttpRequest req = HttpRequest.newBuilder().uri(URI.create(baseUrl + path)).timeout(Duration.ofSeconds(30)).header("Content-Type", "application/json").header("Authorization", "Bearer " + token).POST(HttpRequest.BodyPublishers.ofString(jsonBody)).build(); HttpResponse<String> resp = http.send(req, HttpResponse.BodyHandlers.ofString()); if (resp.statusCode() >= 400) throw new RagFlowException(resp.statusCode(), resp.body()); return resp.body(); } }

• 文件上传先确认接口是 multipart 还是 base64，大文件走 multipart，别整个读进内存
• 统一封装一层 client：baseUrl、鉴权头、超时、重试都集中在这一个类里
• 把请求 url、耗时、状态码、响应体摘要记进日志，排查时不用重现现场
• 对外抛自定义异常，别把 HttpException 直接透到业务层

流式读取、超时与并发该怎么定

流式接口在 Java 里要按块读，不能等整个响应回来。连接超时和读取超时是两个概念：连接超时管的是建连，读取超时管的是两次数据之间的间隔。整体超时另设一档，用来兜住一直拖着不结束的连接。三个值分开配，不要合成一个。

1. 先定连接超时按网络环境给一个偏短的值，建连失败要快速失败，不要拖住线程
2. 再定读取超时流式场景下这是两次 chunk 的最大间隔，不是整个请求的总时长
3. 单独设总超时用一个外层的截止时间兜住，超了就主动断开并记录
4. 验证方式故意让下游变慢，看是否在预期时间内断开，日志里能查到是哪个超时触发的

检索类接口通常比对话接口更慢，因为要做向量匹配和召回排序，超时档位要区别对待，别用同一个值套所有接口。并发上限要和你的部署规模对齐：先测出单实例在可接受延迟下的并发数，再决定线程池大小，不要凭感觉设。

• 重试只对可重试的错误生效，比如连接被拒、限流；参数错误重试多少次都没用
• 流式请求中途失败不要盲目重发，可能已经产生部分输出，重发会重复内容
• 并发压测从低往高加，观察延迟曲线拐点，拐点之前才是安全区间
• 把超时和并发值写进配置，按环境覆盖，别硬编码在代码里

报错定位顺序与联调验证

报错别一上来就翻业务代码，按层次排查更快。连接层看能不能建连、DNS 和端口对不对；鉴权层看 token 是否过期、header 格式是否对；参数层看必填字段和类型；最后才是服务层，看后端返回的业务错误码和消息。

把请求 id、耗时、状态码、错误消息记进日志，出问题时才能复盘。写一个最小可跑的联调脚本，先跑通一条最短链路，再往上堆业务逻辑。上线前用固定用例回归一遍，接口行为变了能第一时间发现。

1. 搭最小脚本只调一个最简单的接口，确认鉴权和返回结构，不掺业务逻辑
2. 固化用例把成功和失败的典型响应各存一份，作为回归基线
3. 逐层加业务每加一层都跑一遍基线，确认没破坏已有链路
4. 上线前回归跑一遍固定用例，对比响应结构是否和基线一致

接口行为、模型参数、价格这些都会变，别把某次看到的数字写进注释或文档。要核对当时的数字，到站内价格追踪页面看，或者到模型资料库页面查参数说明。