任务内知识检索¶
在智能体任务的受控执行环境中使用 semantic-model 运行态子命令检索已绑定的知识来源、分页读取完整证据、在解析 Markdown 原文中定位段落,并提交回答所依据的引用集合。对应的服务端 HTTP 契约与权限说明见 任务内知识检索与引用。
使用任务注入连接包¶
智能体执行沙箱启动子进程时,会成套注入 MOI_RUNTIME_AUTHORIZATION(格式为 Bearer <token>)、MOI_ENDPOINT、MOI_API_KEY 与 MOI_WORKSPACE_ID。moi-cli 检测到 MOI_RUNTIME_AUTHORIZATION 后自动绑定该短期任务授权并关闭终端交互提示:
直接调用下文
moi-cli semantic-model ...命令,保留沙箱注入的整套环境变量。运行态模式下传入与注入环境不一致的
-endpoint或-api-key会触发CLI_RUNTIME_CONNECTION_CONFLICT并拒绝发送请求,防止短期任务凭证外泄。用于日常管理知识库的个人访问令牌(PAT)不包含任务执行上下文,无法单独替代短期任务授权。
检索、分页读取证据与提交引用¶
任务内知识问答遵循“检索候选段落 -> 分页读取完整证据 -> 提交引用并核验接受状态”三步闭环。
1. 检索候选段落并保存输出文件¶
指定查询关键词与一个尚不存在的本地输出文件路径:
export KNOWLEDGE_QUERY="retention policy"
moi-cli semantic-model search --keywords "$KNOWLEDGE_QUERY" --output ./search.json
命令标准输出返回包含 path(完整 JSON 结果文件)与 reading_path(供按序阅读的格式化文本文件)的摘要。打开 reading_path 浏览各 PASSAGE 编号与上下文预览,挑选支撑当前问题答案的候选段落索引。
2. 按段落索引分页读取完整证据¶
将 --from 指向检索结果文件,--index 设为选中的段落编号(以下以第 0 段为例):
moi-cli semantic-model read-evidence --from ./search.json --index 0 --output ./evidence-0.json
moi-cli 自动从 --from 文件中提取产物、文件与分段标识。检查返回结果中的 output.content 与 output.has_more;当 output.has_more 为 true 时,将 --from 指向刚刚生成的证据文件并另存新文件名继续读取后续页,直至 has_more 为 false:
moi-cli semantic-model read-evidence --from ./evidence-0.json --index 0 --output ./evidence-1.json
当 search.json 已包含未经截断的完整段落正文且已完整阅读时,也可附加 --local-read 登记该次本地完整读取。
3. 提交引用选择并核对 accepted 状态¶
证据读取完毕后,在生成最终回答前提交实际采用的证据索引:
# 提交单个检索结果文件中采用的第 0 段(多文件可重复传入 --from <file> --indices <list>)
moi-cli semantic-model cite --from ./search.json --indices 0
# 检索与读取后确认无任何证据能够支撑待回答事实时,显式提交空引用集合
moi-cli semantic-model cite --json '{"sources":[]}'
检查返回结果(及 path 指向的完整 JSON)中的 output.accepted(或顶层摘要 accepted):
若为
true,表明引用已通过服务端读取完整性校验,可据此组织回答。若为
false,按返回错误或未满足的读取要求补齐read-evidence后重新提交cite。
发现来源文件、定位解析原文与查询表¶
除通用关键词检索外,运行态还支持按文件查找、解析 Markdown 原文搜索及授权结构化表查询:
子命令与核心参数 |
作用说明 |
|---|---|
|
按名称关键词查找已绑定来源清单;后续通过 |
|
按唯一匹配的名称顺序读取单个来源内容并检查覆盖范围。 |
|
按页列出来源段落,使用返回游标继续读取同一来源的后续页。 |
|
利用当前证据携带的解析 Markdown 定位信息,在解析原文内搜索关键词。 |
|
分页读取解析后的 Markdown 原文内容与后续游标。 |
|
检索知识库中的图片证据及其页面定位信息。 |
|
先查看当前任务授权访问的结构化表结构,再提交查询请求并核对返回行数、截断标记与来源信息。 |
在解析 Markdown 原文中定位关键词示例:
moi-cli semantic-model search-document \
--from ./search.json \
--index 0 \
--query "$KNOWLEDGE_QUERY" \
--output ./matches.json
限制和注意事项¶
所有运行态子命令的
--output参数均要求目标文件路径尚不存在,不会覆盖已有文件;每次翻页或追加检索请指定新的输出文件名。search-document与read-document依赖当前证据条目包含解析后的 Markdown 文档定位元数据;若该来源不含解析原文定位信息,请继续使用read-evidence或list-passages读取段落。本地输出文件生成并不等同于引用已被服务端接受;脚本或智能体执行器必须同时检查命令退出码、业务错误码及
cite返回的accepted字段。