在 Key 可读的内容上执行搜索、构建上下文包和生成带引用的回答。
带引用回答
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,默认 3 个),按该主体的全部 Key 合计;超出的调用最多等 10 秒,然后返回 429 rate_limited,limit 为 concurrency。502 model_failed 和 503 answer_unavailable 可以稍后重试。503 answer_not_configured 表示这个部署没有回答模型,所以重试没有用:请构建上下文,再运行你自己的模型。
需要的能力 knowledge:read knowledge:answer
指南:检索与上下文
请求体
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:由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据,以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选:读范围、元数据范围或权限之外的内容一律不计入。 |
响应
200application/jsonDevAnswer,text/event-streamstring
流式事件
响应为 text/event-stream 时发送的事件,以及每个事件中 data 的结构:
startDevAnswerStreamStartdeltaDevAnswerStreamDeltareplaceDevAnswerStreamReplacefinalDevAnswererrorDevErrorResponse
错误状态
400 401 403 404 409 422 429 500 502 503 504 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"]}'响应结构示例
{
"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
指南:检索与上下文
请求体
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:由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据,以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选:读范围、元数据范围或权限之外的内容一律不计入。 |
响应
200application/jsonDevContextResponse
错误状态
400 401 403 404 409 422 429 500 503 504 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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}'响应结构示例
{
"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
指南:检索与上下文
参数
请求体
application/json DevContextFeedbackRequest
| 字段 | 类型 | 说明 |
|---|---|---|
used_citation_ids必填 | string[] | 包里你实际用到的 citation_id。只传引用,不传内容。报告会累加:重复报告或分几次报告都安全。1 到 256 项 |
响应
204无响应体
错误状态
400 401 403 404 409 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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 中的 retrieval_concurrency,Agent 为 agent_retrieval_concurrency)。超出上限的调用在服务端等待空闲名额,默认约 1 秒,超时仍无空闲名额才返回 429 rate_limited(limit 为 concurrency);此时请按 Retry-After 重试。账户总额(tenant_retrieval_concurrency)不排队:超出总额的调用立即返回 429。需要 knowledge:read。
需要的能力 knowledge:read
指南:检索与上下文
请求体
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:由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据,以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选:读范围、元数据范围或权限之外的内容一律不计入。 |
响应
200application/jsonDevSearchResponse
错误状态
400 401 403 404 409 422 429 500 503 504 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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}'响应结构示例
{
"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
}