java ragflow api

Java 项目里调 RAGFlow，多数人不是卡在「不知道接口」，而是卡在封装上：用 RestTemplate 还是 OkHttp、流式响应怎么读、超时设多少、线程池怎么配、失败了要不要重试。这篇按工程落地的顺序讲一遍，给出可直接套用的封装结构和排查顺序，具体接口字段与参数以站内页面当时的口径为准。

Java 项目里调 RAGFlow，卡人的往往不是「不知道有哪个接口」，而是封装那一层没想清楚：用 RestTemplate 还是 OkHttp、流式响应怎么读、超时设多少、线程池配多大、失败了要不要重试。这些问题在写第一行代码前不定下来，后面就是一边改调用一边改架构。

这篇按工程落地的顺序走一遍：先选客户端，再定模型层，然后处理超时并发和流式解析，最后落到日志降级和上线验收。具体的接口路径、字段含义和参数取值，以站内资料库当时的口径为准，别拿这篇当接口文档用。

先定 HTTP 客户端：RestTemplate、WebClient 还是 OkHttp

选型先看团队现有栈，别为了调一个接口引入一套新范式。三种方式的核心差别在阻塞模型、流式支持和连接池调优成本上，下面这张表可以当快速对照用。

• 团队已有栈优先：已经在用 WebClient 就别退回 OkHttp，混用两套客户端会带来两套超时和两套连接池
• 连接池必须显式配：最大连接数、单路由连接数、空闲回收时间，默认值在高并发下会排队
• 统一封装一个 RagflowClient 类，把 baseUrl、鉴权头、序列化器、超时收在构造里，业务层只传参数
• 什么情况下不适用：只在启动脚本里跑一两次的批处理任务，直接静态方法拼请求就够，套 Client 反而增加维护面

请求与响应的模型层：别让 Map 满天飞

接口能调通之后，维护成本主要来自模型层。用 Map 传参省时间，但字段一多就会出现「这个 key 到底叫什么」的反复确认，编译期一点忙都帮不上。用 record 或不可变类定义请求体和响应体，字段命名跟接口文档对齐，字段增减时改一处。

1. 抽参数对象把会话 ID、知识库 ID、文档 ID 这类标识单独抽成一个参数对象，避免长参数列表里传错位置——这是这类接口最常见的低级错误
2. 包一层结果对象响应统一包一层：业务数据、原始 JSON、HTTP 状态、耗时。出问题时不用再加日志复现，直接看这层日志就行
3. 流式与非流式分开流式接口和非流式接口的返回类型要分开，别用同一个方法签名靠布尔开关切换，调用方读起来很痛苦

一个容易忽略的点：响应体里带引用来源或分片信息时，不要只保留拼好的字符串就丢掉原始结构。后面要做引用高亮、前端回链时，原始结构才是可用的，字符串只能用来展示。

超时、重试与并发：按接口性质分档

超时不能全项目一个值。短查询类接口和上传文档、触发解析这类长任务，性质完全不同，混用一个超时值要么误杀正常请求，要么让真正的卡死长时间占着连接。分档设置之前，先到站内的速度测试工具量一下自己的延迟基线，别拍脑袋定秒数。

• 重试只对幂等且失败原因明确的操作开：文档上传和入库触发重复提交会造脏数据，靠业务层幂等键挡
• 线程池跟下游限流对齐：池子开得比对方额度还大，只会把请求堆在队列里等到超时，参考站内关于限流与并发的口径
• 流式读取时连接不能被普通超时掐断，要单独配置读超时或心跳，否则长回答会断在半句话上
• 并发突刺时先看队列长度再看错误率，队列先满说明是池子配置问题，不是网络问题

流式解析与错误处理：把失败变成可读信息

流式响应按行或按 SSE 事件边界切，不要按字节读。缓冲区里的残包要留到下一轮拼接，否则中文会被截断成乱码，这种问题在本地测试时经常看不出来，一上生产就变成偶发脏数据。

# Java 侧伪代码结构，不是可直接运行脚本\n// 缓冲残包，按行边界切分\nStringBuilder buf = new StringBuilder();\nwhile ((line = reader.readLine()) != null) {\n  if (!line.endsWith(delimiter)) { buf.append(line); continue; }\n  buffer = buf.append(line).toString(); buf.setLength(0);\n  handle(buffer);\n}

错误要分三类处理：连不上（网络、DNS、证书）、连上被拒（鉴权、权限、额度）、连上但返回业务错误（参数不对、资源不存在）。三类的动作完全不同，统一 catch 成一句日志等于把排查线索全丢了。

• 错误对象至少留：HTTP 状态、请求 ID、接口路径、关键入参摘要、耗时
• 排查顺序先看状态码，再看响应体，最后才回头查自己的参数拼装
• 遇到限流要做退避而不是立刻重投，退避梯度和排队思路见站内限流处理指南
• 不要把所有非 2xx 都当「服务挂了」，很多其实是自己的参数或权限问题

日志、降级与验收：上线前要跑的几条

日志字段固定成几个：traceId、接口名、耗时、状态、重试次数、Token 或文档量级。字段不固定，后面做慢查询和成本复盘时就没法聚合。这部分和站内关于中转站调用成本追踪的思路是一致的：先有可量化的记录，才谈得上优化。

• 降级路径提前想好：不可用时是返回空结果、走缓存、还是降级到纯模型直答，取决于业务能不能接受「没有引用来源」的答案
• 上线前跑一轮小验收：正常查询、空结果、超长文档、并发突刺、断网恢复各一条
• 封装层的单测用本地桩服务，把流式分片和错误响应做成固定样本，回归才有意义
• 降级要能被观测：走到降级分支时打一条明确日志，别让降级悄悄发生

验收跑完再放量。这五条里最容易被跳过的是「断网恢复」——它检验的是连接池和重试逻辑在异常后能不能自己恢复，而不是功能对不对。