攒批写入

更新时间:
复制 MD 格式

攒批写入(Buffer)用于把高频、碎片化的消息先缓冲起来,再批量整理成记忆。它帮助业务在实时对话、事件流等高频写入场景中大幅降低写入开销,同时让抽取出的记忆拥有更完整的上下文。

解决的问题

在未使用攒批写入时,高频消息写入场景可能出现以下问题:

  • 每条消息单独写入时,每条都要消耗一次模型调用,成本高、速度慢。

  • 碎片消息(如“嗯”、“好的”半句话)单独无法抽取出有价值的记忆。

  • 高频写入场景下,写入接口成为 Agent 链路的瓶颈。

主要能力

能力

说明

自动攒批

消息写入后先进入缓冲区,积累到一定量或超过等待时间后自动整理入库,无需业务侧控制节奏。

按用户和标签分组

不同用户、不同 metadata 的消息分开攒批,互不混淆,入库后的记忆保留写入时的 metadata。

手动触发

会话结束等时机可以立即触发整理,不必等待自动触发。

状态可查

可以随时查询某个用户当前缓冲了多少消息、等待了多久。

节奏可调

攒批的触发节奏可以查看和调整,适配不同业务的消息量。

失败自动重试

整理失败的消息不会丢失,系统会自动重试直到成功。

适用场景

  • 实时对话流:用户消息逐条到达,希望降低写入成本。

  • IoT / 事件流:设备上报高频事件,需要攒够一批再形成记忆。

  • 多轮短消息会话:单条消息信息量低,合并后才能抽取出完整结论。

  • 批量导入场景:对写入延迟不敏感、但对成本敏感的场景。

如何使用

操作

接口

说明

写入缓冲

POST /memories/buffer

参数与记忆写入一致,默认异步立即返回。

手动整理

POST /memories/flush

立即触发指定用户的批量整理。

查看缓冲状态

GET /memories/buffer/status?user_id=xxx

查看缓冲中的消息数量与等待时长。

查看攒批配置

GET /memories/buffer/config

查看当前攒批触发节奏。

调整攒批配置

PUT /memories/buffer/config

按需调整攒批节奏,修改即时生效。

写入时通过 async_mode 控制返回方式:默认 true(立即返回,后台处理);设为 false 时同步等待并返回完整结果,适合需要确认落库的关键写入。

说明

缓冲中的消息在整理入库前不会被搜索到。需要“写入即可见”的消息请使用普通的 POST /memories 写入。

查看与调整攒批配置

查看当前配置:

curl -sS "${MEMORY_URL}/memories/buffer/config" \
  -H "Authorization: Token ${MEMORY_API_KEY}"

返回示例:

{
  "char_threshold": 10000,
  "time_threshold_seconds": 1800,
  "scan_interval_seconds": 300,
  "retry_alert_threshold": 5
}

各参数说明如下:

  • char_threshold:触发整理所需的消息量(按字符数),单组缓冲消息累计达到该值即触发整理。

  • time_threshold_seconds:最长等待时间(秒),未达到消息量但超过该时间也会自动整理。

  • scan_interval_seconds:系统检查缓冲的间隔(秒)。

  • retry_alert_threshold:整理连续失败达到多少次时输出告警。

按需修改(只提交要调整的项,参数不合法时返回 400):

curl -sS -X PUT "${MEMORY_URL}/memories/buffer/config" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"char_threshold": 5000}'

示例

以下示例直接调用线上服务,连续写入 3 条碎片消息,再手动触发整理并查看结果。

说明

API Key 建议通过环境变量传入,不要直接写在代码或公共文档中。

步骤一:配置服务地址和认证信息

export MEMORY_URL="https://api-longmemory-cn-beijing.opentrust.net"
export MEMORY_API_KEY="<替换为您的 API Key>"
export USER_ID="demo-user-001"

步骤二:连续写入 3 条消息到缓冲

curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"我下周要去杭州出差"}],"user_id":"'${USER_ID}'","async_mode":false}'
curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"顺便去看看西湖"}],"user_id":"'${USER_ID}'","async_mode":false}'
curl -sS -X POST "${MEMORY_URL}/memories/buffer" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"帮我推荐家西湖附近的酒店"}],"user_id":"'${USER_ID}'","async_mode":false}'

同步模式下,消息进入缓冲时返回 status 为 buffered;若本次写入恰好触发整理,则返回 flush_triggered。

步骤三:手动触发整理

curl -sS -X POST "${MEMORY_URL}/memories/flush" \
  -H "Authorization: Token ${MEMORY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"'${USER_ID}'"}'

接口返回 202,表示整理任务已接受并在后台执行。

步骤四:查看整理出的记忆

curl -sS "${MEMORY_URL}/memories?user_id=${USER_ID}" \
  -H "Authorization: Token ${MEMORY_API_KEY}"

三条碎片消息被合并理解,形成一条更完整的记忆:

{
  "results": [
    {
      "memory": "用户下周要去杭州出差,计划顺便游览西湖,希望入住西湖附近的酒店。"
    }
  ],
  "total": 1
}

如果逐条单独写入,这三条消息各自都难以形成有价值的记忆;攒批后一次性理解,既省调用又更完整。

使用建议

  • 高频低值消息走攒批,关键事实走普通写入:“用户明确说了重要事项”这类一次性关键信息建议直接 POST /memories 立即入库。

  • 会话结束时手动触发一次整理:避免残余消息等待超时才入库,保证记忆时效。

  • 接受“写入到可检索”的延迟:攒批的本质是用实时性换成本与质量,对检索时效敏感的路径不要用攒批。

  • 关键写入用同步模式:async_mode=false 可以拿到落库确认,更可靠。

  • 按业务消息量调整攒批节奏:消息量小、希望记忆尽快入库时可调小 char_threshold;消息量大且对时效不敏感时可调大,进一步降低成本。

  • 用状态接口做监控:pending 数量持续增长且等待时间过久时,说明该用户的消息量长期偏低,可考虑主动触发整理。