ragflow api usage

你多半是这种情况：本地 RAGFlow 跑起来了，想用代码而不是网页去建知识库、传文档、发起问答，一上手却卡在三件事——Key 放哪个头、哪些参数不填会报错、跑批时动不动超时或被限流。这篇不重复讲 RAG 原理，也不讲客户端配置，只给工程侧的落地做法：调用链路怎么拆、参数按什么口径读、超时并发降级日志怎么设、出错按什么顺序查。

你多半是这种情况：本地 RAGFlow 跑起来了，想用代码而不是网页去建知识库、传文档、发起问答，一上手却卡在三个地方——Key 放哪个头、哪些参数不填会报错、跑批时动不动超时或被限流。这篇不讲 RAG 原理，也不讲客户端怎么配，只给工程侧的落地做法：调用链路怎么拆、参数按什么口径读、超时并发降级日志怎么设、出错按什么顺序查。先摆一个最小判断：如果你只是想手动问两句，网页端就够了，API 的价值在于批量、可编排、可回归。

下面五节按「链路—参数—稳定—可观测—排错」的顺序走，基本对应你从第一次跑通到能上线的全过程。每一节末尾都有能直接照做的动作，别只读不做。每个接口的字段名和路径以你本地实例的接口文档页为准，不同部署方式可能对不上别人博客里的示例。

先认清 RAGFlow API 的调用链路：一次问答要跨几个接口

RAGFlow 的 API 不是「一个接口问天下」，而是一条有前后依赖的链。典型顺序是：建知识库 → 上传文档 → 触发解析 → 等切块与向量化完成 → 建会话 → 发起对话。前置步骤没跑完，对话接口通常拿不到内容，这时返回空或答非所问都属正常，别急着怀疑模型。

• 每个环节是独立接口，要分别重试；不能用一个 try 包住整条链，失败时你连哪一步挂的都分不清
• 解析和向量化是异步的，必须轮询状态，而不是提交完立刻去取结果
• 把链路抽成一个客户端类，方法名按业务语义命名（建库、入库、提问），别在业务代码里散着写原始请求
• 批量任务建议先小样本跑通全链路，再放大件数和并发

1. 第一步：固定基线请求手动或用 curl 跑一次最小链路，确认每个接口都通、字段都填对；把这次请求体存下来当模板
2. 第二步：抽客户端类把上一步的请求封装成方法，业务侧只调用语义化方法，不直接拼 JSON；验证方式是业务代码里搜不到原始 URL
3. 第三步：加状态轮询解析触发后轮询状态，设超时上限；验证方式是故意传一个格式有问题的文档，轮询应在预算内返回失败而不是卡死
4. 第四步：串联并记录把知识库标识、文档标识、会话标识一路透传并落日志，验证方式是随便挑一次问答能把整条链路还原出来

参数按三类读：必填、会影响检索质量的、只影响返回格式的

参数不分类，调起来就会乱。建议一上手就把你用的所有字段分成三堆：必填项、影响效果项、格式项。判断标准很简单——改完之后问题的答案会变，就是效果项；只改返回长什么样，就是格式项。

必填项

知识库或会话标识、问题文本这类，缺了直接 4xx，先用最小请求把它们填对

效果项

召回条数、相似度下限、是否重排、是否带引用，改一个答案就变一次，必须做参数快照

格式项

是否流式、返回字段裁剪，可以放客户端默认配置里，不参与效果评测

兜底判断法

不确定某字段是否必填，就把请求体删到只剩必填项跑一次，再逐个加回来

什么情况下这套分类不适用？如果你的应用不关心答案质量、只把接口当数据管道用，那效果项对你就没意义，可以全部按默认值走，精力放在吞吐和稳定性上。

超时、重试与并发：跑批时才暴露的那几个坑

单次调用手动点两下很难发现问题，一上批量全冒出来。核心思路是：不同阶段给不同预算，只对安全动作重试，并发从低档起步再往上摸。限流恢复的完整步骤可以顺着站内 429 相关文章往下看。

并发建议从低档起步，遇到限流类报错先降并发、加排队，再考虑加机器。每个阶段的延迟基线别拍脑袋，可以先到站内 /tools/speed-test 量一遍自己到目标服务的往返延迟，再决定每个阶段设多少，时间预算和分档建议也以那里当时测到的数字为准。

日志与评测：让「这次慢/这次答得差」都能复盘

很多人只记成功日志，出事时一片空白。每次调用至少记请求时间、接口名、状态码、耗时、重试次数、知识库与会话标识；如果只记一个，就记请求标识，它能把同一次问答的所有环节串起来。

• 把提问原文、命中的文档片段标识、最终回答一起落库，才能区分是检索没召回还是模型没用好
• 参数或提示词一改，固定一组几十条典型问题跑回归，记录命中率与人工判定可用比例，别凭单次观感下结论
• 成本与用量按会话、按知识库维度汇总，方便定位哪条业务线在烧量，口径参照站内 token 与调用费说明
• 日志里不要落完整密钥和敏感原文，用截断或哈希代替，出事时排查够用就行

如果团队没有人力搭评测集，退一步的做法是：每次上线前手动抽十条最难的问题跑一遍，记录通过几条。这个动作成本很低，但能拦住大部分「参数一改就崩」的改动。

出错先查这几步，按顺序走别跳

排错最忌讳东一榔头西一棒子。下面这个顺序的好处是每一步都能排除一大类可能，走完基本能定位到是环境、身份、数据还是模型的问题。

1. 第一步：确认服务在不在本地容器是否健康、端口是否可达，再谈鉴权；验证方式是用最朴素的连通性请求打一下
2. 第二步：看返回码分类401/403 是身份与权限，404/405 是路径和方法，参数类 4xx 基本是字段名或类型不对
3. 第三步：看数据状态文档解析是否完成、切块是否生成、向量是否入库；前置没完成时对话返回空内容属正常
4. 第四步：交叉验证模型侧换一个已知可用的模型配置再问一次，能立刻区分是接口问题还是模型服务问题

什么情况下这套顺序不适用？如果错误是间歇性出现、且集中在高并发时段，那大概率不是逻辑问题，而是超时与并发配置问题，直接跳到上一节重看时间预算和限流处理更高效。