Skip to main content
POST

Authorizations

​
Authorization
string
header
required

创建查询令牌 返回的查询令牌，以 Authorization: Bearer {token} 形式发送。须在返回的 expires_at 之前使用，该时间最晚为签发后 60 秒。该令牌只能用于对该知识库调用「运行查询」。

在同一请求中发送 X-Trace-ID，值为「创建查询令牌」返回的 trace_id。

Headers

​
X-Trace-ID
string
required

创建查询令牌 响应中的 trace_id，与令牌中的 trace_id 声明值相同。与令牌不一致的值会被拒绝并返回 403。参见 查询知识库。

Body

application/json

原样发送 创建查询令牌 返回的 request 对象。包含未知字段时返回 400。

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

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

需提供非空白的 query。

​
knowledgeSpaceId
string<uuid>
required

知识库的内部 ID，从 创建查询令牌 返回的 request 对象复制。必须与令牌一致，不一致会被拒绝并返回 403。

Minimum string length: 1
​
query
string
required

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

Maximum string length: 16000
Pattern: \S
​
activeDocumentIds
string<uuid>[]

从返回的 request 对象复制。这些 ID 不会对检索到的内容进行筛选或排序。

Maximum array length: 100
​
activeEntityIds
string[]

从返回的 request 对象复制。这些 ID 不会对检索到的内容进行筛选或排序。

Maximum array length: 100
Required string length: 1 - 200
​
mode
enum<string> | null

检索深度，从 创建查询令牌 返回的 request 对象复制。可传 null，表示使用知识库的默认深度。

Available options:
fast,
deep,
research,
null
​
sessionId
string<uuid> | null

会话 ID，从 创建查询令牌 返回的 request 对象复制。

Response

流已建立。无论请求发送的 Accept 是什么，后续事件都以 text/event-stream 返回。流建立之前，按 HTTP 错误处理失败；流建立之后，即使 HTTP 状态码为 200，收到 answer.error 事件也应按失败处理。

每一帧包含一行 event:（事件名）和一行 data:（一个 JSON 对象）。按 event: 行分发事件，JSON 中没有 event 字段。

客户端的读取超时要足以覆盖你所用的最慢检索模式。API 本身没有读取超时，也不发送保活事件。不能因客户端超时而中断的工作，改用 创建研究任务。

流式调用流程详见 查询知识库。

事件

  • answer.delta：回答的一个片段。
    • delta：要追加的文本。
    • traceId：查询记录 ID。
  • answer.done：回答已完成，查询记录已保存。

    • finishReason：找到分段时为 retrieval-evidence，没有任何匹配时为 no-retrieval-evidence。

    • metadata：键不固定的对象。在 fast、deep、research 深度下均包含 mode 和 evidenceBundle，结果为 retrieval-evidence 时包含 citations，还可能包含本次运行产生的其他键。evidenceBundle.items 包含检索到的分段及其文本和分数。

      如需事后查看这些分段，调用 获取查询分段列表。它会分页返回，并标出所属文档此后已被删除的分段。

    • traceId：查询记录 ID。

  • answer.error：流建立后查询失败。
    • code：失败类型，取值之一：
      • RETRIEVAL_EXECUTION_LEASE_LOST：知识库进入删除流程，或本次运行已过期。重新运行查询。
      • KNOWLEDGE_FS_UNAVAILABLE：生成回答或保存查询记录时发生的其他任何失败。
    • error：错误消息。
    • failure：错误详情，包括 category、code、message、retryPolicy、stage、traceId，以及可选的 action。
      • stage：始终为 query_generation。
    • traceId：查询记录 ID。

citations

每个支撑回答的检索分段对应一条：

  • nodeId：分段 ID。
  • label：node:<nodeId>。
  • documentAssetId：分段所属的文档文件。
  • sectionPath：大纲路径。
  • pageNumber：页码，从 1 开始，源文件提供页码信息时返回，否则省略。
  • projectionIds：参与本次匹配的检索索引 ID。识别源文件请使用 documentAssetId。
  • sources：找到该分段的检索方式：dense、fts、pageindex 或 visual。

图片引用可能包含 multimodalCandidate.assetRef.analysisUnavailable.reason。出现该字段表示图片分析因资源限制或图片处理失败而被跳过，相关文本仍可能计入结果。

evidenceBundle.items[].citations[] 还可能带有 startOffset 和 endOffset。它们是解析后文档文本中的 UTF-8 字节偏移量，从 0 开始计数，包含起点、不包含终点。展示引用时使用返回的分段文本，不要按这些偏移量截取原始文件。

不同结果下的结束顺序

  • 成功：零个或多个 answer.delta，然后是一个 answer.done，随后流关闭。
  • 失败：以 answer.error 代替 answer.done，随后流关闭。在此之前可能已发送部分片段，HTTP 状态码仍为 200。将其视为最终结果，如需重试，重新发起查询。
  • 客户端断开连接：本次运行被取消，流结束。

回答内容：在 fast 和 deep 深度下，由一个 answer.delta 携带检索分段的汇总（Retrieval evidence answer: 后接带编号的章节路径及其文本）。在 research 深度下，综合生成的回答以一个或多个片段流式返回。没有任何匹配时，唯一的片段是 I could not find evidence for that query in the indexed retrieval projections.，且 finishReason 为 no-retrieval-evidence。

在所有深度下，回答最长 2,000 个字符。回答达到这个长度，并不能说明它是否被截断。

一次成功的运行：

流建立后失败：