Operations 模块

更新时间：2026-11-03

异步操作接口

本文介绍异步操作相关的 5 个接口。查询、取消、重试和删除异步操作，例如异步 Retain、刷新心智模型、创建知识库页面返回的 operation_id。

调用说明

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

接口列表

接口	方法	路径
列出异步操作	`GET`	`/v1/default/banks/{bank_id}/operations`
获取异步操作状态	`GET`	`/v1/default/banks/{bank_id}/operations/{operation_id}`
取消异步操作	`DELETE`	`/v1/default/banks/{bank_id}/operations/{operation_id}`
删除已终止的异步操作	`DELETE`	`/v1/default/banks/{bank_id}/operations/{operation_id}/delete`
重试异步操作	`POST`	`/v1/default/banks/{bank_id}/operations/{operation_id}/retry`

列出异步操作

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

列出指定 Bank 的异步操作，可按 status 和 operation type 筛选；结果按最近时间优先排序。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`status`	query	`string?`	否	按状态筛选：pending、processing、completed、failed 或 cancelled。
`type`	query	`string?`	否	按 operation type 筛选：retain、consolidation、refresh_mental_model、file_convert_retain、webhook_delivery。
`limit`	query	`integer`	否	返回异步操作的最大数量；默认值：`20`；取值范围：`1`–`100`
`offset`	query	`integer`	否	跳过的异步操作数量；默认值：`0`；最小值：`0`
`exclude_parents`	query	`boolean`	否	从结果中排除父级批量异步操作；默认值：`false`

请求头

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

响应

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

字段	类型	必填	说明
`bank_id`	`string`	是	所属 Bank 的唯一标识符。
`total`	`integer`	是	总数量。
`limit`	`integer`	是	返回数量上限。
`offset`	`integer`	是	分页偏移量。
`operations`	`array<OperationResponse>`	是	operation 列表。

operations[] · OperationResponse

数据结构 OperationResponse：

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`task_type`	`string`	是	任务类型。
`items_count`	`integer`	是	项目数量。
`document_id`	`string?`	否	Document 的唯一标识符。
`filename`	`string?`	否	文件转换 operation（file_convert_retain）的原始文件名；其他 task type 为 null。
`created_at`	`string`	是	资源创建时间（ISO 8601）。
`updated_at`	`string?`	否	此 operation 记录最近一次发生变化的时间（claim、progress heartbeat 或 completion）。
`status`	`string`	是	当前处理状态；异步操作通常为 pending、processing、completed、failed 或 cancelled。
`error_message`	`string?`	否	错误消息。
`retry_count`	`integer?`	否	该异步操作失败后已重试的次数。
`next_retry_at`	`string?`	否	worker 下次尝试该异步操作的时间。对于 pending 状态的异步操作，未来时间表示任务正在等待而不是立即可取；例如扩展可能抛出 DeferOperation，让任务等待背压窗口开启。已完成任务始终为 null。
`progress`	`OperationProgress?`	否	运行中异步操作最近一次已知的进度快照；未记录时为 null。

progress · OperationProgress

数据结构 OperationProgress：

字段	类型	必填	说明
`stage`	`string`	是	Operation 最近报告的粗粒度阶段（例如 processing_batch）。
`at`	`string`	是	写入此快照的 ISO 8601 时间戳。
`processed`	`integer?`	否	目前已完成的工作单元数（如子批次、memories）；未知时为空。
`total`	`integer?`	否	Operation 的工作单元总数；未知时为空。
`detail`	`map<string, integer>?`	否	Operation 专属计数器（例如 observations_created、round、items_in_sub_batch）。

响应示例

                JSON
                
            

                {
  "bank_id": "user123",
  "limit": 20,
  "offset": 0,
  "operations": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "task_type": "retain"
    }
  ],
  "total": 150
}
            

响应

状态码：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_operations

获取异步操作状态

GET /v1/default/banks/{bank_id}/operations/{operation_id}

获取指定异步操作的状态。返回 pending、processing、completed、failed 或 cancelled。已完成的异步操作在配置的保留窗口内仍可携带 payload 查询，之后会被清理。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`operation_id`	path	`string`	是	Operation 的唯一 ID。
`include_payload`	query	`boolean`	否	在响应中包含原始任务 payload（提交参数），内容可能较大；默认值：`false`

请求头

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

响应

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

字段	类型	必填	说明
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。
`status`	`"pending" \\| "processing" \\| "completed" \\| "failed" \\| "cancelled" \\| "not_found"`	是	当前状态。
`operation_type`	`string?`	否	operation 类型。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。
`completed_at`	`string?`	否	完成时间。
`error_message`	`string?`	否	错误消息。
`retry_count`	`integer?`	否	该异步操作失败后已重试的次数。
`next_retry_at`	`string?`	否	worker 下次尝试该异步操作的时间。对于 pending 状态的异步操作，未来时间表示任务被暂停（例如扩展抛出 DeferOperation），而不是等待立即处理。
`progress`	`OperationProgress?`	否	运行中异步操作最近一次已知的进度快照；未记录时为 null。
`result_metadata`	`object?`	否	用于调试的内部 metadata。结构可能随时变化，不应在生产逻辑中依赖。
`child_operations`	`array<ChildOperationStatus>?`	否	批量异步操作的子 operations（如适用）。
`task_payload`	`object?`	否	提交异步操作时使用的原始 task payload（参数）。仅在`include_payload=true` 时填充。

progress · OperationProgress

数据结构 OperationProgress：

字段	类型	必填	说明
`stage`	`string`	是	Operation 最近报告的粗粒度阶段（例如 processing_batch）。
`at`	`string`	是	写入此快照的 ISO 8601 时间戳。
`processed`	`integer?`	否	目前已完成的工作单元数（如子批次、memories）；未知时为空。
`total`	`integer?`	否	Operation 的工作单元总数；未知时为空。
`detail`	`map<string, integer>?`	否	Operation 专属计数器（例如 observations_created、round、items_in_sub_batch）。

child_operations[] · ChildOperationStatus

数据结构 ChildOperationStatus：

字段	类型	必填	说明
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。
`status`	`string`	是	当前处理状态；异步操作通常为 pending、processing、completed、failed 或 cancelled。
`sub_batch_index`	`integer?`	否	子批次索引。
`items_count`	`integer?`	否	项目数量。
`error_message`	`string?`	否	错误消息。

响应示例

                JSON
                
            

                {
  "completed_at": "2024-01-15T10:31:30Z",
  "created_at": "2024-01-15T10:30:00Z",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "refresh_mental_models",
  "status": "completed",
  "updated_at": "2024-01-15T10:31:30Z"
}
            

响应

状态码：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_operation_status

取消异步操作

DELETE /v1/default/banks/{bank_id}/operations/{operation_id}

从队列中移除待处理的异步操作，以取消该操作。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string`	是	操作结果或错误的可读消息。
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。

响应示例

                JSON
                
            

                {
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "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=cancel_operation

删除已终止的异步操作

DELETE /v1/default/banks/{bank_id}/operations/{operation_id}/delete

永久删除失败、已取消或已完成的异步操作记录。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string`	是	操作结果或错误的可读消息。
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。

响应示例

                JSON
                
            

                {
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 deleted",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "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_operation

重试异步操作

POST /v1/default/banks/{bank_id}/operations/{operation_id}/retry

重新入队失败的异步操作，使 worker 再次处理。

参数

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

请求头

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

响应

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

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string`	是	操作结果或错误的可读消息。
`operation_id`	`string`	是	异步操作的唯一标识符，可用于查询状态。

响应示例

                JSON
                
            

                {
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "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=retry_operation

评价此篇文章

有帮助没帮助

Directives 模块

Webhooks 模块

上下文数据服务

Operations 模块

异步操作接口

调用说明

接口列表

列出异步操作

参数

请求头

响应

响应示例

响应

响应示例

获取异步操作状态

参数

请求头

响应

响应示例

响应

响应示例

取消异步操作

参数

请求头

响应

响应示例

响应

响应示例

删除已终止的异步操作

参数

请求头

响应

响应示例

响应

响应示例

重试异步操作

参数

请求头

响应

响应示例

响应

响应示例