LTM 使用指南
这一页回答接入时最常被问到的几件事:LTM 和知识库有什么区别、会召回什么、依据是什么、哪些东西可以自己控制,以及怎么按业务标签区分记忆。排查具体问题见 LTM 常见问题,费用估算见 LTM 成本估算,字段级契约见 LTM API 参考。
和知识库的区别
一句话:知识库回答"产品和世界是怎样的",LTM 记住"这个用户是怎样的"。
| 企业知识库(RAG) | LTM | |
|---|---|---|
| 数据从哪来 | 管理员导入的文档 | 用户的对话(Event),后台自动提炼 |
| 存什么 | 文档切片 | 画像字段、事实、会话摘要 |
| 谁能看到 | 所有用户共享 | 每个用户一份(按 actor_id);Space 级共享事实要显式开启才读得到 |
| 怎么更新 | 重新导入 | 写入后自动提炼:重复的跳过,过时的更新,矛盾的撤回 |
| 怎么召回 | 通常在大量切片里做混合检索,再 rerank | 候选很少,按类型和新旧组装,语义检索作补充 |
两者可以一起用:先用 LTM 恢复用户背景,再用知识库查产品和外部事实。
会召回什么
- 用户画像(Profile):按 Space 的字段表提取;默认记录回答语言、详略、语气等交互偏好。
- 关键事实(Facts):按主题归类;设置
include_shared: true时会带上 Space 级共享事实。 - 会话摘要(Summary):最近几次会话的摘要。
- Reflection 和活动洞察:Reflection 是对用户的整体画像报告;活动洞察是多次会话里反复出现的行为,每条至少来自两次不同的会话。两者需要先在 Space 里启用并生成,Context 只在
sections里显式请求时才返回。
Space 设置了记忆保留期时,超过期限的记忆不会被召回,见记忆保存多久。
召回依据
没有单独的 rerank 模型。召回分两路,托管 Chat 会同时使用两路。
Context:不带问题
通常在会话开始时调用一次。不调用模型,也不做向量检索:
- 按固定顺序组装:画像、事实摘要、会话摘要、Reflection、活动洞察;可以只请求其中几部分,但顺序不变;
- 同一类按更新时间取最新;
- 按 token 预算截断,预算不够时排在后面的部分先被裁掉。
Search:带问题
每轮按需调用:
- 把问题转成向量,在按用户、记忆类型、主题、时间和元数据过滤后的范围内,按余弦相似度取 top-k;
- 只搜事实和会话摘要,用户画像不参与语义检索;
- 结果带
confidence和abstain_recommended。最高分低于阈值(默认 0.65,约等于余弦 0.3),或最高分没有明显高于其余结果时,abstain_recommended为true,建议不使用这批结果,避免把不相关的记忆交给模型。
需要更强的排序时,可以把 Search 的结果交给自己的 rerank 再排一次。
托管 Chat
每轮先召回,再调用主模型:
- Context 和 Search 两路都走,Search 的检索词直接用用户最新一条消息的原文,不经过模型改写;
- 纯图片、语音或文件的轮次只走 Context;
- 召回多少由 Space 的
managed_recall决定,默认会话简报 2048 token、带最近 3 次会话摘要,Search 取 8 条,注入总量不超过 4096 token,见托管 Chat 召回设置; - 拿到最终回答后写入一次 Event,工具调用的中间轮次不写入。
请求里的 recall 和 capture 可以分别关闭读取和写入,比如访客对话只读不写,或者评测时不把对话写进记忆。
可以控制的参数
Space 配置:决定提炼什么
完整字段见 创建 LTM Space,创建后修改见 更新 LTM Space。
| 参数 | 作用 | 说明 |
|---|---|---|
profile_schema | Profile 字段表,每个字段带提取说明 | 不传则用平台默认字段;第一条用户 Event 写入后固定,请提前设计 |
memory_strategies | Profile、Facts、Summary 各自的提炼策略 | 可以写自定义提取指令、定义 Facts 主题和 Profile 字段、单独指定模型;某一类的 enabled 留空即关闭该类;不传则三类都用平台默认策略 |
model_profile | 提炼用的模型家族 | default 是默认家族,stages 可按阶段覆盖 |
embedding_model | 向量模型 | 创建后不能修改 |
reflection_enabled | 是否允许生成 Reflection 和活动洞察 | 不传则用平台默认值 |
event_retention_days | 原始 Event 可用于提炼的天数 | 默认 90,范围 1–365;需要 CLIENT_ADMIN 权限,见记忆保存多久 |
memory_retention_days | Profile、Facts、Summary 各自的保留天数 | 默认不过期,范围 1–3650;需要 CLIENT_ADMIN 权限 |
metadata_keys | 带到 Facts 上、可用于过滤的 Event 元数据键 | 最多 5 个;只能新增,不能删除,见按业务标签区分记忆 |
managed_recall | 托管 Chat 每轮召回的条数和预算 | 只作用于托管 Chat,默认值和范围见托管 Chat 召回设置 |
facts_session_history_events | 提炼事实时带上的同一会话前文 Event 个数 | 默认 2,范围 0–50,0 表示不带,见提炼时会看前面的对话吗 |
写入:决定记什么
完整字段见 写入 LTM Event。
| 参数 | 说明 |
|---|---|
owner_type | 默认 actor,写给某个用户;space 写成整个 Space 共享,只提炼事实,此时不传 actor_id |
actor_id | 用户 ID,owner_type 为 actor 时必填;建议使用不含个人信息的内部 ID |
session_id | 必填;同一段会话的后续消息用同一个值。会话摘要按它归集,提炼事实时也会把同一会话之前的几轮作为上下文,见提炼时会看前面的对话吗 |
messages | 这次新增的对话轮次,不要重复提交整段历史;只处理文本,提炼只看 user 和 assistant |
metadata | 标量业务字段,最多 32 个;Space 声明的元数据键会带到提炼出的 Facts 上,见按业务标签区分记忆 |
event_timestamp | 对话实际发生的时间,可选,默认为接收时间 |
Idempotency-Key 请求头或 idempotency_key | 可选,建议传;同一个 key 重试同一请求会返回原 Event,不会重复写入;同一个 key 配不同内容返回 409 |
读取:决定召回什么
Context(获取有界 LTM 上下文)
| 参数 | 说明 |
|---|---|
actor_id / include_shared | 读哪个用户;只设置 include_shared: true 时只读共享事实;两者至少给一个 |
token_budget | 默认 4000,范围 512–16000 |
sections | 默认只返回画像、事实摘要、会话摘要;Reflection 和活动洞察要显式请求 |
summary_limit | 最多带几次会话的摘要,默认 5,最多 10 |
strategy_ids | 一类记忆配置了多个策略时,指定读哪些;默认读主策略 |
Search(搜索 LTM 记忆)
| 参数 | 说明 |
|---|---|
query | 检索的问题 |
actor_id / include_shared | 同 Context |
memory_type | facts 或 summary;不传则两类都搜 |
topic | 按主题精确过滤,可传多个,命中任一即可 |
created_at / updated_at | 时间范围(gte / lte);按 updated_at 过滤时,没有更新时间的记录(如会话摘要)会被排除 |
metadata | 按 Space 声明的元数据键精确过滤,最多 5 个键,需要同时满足;设置后只命中 Facts |
top_k | 默认 10,最多 50 |
abstain_threshold | 默认 0.65 |
strategy_ids | 同 Context |
托管 Chat(Chat Completions 的 turing_options.memory)
| 参数 | 说明 |
|---|---|
enabled | true 开启;false 关闭,其余配置可以留着不删 |
space_id | 必填,使用的 Space |
owner_type / actor_id | 同写入;owner_type 为 space 时不能设置 include_shared |
session_id | 必填 |
turn_id | 可选,标识这一轮;不传时按对话内容推导,同一轮重试不会重复写入 |
include_shared | 召回时带上共享事实 |
strategy_ids | 同 Context |
recall | 默认 true;false 时不召回、不注入,本轮照常写入 |
capture | 默认 true;false 时照常召回,本轮不写入 |
recall 和 capture 不能同时为 false,要整体关闭记忆请用 enabled: false。召回的条数和预算不在请求里传,见下一节。请求同时配置了 turing_options.fallbacks 时记忆整体跳过,见为什么没有效果。
托管 Chat 召回设置
托管 Chat 每轮召回多少,由 Space 的 managed_recall 决定。创建 Space 时传入,或者用 更新 LTM Space 修改;不设置时使用下表的默认值。这些值只作用于托管 Chat,直接调用 Context 和 Search 时仍按每次请求的参数。
| 字段 | 默认值 | 范围 | 作用 |
|---|---|---|---|
search_top_k | 8 | 1–50 | 每轮按问题检索的 Search 结果条数 |
abstain_threshold | 0.65 | 0–1 | Search 的弃权阈值;Search 建议弃权时(见 Search),本轮不注入 Search 结果 |
context_token_budget | 2048 | 512–16000 | 会话简报的 token 预算 |
summary_limit | 3 | 1–10 | 会话简报里最多带几次会话的摘要 |
evidence_token_budget | 4096 | 512–16000 | 注入模型的记忆总量上限,按追加给模型的整条消息计,包括外层说明和记录 ID;超出时先去掉排在后面的 Search 结果,仍然超出时整段去掉会话简报 |
context_token_budget 不能大于 evidence_token_budget,否则返回 HTTP 400 / code 1004。会话简报放进消息后还要加上外层说明,两者设得太接近时,写满的简报会被整段去掉,所以 evidence_token_budget 建议至少是 context_token_budget 的 1.5 倍(默认是 2 倍)。更新时按字段合并:只传要改的字段,某个字段传 null 恢复默认值,整个 managed_recall 传 null 全部恢复默认值。
curl -X PUT "$TURING_BASE_URL/ltm/spaces/$SPACE_ID" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"managed_recall": {"search_top_k": 12, "evidence_token_budget": 6000}}'
调大预算会增加主模型的输入 token。读取 Space 时返回当前生效的五个值;默认值也可以从 列出 LTM 模型族 返回的 defaults.space.managed_recall 读取。
按业务标签区分记忆
同一个 Space 服务多个市场、门店或产品线时,可以在 Space 上声明最多 5 个元数据键。写入 Event 时在 metadata 里带上这些键的值,从这条 Event 提炼出的 Facts 会原样带上这些值,之后:
- Search 和记忆列表可以按这些值精确过滤;
- 取值不同的 Facts 不会互相合并,比如两个市场的退货规则会各自保留。
下面以按市场区分售后规则为例。
1. 声明元数据键。创建 Space 时传 metadata_keys,或者对已有 Space 调用 更新 LTM Space:
curl -X PUT "$TURING_BASE_URL/ltm/spaces/$SPACE_ID" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata_keys": ["market"]}'
键只能新增,不能删除:之后再更新时,metadata_keys 要包含所有已声明的键,否则返回 HTTP 400 / code 1749。
2. 写入时带上市场。各市场的规则写成 Space 共享 Event,用户自己的对话也在 metadata 里带上所在市场:
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/events" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"owner_type": "space",
"session_id": "market-rules",
"metadata": {"market": "US"},
"messages": [
{"role": "user", "content": "美国市场的标准退货期限是 30 天。"}
]
}'
欧洲市场的规则用同样的方式写入,metadata 改为 {"market": "EU"}。
3. 按市场检索:
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories/search" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "退货期限是多久?",
"actor_id": "user-123",
"include_shared": true,
"metadata": {"market": "US"}
}'
结果只包含 market 为 US 的 Facts:这个用户在美国市场的事实,以及美国市场的共享规则。浏览记录时,列出 LTM 记忆 用查询参数 metadata=market:US 过滤,多个键可以重复传入。
- 只有 Facts 带这些值:设置
metadata过滤后,Search 和记忆列表只返回 Facts,Profile 和 Summary 不参与。 - Context 和托管 Chat 不过滤:它们会带上所有市场的记忆。需要在这两条路径上严格区分市场时,请为每个市场使用单独的 Space。
- 托管 Chat 写入的 Event 不带 metadata:从这些对话提炼的 Facts 不带任何键值,按
metadata过滤时不会命中,也不会和带标签的 Facts 合并;需要按标签区分时,用 Events API 写入。 - 不会回填:声明键之前写入的 Facts,以及来自不带这个键的 Event 的 Facts,都不会被过滤命中。
- 新增键会分开合并:新增一个键后,带这个键的新 Facts 不会再和之前的 Facts 合并,同一内容可能出现两条。
- 取值按字符串精确匹配:数字按解析后的值转成字符串(
1.0保存为"1.0",与1不同),布尔值保存为"true"/"false",null视为没有这个值,所以建议直接传字符串。 - 过滤 Space 没有声明的键会返回 HTTP 400 / code 1749。
直接写入记忆
需要把整理好的内容直接存成记忆时,比如在控制台里补录或修改、导入已有的用户档案、初始化 Space 共享的规则,用 批量新增 LTM 记忆 和 批量修改 LTM 记忆,不用构造对话。两个接口每次最多 100 条,逐条返回结果。
1. 新增。每条指定类型、归属、主题、内容和时间。Facts 的 topic 是所属策略的主题,Profile 的 topic 是字段名:
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories:batchCreate" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_token": "crm-import-0001",
"records": [
{"request_identifier": "r1", "owner_type": "actor", "actor_id": "user-123",
"memory_type": "facts", "topic": "project_context",
"content": "负责支付服务本季度的值班", "timestamp": "2026-11-09T11:00:00+08:00"},
{"request_identifier": "r2", "owner_type": "actor", "actor_id": "user-123",
"memory_type": "profile", "topic": "preferred_language",
"content": "中文", "timestamp": "2026-11-09T11:00:00+08:00"}
]
}'
响应的 created 按 request_identifier 列出每条的 record_id,failed 列出没有写入的记录和错误码。用同一个 client_token 重试同一个请求,不会重复写入;第一次写过的记录之后即使被删除,重试也不会把它写回来。
2. 修改。按 record_id 修改内容、Facts 的主题或元数据,从对话提炼出的记忆也能改:
curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories:batchUpdate" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{"record_id": "<record_id>", "content": "负责支付和清结算的值班",
"timestamp": "2026-11-09T15:00:00+08:00"}
]
}'
timestamp决定之后的对话能不能改它:它是这条信息成立或被说出的时间,也是记录的时间。之后提炼出的说法如果比它旧(比如修改前写入、还没提炼完的对话),改不动这条记录;更新的说法照常更新或撤回它。timestamp可以是过去的时间,但不能比服务器时间晚 5 分钟以上。- Profile 每个字段只有一个值:字段已经有别的值时,新增的这一条失败(code 1746),并返回已有记录的
record_id,请改用修改接口。 - 内容由你负责:直接写入的内容不经过提炼,"只记明确说过的、不存敏感信息"这类规则不适用。平台只检查主题或字段是否在策略里、元数据键是否已声明。
- 读取时一起返回:List、Search、Context 和托管 Chat 召回都会返回这些记录,
source_type为api;之后的对话更新了这条事实,它会变回event。修订历史会记下是谁修改的。 - 删除的记忆可能再回来:删除后,之后的对话再提到同样的内容,会重新提炼出来。
- 保留期从写入时算:导入的旧记忆不会因为
timestamp早而马上过期。