World MachineAPI v1

How-to guides

按任务查的做法

每一节解决一个具体问题,可以单独读。所有命令都假设你已经设好 $WM_API 与 $WM_TOKEN。

前置知识:读完教程,或熟悉四个接口

写好一条记忆

text 是唯一必填字段,长度上限 8192 字节。几个实际取舍:

场景文本怎么组织
对话片段保留原句,不要改写成摘要。抽取依赖原句里的人名、机构名和时间词。
一条记录里有多件事拆成多次写入。一次写入只对应一个 eventId,混在一起会降低抽取质量。
结构化系统同步把字段拼成一句可读的陈述,例如「订单 A-1024 于 3 月 2 日发货,承运商顺丰」。

source 与 metadata 用在哪

source 是自由文本来源标签,例如 crm、chat、ticket。metadata 是任意 JSON 对象,原样存下、不参与解释。

两者都只进不出。它们随原文一起保存,但召回响应里的 MemoryView 只有 eventId、occurredAtMs、eventType、summary、affectedEntityIds,没有任何接口能把它读回来。如果你的业务需要凭这些值做后续处理,请在你自己的系统里另存一份对应关系(用返回的 eventId 做键)。

它们仍然值得填:source 会存在证据侧,便于服务方排查问题;metadata 则随原文留档。填写示例:

-d '{
  "text": "客户要求把交付日期改到 12 月 15 日",
  "source": "crm",
  "timezone": "Asia/Shanghai",
  "metadata": { "ticketId": "T-8821", "accountId": "A-1024" }
}'
metadata 不会被索引,也不能作为查询条件。需要能检索的信息,放进 text。

处理时间与时区

有两个与时间有关的字段,管的事不同。

字段管的什么什么时候必须填
occurredAtMs这件事实际发生在哪一刻(epoch 毫秒)回溯导入历史数据时
timezone说话人所在时区(IANA 名称)文本里有「昨天」「上个月」这类相对表达时

两个都省略时,发生时刻取服务器当前时间,时区按 UTC 处理。对于「用户刚说了一句话」这种实时场景,省略即可。

对于历史数据导入,两个都要给:

-d '{
  "text": "2025 年 10 月 1 日从北京搬到上海",
  "occurredAtMs": 1759248000000,
  "timezone": "Asia/Shanghai"
}'

非法值会怎样

输入结果
timezone: "Mars/Olympus"400,timezone must be an IANA name
timezone: "Asia/Shanghai"正常
occurredAtMs 是负数,或超过当前时间 24 小时400,occurred_at_ms is out of range
不要把未来时间当成「预约」。写入允许的时间上限是当前时间加 24 小时,超出即拒绝。这不是一条可以排期的写入通道。

安全地重试

写入接口支持幂等。策略取决于你是否传了 Idempotency-Key。

传了幂等键:同键同内容 = 同一条记忆

# 第一次
curl -sS -X POST "$WM_API/v1/memories" \
  -H "Authorization: Bearer $WM_TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-A1024-shipped' \
  -d '{"text":"订单 A-1024 已发货","occurredAtMs":1763300000000}'

# {"eventId":"85c5751f-d706-5b7f-abfc-707d9ca8590a"}

# 超时后重试,键与内容都不变
# {"eventId":"85c5751f-d706-5b7f-abfc-707d9ca8590a", "deduplicated":true}

同一个 eventId 加 deduplicated:true,说明这是重放,不是新记录。

键的格式有限制:[A-Za-z0-9][A-Za-z0-9_.:@-]{0,127}。不合法直接 400,不会截断后继续用——截断可能让两个不同的请求撞到一起。

幂等记录没有公布过期时间,会一直保留到你执行擦除。所以中断几小时甚至几天后重跑同一批键,仍会正确地变成重放,不会重复写入。

没传幂等键:按内容去重

服务端会用「文本 + 来源 + 时间 + 时区 + 归属」算一个键。所以内容完全相同的重复提交也会被去重,但只在 occurredAtMs 也一致时才成立。

省略 occurredAtMs 时它取服务器当前时间。两次请求的时间戳不同,内容派生键就不同,重复提交会产生两条记录。需要可靠去重的场景,必须显式传幂等键。

重试时机的建议

响应要不要重试
网络超时、连接中断要,用原键原内容重发
500 internal要,退避后重发
503 unavailable要,退避后重发
409 conflict不要。同键配了不同内容,换新键
400 invalid_argument不要。请求本身有问题

批量导入

没有批量写入接口,一次请求就是一条记忆。导入大批量数据时按这个顺序做:

  1. 给每条记录一个稳定的幂等键。用你的源系统主键,例如 crm:contact:8821。这样中断后可以从头重跑,已经写成功的会变成重放。
  2. 并发控制在个位数。接口没有公布吞吐承诺,稳妥做法是 4 到 8 个并发,观察延迟与错误率再调整。
  3. 先跑 100 条看抽取质量。抽不出来、抽错了的信息,在这一步就能发现,而不是等全量写完再去回溯。
  4. 记录失败清单。把 4xx 的请求体和响应写进日志,导入结束后逐条修正重投。

一个可用的脚本骨架:

while read -r id text; do
  curl -sS -o /dev/null -w "%{http_code} $id\n" \
    -X POST "$WM_API/v1/memories" \
    -H "Authorization: Bearer $WM_TOKEN" \
    -H 'Content-Type: application/json' \
    -H "Idempotency-Key: crm:contact:$id" \
    -d "{\"text\":$(printf '%s' "$text" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))'),\"source\":\"crm\",\"timezone\":\"Asia/Shanghai\"}"
done < contacts.tsv
文本里有引号或换行时,手工拼 JSON 很容易出错。生产环境用真正的 HTTP 客户端与 JSON 序列化库,上面的脚本只适合一次性验证。

处理错误

所有错误响应共用同一个信封,没有例外:

{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}}

按 error.code 分支处理,不要匹配 HTTP 状态码的文本,也不要依赖 message 的措辞——它是给人看的,可能变。

error.codeHTTP意味着怎么处理
invalid_argument400参数不合法,或请求体里有未知字段读 message 里点名的字段,修请求
unauthenticated401没有凭证,或凭证不被识别检查 Authorization 头
permission_denied403凭证有效,但该主体已被擦除不要重试。换一个人名的凭证才有意义——同一人的任何凭证都会被拦住
not_found404实体不存在,或在指定的时间点不存在确认 ID 与时间参数
conflict409幂等键复用了但内容不同换新键
unavailable503依赖暂时不可用退避重试
unsupported501该部署缺少请求依赖的后端能力不要重试,联系接入方
deadline_exceeded504服务端等待超时用原键重试
internal500服务端内部错误,不含细节退避重试,持续失败则上报
internal 永远不带内部细节。这是有意的:响应里不会出现 SQL、堆栈或模块名。接口不回传请求 ID,排障时把你发出的请求(方法、路径、请求体)和发生时间一起提供给服务方。

一个常见的 400:请求体里多了字段。

-d '{"text":"hi","tenantId":"demo"}'
# {"error":{"code":"invalid_argument","message":"proto: (line 1:13): unknown field \"tenantId\""}}

未知字段一律拒绝,不静默忽略。这是防止字段拼错被当成默认值处理,从而悄悄改变语义。

控制响应体积

召回会把实体连同全部组件一起返回,体积可能远超你的预期。三个可调的地方:

调什么效果副作用
maxEntities 下调实体条数减少可能丢掉不相关但仍有用的上下文
maxEvents 下调原文条数减少回顾历史时可用素材变少;排序靠后的记录被截掉
改问更具体的 query排序更靠前的结果更相关无

先量一下,再决定要不要调。这个命令会告诉你去重后的响应字节数:

curl -sS -G "$WM_API/v1/memories:recall" \
  --data-urlencode 'query=客户' \
  --data-urlencode 'maxEntities=20' \
  -H "Authorization: Bearer $WM_TOKEN" | wc -c
没有分页游标。想拿「更多」只能提高 maxEntities,而它硬上限是 100,超过会被静默替换成缺省值 20。一次拿不完时,改用更精确的实体 ID 逐个直取。

擦除与抑制

DELETE /v1/users/me/data 执行的是主体擦除,不是「隐藏」。它做三件事:

  1. 删除该主体名下的记忆与结构化状态。包括原文、由它抽出的组件、写入回执。
  2. 把该主体写入抑制名单。之后用同一凭证调用任何接口都返回 403 permission_denied。
  3. 阻止旧数据复活。上游若重放历史事件,抑制名单会拦住它们,不会把已删除的内容写回来。
擦除请求写入抑制名单,之后的调用与重放都被拦住 流程自上而下:DELETE /v1/users/me/data 先删除该主体的记忆与组件,再写入抑制名单。之后两条路径都返回 permission_denied:一条是同一凭证的新请求,另一条是上游重放历史事件。 DELETE /v1/users/me/data 删除记忆与组件 原文 / 组件 / 回执 写入抑制名单 主体指纹,不含明文 同一凭证的新请求 召回 / 读取 / 再写入 上游重放历史事件 不会把数据写回来 403 permission_denied · 该主体已被擦除
抑制是这个接口和「删表」最重要的区别。没有它,任何一次历史重放都会让已删除的数据重新出现。

什么时候该用它

  • 用户行使删除权,要求不再保留其任何记录。
  • 测试环境清理,用专用凭证反复验证接入流程。

什么情况下不该用它:只是想清掉几条错误的记忆。擦除是主体级的、不可撤销的,没有「删这一条」的操作。

写错了的正确做法是再写一条更正后的陈述。原文是追加的,旧的那条不会消失,两条都留在 memories 里;结构化这一侧由抽取按较新的陈述更新组件。对外接口没有让你直接指定 validToMs 或删除单个组件的入口,状态怎么切分由服务端决定。

擦除后的 403 是粘性的。抑制状态与你擦除时使用的主体绑定,不会因为再发一次 DELETE 而解除。需要恢复接入,得由服务方在抑制名单层面处理。

上线检查清单

接入完成准备上线时,逐项确认:

项确认什么
凭证管理凭证不写进客户端代码;每个终端用户对应独立凭证,不要在多人之间共享
传输安全只走 HTTPS
幂等键写入请求都有稳定键;重试路径复用原键
时区文本含相对时间时必传 timezone
错误处理按 error.code 分支,未匹配的按可重试处理
体积对典型请求量过响应字节数,据此设定 maxEntities
擦除有面向用户的数据删除入口,且明确告知不可撤销
大整数JSON 解析不会把 "1794968245880" 当数字处理
未知字段确认客户端不会给请求体加多余字段,否则会收到 400