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 |
安全地重试
写入接口支持幂等。策略取决于你是否传了 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 | 不要。请求本身有问题 |
批量导入
没有批量写入接口,一次请求就是一条记忆。导入大批量数据时按这个顺序做:
- 给每条记录一个稳定的幂等键。用你的源系统主键,例如
crm:contact:8821。这样中断后可以从头重跑,已经写成功的会变成重放。 - 并发控制在个位数。接口没有公布吞吐承诺,稳妥做法是 4 到 8 个并发,观察延迟与错误率再调整。
- 先跑 100 条看抽取质量。抽不出来、抽错了的信息,在这一步就能发现,而不是等全量写完再去回溯。
- 记录失败清单。把 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
处理错误
所有错误响应共用同一个信封,没有例外:
{"error": {"code": "invalid_argument", "message": "invalid argument: text must be 1..8192 bytes"}}
按 error.code 分支处理,不要匹配 HTTP 状态码的文本,也不要依赖 message 的措辞——它是给人看的,可能变。
| error.code | HTTP | 意味着 | 怎么处理 |
|---|---|---|---|
| invalid_argument | 400 | 参数不合法,或请求体里有未知字段 | 读 message 里点名的字段,修请求 |
| unauthenticated | 401 | 没有凭证,或凭证不被识别 | 检查 Authorization 头 |
| permission_denied | 403 | 凭证有效,但该主体已被擦除 | 不要重试。换一个人名的凭证才有意义——同一人的任何凭证都会被拦住 |
| not_found | 404 | 实体不存在,或在指定的时间点不存在 | 确认 ID 与时间参数 |
| conflict | 409 | 幂等键复用了但内容不同 | 换新键 |
| unavailable | 503 | 依赖暂时不可用 | 退避重试 |
| unsupported | 501 | 该部署缺少请求依赖的后端能力 | 不要重试,联系接入方 |
| deadline_exceeded | 504 | 服务端等待超时 | 用原键重试 |
| internal | 500 | 服务端内部错误,不含细节 | 退避重试,持续失败则上报 |
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 执行的是主体擦除,不是「隐藏」。它做三件事:
- 删除该主体名下的记忆与结构化状态。包括原文、由它抽出的组件、写入回执。
- 把该主体写入抑制名单。之后用同一凭证调用任何接口都返回
403 permission_denied。 - 阻止旧数据复活。上游若重放历史事件,抑制名单会拦住它们,不会把已删除的内容写回来。
什么时候该用它
- 用户行使删除权,要求不再保留其任何记录。
- 测试环境清理,用专用凭证反复验证接入流程。
什么情况下不该用它:只是想清掉几条错误的记忆。擦除是主体级的、不可撤销的,没有「删这一条」的操作。
写错了的正确做法是再写一条更正后的陈述。原文是追加的,旧的那条不会消失,两条都留在 memories 里;结构化这一侧由抽取按较新的陈述更新组件。对外接口没有让你直接指定 validToMs 或删除单个组件的入口,状态怎么切分由服务端决定。
DELETE 而解除。需要恢复接入,得由服务方在抑制名单层面处理。上线检查清单
接入完成准备上线时,逐项确认:
| 项 | 确认什么 |
|---|---|
| 凭证管理 | 凭证不写进客户端代码;每个终端用户对应独立凭证,不要在多人之间共享 |
| 传输安全 | 只走 HTTPS |
| 幂等键 | 写入请求都有稳定键;重试路径复用原键 |
| 时区 | 文本含相对时间时必传 timezone |
| 错误处理 | 按 error.code 分支,未匹配的按可重试处理 |
| 体积 | 对典型请求量过响应字节数,据此设定 maxEntities |
| 擦除 | 有面向用户的数据删除入口,且明确告知不可撤销 |
| 大整数 | JSON 解析不会把 "1794968245880" 当数字处理 |
| 未知字段 | 确认客户端不会给请求体加多余字段,否则会收到 400 |