# 检索

在 Key 可读的内容上执行搜索、构建上下文包和生成带引用的回答。

API 参考。Base URL：`https://api.mirabase.dev`

## 带引用回答

`POST /v2/retrieval/answer`

用 `context` 会选的证据回答问题，以 `[cN]` 引用。需要 `knowledge:read` 和 `knowledge:answer`。模型会得知每段内容的写入时间，以及（已知时）内容对应的日期（`occurred_at`，没有时用 `stated_date`）；问题询问当前状态（“now”、“currently”、“现在”）时，同一主题的段落按从新到旧排列。带 `stream: true` 时，200 响应为 `text/event-stream`：本操作的 `x-mirabase-sse-events` 列出每种事件的 `data` 对应的模型，请求的 `stream` 字段说明事件的顺序。生成的客户端对不带 `stream` 的调用仍使用 JSON 类型。每个主体同时最多运行 `answer_concurrency` 个回答（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)，默认 3 个），按该主体的全部 Key 合计；超出的调用最多等 10 秒，然后返回 429 `rate_limited`，`limit` 为 `concurrency`。502 `model_failed` 和 503 `answer_unavailable` 可以稍后重试。503 `answer_not_configured` 表示这个部署没有回答模型，所以重试没有用：请构建上下文，再运行你自己的模型。

**需要的能力** `knowledge:read` `knowledge:answer`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md)

### 请求体

`application/json` `DevAnswerRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `question` | `string` | 必填 | 要回答的问题，1 到 4000 个字符。 长度 1 到 4000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则使用调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `purpose` | `DevContextPurpose` | 可选 | 回答用来做什么，与 `context` 的同一个参数：`task`、`coding`、`research` 或 `audit`。 |
| `weights` | `DevContextWeights` | 可选 | 与 `context` 相同。不传时，回答不使用 `changes` 和 `skills` 两个来源：无论问题是什么，它们列出的都是最近的文件和技能。这时 `route.rules_fired` 会列出 `source:off:changes:answer_default` 和 `source:off:skills:answer_default`。要包含它们，请传 `weights`。 |
| `tier` | `DevContextTier` | 可选 | 检索证据时投入的工作量，与 `context` 上的含义相同：`fast`、`standard` 或 `deep`。 默认 "standard" |
| `budget_tokens` | `integer` | 可选 | 模型读取的证据的预算。 500 到 16000，默认 4000 |
| `history` | `DevAnswerTurn[]` | 可选 | 之前的对话轮次，最早的在前。追问会和它所追问的问题一起搜索。各轮合计超过 12,000 个字符时，最早的几轮会被略去。 最多 10 项 |
| `output_language` | `string` | 可选 | BCP 47 语言标签，如 `en` 或 `zh-CN`。只影响 `answer` 的语言。 最长 35 |
| `filter` | `DevRetrievalFilter` | 可选 | 缩小答案可引用的证据范围，和 `context` 相同。 |
| `include` | `evidence[]` | 可选 | `["evidence"]` 在响应里增加 `evidence`：模型读过的每一条证据，不带正文。用它查看回答除了引用的段落之外还依据了什么。 1 项 |
| `stream` | `boolean` | 可选 | 为 true 时以 `text/event-stream` 流式返回回答，而不是单个 JSON 响应体。每个事件有一个 `id`（按顺序为 1、2、3……）、一个 `event` 名称和一行 JSON 格式的 `data`： - `start`（`DevAnswerStreamStart`）：检索完成后、任何文本之前发送一次，带 `request_id`、`pack_id` 和交给模型的证据数量。在检索阶段失败的流没有 `start`。 - `delta`（`DevAnswerStreamDelta`）：回答的下一段文本，按顺序拼接。 - `replace`（`DevAnswerStreamReplace`）：至多发送一次，紧接在 `final` 之前，表示已流式返回的文本不是最终回答（服务修正了没有引用的草稿，或回答改为放弃）。丢弃已流式返回的文本，显示 `final.answer`。 - `final`（`DevAnswer`）：与本操作不带 `stream` 时返回的 JSON 相同，以它为准。 - `error`（`DevErrorResponse`）：与 HTTP 错误相同的错误信封，其中的 `status` 是这个请求本应得到的状态码。丢弃已流式返回的文本：没有生成回答。`retryable` 说明重新提问是否有用。 `final` 和 `error` 只发送其中一个，它是最后一个事件，之后流关闭。没有收到这两者就结束的流是被中断了：按请求失败处理，重新提问。以 `:` 开头的行是注释，在流打开时以及每空闲 15 秒时发送，用于保持连接，不带任何内容。流不能续传：`id` 只表示顺序，`Last-Event-ID` 会被忽略。忽略未知的事件名，后续可能新增事件。关闭连接会取消回答。认证、校验和等待空闲名额都在流打开之前完成，因此这些错误是普通的 HTTP 响应。 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

### 响应

- `200` `application/json` `DevAnswer`, `text/event-stream` `string`

### 流式事件

响应为 `text/event-stream` 时发送的事件，以及每个事件中 `data` 的结构：

- `start` `DevAnswerStreamStart`
- `delta` `DevAnswerStreamDelta`
- `replace` `DevAnswerStreamReplace`
- `final` `DevAnswer`
- `error` `DevErrorResponse`

### 错误状态

`400` `401` `403` `404` `409` `422` `429` `500` `502` `503` `504` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/retrieval/answer" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"When does version 2.4 launch?","space_ids":["default"]}'
```

### 响应结构示例

```json
{
  "status": "answered",
  "answer": "Version 2.4 launches on Friday 21 November [c1].",
  "citations": [
    {
      "citation_id": "c1",
      "entry_id": "ent_01JD2M8Z4K",
      "version_id": "ver_01JD2M8Z4M",
      "space_id": "col_01JD2M7QK3",
      "path": "/notes/plan.md",
      "modified_at": "2026-11-17T08:02:00Z",
      "title": "plan.md",
      "source": "knowledge",
      "text": "The launch of version 2.4 moved to Friday 21 November."
    }
  ],
  "evidence_count": 1,
  "pack_id": "trc_01JD2M7R",
  "partial": false,
  "route": {
    "purpose": "task",
    "tier": "standard",
    "rules_fired": [],
    "sources": [
      {
        "source": "knowledge",
        "budget": 4000,
        "used": 38,
        "picked": 1,
        "omitted": 0,
        "why": "matched the question"
      }
    ],
    "unused_tokens": 3962
  }
}
```

## 构建上下文

`POST /v2/retrieval/context`

由服务为任务挑选来源并分配预算，结果在 `route` 里说明选择理由。与 `search` 共用同一个按主体的并发上限。任务要对你能读的表格求和、计数、求平均或找最大值、最小值时，服务按固定规则在整张表上计算，不调用模型，每次最多计算 3 张表。结果是单独的一条，排在所属来源的最前面，引用这张表的 Entry 和版本，`route.rules_fired` 中包含 `table_aggregate:computed`。只有理解任务中的每个词且表格适合这项计算时才计算；否则记为 `table_aggregate:not_computed:<reason>`，表格的行仍作为证据返回。每次请求扫描的行数、单元格数和计算时间都有上限，超过上限时不计算。`answer` 使用同一条结果。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md)

### 请求体

`application/json` `DevContextRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task` | `string` | 必填 | 这份上下文的用途，以自然语言描述。任务包含多个事项时，会分别为每个事项检索。 长度 1 到 1000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则使用调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `purpose` | `DevContextPurpose` | 可选 | 上下文的用途（`task`、`coding`、`research` 或 `audit`）。设置后将跳过意图推断。 |
| `weights` | `DevContextWeights` | 可选 | 在各来源之间调整预算。不传则使用该用途对应的比例。 |
| `tier` | `DevContextTier` | 可选 | `fast` 不调用模型，只按词面匹配；`standard` 加上语义检索和重排；`deep` 查看两倍的候选。 默认 "standard" |
| `budget_tokens` | `integer` | 可选 | 覆盖整个响应，不只是 `items`。设为 `render: "compact"` 时改为覆盖 `rendered.text`，即放入提示词的文本。 500 到 16000，默认 4000 |
| `have_memory_etag` | `string` | 可选 | 仍与 `memory_view_etag` 一致时省略 `memory_view`。 长度 1 到 128 |
| `filter` | `DevRetrievalFilter` | 可选 | 在排序之前缩小搜索范围。作用于所有读取 Entry 的来源；`memory_view` 不受过滤。 |
| `render` | `text \| compact` | 可选 | 设为 `text` 时响应增加 `rendered`：将同一上下文包排版为可直接放入提示词的文本，每个来源列在其引用 id 下。自行使用 `items` 组装提示词时无需传入。设为 `compact` 时以更简短的版式增加 `rendered`（每个来源一行，带出处和一个时间；对话片段中重复的消息时间戳只写一次），并按这段文本而非 JSON 响应计算 `budget_tokens` 和 `tokens_used`，因此同样的预算可容纳更多证据。当模型直接读取该文本时使用此值。`items` 仍包含全部 id、时间和定位信息。 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

### 响应

- `200` `application/json` `DevContextResponse`

### 错误状态

`400` `401` `403` `404` `409` `422` `429` `500` `503` `504` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/retrieval/context" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Draft the release notes for version 2.4","space_ids":["default"],"budget_tokens":4000}'
```

### 响应结构示例

```json
{
  "pack_id": "<pack_id>",
  "items": [
    {
      "entry_id": "<entry_id>",
      "version_id": "<version_id>",
      "title": "Launch notes",
      "text": "The launch moved to March 14.",
      "citation_id": "<citation_id>",
      "source": "memory"
    }
  ],
  "route": {
    "purpose": "task",
    "tier": "fast",
    "rules_fired": [
      "<rules_fired>"
    ],
    "sources": [
      {
        "source": "memory",
        "budget": 1,
        "used": 1,
        "picked": 1,
        "omitted": 1,
        "why": "<why>"
      }
    ],
    "unused_tokens": 1
  },
  "tokens_used": 1,
  "budget_tokens": 1,
  "tokenizer": "cl100k_base",
  "omitted": {
    "count": 1,
    "max_score": 1
  },
  "scope_used": {
    "space_ids": [
      "<space_ids>"
    ]
  },
  "partial": false
}
```

## 发送上下文反馈

`POST /v2/retrieval/context/{pack_id}/feedback`

报告一个包里哪些条目已被使用。包里没有的引用返回 422 `unknown_citation`。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md#feedback)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `pack_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |

### 请求体

`application/json` `DevContextFeedbackRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `used_citation_ids` | `string[]` | 必填 | 包里你实际用到的 `citation_id`。只传引用，不传内容。报告会累加：重复报告或分几次报告都安全。 1 到 256 项 |

### 响应

- `204` 无响应体

### 错误状态

`400` `401` `403` `404` `409` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/retrieval/context/$PACK_ID/feedback" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"used_citation_ids":["<used_citation_ids>"]}'
```

## 搜索

`POST /v2/retrieval/search`

在你指定的来源中检索 `query`。写入后的下一个请求即可通过词法检索到。除请求速率外，每个主体可同时运行的搜索和上下文请求数量也有上限（见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 中的 `retrieval_concurrency`，Agent 为 `agent_retrieval_concurrency`）。超出上限的调用在服务端等待空闲名额，默认约 1 秒，超时仍无空闲名额才返回 429 `rate_limited`（`limit` 为 `concurrency`）；此时请按 `Retry-After` 重试。账户总额（`tenant_retrieval_concurrency`）不排队：超出总额的调用立即返回 429。需要 `knowledge:read`。

**需要的能力** `knowledge:read`

指南：[检索与上下文](https://mirabase.io/zh/developers/retrieval.md)

### 请求体

`application/json` `DevSearchRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 必填 | 要检索的内容，可使用自然语言或关键词。 长度 1 到 1000 |
| `space_ids` | `DevSpaceRef[]` | 可选 | Space 的 id；`default` 指你的默认 Space，和路径里的含义相同。不传则搜索调用方可读的全部 Space；可读 Space 超过 200 个的 Key 必须显式指定（否则返回 422）。 1 到 64 项 |
| `path` | `DevPath` | 可选 | 把结果限定在这棵子树或这一个文件。在每个被搜索的 Space 里分别解析，都不存在时结果为空。 |
| `include` | `memory[]` | 可选 | `["memory"]` 在结果中加入记忆分面，并把排序切换到记忆档：没有相关性下限，每个 Entry 最多一段。只接受这一个值，且只能指定一次。 1 项 |
| `limit` | `integer` | 可选 | 最多返回多少条命中。这是总数，和列表的每页条数不同。 1 到 50，默认 20 |
| `filter` | `DevRetrievalFilter` | 可选 | 在排序之前缩小搜索范围。与 `path`、`space_ids` 同时生效：必须全部满足。 |
| `tier` | `DevContextTier` | 可选 | 与 `context` 相同：`fast` 不调用模型，只按词面匹配（分数不代表相关性，有命中时 `partial` 为 true）；`standard` 加上语义检索和重排；`deep` 查看两倍的候选，并重排两倍的候选。 默认 "standard" |
| `fields` | `DevSearchHitField[]` | 可选 | 每个命中只保留这些可选字段。`entry_id`、`version_id`、`title`、`text`、`score`、`citation_id` 和 `source_type` 始终返回。每个字段只能指定一次。不传时返回全部字段。 最多 9 项 |
| `profile` | `string` | 可选 | 当前部署上声明的检索配置：上述设置（以及候选数和重排数）的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时，使用部署为所检索的 Space 或本账户设定的默认配置。 |
| `rerank` | `boolean` | 可选 | `false` 跳过重排：结果保持融合后候选的顺序，分数不代表相关性，有结果时 `partial` 为 true。不能与 `min_score` 同时使用；`true` 不能与 `fast` 档同时使用。 |
| `min_score` | `number` | 可选 | 保留的最低重排分数，取值 0 到 1。它替代服务默认的相关性下限，同时移除低于该值的词法匹配。来自新鲜缓冲的命中（`freshness: pending_index`）没有重排分数，会被保留。重排失败时不生效（`partial` 会注明）。需要启用重排。 0 到 1 |
| `max_per_entry` | `integer` | 可选 | 每个 Entry 最多返回的片段数。这是硬上限：腾出的名额分给其他 Entry，而不是同一 Entry 的更多片段。在 `context` 和 `answer` 中，它只作用于搜索结果，不作用于任务指定的文件或最近的变更。 1 到 50 |
| `reference_time` | `string (date-time)` | 可选 | 查询中的相对时间（“昨天”“上周”）从哪一刻算起。默认为当前时刻。替一条较早的消息检索时，传该消息的时间。在 `answer` 上，它同时是告诉模型的“今天”。 |
| `timezone` | `string` | 可选 | 提问者所在的 IANA 时区，例如 `Asia/Shanghai`：它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。 |
| `explain` | `boolean` | 可选 | 为 true 时，每个命中、条目或引用以及响应本身都带上 `explain`：由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据，以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选：读范围、元数据范围或权限之外的内容一律不计入。 |

### 响应

- `200` `application/json` `DevSearchResponse`

### 错误状态

`400` `401` `403` `404` `409` `422` `429` `500` `503` `504` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/retrieval/search" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"launch date for version 2.4","space_ids":["ext:user-42"],"include":["memory"],"limit":5}'
```

### 响应结构示例

```json
{
  "data": [
    {
      "entry_id": "ent_01JD2M8Z4K",
      "version_id": "ver_01JD2M8Z4M",
      "space_id": "col_01JD2M7QK3",
      "title": "plan.md",
      "text": "The launch of version 2.4 moved to Friday 21 November.",
      "score": 0.82,
      "citation_id": "c1",
      "source_type": "file",
      "path": "/notes/plan.md",
      "modified_at": "2026-11-17T08:02:00Z"
    }
  ],
  "trace_id": "trc_01JD2M7R",
  "partial": false
}
```
