跳到主要内容

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 预算截断,预算不够时排在后面的部分先被裁掉。

每轮按需调用:

  • 把问题转成向量,在按用户、记忆类型、主题、时间和元数据过滤后的范围内,按余弦相似度取 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_schemaProfile 字段表,每个字段带提取说明不传则用平台默认字段;第一条用户 Event 写入后固定,请提前设计
memory_strategiesProfile、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_daysProfile、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_typefacts 或 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)

参数说明
enabledtrue 开启;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_k81–50每轮按问题检索的 Search 结果条数
abstain_threshold0.650–1Search 的弃权阈值;Search 建议弃权时(见 Search),本轮不注入 Search 结果
context_token_budget2048512–16000会话简报的 token 预算
summary_limit31–10会话简报里最多带几次会话的摘要
evidence_token_budget4096512–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 早而马上过期。
自助排查