任务内知识检索与引用¶
在正在执行的智能体任务中检索授权知识、读取原文证据并提交引用选择。知识库管理、任务检索与回答引用是不同操作。
认证与请求范围¶
这些接口要求当前任务执行环境提供的产品凭据、工作区和短期任务授权。沿用运行环境提供的 Base URL;以下路径相对于产品前缀。请求使用 JSON,并携带:
X-API-Key: <runtime-product-credential>
X-Workspace-ID: <runtime-workspace-id>
X-MOI-Runtime-Authorization: Bearer <runtime-task-grant>
Content-Type: application/json
资源范围由当前任务绑定、授权和运行状态决定。请求体不提供可用于切换身份的任务或角色参数。每次新操作使用唯一 request_id;重放同一请求时保留原标识及相同输入。
检索文本证据¶
POST /semantic-models/runtime/search:
{"request_id":"search-retention-1","keywords":["retention policy"],"max_hits":3,"before":2,"after":1}
普通检索可以使用 file_ids、volume_id 限定来源,或用 fulltext_only 选择全文检索。无命中不表示整个知识库不存在相关事实。
响应公共对象包含 call_id、output、artifacts、metadata 和 failed。HTTP 成功后仍需检查 failed 及操作结果。文本证据通常在 artifacts[].data.chunks,产物标识在同一对象的 artifact_id。保留段落的 chunk_id、file_id 和 semantic_model_id;不要用名称重建身份。
读取所选证据¶
POST /semantic-models/runtime/read-evidence,将占位值替换为同一次检索实际返回的标识:
{"request_id":"read-retention-1","artifact_id":"<retrieval-artifact-id>","chunk_id":"<chunk-id>","file_id":"<file-id>","semantic_model_id":7,"cursor":0,"limit_chars":4000}
semantic_model_id 使用实际返回的整数。读取返回 output.content、has_more 和 next_cursor。有后续页时,以返回游标读取同一段证据;每页使用独立请求标识。分页产物也可使用 artifact_id 与 part_index,此时不混入分段、文件、模型或字符分页字段。
已在本地读取完整原始段落的调用方可以提交 local_content_sha256;服务端按当前任务保存的证据核验摘要。该方式不与分页参数组合。local_reads 可原子登记多个本地完整读取,不与单段读取字段组合。
确认引用选择¶
POST /semantic-models/runtime/cite:
{"request_id":"cite-retention-1","sources":[{"type":"rag_chunk","artifact_id":"<retrieval-artifact-id>","chunk_id":"<chunk-id>","file_id":"<file-id>","semantic_model_id":7}],"complete_read_requirements":true}
仅提交支持回答且实际读取的来源。检查 output.accepted;返回未读要求时先补读,再提交选择。新选择应包含回答采用的全部来源。没有依据时显式提交 sources: [],回答中说明无法确认的事实。
定位 Markdown 原文¶
从当前证据取得 markdown_file_id 后,可调用以下接口。该标识不能由原始文件 ID 推算。
操作 |
POST 路径 |
请求要点 |
|---|---|---|
在解析原文内查找文本 |
|
|
分页读取解析原文 |
|
|
查找来源文件 |
|
|
检索图片 |
|
|
查询可用表结构 |
|
|
查询结构化知识 |
|
|
按来源顺序列出启用的文本段落时,仍调用 search,请求使用 source_page 的模型 ID、文件 ID、游标和页大小。该模式不与普通检索字段混合;以返回的 output.source_page.has_more 判断是否继续,为假时结束。它列出来源段落,不进行语义排序。
区分读取模式和游标¶
证据读取的单段模式使用整数游标,单位为 Unicode 字符位置;不指定分段而读取证据列表时,游标是服务端返回的 {item_index, content_offset} 对象。列表响应使用 complete=true 表示读取完成,两种游标不能互换。limit_chars 省略或为 0 时单段使用 2000,显式有效上限为 8000。
Markdown 的 read-document 返回 next_cursor,为 0 时结束;它没有证据窗口的 has_more 字段。保留返回的原游标,不按字节长度自行计算。Markdown 的读取窗口省略或为非正数时使用 8000,最大 20000。
Markdown 读取使用当前任务范围内启用的分段。解析原文由当前有效分段构成,不保证与旧的完整 Markdown 文件逐字一致;已删除或停用的分段不作为当前可读证据。