Skip to main content
POST
创建研究任务

Authorizations

Authorization
string
header
required

每个请求都通过 API Key 认证:Authorization: Bearer {API_KEY}。应用接口使用应用 API Key,知识库接口使用知识库 API Key(快速开始)。

API Key 应保存在服务端,切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401(unauthorized)。

Headers

Idempotency-Key
string

可选的幂等键,用于安全地重试创建。使用 8~255 个可打印 ASCII 字符,首尾不得有空白;格式不正确的键返回 400。

用同一个 API 密钥重复发送相同的键和请求体,会以 202 返回原任务及其当前状态,不会再创建新任务。键在工作空间内唯一:以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作复用该键,会返回 409。

Required string length: 8 - 255

Path Parameters

knowledge_base_id
string<uuid>
required

知识库 ID:即知识库 API 访问 对话框中所示服务 API 端点的最后一段(…/knowledge-fs/spaces/<knowledge base ID>),也是地址栏中 /datasets/new/ 之后的那一段。

Body

application/json

标记为 nullable 的可选字段,传 null 等同于省略。

规范化后的请求不得超过 65,536 个 UTF-8 字节。参见 请求大小限制。

需提供非空白的 query。

query
string
required

要查询的问题。不能为空白,且不超过 16,384 个 UTF-8 字节。

Maximum string length: 16000
Pattern: \S
budgetUsd
number | null

花费上限(USD)。在任务运行期间生效,创建时不检查。即使 规划研究任务 的估算超出该上限,任务也会被受理。每次调用模型之前,任务会用这次调用的最坏情况成本对照预算检查;如果这次调用可能超出预算,任务会被取消,不再发起调用。

单次调用的实际成本仍可能高于其最坏情况估算,因此 cost.totalUsd 最终可能超过 budgetUsd。如果任务在 generating 阶段之前因预算被取消,就不会有回答。最坏情况成本通常远高于规划结果中的估算,因此需要得到回答时,把上限设得远高于 estimates.costUsd.max;topK 较大时还要更高。

因预算停止的任务,stage 为 canceled。

Required range: x >= 0
limits
object | null

仅在创建时对照规划结果中的估算检查一次。估算超出任一限制的任务会被拒绝并返回 422。省略 limits 则跳过这些检查。如需在任务运行期间限制花费,使用 budgetUsd。

估算值等于限制值时视为通过。参照 规划研究任务 返回的 estimates 设定这些值。

metadata
object

自由格式的对象,随任务保存,并以 metadata 返回。以 __knowledgeFs 开头的键为保留键,会被丢弃。

可在其中放入 client_request_id 等唯一值,创建响应丢失时,可据此识别并找到该任务。如需让重试直接返回原任务、不再创建新任务,发送 Idempotency-Key。

mode
enum<string> | null

检索深度:fast、deep 或 research(参见 检索深度)。省略时使用知识库的默认深度,即 获取知识库设置 中的 retrieval.default_mode。

Available options:
fast,
deep,
research,
null
topK
integer | null

检索结果合并并重排序后最多保留的分段数。显式传入的值必须在 1~50 之间。省略时使用知识库已发布的 Top K 设置,该设置最高可达 100。值越大,模型获得的上下文越多,干扰也越多;值越小,结果越集中,但可能漏掉相关分段。

Required range: 1 <= x <= 50

Response

任务已受理。stage 为 queued,mode 为实际采用的深度,cost.totalUsd 为 0。用相同的 Idempotency-Key 和请求体重复请求,会返回原任务及其当前状态。

budget_usd
number | null

请求中设置的花费上限,单位为 USD。未设置时为 null。

completed_at
number | null

任务到达 completed、failed 或 canceled 的时间,Unix 纪元毫秒。任务运行期间为 null。

cost
object

目前已记录的花费。

created_at
number

任务创建时间,Unix 纪元毫秒。

error
string | null

错误码,与 failure.code 的值相同。仅当 stage 为 failed 时有值,其他情况下为 null,已取消的任务也是如此。

研究任务失败时,failure.code 为以下之一:RESEARCH_TASK_CAPABILITY_REVOKED、RESEARCH_TASK_DISPATCH_DEAD、RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED、RESEARCH_TASK_FAILED、RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID 或 RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID。

failure
object | null

错误详情。仅当 stage 为 failed 时有值,其他情况下为 null。此处没有值的成员为 null。traceId 为任务 ID。

当 action 为 retry 时,使用 创建研究任务 创建新任务。

id
string

研究任务 ID。在研究任务的各项操作中用作 research_task_id。

knowledge_space_id
string

知识库的内部 ID,并非路径中的知识库 ID。

limits
object | null

请求中的限制项,键名为 snake_case。请求未携带 limits 时为 null,未发送的成员为 null。再次发送给 创建研究任务 前,需将键名转换回 camelCase。

metadata
object

创建时发送的 metadata 对象,不含以 __knowledgeFs 开头的键。

mode
string | null

任务的检索深度:fast、deep 或 research。

query
string

存储的研究问题。

query_images
object[]

原始查询中使用的图片。纯文本查询不返回此字段。

stage
string

任务在生命周期中所处的阶段。任务每次前进一个阶段:

  • queued:已受理,等待工作进程处理。
  • planning:正在确定检索计划。
  • retrieving:正在检索知识库,可能会写入检索检查点。
  • analyzing:正在阅读和权衡检索到的分段。
  • generating:正在撰写回答,最终结果在此阶段写入。
  • completed:已完成。可用 获取研究任务结果列表 读取结果。
  • failed:因错误停止。详见 error 和 failure。
  • canceled:因 取消研究任务 或超出预算而停止。
  • paused:任务已暂停。可向部署的运维人员确认失败详情(如有),或取消该任务。

completed、failed 和 canceled 为终态。

top_k
integer | null

检索结果合并并重排序后最多保留的分段数:取请求中的 topK,未传时取知识库的 Top K。

updated_at
number

任务记录最后更新的时间(Unix 纪元毫秒),包括内部检查点和重试调度产生的更新。