跳到主要内容
开发者文档
文档目录

在 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_idsDevSpaceRef[]Space 的 id;default 指你的默认 Space,和路径里的含义相同。不传则使用调用方可读的全部 Space;可读 Space 超过 200 个的 Key 必须显式指定(否则返回 422)。1 到 64 项
purposeDevContextPurpose回答用来做什么,与 context 的同一个参数:task、coding、research 或 audit。
weightsDevContextWeights与 context 相同。不传时,回答不使用 changes 和 skills 两个来源:无论问题是什么,它们列出的都是最近的文件和技能。这时 route.rules_fired 会列出 source:off:changes:answer_default 和 source:off:skills:answer_default。要包含它们,请传 weights。
tierDevContextTier检索证据时投入的工作量,与 context 上的含义相同:fast、standard 或 deep。默认 "standard"
budget_tokensinteger模型读取的证据的预算。500 到 16000,默认 4000
historyDevAnswerTurn[]之前的对话轮次,最早的在前。追问会和它所追问的问题一起搜索。各轮合计超过 12,000 个字符时,最早的几轮会被略去。最多 10 项
output_languagestringBCP 47 语言标签,如 en 或 zh-CN。只影响 answer 的语言。最长 35
filterDevRetrievalFilter缩小答案可引用的证据范围,和 context 相同。
includeevidence[]["evidence"] 在响应里增加 evidence:模型读过的每一条证据,不带正文。用它查看回答除了引用的段落之外还依据了什么。1 项
streamboolean为 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 响应。
profilestring当前部署上声明的检索配置:上述设置(以及候选数和重排数)的具名组合。请求中传入的字段会覆盖配置中的值。名称未知时返回 422。不传时,使用部署为所检索的 Space 或本账户设定的默认配置。
rerankbooleanfalse 跳过重排:结果保持融合后候选的顺序,分数不代表相关性,有结果时 partial 为 true。不能与 min_score 同时使用;true 不能与 fast 档同时使用。
min_scorenumber保留的最低重排分数,取值 0 到 1。它替代服务默认的相关性下限,同时移除低于该值的词法匹配。来自新鲜缓冲的命中(freshness: pending_index)没有重排分数,会被保留。重排失败时不生效(partial 会注明)。需要启用重排。0 到 1
max_per_entryinteger每个 Entry 最多返回的片段数。这是硬上限:腾出的名额分给其他 Entry,而不是同一 Entry 的更多片段。在 context 和 answer 中,它只作用于搜索结果,不作用于任务指定的文件或最近的变更。1 到 50
reference_timestring (date-time)查询中的相对时间(“昨天”“上周”)从哪一刻算起。默认为当前时刻。替一条较早的消息检索时,传该消息的时间。在 answer 上,它同时是告诉模型的“今天”。
timezonestring提问者所在的 IANA 时区,例如 Asia/Shanghai:它决定“昨天”是哪一天。默认是部署的时区。未知的时区名返回 422。
explainboolean为 true 时,每个命中、条目或引用以及响应本身都带上 explain:由哪几路检索找到、重排前后的位置、匹配的查询词、通过相关性下限的依据,以及哪些规则调整了它的位置。是否传入不影响结果及其顺序。不传时没有额外开销。计数、位置和分数只统计你能读取的候选:读范围、元数据范围或权限之外的内容一律不计入。

响应

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

流式事件

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

错误状态

400 401 403 404 409 422 429 500 502 503 504 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

指南:检索与上下文

请求体

application/json DevContextRequest

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

响应

错误状态

400 401 403 404 409 422 429 500 503 504 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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

指南:检索与上下文

参数

名称位置类型说明
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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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>"]}'