任务内知识检索与引用

在正在执行的智能体任务中检索授权知识、读取原文证据并提交引用选择。知识库管理、任务检索与回答引用是不同操作。

认证与请求范围

这些接口要求当前任务执行环境提供的产品凭据、工作区和短期任务授权。沿用运行环境提供的 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 路径

请求要点

在解析原文内查找文本

/semantic-models/runtime/search-document

request_id、markdown_file_id、query,可选 max_matches、context_chars。

分页读取解析原文

/semantic-models/runtime/read-document

request_id、markdown_file_id、cursor、limit_chars;继续使用返回游标。

查找来源文件

/semantic-models/runtime/find-files

request_id、query、top_k;清单定位来源,不等于检索证据。

检索图片

/semantic-models/runtime/search-images

request_id;按任务使用 query_text 或 query_visual_file_id,以及匹配的排序配置。

查询可用表结构

/semantic-models/runtime/describe-tables

request_id、table_names 或 keywords,可指定样本和 DDL 长度。

查询结构化知识

/semantic-models/runtime/query

request_id、sql、max_rows,可附 semantic_claims;检查结果截断和来源。

按来源顺序列出启用的文本段落时,仍调用 search,请求使用 source_page 的模型 ID、文件 ID、游标和页大小。该模式不与普通检索字段混合;以返回的 output.source_page.has_more 判断是否继续,为假时结束。它列出来源段落,不进行语义排序。

完整调用见 SDK 检索知识与读取证据 及 CLI 任务内知识检索。

区分读取模式和游标

证据读取的单段模式使用整数游标,单位为 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 文件逐字一致;已删除或停用的分段不作为当前可读证据。

最后更新于