ragflow api

很多人拿到 RAGFlow 的 API Key 就先去调对话接口，结果发现没建知识库、没解析文档、没拿到会话 ID，一路报错还不知道错在哪。这篇按「先鉴权、再灌数据、最后对话」的顺序把调用链路捋一遍，每一步给可执行动作和验证方法，报错按固定顺序排。具体参数与字段以站内接口文档和模型库页面的现时内容为准。

RAGFlow 的 API 不难，难的是调用顺序。很多人拿到 API Key 就直接去调对话接口，结果发现知识库没建、文档没解析、会话 ID 也没有，报了一堆错还不知道从哪儿下手。这篇按「先鉴权、再灌数据、最后对话」的顺序把链路捋一遍，每一步给可执行动作和验证方法。具体参数名、字段类型和路径请到站内接口文档页面核对当时的写法，不要照抄旧笔记。

先说明适用范围：下面讲的是自建实例和托管实例通用的调用思路，主要面向后端开发者。如果你用的是别人搭好的中转服务，路径前缀和服务地址会不一样，先确认清楚再写代码；纯前端直连的场景不适用，密钥暴露在浏览器里迟早出事，建议加一层自己的后端代理。

鉴权先跑通，再谈别的

RAGFlow 走的是 API Key 放在请求头里的方式，不是拼在 query 参数上，先把这一条固定住。请求头字段名、是否需要 Bearer 前缀，到站内接口文档页面确认当时的写法。调用前还要确认服务地址是自建实例还是托管实例，两者的路径前缀不一样，前缀写错就是 404，跟 Key 对不对没关系。

1. 最小验证随便调一个列表类接口，只看能不能返回数据。返回了说明 Key 和地址都对，再去接业务逻辑。这一步别急着传业务参数。
2. 确认访问范围远程访问有没有放行、实例是不是只绑在本机、端口是否对外开放，这三项都会让请求直接连不上。用 curl 或 Postman 单独验一遍，不要混在业务代码里排查。
3. 过网关的情况如果前面挂了一层中转或自建网关，把鉴权和转发分开看：先直连实例验证 Key 有效，再判断是不是网关把请求头吃掉了，或者做了二次改写。

知识库与文档：先建库，再传文件，最后等解析

这一步的顺序是固定的：建知识库 → 传文档 → 触发解析 → 轮询解析状态 → 建检索用的对话助手。跳过解析直接去问，召回必然是空的。建库和上传接口的字段名以站内接口文档为准，各版本之间可能有差异。

知识库

先创建再上传，后面的文档和对话都挂在它下面，取不到它的 ID 后面全断

文档上传

单文件和批量通常都支持，小团队先单文件跑通再批量，出问题好定位

解析

异步执行，接口返回成功不等于能检索，必须靠轮询状态字段判断

检索助手

绑定到知识库上，对话接口检索的就是它，不建它对话没有内容可召回

解析是异步的，写轮询拿状态字段判断，别用固定 sleep 猜时间。如果长时间停在解析中，先查切片配置和文件本身：扫描件、加密 PDF、超大文件是常见卡点，先进料清洗再重传。纯图片或手写体文档走这条路基本白费，得先做 OCR，但这一步的效果取决于原图质量，不是所有文档都适合。

• 上传前先确认文件格式和大小在原实例的接受范围内
• 解析失败先看状态返回的错误信息，别反复重传同一个文件
• 切片配置不同的知识库不要混用，检索参数对不上会拉低召回
• 上线前用一批真实文档压一遍，只看解析耗时和成功率，不要用测试小文件代替

对话接口：会话 ID 是那个最容易漏的东西

对话分两步：先建会话拿到会话 ID，再用这个 ID 发提问。少这一步就会每次提问都开新会话，多轮上下文对不上，用户看到的永远是「第一次对话」。会话 ID 要存下来复用，服务重启或用户重进也尽量恢复。

提问接口有几个开关要记住：是否流式返回、是否带引用来源、检索范围限定在哪个知识库。这三个决定了返回结果长什么样，也决定了前端怎么渲染。具体字段名到站内接口文档页面核对当时的写法。

报错排查：固定顺序走一遍，别东一榔头西一棒子

排查最忌讳跳步。按下面四步顺序走，前面干干净净再往下查，能省掉大量来回试错。第一步先看 HTTP 状态码：401 或 403 查 Key 和请求头，404 查路径前缀和实例地址，参数类报错查字段名和类型，这类错误信息通常写得很明确，别忽略。

1. 看状态码401/403 查 Key 和请求头写法，404 查路径前缀和实例地址，400 类查字段名、类型、必填项。
2. 看链路是否通用最简请求单独验地址、端口、证书、目标实例是否在运行。这一步排除的是网络层，不是业务层。
3. 看数据侧知识库是否为空、文档是否解析完、检索参数是否过严。召回为 0 绝大多数是这一类问题。
4. 最后看模型侧用了哪家的对话模型和嵌入模型、是否可达、额度是否用完。前面三步干净了再查这里。

这里提醒一句：模型侧的额度、可用模型列表和接口地址经常变，不要写死在代码里，集中放一处配置，定期到站内模型库页面核对当时的数字和字段。排查顺序不是绝对教条，如果 401 和 404 同时出现，先解决鉴权再谈路径。

调用顺序错了，再好的模型也召不回内容；排查顺序错了，再明显的问题也会被埋在一堆试错里。