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

核心概念

Markdown 版

API 背后的数据模型:Space、Entry 与版本、文件、知识、记忆、分支和访问控制。

Mirabase 的来源层只有一种数据:Entry 加不可变版本。文件是 Entry 的定位方式,知识是它的处理结果,记忆的一部分来源于它。

text
Entry
├─ id, space_id, title, metadata
├─ latest_version_id      newest committed version
├─ current_version_id     version serving search
├─ file                   { path, size, media_type, etag } or null
├─ knowledge              { state, indexed_version_id }
├─ memory                 { scope, kind, pinned, exclude } or null
├─ memory_exclude         kept out of memory distillation
└─ access                 { role, capabilities }

Space

Space 是权限和路径的边界。每个账户有一个默认 Space,也可以用 POST /v2/spaces 创建更多 Space。成员、角色和文件树都按 Space 划分。

一个账户可以有多个 Space(上限为 tenant_spaces,见 限流与限额),因此可以为每个最终用户或每个项目分别创建一个。删除 Space 会删除其中的全部内容,不能撤销,默认 Space 不能删除,见 DELETE /v2/spaces/{space_id}。

一个最终用户一个 Space

最终用户之间要硬隔离时,给每个用户一个 Space:文件、知识和记忆都按 Space 分开,元数据做不到这一点。把你自己的用户 id 设为 Space 的 external_id,之后在需要 Space id 的地方写 ext:<external_id>,例如 ext:user-42。路径、?space_id= 和请求体中的 space_ids 均支持这种写法,无需维护映射表。

PUT /v2/spaces/ext:<external_id> 有则返回、无则创建。同时到达的两个请求只创建一个 Space,重复调用也是安全的,所以给新用户写入之前调用一次即可。SDK 里对应 spaces.ensure,spaceFor(Python 是 space_for)还会返回一个固定在这个 Space 上的客户端。

curl
# Returns the Space whose external_id is user-42 (200), or creates it (201).
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "User 42"}'

# ext:user-42 works wherever a Space id does.
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42/files?path=/notes/plan.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary "We ship on Friday."
  • search、context 和 answer 不传 space_ids 时读取这个 Key 能读取的全部 Space,不只是默认 Space。请求只涉及一个用户时,请指定这个用户的 Space。SDK 中固定在一个 Space 上的客户端只读那个 Space。
  • GET /v2/spaces?external_id= 按 external_id 查找,最多返回一个 Space,不会创建(SDK 的 spaces.findByExternalId、spaces.find_by_external_id)。
  • 删除 Space 之后,它的 external_id 可以再次使用。

Entry 与版本

Entry 是一份来源的稳定身份:文件、网址或一段文本。每次内容变化产生一个版本,版本不可变,版本链一直保留。

  • latest_version_id 是最新提交的版本,读取操作默认使用该版本,因此刚写入的内容立即可读。
  • current_version_id 是 search 和 context 读取的版本。最新版本完成索引后它等于 latest_version_id;更新的版本还在处理时,它仍是之前的版本。第一版处理完之前不存在。
  • 修改标题也会产生新版本,因为标题会编入索引。版本上唯一可修改的字段是 message。

同一个 Entry 可以按路径、按 id 或按语义(检索)到达。身份、权限和版本链是同一套。

文件

有路径的 Entry 即文件。路径即身份:两个路径存放相同的字节即为两个文件。改名和移动不改变 Entry id。没有路径的 Entry 也合法,比如用 ingest 导入的网址和文本,它们的 file 是 null。

有路径用 `files`,按 id 用 `entries`,两者的读取参数相同。详见 文件与版本。

知识

知识不是单独的资源,而是 Entry 的处理状态。写入提交后,后台解析、切块、建索引,状态在 knowledge.state 上:

状态含义能做什么
readable已提交按路径或 id 读取原件
searchable请求体中 64 KiB 以内的文本已进入新鲜缓冲词法检索
indexed处理完成全文检索、向量检索和重排检索
failed处理失败,字节仍可读读取原件,或调用 reprocess

写入在处理完成之前就已提交。需要等待处理完成时,在写入请求中带上 Prefer: wait=N,见 PUT /v2/spaces/{space_id}/files。

记忆

记忆是一条有范围、状态和来源的陈述:账户记忆、以 Entry 写入的记忆,或从 Entry 提炼出的事实。提炼出的事实不是 Entry,它的 id 也不是 Entry id;范围、状态和有效期见 记忆模型。

分支

分支是叠在 Space 主线上的写时复制层,用作 Agent 的工作区。分支里的内容不产生版本、不处理,合并进主线时每个路径才成为一个新版本。详见 分支与挂载。

访问控制

每个请求以一个主体(人或 Agent)的身份执行,由 API Key 携带。请求能做什么,取决于主体和 Key 共同持有的能力、主体在 Space 里的角色,以及 Space 所有者为成员设的读写根路径,见 权限。

下一步