超级大脑 · 开放平台 API

健康检查

用途：连通性自检。用于接入前确认网关可达，以及给监控 / 巡检做探活。它不查业务数据、不需要令牌、不消耗配额、不写审计。

前置条件与鉴权：无。任何能访问网关网络的调用方都可直接请求。

请求参数

无。

响应字段

字段	类型	说明
status	string	恒为 ok，表示网关进程可用（不回显版本 / 地址等内部信息）

请求示例

curl -s http://<host>/openapi/v1/health

响应示例

{"status":"ok"}

常见错误与排错

现象	可能原因	处理
连接失败 / 超时	域名解析、网络或防火墙 / 安全组未放行	先 curl -v 看是否握手成功，再核对域名、端口与网络策略
返回 404	路径漏了 /openapi/v1 前缀，或误用了平台内部接口路径	使用完整路径 /openapi/v1/health
返回 5xx	网关或依赖尚未就绪	稍后重试；持续失败请联系平台

换取访问令牌

用途：用应用凭证 app_key + app_secret 换取 access_token（调用数据面接口用）与 refresh_token（过期续期用）。这是调用任何数据面接口的第一步。

前置条件与鉴权：已在企业管理端创建 API 应用并取得 app_key / app_secret（明文仅在创建应用、控制台「重置主密钥」时各展示一次）。本端点不需要 Bearer 令牌，但按 IP 级限流。请缓存令牌，不要每次调用业务接口都重新换取。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
app_key	string	是	应用 Key（创建应用时下发）
app_secret	string	是	应用 Secret（创建应用 / 重置主密钥时下发）

响应字段

字段	类型	说明
access_token	string	访问令牌，以 Authorization: Bearer <access_token> 调用数据面接口
token_type	string	恒为 Bearer
expires_in	integer	access_token 有效期（秒；默认 7200 = 2 小时）
refresh_token	string	续期令牌，仅此一次明文返回，请立即保存；有效期 7 天
refresh_expires_in	integer	refresh_token 有效期（秒，默认 604800）

请求示例

curl -s -X POST http://<host>/openapi/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"app_key":"ak_xxx","app_secret":"sk_xxx"}'

响应示例

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "a1b2c3…",
  "refresh_expires_in": 604800
}

常见错误与排错

状态码	含义	处理
401 凭证无效	app_key / app_secret 错误；主密钥已被重置；应用已被删除（统一文案，不区分原因，防枚举）	核对凭证；若刚重置过主密钥，改用新 secret；不要继续重试旧凭据
403 应用已停用	应用被平台停用，或所属开发者被禁用	联系平台确认应用 / 开发者状态
429（code=42902）	本端点 IP 级限流	按响应头 Retry-After（秒）退避重试；更好的做法是缓存令牌、减少换取次数

刷新访问令牌

用途：access_token 过期后，用 refresh_token 换一枚新的 access_token，无需重新提交 app_secret。适合常驻服务在令牌到期前主动续期，或在收到 401 时先续期再重试一次。

前置条件与鉴权：持有有效的 refresh_token（来自 /auth/token 或上一次刷新）。refresh_token 不轮换——刷新成功后继续沿用原值，直到 7 天到期或被管理端吊销。无需 Bearer 令牌；无 IP 级限流。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
refresh_token	string	是	换取访问令牌时下发的 refresh_token（仅此一次明文可见）

响应字段

字段	类型	说明
access_token	string	新签发的访问令牌（携带新 jti，可被管理端单独吊销）
token_type	string	恒为 Bearer
expires_in	integer	新 access_token 有效期（秒）
refresh_expires_in	integer	原 refresh_token 的剩余有效期（秒；不因刷新而延长）

请求示例

curl -s -X POST http://<host>/openapi/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"a1b2c3…"}'

响应示例

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_expires_in": 604000
}

常见错误与排错

状态码	含义	处理
401 凭证无效	refresh_token 过期 / 已被吊销（如主密钥重置）/ 不匹配（统一文案，防枚举）	改用 app_key + app_secret 重新走 /auth/token 换一对新令牌
403 应用已停用	应用被停用 / 开发者被禁用	联系平台确认状态
503	令牌刷新服务暂不可用（登记表尚未迁移完成时的降级态）	稍后重试；也可回退用 app_secret 换取新令牌

知识检索（只读）

用途：在应用授权范围内做语义检索，直接返回命中的原文片段（不做生成）。适合：把知识片段喂给自己已有的大模型、在自有系统里做搜索 / 命中展示、或先检索再自行组织答案。

前置条件与鉴权：Authorization: Bearer <access_token>；应用已授权至少一个知识库；本路径在应用接口白名单内。可访问范围由应用创建时勾选决定，请求里无法扩大；管理端调整范围后下一次调用即生效，无需更换凭证。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
query	string	是	检索语句，长度 ≤ 2000 字符；为空或超长 → 422
top_k	integer	否	返回条数（默认 5，上限 20；超出自动收敛为上限并在响应回显，不报错）
kb_ids	array<string>	否	本次限定检索的知识库 ID（≤20 个；须在授权范围内，越权 403「该知识库不在应用的授权范围内」；不传 = 应用级范围）
metadata_filters	object	否	元数据过滤（≤10 键）。已预留——当前引擎不支持，传了不改变结果
rerank	boolean	否	重排开关。已预留，当前不生效
score_threshold	number	否	分数阈值（0~1）。已预留，当前不生效

响应字段

字段	类型	说明
query	string	回显本次检索语句
top_k	integer	实际生效的条数（被收敛后的值）
results[].title	string	片段标题（可读文档名：平台识别到来源文档时由平台补齐，否则回落引擎名 / 章节路径）
results[].content	string	片段内容（已按应用配置脱敏）
results[].source	string	来源文档标识（引擎文档 ID，兼容旧字段）
results[].doc_id	string	平台文档 ID——可直接用于 GET /openapi/v1/documents/{doc_id}/download（识别不到来源文档时缺省）
results[].url	string	原文链接：URL 摄入 = 原始公网地址；上传文件 = 平台下载端点地址（需带同一个 Bearer 令牌）
results[].source_url	string	原始来源 URL（仅 URL 摄入且为公网地址时出现）
results[].score	number	相关度分数：仅同一响应内可比，跨查询 / 跨知识库无可比性，勿用作绝对阈值判断
results[].chunk_id	string	命中的知识片段 ID（可选，仅部分引擎后端提供，无值则不出现）
results[].positions	array<string>	片段在原文中的页码 / 位置定位（可选，同上）
latency_ms	integer	服务端处理耗时（毫秒）
notice	string	仅空结果时出现的提示文案（合法业务态，见下方示例）

请求示例

curl -s -X POST http://<host>/openapi/v1/retrieve \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"报销流程","top_k":5}'

响应示例

命中：

{
  "query": "报销流程",
  "top_k": 5,
  "results": [
    {"title": "费用报销制度.docx", "content": "…报销标准与流程…",
     "source": "a1b2c3_external-download", "score": 0.87}
  ],
  "latency_ms": 356
}

空结果（正常业务态，不是错误）：

{
  "query": "不存在的主题",
  "top_k": 5,
  "results": [],
  "latency_ms": 120,
  "notice": "未检索到相关内容"
}

常见错误与排错

状态码	含义	处理
401	凭证无效 / 令牌过期（统一文案，防枚举）	用 refresh_token 续期后重试一次
403	接口未授权 / 应用停用 / 未授权任何空间 / 密钥 scope 不含本接口 / 请求的 kb_ids 越权	按 detail 定位：核对应用授权范围、接口白名单与密钥权限；kb_ids 只在授权范围内传
422	query 为空或超长；kb_ids 非 UUID 或超 20 个	修正请求体（超长先截断或改写）
429	42902 频率超限 / 42901 配额用尽	读 Retry-After 退避；配额类需等周期重置（看 X-Quota-* 响应头）
451	query 命中内容安全敏感词（拦截发生在配额预留之前，不消耗配额）	改写 query 后重试
502 / 504	引擎异常 / 引擎响应超时	按指数退避重试（引擎侧问题，重试通常有效）

知识检索（批量）

用途：一次提交多条检索（1~50 条），逐条并发执行。单条失败不影响其它条——整批恒定返回 HTTP 200，失败的那条在结果里用 error 标注。适合离线批量补数据、一次取多个主题的原文。

前置条件与鉴权：Authorization: Bearer <access_token>；本路径需应用显式授权（存量应用默认未授权 → 403「该接口未授权」）。配额按实际条数预留（N 条计 N 次），限流按 1 次调用计。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
items	array	是	检索条目列表（1~50 条；为空或超出 → 422 整体拒绝）
items[].query	string	是	该条检索语句（≤ 2000 字符）
items[].top_k	integer	否	该条返回条数（默认 5，上限 20，超出自动收敛）
items[].kb_ids	array<string>	否	该条限定知识库（≤20）；越权只在该条 error 里回显，不影响其它条

响应字段

字段	类型	说明
results[]	array	逐条结果，与请求顺序一致；必须逐条判 ok，不能只看 HTTP 状态码
results[].ok	boolean	该条是否成功
results[].query / top_k	string / integer	回显该条入参与实际生效条数
results[].results	array	该条命中的片段（字段同单条 /retrieve：title/content/source/score…）
results[].error	object	仅失败条出现：{status, detail}（如 403 越权、504 超时）
results[].latency_ms / notice	integer / string	该条耗时 / 空结果提示（可选）
latency_ms	integer	整批耗时（毫秒）

请求示例

curl -s -X POST http://<host>/openapi/v1/retrieve/batch \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"items":[{"query":"报销流程","top_k":5},{"query":"请假制度"}]}'

响应示例

{
  "results": [
    {"ok": true, "query": "报销流程", "top_k": 5,
     "results": [{"title": "费用报销制度.docx", "content": "…", "source": "…", "score": 0.87}],
     "latency_ms": 340},
    {"ok": false, "query": "请假制度", "top_k": 5,
     "error": {"status": 504, "detail": "知识引擎响应超时"}}
  ],
  "latency_ms": 812
}

常见错误与排错

状态码	含义	处理
401	凭证无效 / 令牌过期	续期后重试一次
403	接口未授权（存量应用默认如此）/ 应用停用 / 密钥 scope 不含本接口	请平台运营把本路径加入应用接口白名单
422	items 为空或超 50 条、条目校验失败（整批拒绝）	分批提交（每批 ≤50 条）
429	频率超限 / 配额用尽	退避重试；配额类等周期重置
整批 200 但有条目失败	该条引擎超时 / 越权等	只重试 ok=false 的那几条，避免整批重发浪费配额

知识问答

用途：提问并拿到「答案 + 引用来源」。默认同步 JSON——服务端把流式结果聚合好再返回，接入最简单；传 stream=true 时直通 SSE 逐 token 输出，首字延迟低，适合客服机器人 / IM 等交互场景。支持多轮对话。

前置条件与鉴权：Authorization: Bearer <access_token>；应用已授权至少一个知识库；本路径在应用接口白名单内。授权范围内暂无内容时不会报错，而是返回空结果（见下）。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
query	string	是	问题文本（≤ 2000 字符）
top_k	integer	否	检索条数（默认 8，上限 20，超出自动收敛）
kb_ids	array<string>	否	本次限定知识库（≤20；越权 403；不传 = 应用级范围；流式 / 非流式均生效）
stream	boolean	否	true = SSE 流式；默认 false = 同步 JSON
conversation_id	string	否	会话 ID（字母 / 数字 / _ / -，≤64 位，应用内唯一）。服务端按（应用, 会话）保留最近 20 轮历史，24 小时未活跃自动清理；再次携带即续接多轮
history	array	否	本轮之前的历史 [{role:"user"|"assistant", content}]，≤ 20 轮；与 conversation_id 同时传时以本字段为准
temperature / top_p / max_tokens	number / number / integer	否	请求级生成参数（超安全区间自动收敛）。已预留——当前引擎不支持透传，平台暂不消费这些值
tools	array	否	工具定义（≤5 个）。已预留，当前不生效
response_format	object	否	结构化输出（仅支持 {"type":"json_object"}）。已预留，当前不生效

响应字段

stream=false（同步 JSON）：

字段	类型	说明
answer	string	答案全文，恒为非空字符串（无内容时为固定文案「知识库中未找到相关信息。」）
sources[]	array	引用来源，字段同 /retrieve 的 results（title/content/source/score，可选 doc_id/url/source_url/chunk_id/positions）
model	string	实际使用的引擎 / 模型标识（如 ragflow）
latency_ms	integer	服务端处理耗时（毫秒）
notice	string	空结果提示（仅空结果时出现）

stream=true（SSE，text/event-stream）：每帧一行 data: <json> + 空行分隔。

帧类型	载荷	说明
增量帧	{"token":"…"}	逐 token 输出正文
终态帧	{"done":true, content, sources, model, latency_ms, truncated}	流正常结束。truncated=true 表示未以引擎终态帧结束，content 为已累计部分；空结果时另含 notice
错误帧	{"error":"知识引擎暂时不可用"} / {"error":"知识引擎响应超时"}	流开始后引擎出错只能靠带内帧告知（文案与同步 502/504 一致）

请求示例

# 同步（默认）
curl -s -X POST http://<host>/openapi/v1/ask \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"试用期多久"}'

# SSE 流式（-N 关闭缓冲，逐帧到达）
curl -sN -X POST http://<host>/openapi/v1/ask \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"试用期多久","stream":true}'

# 多轮（conversation_id 续接上下文）
curl -s -X POST http://<host>/openapi/v1/ask \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"那转正后呢？","conversation_id":"chat-42"}'

响应示例

同步 JSON：

{
  "answer": "试用期为 3 个月。",
  "sources": [
    {"title": "员工手册.pdf", "content": "…试用期：3 个月…", "source": "doc_123", "score": 0.91}
  ],
  "model": "ragflow",
  "latency_ms": 2410
}

SSE 流式（逐帧）：

data: {"token":"试用期"}

data: {"token":"为 3 个月。"}

data: {"done":true,"content":"试用期为 3 个月。","sources":[],"model":"ragflow","latency_ms":2410,"truncated":false}

常见错误与排错

状态码 / 现象	含义	处理
401	凭证无效 / 令牌过期	续期后重试一次
403	接口未授权 / 应用停用 / 未授权任何空间 / 密钥 scope 不含本接口 / kb_ids 越权	按 detail 定位并联系平台确认授权
422	query 为空或超长；kb_ids 非 UUID 或超 20 个；history 超 20 轮	修正请求体
429	频率超限 / 配额用尽	读 Retry-After；/ask 的配额响应另带 X-Quota-Reset（重置时刻）
451	query 命中内容安全敏感词（不消耗配额）	改写 query 后重试
502 / 504	引擎异常 / 聚合超时（上限 60 秒）	指数退避重试；可降低 top_k 减轻引擎压力
长连接突然中断	首 token 30s 内无输出 / 帧间静默超 30s / 总时长超上限	服务端会下发终止帧；客户端应把「连接结束但没有终态帧」当作失败并重试

知识写入（上传文档）

用途：把文档写入应用已授权的知识库，异步解析入库。提交后立即返回 task_id，再用「查询写入任务」接口轮询进度与结果。

前置条件与鉴权（缺一不可）：① 应用已由平台运营授予写入能力（write_enabled，默认关闭）；② 目标 kb_id 在应用授权范围内；③ 文件扩展名在 pdf / docx / xlsx / txt / md / csv 内，且大小 ≤ 20MB。鉴权用 Authorization: Bearer <access_token>。写入配额与检索共用同一配额桶（每次提交预留 1 次额度）。

请求参数

multipart 上传文件，或 JSON 传 source_url —— 二选一。

字段	类型	必填	说明
kb_id	string	是	目标知识库 ID（必须已在应用授权范围内，否则 403）
file	file	二选一	文档文件（pdf / docx / xlsx / txt / md / csv，≤ 20MB）
source_url	string	二选一	文档 URL（http/https；路径扩展名须在白名单内）

响应字段

字段	类型	说明
task_id	string	写入任务 ID（用于轮询 GET /openapi/v1/documents/tasks/{task_id}）
status	string	恒为 queued（已入队，解析尚未开始）
doc_id	string|null	文档 ID（创建时恒为 null；任务终态后从「查询写入任务」响应获取，用于删除 / 恢复寻址）

请求示例

# multipart 上传文件
curl -s -X POST http://<host>/openapi/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "kb_id=a1b2c3d4-..." -F "file=@/path/to/guide.pdf"

# 或：JSON 传来源 URL
curl -s -X POST http://<host>/openapi/v1/documents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"kb_id":"a1b2c3d4-...","source_url":"https://example.com/guide.pdf"}'

响应示例

{"task_id": "2f1e4a…", "status": "queued", "doc_id": null}

常见错误与排错

状态码	含义	处理
400	文件类型 / 大小 / 来源参数不合法	核对扩展名白名单与大小上限；URL 需为 http/https 且扩展名合规
403 写入能力未开通	应用尚未被授予写入能力（默认关闭）	联系平台运营为你的应用开通「写入能力」
403 该知识库不在应用的授权范围内	目标 kb_id 不在授权范围	换用已授权的知识库，或请管理端补充授权
403 该密钥未授权本接口	所用扩展密钥的权限不含 upload scope	改用主密钥，或在控制台把该密钥权限放开
422	file 与 source_url 未二选一 / kb_id 格式错误	只传其中一个来源字段
429	频率超限 / 配额用尽（与检索共用配额桶）	退避重试；配额类等周期重置

诚实边界：上传时不拦截内容安全（标题 / 内容命中仅告警）；在 document_ingest 执行时命中的，任务会置为 failed，error_log 显示「内容安全未通过」。任务不支持取消（引擎无取消接口）。URL 来源的文档在企业端文件列表不可见（仅知识原子可见）。

查询写入任务

用途：轮询文档写入任务的状态。processing → done 表示已解析入库；failed 时读 error_log 定位原因。进度是查询时点的引擎实时值（任务表不持久化进度）。本端点不计量，可以放心轮询。

前置条件与鉴权：Authorization: Bearer <access_token>；task_id 必须由本应用创建（他人任务返回 404，防枚举）。

请求参数

路径参数（task_id 取自请求地址）。

字段	位置	必填	说明
task_id	path	是	POST /openapi/v1/documents 返回的任务 ID

响应字段

字段	类型	说明
task_id	string	任务 ID
doc_id	string|null	文档 ID（任务已创建知识原子后非空——done 及多数 failed；内容安全未通过等无原子任务为 null）。删除 / 恢复用它寻址，与「文档列表」同源
status	string	queued / processing / done / failed
progress	integer	进度 0~100（引擎实时值；done = 100）
document_name	string	文档名
source_type	string	file（上传文件）/ url（来源 URL）
kb_id	string	目标知识库 ID
error_log	string	失败原因 / 降级说明；成功时为空串
created_at / updated_at	string	创建 / 最近更新时间

请求示例

curl -s http://<host>/openapi/v1/documents/tasks/2f1e4a… \
  -H "Authorization: Bearer $TOKEN"

响应示例

{
  "task_id": "2f1e4a…",
  "doc_id": "5f3a…",
  "status": "done",
  "progress": 100,
  "document_name": "guide.pdf",
  "source_type": "file",
  "kb_id": "a1b2…",
  "error_log": "",
  "created_at": "2026-10-10T08:00:00",
  "updated_at": "2026-10-10T08:00:12"
}

常见错误与排错

状态码 / 现象	含义	处理
401	凭证无效 / 令牌过期	续期后重试
404	任务不存在（含他人任务，防枚举）	核对 task_id 是否由本应用创建
422	task_id 格式错误	使用创建任务时返回的原值
status=failed	解析失败 / 内容安全未通过	看 error_log：内容安全类需修改文档后重新上传
progress 长时间不变	引擎侧解析慢（大文件 / 队列积压）	继续轮询（建议间隔 2~5 秒）；长时间停在 queued 请联系平台

批量导入

用途：一次提交多个文档（multipart 多文件 或 JSON 多 URL 二选一），每个文档各自生成一个任务，整批共享一个 batch_id。

前置条件与鉴权：需 upload scope + 应用写入能力（write_enabled，运营按应用授予）；目标知识库必须已在应用授权范围内。

请求参数

项	上限 / 取值	说明
单次文件数 / URL 数	≤50	超出 → 422 整批拒绝
单文件大小	≤20 MB	与单条上传一致
整批总量	≤200 MB	超出后该文件与后续项逐项返回 413（前面已入队的保留）
类型	pdf / docx / xlsx / txt / md / csv	URL 模式按路径扩展名判定（无扩展名放行）
kb_id	string	必填，须在应用授权范围内
files / urls	array	二选一，同时给或都不给 → 422

响应字段

字段	类型	说明
batch_id	string	批次 ID（查进度、溯源用）
total / accepted / rejected	integer	总项数 / 已入队 / 未入队
items[]	array	逐项：index / document_name / ok / task_id / doc_id / status / error{status,detail}

部分成功语义：整体恒 200；单项失败只体现在 items[].ok=false。配额按文件计（每个文件 1 次），配额不足时能入多少算多少（后续项返回 429），不会整批失败。

请求示例

# 多文件（multipart）
curl -s -X POST "http://<host>/openapi/v1/documents/batch"   -H "Authorization: Bearer <access_token>"   -F "kb_id=a1b2c3d4-..."   -F "files=@a.pdf" -F "files=@b.md"

# 多 URL（JSON）
curl -s -X POST "http://<host>/openapi/v1/documents/batch"   -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json"   -d '{"kb_id":"a1b2c3d4-...","urls":["https://example.com/a.pdf","https://example.com/b.md"]}'

响应示例

{"batch_id": "9f2c…", "total": 3, "accepted": 2, "rejected": 1,
 "items": [
   {"index": 0, "document_name": "a.pdf", "ok": true,  "task_id": "2f1e…", "doc_id": null, "status": "queued"},
   {"index": 1, "document_name": "b.md",  "ok": true,  "task_id": "3a7d…", "doc_id": null, "status": "queued"},
   {"index": 2, "document_name": "x.exe", "ok": false, "task_id": null, "doc_id": null, "status": "failed",
    "error": {"status": 400, "detail": "不支持的文件类型: .exe（仅支持 csv, docx, md, pdf, txt, xlsx）"}}
 ]}

常见错误与排错

状态码	含义	处理
403	写入能力未开通 / 知识库不在授权范围 / 密钥 scope 不含 upload	按 detail 定位；写入能力找运营开通
422	files 与 urls 未二选一 / 超过 50 项 / URL 非法	修正请求体
429	限流（整批拒绝）	按 Retry-After 退避
单项 error.status=429	配额用尽（部分成功）	次日重试剩余项，或联系平台提额

批量进度

用途：按 batch_id 汇总本批任务进度（总数 / 各状态计数 / 逐项 task_id 与状态）。

前置条件与鉴权：需 upload scope；只返回本应用提交的批次（他人批次 404 防枚举）；不计量。

响应字段

字段	类型	说明
total	integer	批次内任务数（= 入队成功数）
status_counts	object	{queued, processing, done, failed}
progress	object	同上 + terminal_ratio（终态占比）
finished	boolean	是否全部到达终态（done/failed）
items[]	array	逐项 task_id / doc_id / document_name / source_type / status / parse_status / error_log

状态取自任务行（执行侧落库为准）；需要引擎实时进度时用单任务轮询 /documents/tasks/{task_id}。

请求示例

curl -s "http://<host>/openapi/v1/documents/batches/9f2c…" -H "Authorization: Bearer <access_token>"

响应示例

{"batch_id": "9f2c…", "total": 2,
 "status_counts": {"queued": 0, "processing": 0, "done": 2, "failed": 0},
 "progress": {"done": 2, "failed": 0, "processing": 0, "queued": 0, "terminal_ratio": 1.0},
 "finished": true,
 "items": [{"task_id": "2f1e…", "doc_id": "5f3a…", "document_name": "a.pdf", "source_type": "file",
            "status": "done", "parse_status": "ready", "error_log": ""}]}

常见错误与排错

状态码	含义	处理
404	批次不存在 / 不属于本应用	核对 batch_id 与所用密钥所属应用

文档列表

用途：列出本应用经开放平台写入的文档（含软删墓碑行与失败任务）。doc_id 用于后续下载原文 / 软删 / 恢复寻址。

前置条件与鉴权：需 read scope（只读操作；开发者自建密钥默认即含 read）；只返回本应用写入的文档，他人文档不可见。

请求参数

字段	位置	必填	说明
source	query	否	固定 openapi（仅本应用写入）
kb_id	query	否	按知识库过滤
page_size	query	否	每页条数（默认 100，上限 200）
cursor	query	否	keyset 游标（取上次响应 next_cursor）

响应字段

字段	类型	说明
items[]	array	每项含 doc_id / task_id / document_name / source_type / kb_id / status(active|deleted) / parse_status(processing|ready|failed) / created_at / updated_at
next_cursor	string|null	下一页游标（无更多为 null）
total	integer	匹配总数（含墓碑行）

请求示例

示例中的 YOUR_ACCESS_TOKEN 需替换为 POST /openapi/v1/auth/token 换取的 access_token（Bearer 后是访问令牌，不是 app_key）。

curl -s "http://<host>/openapi/v1/documents?source=openapi" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

// JavaScript (fetch)
const r = await fetch("https://<host>/openapi/v1/documents?source=openapi", { headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" } });
const { items } = await r.json();

# Python (requests)
import requests
r = requests.get("https://<host>/openapi/v1/documents", params={"source": "openapi"}, headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"})
items = r.json()["items"]

响应示例

{
  "items": [{"doc_id": "5f3a…", "task_id": "2f1e…", "document_name": "guide.pdf", "source_type": "file",
             "kb_id": "a1b2…", "status": "active", "parse_status": "ready",
             "created_at": "2026-10-10T08:00:00", "updated_at": "2026-10-10T08:00:12"}],
  "next_cursor": null,
  "total": 1
}

常见错误与排错

状态码	含义	处理
401	凭证无效	续期后重试
403	密钥 scope 不含 read	改用主密钥，或在控制台把该密钥权限放开（含 read）
429	配额用尽 / 限流	按 Retry-After 退避

下载文档原文

用途：按 doc_id 下载本应用写入的文档原文。检索结果里的 url（文件类文档）即指向本端点，doc_id 与检索结果 / 文档列表下发的同一个值。

前置条件与鉴权：需 read scope；仅限本应用写入的文档（他人文档 404 防枚举）；不消耗调用配额，仍受应用级限流。

来源差异：上传的文件 → 返回文件流（Content-Disposition: attachment）；URL 摄入的文档没有平台存储文件 → 404，请改用检索结果里的 source_url。软删（墓碑）文档 → 404，恢复后可下载。

请求参数

路径参数（doc_id 取自检索结果 doc_id 或文档列表 items[].doc_id）。

响应字段

项	类型	说明
响应体	binary	文件字节流；响应头 Content-Disposition: attachment; filename*=UTF-8''<文件名>

请求示例

curl -s -OJ "http://<host>/openapi/v1/documents/5f3a…/download" -H "Authorization: Bearer <access_token>"

# Python (requests)
import requests
r = requests.get("https://<host>/openapi/v1/documents/5f3a…/download", headers={"Authorization": "Bearer <access_token>"})
open("guide.pdf", "wb").write(r.content)

响应示例

二进制文件流（无 JSON 响应体）。失败时为标准错误体：

{"detail": "文档已删除，请先恢复后再下载"}

常见错误与排错

状态码	含义	处理
401	凭证无效	续期后重试
403	密钥 scope 不含 read / 应用停用 / IP 不在白名单	按 detail 定位
404	文档不存在 / 已软删 / URL 摄入无平台文件 / 文件记录缺失	软删先恢复；URL 摄入改用 source_url；确认 doc_id 来自本应用
429	调用频率超限	按 Retry-After 退避

软删文档

用途：软删除本应用写入的文档——打 deleted_at 墓碑并删引擎向量（不删物理文件，可恢复）。删除豁免配额（纠错操作，配额用尽仍可删）。幂等：已删文档再次删除仍返回 200。

前置条件与鉴权：需 delete scope + write_enabled；仅限本应用写入的文档（他人文档 404 防枚举）。

请求参数

路径参数（doc_id 取自文档列表接口下发的 doc_id）。

响应字段

字段	类型	说明
doc_id	string	文档 ID
status	string	恒为 deleted

请求示例

curl -s -X DELETE "http://<host>/openapi/v1/documents/5f3a…" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

响应示例

{"doc_id": "5f3a…", "status": "deleted"}

常见错误与排错

状态码	含义	处理
403	写入能力未开通 / 密钥 scope 不含 delete	联系平台运营
404	文档不存在（含非本应用文档，防枚举）	核对 doc_id 是否由本应用写入

恢复文档

用途：恢复软删的文档（重新入库）。对外 doc_id 不变，但引擎身份（external_doc_id）会变化。恢复按写入计 1 次配额。幂等：未删文档 restore 仍返回 200。

前置条件与鉴权：需 delete scope + write_enabled；仅限本应用写入的文档。

请求参数

路径参数（doc_id）。

响应字段

字段	类型	说明
doc_id	string	文档 ID
task_id	string	恢复任务 ID（轮询用）
status	string	queued（异步重新入库）

请求示例

curl -s -X POST "http://<host>/openapi/v1/documents/5f3a…/restore" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

响应示例

{"doc_id": "5f3a…", "task_id": "8b2d…", "status": "queued"}

常见错误与排错

状态码	含义	处理
400	无知识原子无法恢复 / url 来源指向内网（SSRF 拒绝）	重新上传
409	文档仍在处理中	稍后重试

商务文档生成

用途：在应用授权范围内检索语料，异步生成 8 类商务文档（产品介绍 / 解决方案 / 技术培训 / 内部办公 / 推广方案 / 政府公文 / 商业计划书 / 演示文档），或先出 doc_outline 大纲、确认后再按大纲成文（两阶段）。提交后返回 task_id，用「查询生成任务」接口取结果。

前置条件与鉴权：Authorization: Bearer <access_token>；应用已由平台运营在应用治理里把 /openapi/v1/generate 加入接口白名单（默认未授权，fail-closed）；应用授权范围内有可用知识库。生成配额与检索 / 写入共用同一配额桶（每次提交预留 1 次额度）。

请求参数

JSON 请求体（Content-Type: application/json）。

字段	类型	必填	说明
kind	string	是	产物类型：8 类商务文档之一，或 doc_outline（两阶段大纲）
topic	string	否	生成主题 / 检索 query（≤ 2000 字符；缺省取知识库名）
kb_ids	array<string>	否	本次限定知识库（≤20；须在授权范围内，越权 403；不传 = 应用级范围）
top_k	integer	否	语义检索取回条数（8~60，越界自动收敛）
outline	object	否	已确认的大纲（两阶段第二阶段回传；含 sections 时按章节分段生成长文）
target_kind	string	否	kind=doc_outline 时指定目标文档类型（须为 8 类之一）

响应字段

字段	类型	说明
task_id	string	生成任务 ID（用于轮询 GET /openapi/v1/generate/tasks/{task_id}）
status	string	恒为 queued

请求示例

curl -s -X POST http://<host>/openapi/v1/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"kind":"product_intro","topic":"我们的知识库产品"}'

# 两阶段第一阶段：先出大纲
# -d '{"kind":"doc_outline","target_kind":"solution","topic":"制造业知识管理"}'

响应示例

{"task_id": "2f1e4a…", "status": "queued"}

常见错误与排错

状态码	含义	处理
401	凭证无效 / 令牌过期	续期后重试一次
403 该接口未授权	本路径默认未授权（fail-closed）	请平台运营在应用治理里把本路径加入白名单
403 其它	知识库不在授权范围 / 未授权任何可用知识库 / 密钥缺 generate scope	按 detail 逐项核对并联系平台
422	kind 非法 / topic 超长 / kb_ids 非 UUID 或超 20 个	按 8 类枚举值传 kind；修正其它字段
429	频率超限 / 配额用尽	退避重试；配额类等周期重置
451	topic 命中内容安全敏感词（不消耗配额）	改写 topic 后重试
任务 failed	生成 LLM 通道未配置（error_log 显示「产物生成 LLM 未配置」）	联系平台检查生成通道配置

诚实边界：单次生成无引擎侧真实进度可采，progress 为粗粒度（done=100，其余为 0）；正文不带 [n] 引用标记，溯源走结果里的 result.grounding.provenance 文档级来源清单。

查询生成任务

用途：轮询生成任务状态并在 done 时取回结果（result）。与「查询写入任务」不同，它在终态带回生成内容。本端点不计量。

前置条件与鉴权：Authorization: Bearer <access_token>；task_id 必须由本应用创建（他人任务返回 404，防枚举）。

请求参数

路径参数（task_id 取自请求地址）。

字段	位置	必填	说明
task_id	path	是	POST /openapi/v1/generate 返回的任务 ID

响应字段

字段	类型	说明
task_id	string	任务 ID
status	string	queued / processing / done / failed
progress	integer	进度 0~100（done=100；其余为 0，无细粒度进度）
kind	string	产物类型（回显请求的 kind）
result	object	仅 done 时返回：生成结果（已按应用规则脱敏），含 data 与 grounding.provenance 文档级来源清单
error_log	string	失败原因；成功为空串
created_at / updated_at	string	创建 / 最近更新时间

请求示例

curl -s http://<host>/openapi/v1/generate/tasks/2f1e4a… \
  -H "Authorization: Bearer $TOKEN"

响应示例

{
  "task_id": "2f1e4a…",
  "status": "done",
  "progress": 100,
  "kind": "product_intro",
  "result": {
    "data": { "title": "…", "sections": [ … ] },
    "grounding": { "provenance": [ {"document_name": "产品白皮书.pdf"} ] }
  },
  "error_log": "",
  "created_at": "2026-10-12T08:00:00",
  "updated_at": "2026-10-12T08:00:30"
}

常见错误与排错

状态码 / 现象	含义	处理
401	凭证无效 / 令牌过期	续期后重试
404	任务不存在（含他人任务，防枚举）	核对 task_id 是否由本应用创建
422	task_id 格式错误	使用创建任务时返回的原值
status=failed	生成失败（如 LLM 未配置）	看 error_log；LLM 未配置需联系平台
done 但 result 为空	尚未写入结果或生成内容为空	稍后再轮询一次；持续为空请携带 X-Request-Id 报障