ragflow deepseek api

你本地或服务器上已经跑起了 RAGFlow，DeepSeek 的 Key 也拿到了，真动手时却卡在「接口地址拼哪一段、用 Python 还是直接发 HTTP、返回是空的算成功还是失败」。这篇不重复协议兼容和客户端配置，只给两条调用路径的落地写法、参数取舍和一套排错顺序，让你二十分钟内把第一次检索跑通。

本地或服务器上已经跑起了 RAGFlow，DeepSeek 的 Key 也拿到了，真动手时却卡在接口地址拼哪一段、用 Python 还是直接发 HTTP、返回是空的算成功还是失败。这篇不重复协议兼容和客户端配置那套东西，只给两条调用路径的落地写法、参数取舍和一套排错顺序。

目标很具体：二十分钟内把第一次检索跑通，并且知道下一次出问题时先看哪里。下面每节都给判断标准和能直接照做的动作，凡是涉及具体数值（端口、超时秒数、配额）的地方，都请到站内对应页面核对当时的情况，别照抄别人截图里的数字。

先决定走 HTTP 还是 Python SDK：两条路的边界在哪

两条路的终点是同一个服务端，区别只在你这一侧怎么写。HTTP 直连适合脚本、后端服务、和已有网关拼在一起；Python SDK 适合本地调试、在 Notebook 里反复试参数。别一上来就纠结，先看你的真实约束再选。

什么情况下这个选择不适用：如果你只是临时验证连通性，两条路都不用认真搭，一条 curl 或几行脚本跑通即可，验证完就丢。真正需要按上面这张表决定的是要长期维护的调用方。

HTTP 调用的最小骨架：地址、鉴权、请求体三段拼装

一次请求拆成三段：地址、鉴权、请求体。三段里任何一段拼错，表现都不一样——地址错通常连不上，鉴权错返回明确的拒绝，请求体错往往返回一个看起来成功的空结果，这也是最容易误判的一种。

• 地址由部署方式决定，本地自托管和容器端口不一样，别照抄别人的截图，先去站内核对当前部署形态对应的入口
• 鉴权走请求头，Key 最常见的泄漏来源是写进前端或提交进仓库，让服务端转发可以规避
• 请求体里最容易被忽略的是知识库或会话的标识字段，拿不到这个标识通常不报错，只返回空结果
• 判断成功要看两件事：HTTP 状态码是不是 2xx，以及业务字段里是不是真的回了内容，这两者不等价

# 结构示意，地址与字段名请按站内文档替换
curl -sS -X POST "<你的服务入口>/<对应接口路径>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的 Key>" \
  -d '{"<必填标识字段>":"<知识库或会话标识>","<查询字段>":"<你的问题>"}' \
  -w "\nHTTP=%{http_code} time=%{time_total}s\n"

加 -w 打印状态码和耗时是个小习惯，但能省很多事：断网、鉴权失败、网关超时这三种在你的终端里会呈现出明显不同的耗时和状态码，一眼可分。具体接口路径和字段名请以站内文档为准，不要凭记忆写。

Python 调用：把重试、超时、日志写在业务代码之前

直接调也行，但只要这个调用会被多处复用，就先封一层薄客户端。目的不是抽象，是把超时、重试、日志集中在一个文件里，别让它们散落在十几个调用点，后面改一个参数要翻半个项目。

1. 封一层客户端建一个模块，只暴露一两个方法，地址、Key 从环境变量读，不硬编码。
2. 分开设超时连接超时和读取超时分开配。检索类请求天然比纯生成慢，一刀切的小超时会让偶发失败看起来像必现故障。
3. 重试只做幂等的读取类请求可以重试，写入类要谨慎，重试前先确认服务端是否去重。
4. 日志留够字段至少记请求标识、耗时、状态码、返回条数。缺了这几个字段，复盘只能靠猜。
5. 验证方式故意把一个字段写成错类型，看日志里能不能区分出「参数错」和「鉴权错」。

不适用的情况：一次性脚本、Notebook 里的探索性调用不用搭这层，直接调更省事，套上封装反而多一层调试噪声。判断标准很简单——这段代码会不会被第二次调用。

调不通时的排查顺序：从连通性一路收到参数

最常见的浪费是顺序颠倒：明明地址写错了，却一直在改请求体参数，改到最后连自己改过什么都不记得。固定一个从外往里的排查顺序，能让每一步都在排除一个变量。

• 第一步先验连通性和鉴权：地址能不能通、Key 有没有被拒，这一步只关心能不能连上，不碰业务参数
• 第二步看返回结构：是错误码、空结果还是格式不对，这三种走的是完全不同的分支
• 第三步才做参数级排查，逐个字段对照文档，重点看类型和必填项有没有对上
• 第四步再看是不是被上游网关或代理改了请求，尤其是加了反代的环境

如果你所在的环境本身网络条件一般，建议先到站内的测速页面量一个基线，把延迟数字记下来。这样后面出现慢的时候，你能立刻区分是网络变差了还是请求本身变重了，而不是凭感觉判断。

什么情况下这两条路都不合适

这两种调用方式都是「你主动发起、明确指定一次检索」。一旦需求越过这条线，硬套就不合适了，继续往上堆代码只会让后面更难维护。

还有一种容易忽略的情况：团队里多个人各自持有 Key 各自直连，出了事没人说得清是哪条链路的问题。如果你所在的组织有统一网关，把这一跳收进去，比在业务代码里各写各的更能省后续的沟通成本。

能跑通靠的是地址对、Key 对、标识对；能长期跑得住靠的是超时、重试和日志写在了业务之前。