处理进度
Markdown 版文件写入后先变为可检索,记忆随后生成:等待单个文件可检索、跟踪批量导入进度,并识别检索时尚未处理完成的内容。
写入文件后,服务依次提取文本、建立索引并发布到搜索。这三步完成后,文件即可按语义检索;关联、分类、摘要和记忆在之后生成,不影响检索。请求体中 64 KiB 以内的文本在写入后立即可以按词检索,见 检索。
最新版本所处的阶段记在 stage 中:为 enriching 或 ready 时,搜索即可找到该版本。
等待单个文件可检索
GET /v2/entries/{entry_id}/processing 返回最新版本的 stage 和 progress;排队等待期间还会返回 queue,说明排在前面的任务数和等待原因。SDK 的 entries.waitUntil(Python 为 entries.wait_until)会自动轮询该接口,默认等待至文件可检索;传入 until: "ready" 时则等待全部步骤完成。
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
-H "Authorization: Bearer $MIRABASE_API_KEY"- 处理失败时,
waitUntil会返回最后获取的状态而不抛出异常,此时请检查error字段。失败的版本可通过POST /v2/entries/{entry_id}/reprocess重试。 - 超过等待时间(默认 10 分钟)时,SDK 抛出代码为
wait_timeout的错误,服务端的处理继续进行。 - 只写入一个文件时,也可以在写入请求中带
Prefer: wait,见 写入文件。
跟踪批量导入
导入大量文件时,无需逐个查询 Entry。GET /v2/spaces/{space_id}/processing 按阶段统计 Space 中的 Entry,并返回其变为可检索的速率和预计剩余时间。SDK 的 spaces.waitUntil(Python 为 spaces.wait_until)会轮询该接口,直至 Space 中的全部 Entry 可检索;onProgress 会接收每次轮询获取的统计数据,可用于展示进度。
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \
-H "Authorization: Bearer $MIRABASE_API_KEY"- 失败的 Entry 计入
counts.failed,失败原因可通过GET /v2/entries/{entry_id}/processing查看。 - 记忆在文件可检索之后单独提炼,
memory报告仍在排队或运行的提炼任务。仅等待提炼的 Entry 仍计为可检索。如需等待记忆提炼完成,请传入until: "ready"。 - 不同 Space 和账户的任务轮流执行,因此一个 Space 的大批量导入不会阻塞其他 Space 的新文件。
识别尚未处理完成的内容
所检索的 Space 中仍有 Entry 在处理时,search、context 和 answer 的响应带 pending_processing,其中 entries 是尚不可检索的 Entry 数。这些 Entry 的内容可能不在本次结果中:如果需要的内容可能在其中,请稍后再查询,或先等待处理完成。
{
"pack_id": "pck_...",
"items": [
"..."
],
"pending_processing": {
"entries": 12
}
}SDK 的 context 和 answer 会原样返回该字段;search 返回命中结果数组,该字段位于数组的 pendingProcessing 属性中(Python 为 pending_processing)。MCP 工具 mira.search 的结果同样包含 pending_processing。
处理队列已满时
账户排队的任务数超过上限时,写入请求会返回 429 ingest_backlog:queue 给出排队任务数和预计等待时间,Retry-After 为 30 到 600 秒。请按 Retry-After 等待后重试。SDK 仅在 Retry-After 不超过 maxRetryAfterMs(Python 为 max_retry_after,默认 60 秒)时自动等待并重试;超过时抛出 MirabaseRateLimitError,请读取 retryAfterSeconds(Python 为 retry_after_seconds)后自行等待,或调大该选项,见 重试和幂等。账户管理员可以随时通过 GET /v2/queue 查看队列。
