你已经把 RAGFlow 跑起来了，知识库也建了，现在要把问答能力接进自己的后端或前端，结果发现官方文档翻半天还是不知道从哪下手：接口分几类、Token 放哪、批量导入走哪条路、超时和并发怎么设才不炸。这篇不给万能答案，只给一份调用要点的速查清单和排查顺序，帮你在动手前把坑先圈出来。
你已经把 RAGFlow 跑起来了，知识库也建了，接下来要把问答能力接进自己的后端或前端。翻官方文档半天，最容易卡的不是「接口在哪」，而是不知道先动哪一类、Token 放哪、超时和并发怎么设才不炸。这篇给一份调用要点速查清单和排查顺序，帮你动手前先把坑圈出来。
先说清一件事：RAGFlow 这类自建检索服务的接口不是「一个万能入口」，而是按用途分成几档。你对不上档，写出来的封装函数迟早要推倒重来。判断自己该走哪条路的办法很简单——先写下业务里「谁建库、谁传文件、谁提问、谁消费结果」四个角色，再对着接口清单划勾。
先分清你要调的是哪一类接口
把接口按用途粗分三档：知识库与文档管理类负责建库、传文件、触发切片解析；会话与问答类负责建会话、发起提问、拿回带引用的回答；检索类只做召回不生成，把片段交给你自己的模型二次加工。三档的调用节奏和超时策略完全不同，混在一个客户端里会很难维护。
- 知识库与文档管理类
- 建库、上传、解析、删除；重操作，适合异步或后台任务里跑
- 会话与问答类
- 建会话、提问、取引用；面向在线请求，对延迟敏感
- 检索类
- 只召回片段，不生成答案；适合你自有模型做下游生成
判断标准：如果答案要由你自己的模型来写，就走检索类，别用问答类再套一层，否则你会拿到一段别人的措辞再让模型改写，既浪费一次生成，也丢了引用可控性。如果只要一个现成回答，走问答类更省事。
不适用情形也要说清：如果你的场景是离线批量灌文档、根本不做在线问答，那重点全在文档管理类，会话和问答类可以先不碰，别为了「接口齐全」去接一堆用不上的能力。落地动作就是给上面三档各写一个独立客户端封装，别让一个函数既传文件又发提问。
鉴权、地址与调用姿势
Token 一般放在请求头里，服务地址由你自建的部署域名拼上版本前缀。这两项永远从环境变量或配置中心读，不要写死在代码里，也不要在日志里打印出来。多人协作时，建议本地用一套自己的 Token，别共用同一个，出问题能按人排查。
- 先打通最小链路用一个最轻的请求，比如列一次知识库或者建一个空会话，确认鉴权和地址都对。这一步过了再往上传文件、发提问这类重操作推进。
- 确认请求体格式普通接口走 JSON，文件上传通常是另一套 multipart 形式。别把两种塞进同一个封装函数，参数校验会互相打架。
- 先关流式调试调试阶段关掉流式，拿完整响应把字段结构看清楚。确认无误再打开流式接生产，否则你连错误返回长什么样都不知道。
还有个容易被忽略的点：错误返回的结构。鉴权失败、参数缺失、知识库不存在，这几类错误的响应长什么样，最好在打通链路阶段就各造一次，把状态码和错误字段记下来，后面写统一异常处理时就不用猜。
超时、并发与降级怎么设
超时不要一套参数打天下。普通查询给短超时，超了就让上游快速失败；文件解析和批量导入给长超时，甚至直接改成异步轮询状态。把这两个档位写成两个常量，谁调哪类接口就用哪档。
| 场景 | 超时策略 | 失败后动作 |
|---|---|---|
| 普通查询、取引用 | 短超时，快速失败 | 提示稍后重试，不阻塞页面 |
| 在线提问 | 中等超时，允许一次重试 | 重试仍失败则返回降级话术 |
| 文件解析、批量导入 | 长超时或异步轮询 | 记录任务标识，后台补查状态 |
| 健康检查类 | 极短超时 | 标记服务不可用，触发告警 |
并发要从你自己的部署规格反推，不要照抄别人的数字。做法是先小并发压一轮，观察服务端响应时间和失败率，再一档一档往上加，直到失败率开始抬头就停。这个拐点只有你自己压得出来。
- 可重试的失败：超时、连接断开、限流，用退避重试，重试次数设上限
- 不可重试的失败：参数错、鉴权失败、文件格式不支持，直接把错误抛给调用方，重试只是浪费
- 降级路径要写进代码：检索服务不可用时，是返回「暂时查不到」还是退回纯模型回答，提前定好
- 降级触发要有开关：别写死逻辑，留个配置项方便临时关掉降级、观察真实错误
不适用情形：如果你的调用量很小、一天就几百次，严格的分档超时和退避重试可能显得过度设计，先把最基础的重试和超时加上就行，等量级上来再细化。但降级这个决定无论量大量小都得先想清楚。
日志留痕与回归验证
日志不是越多越好，而是要能回放一次调用。每次请求至少记这几个字段：请求 ID、接口类型、知识库标识、耗时、状态码、是否命中引用。有这六项，出问题时就能按请求 ID 把整条链路捞出来，而不是靠时间戳碰运气。
| 字段 | 用途 | 注意 |
|---|---|---|
| 请求 ID | 串联同一次调用的多个接口 | 由调用方生成并透传 |
| 接口类型 | 区分管理/问答/检索 | 用枚举，别写自由文本 |
| 知识库标识 | 定位是哪个库的问题 | 只记 ID，不记库名原文 |
| 耗时 | 发现慢接口和拐点 | 按接口类型分开统计 |
| 状态码 | 快速筛失败请求 | 区分鉴权和参数错误 |
| 是否命中引用 | 判断召回是否为空 | 空召回往往不是接口故障 |
把一次典型调用拆成「建会话—提问—取引用—关会话」四步，每一步都单独打点。任一环节失败，你都能从日志看出是卡在会话没建上，还是提问返回了但引用为空。这两种情况的排查方向完全不同。
- 准备一批固定问题挑十来个覆盖不同知识点的稳定问题，答案结构相对可预期，作为回归基线。
- 升级后先跑回归接口或镜像升级后，先跑这批问题，比对命中片段和答案结构有没有变，别等用户来报。
- 比对召回而非措辞重点看召回的片段是否一致、引用是否还带得回来。生成措辞会飘，召回变化才是真信号。
- 记录差异再放行有差异就记下来，判断是切分策略变了还是模型变了，确认可接受再上新版本。
还有一条底线：敏感内容脱敏后再落盘。知识库里的原文不要整段写进日志，记个摘要或者片段 ID 就够了。日志系统的访问权限也要收一收，别让谁都能翻。
下一步动手前先去站内的数据页把当时的价格与模型资料核一遍，再对照工具目录挑合适的调试工具；具体数字和版本别抄别处，以页面当时为准。→常见问题
RAGFlow 的接口文档在哪看，站内有整理吗？
站内不复制官方文档内容，只在 /stacks/frameworks 这类目录页帮你定位入口。动手前建议先确认你部署的版本，不同版本接口路径和字段会有差异，以你本地实例的文档为准，别照抄网上别的版本的示例。
调 RAGFlow 接口一直超时，先查什么？
先分清是解析类接口还是问答类接口：解析大文件本来就慢，超时值要给够。再看服务端日志有没有在真正处理，还是请求根本没进来。最后才怀疑网络和反向代理，用 /tools/speed-test 先量一下到你自己部署地址的延迟基线。
想先小成本验证接口能不能用，怎么做？
搭一个最小实例，只放几份小文档，用脚本跑「建库—上传—提问」三条链路各一次，确认返回结构符合预期再扩量。别一上来就灌几百份文件，解析队列一堵你分不清是接口问题还是容量问题。
