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

处理进度

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
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
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 的内容可能不在本次结果中:如果需要的内容可能在其中,请稍后再查询,或先等待处理完成。

json
{
  "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 查看队列。

下一步