# 任务内知识检索与引用

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

## 认证与请求范围

这些接口要求当前任务执行环境提供的产品凭据、工作区和短期任务授权。沿用运行环境提供的 Base URL；以下路径相对于产品前缀。请求使用 JSON，并携带：

```http
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`：

```json
{"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`，将占位值替换为同一次检索实际返回的标识：

```json
{"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`：

```json
{"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: []`，回答中说明无法确认的事实。

(runtime-knowledge-markdown)=
## 定位 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 [检索知识与读取证据](../../../sdk/ai-studio/智能体/检索知识并读取引用证据.md#sdk-ai-studio-runtime-knowledge-read) 及 CLI [任务内知识检索](../../../cli/tasks/runtime-knowledge.md)。

## 区分读取模式和游标

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