Documents 模块

更新时间：2026-11-03

文档接口

本文介绍文档相关的 7 个接口。按 document 查看、更新、删除和重新处理已写入的内容，并查看 document 的分块（chunk）。

调用说明

接入地址：https://cloud.memory.bj.baidubce.com/api，下文路径直接拼接在该地址后。
请求头：Authorization: Bearer <token> 必填；有 JSON 请求体时需携带 Content-Type: application/json。
错误码、异步操作和 operationId 的说明见 API 简介。

接口列表

接口	方法	路径
列出 document	`GET`	`/v1/default/banks/{bank_id}/documents`
获取 document 详情	`GET`	`/v1/default/banks/{bank_id}/documents/{document_id}`
更新 document	`PATCH`	`/v1/default/banks/{bank_id}/documents/{document_id}`
删除 document	`DELETE`	`/v1/default/banks/{bank_id}/documents/{document_id}`
列出 document chunk	`GET`	`/v1/default/banks/{bank_id}/documents/{document_id}/chunks`
重新处理 document	`POST`	`/v1/default/banks/{bank_id}/documents/{document_id}/reprocess`
获取 chunk 详情	`GET`	`/v1/default/chunks/{chunk_id}`

列出 document

GET /v1/default/banks/{bank_id}/documents

分页列出 document，并支持可选搜索。document 是抽取 memory unit 的来源内容。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`q`	query	`string?`	否	对 document ID 进行不区分大小写的子字符串筛选（例如 report 匹配 report-2024）。
`tags`	query	`array<string>?`	否	按 tags 筛选 documents。
`tags_match`	query	`string`	否	tag 的匹配方式: 'any', 'all', 'any_strict', 'all_strict'；默认值：`"any_strict"`
`limit`	query	`integer`	否	默认值：`100`；最小值：`0`
`offset`	query	`integer`	否	默认值：`0`；最小值：`0`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<object>`	是	结果项目列表。
`total`	`integer`	是	总数量。
`limit`	`integer`	是	返回数量上限。
`offset`	`integer`	是	分页偏移量。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "bank_id": "user123",
      "content_hash": "abc123",
      "created_at": "2024-01-15T10:30:00Z",
      "id": "session_1",
      "memory_unit_count": 15,
      "tags": [
        "user_a",
        "session_123"
      ],
      "text_length": 5420,
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 50
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_documents

获取 document 详情

GET /v1/default/banks/{bank_id}/documents/{document_id}

获取指定 document，包括Document 的原始文本；未启用文本存储时可能为 null。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`document_id`	path	`string`	是	Document 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`original_text`	`string?`	否	Document 的原始文本；未启用文本存储时可能为 null。
`content_hash`	`string?`	否	内容哈希值。
`created_at`	`string`	是	资源创建时间（ISO 8601）。
`updated_at`	`string`	是	资源最后更新时间（ISO 8601）。
`memory_unit_count`	`integer`	是	memory unit 数量。
`nodes_by_fact_type`	`map<string, integer>?`	否	按 fact type（world、experience、observation）统计的 memory 数量。
`tags`	`array<string>`	否	与此 document 关联的标签；默认值：`[]`
`document_metadata`	`object?`	否	Document 的附加 metadata。
`retain_params`	`object?`	否	Retain 时使用的参数。
`observation_scopes`	`string \\| array<array<string>> \\| null`	否	Retain 时配置并记录到 retain_params 的 observation_scopes 规范（例如 all_combinations、per_tag 或显式 tag-set 列表）。未设置时为 null（默认使用 combined scope），在该字段开始记录之前 Retain 的 documents 也为 null。

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "content_hash": "abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "document_metadata": {
    "channel": "#general",
    "source": "slack"
  },
  "id": "session_1",
  "memory_unit_count": 15,
  "original_text": "Full document text here...",
  "retain_params": {
    "context": "Team meeting notes",
    "event_date": "2024-01-15"
  },
  "tags": [
    "user_a",
    "session_123"
  ],
  "updated_at": "2024-01-15T10:30:00Z"
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_document

更新 document

PATCH /v1/default/banks/{bank_id}/documents/{document_id}

更新 document 的可变字段，不重新处理其内容。

标签（tags）： 新标签会传播到所有关联的 memory unit。由这些 memory unit 派生的 observations 将失效，并使用新标签排队重新 consolidation。其他 document 中与其共享这些 observations 的同源 memories 也会被重置。

至少必须提供一个字段。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`document_id`	path	`string`	是	Document 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`tags`	`array<string>?`	否	Document 及其 memory units 的新 tags。修改后会使现有 observations 失效并触发重新 consolidation。

请求示例

                JSON
                
            

                {
  "tags": [
    "team-a",
    "team-b"
  ]
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	否	默认值：`true`

响应示例

                JSON
                
                {
  "success": true
}

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=update_document

删除 document

DELETE /v1/default/banks/{bank_id}/documents/{document_id}

删除 document 及其关联的全部 memory unit 和链接。

此操作将级联删除：

document 本身
从该 document 抽取的全部 memory unit
与这些 memory unit 关联的全部链接（时序、语义和实体链接）

此操作无法撤销。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`document_id`	path	`string`	是	Document 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string`	是	操作结果或错误的可读消息。
`document_id`	`string`	是	Document 的唯一标识符。
`memory_units_deleted`	`integer`	是	已删除的 memory unit 数量。

响应示例

                JSON
                
            

                {
  "document_id": "session_1",
  "memory_units_deleted": 5,
  "message": "Document 'session_1' and 5 associated memory units deleted successfully",
  "success": true
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=delete_document

列出 document chunk

GET /v1/default/banks/{bank_id}/documents/{document_id}/chunks

列出指定 document 的所有 chunks，按 chunk index 排序。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`document_id`	path	`string`	是	Document 的唯一 ID。
`limit`	query	`integer`	否	返回 chunk 的最大数量；默认值：`100`；取值范围：`1`–`1000`
`offset`	query	`integer`	否	分页偏移量；默认值：`0`；最小值：`0`

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<ChunkResponse>`	是	结果项目列表。
`total`	`integer`	是	总数量。
`limit`	`integer`	是	返回数量上限。
`offset`	`integer`	是	分页偏移量。

items[] · ChunkResponse

数据结构 ChunkResponse：

字段	类型	必填	说明
`chunk_id`	`string`	是	Chunk 的唯一标识符。
`document_id`	`string`	是	Document 的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`chunk_index`	`integer`	是	Chunk 在 document 中的索引。
`chunk_text`	`string`	是	Chunk 文本。
`created_at`	`string`	是	资源创建时间（ISO 8601）。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "bank_id": "user123",
      "chunk_id": "user123_session_1_0",
      "chunk_index": 0,
      "chunk_text": "This is the first chunk of the document...",
      "created_at": "2024-01-15T10:30:00Z",
      "document_id": "session_1"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_document_chunks

重新处理 document

POST /v1/default/banks/{bank_id}/documents/{document_id}/reprocess

在不改变 document 内容的情况下重新运行 retain pipeline。此操作会删除现有 memory units，并使用当前 engine 配置重新抽取 facts。适用于 LLM model、分块策略或抽取设置发生变化的情况。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`document_id`	path	`string`	是	Document 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。
`items_count`	`integer`	是	项目数量。

响应示例

                JSON
                
            

                {
  "success": false,
  "operation_id": "string",
  "items_count": 0
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=reprocess_document

获取 chunk 详情

GET /v1/default/chunks/{chunk_id}

按 ID 获取指定 chunk。

参数

名称	In	类型	必填	说明
`chunk_id`	path	`string`	是	Chunk 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`chunk_id`	`string`	是	Chunk 的唯一标识符。
`document_id`	`string`	是	Document 的唯一标识符。
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`chunk_index`	`integer`	是	Chunk 在 document 中的索引。
`chunk_text`	`string`	是	Chunk 文本。
`created_at`	`string`	是	资源创建时间（ISO 8601）。

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "chunk_id": "user123_session_1_0",
  "chunk_index": 0,
  "chunk_text": "This is the first chunk of the document...",
  "created_at": "2024-01-15T10:30:00Z",
  "document_id": "session_1"
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=get_chunk

评价此篇文章

有帮助没帮助

Mental Models 模块

Document Transfer 模块

上下文数据服务

Documents 模块

文档接口

调用说明

接口列表

列出 document

参数

请求头

响应

响应示例

响应

响应示例

获取 document 详情

参数

请求头

响应

响应示例

响应

响应示例

更新 document

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

删除 document

参数

请求头

响应

响应示例

响应

响应示例

列出 document chunk

参数

请求头

响应

响应示例

响应

响应示例

重新处理 document

参数

请求头

响应

响应示例

响应

响应示例

获取 chunk 详情

参数

请求头

响应

响应示例

响应

响应示例