尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
实体图
Loom 在同一个 ClickHouse 数据库中,将实体图与记忆行并列保存。实体是节点。同一条记忆中提到的两个实体之间存在共现边;抽取过程还会将带类型的 (subject, relation, object) 三元组作为第二组边加入图中。该图是记忆的投影:每条边都可以追溯到生成它的行。可以用它来回答向量搜索无法回答的问题,例如“哪些内容与 billing service 相关联”。
实体社区默认关闭(LOOM_ENTITY_COMMUNITIES_ENABLED)。
图中保存的内容
| 表 | 保存内容 |
|---|---|
loom.entity_edges (+ entity_edge_memories, entity_edge_rows) |
每条共现观察记录一行(co_occur = 1),读取时按实体对求和。包含每个实体对的来源键,以及指明该实体对的行和值。 |
loom.entity_triples (+ entity_triple_memories, entity_triple_rows) |
带有 confidence 的类型化三元组,抽取模型记录为 adapter_name。包含每个三元组的来源键,以及陈述该三元组的行和值。 |
loom.entity_degree |
每个实体的共现度总数(SummingMergeTree),枢纽规则会读取它。 |
loom.entity_canonical_map |
提及文本 → 规范实体。 |
loom.entity_communities |
每个实体在各层级上的社区 id。 |
loom.entity_vectors, loom.entity_summaries |
搜索中的实体分支所读取的嵌入。 |
loom.derived_facts |
带单位和日期的数值事实,用于搜索中的计算型答案。 |
memory.link edges |
由 agent 或用户断言的边(supports、depends_on、caused 等),由图模式搜索读取。 |
边和三元组带有 valid_from / valid_to(来自源记忆的 valid_at / valid_to)以及用于使其失效的 invalid_at 时间戳。带 as_of 的读取只对在该时刻有效的观察记录求和。
图存放在 ClickHouse 中,这样边与其所属的行在同一个请求中写入,由同一个 saga 擦除,并且无需网络往返即可与记忆进行关联查询。代价是:一次遍历由一系列有界的聚合查询组成,因此每次遍历都有上限。
图的构建方式
记忆行最先写入,图中的行是它的投影。投影失败会记录到 loom.memory_projection_failures 并重试,但只有当该行仍保留投影失败时的那个值时才会重试。投影失败从不会导致写入失败。high 敏感级别的批量条目不投影任何内容;high 级别的 memory.set 只投影写入方声明的实体之间的边,从不投影其文本。
- 实体。 写入方在
memory.set中传入entities,或由memory.set_from_messages提取实体。entity_extractorworker(LOOM_ENTITY_EXTRACT_ENABLED,默认开启)会在写入路径之外,为未带实体写入的行打上标签;它需要真实的 LLM provider。实体文本在写入和读取时按相同方式规范化(去掉冠词和所有格,中心名词转为单数,第一人称映射为user),因此 "The Billing Service's" 和 "billing service" 是同一个节点。commit:<sha>或error:<name>形式的名称是标识符,规范化方式相同,但不会转为单数:error:Timeouts,或放在反引号或引号中的同一名称,对应的节点是error:timeouts。冒号后紧跟空白或标记符号(Error: the build failed、error:`Timeouts`)时,则视为普通文本。代词、感叹词、轻动词和两个字符的 token 会被丢弃;按原样书写或规范化之后(NFKC 会把fi转为fi)超过 256 个字符的文本也会被丢弃,写入时和在entity_filter中都是如此;点写入则会拒绝这样的事实主语或宾语,而不是丢弃。 - 边。 一条记忆的实体两两配对,每一对成为一行观察记录,每条记忆最多 100 对。
- 三元组。 提取出的事实的关系会成为三元组,每条记忆最多 8 个。动词规范化为
lower_snake形式。namespace.register_ontology(管理员)可以注册首选的实体类型、动词和属性,并指定基数。集合之外的名称会产生ontology_warnings;不会拒绝任何内容。 -
取代会关闭三元组。 当一行取代另一行时,旧行中新行未予证实的开放三元组会获得
invalid_at。对于one关系(雇主、所在地),较新的值保持有效,较旧的值在较新的值开始时关闭。如果在关闭过程执行期间有写入再次声明较旧的值,则它保持开放。- 各值按起始日期排序(未标注日期的值以到达时间为起始),再按精确到微秒的到达顺序排序,因此并发写入方会就同一个当前值达成一致。在同一次写入中,后声明的值更新。
- 在同一次写入中,过去时态的无日期值(
lived_in、worked_at)比有日期的值更旧,与顺序无关:"user lived_in london" 与 10 月 1 日起的 Paris 并列时,Paris 保持有效。 - 每个值以其最新的一行为准:"London from Oct 15, Paris from Oct 14, London from Oct 13" 的结果是 London 保持有效。
- 带有自身结束时间的值("London until December")绝不会被提前关闭。它会与较新的值并存有效,直到该结束时间。
- 撤销(
memory.restore)会使恢复的值从恢复时起成为当前值,或从事实自身较晚的起始时间起生效("moving to Berlin on Dec 1")。另一个值会关闭,但其行仍保持有效。日期更晚的值仍然优先,撤销之后声明的值也是如此。来回撤销不会增加权重。 - 失败的关闭操作会按引发它的那次写入或撤销发生时的状态重放,因此之后声明的值仍保持有效。
撤销如何重述其事实和边、如何为它们加权以及如何重放,见记忆架构。
点写入(memory.set、memory.update、memory.update_by_id)会写入调用方在 relations 中传入的三元组,最多 8 个,可通过 HTTP 以及 SDK 的类型化操作使用(不在 MCP 列表中);它不做任何提取。自动提取在批量路径上运行:memory.set_from_messages,或提供关系的批量写入方。使用默认的 fake provider 时,只有你传入的实体会形成边。
操作
| 操作 | 角色 | 回答的问题 |
|---|---|---|
facts.list |
viewer | 按 subject、object、relation(AND)或 entity(任一端)过滤的三元组。 |
facts.related |
viewer | 与某个实体共现的实体,按强度从高到低排列,并指明种子位于哪一侧。 |
facts.traverse |
viewer | 从种子出发 N 跳以内的邻域。 |
facts.path |
viewer | 在 max_hops 以内,两个实体之间最短的边链。 |
facts.expire_by_adapter |
admin | 将某个提取器写入的三元组标记为墓碑。记忆保留。 |
memory.search(graph 模式) |
viewer | search_mode="graph":返回与查询中的实体相距一跳的命中(搜索与问答)。 |
memory.related |
viewer | 与给定记忆共享实体的记忆。 |
memory.timeline |
viewer | 某个实体的记忆,按时间顺序排列(entity=…)。 |
memory.backlinks |
viewer | 与某一行共享实体的记忆。 |
namespace.taxonomy |
viewer | 命名空间中的顶层实体,以及已计算出的社区。 |
字段列表:事实、记忆。在 graph 模式之外,entity_filter 会提升与指定实体相关的行的排名,搜索的实体通道还能找到那些以其他措辞提到查询中实体的行(检索与排序)。
facts.list
不加过滤时,返回按 co_occur 排序的前几个三元组;sort_by="recency" 则按 last_seen 排序。
| 字段 | 作用 |
|---|---|
include_sources |
为每个三元组附加最多约十个来源记忆键。 |
include_source_status |
读取每个来源行;当三元组仍为开放状态、但其背后的所有行都已被取代时,将其标记为 stale。 |
provenance |
extracted(两端都在源文本中)、inferred,或 facet(Loom 生成的导航边)。 |
as_of |
保留在该时刻有效的三元组。 |
facts.traverse
遍历先裁剪再展开。每一跳把当前边界作为一次查询发出,在有效期窗口内按实体对汇总观测次数,丢弃已访问的实体,并为每个父节点保留最强的 top_k_per_hop 个实体对。第 h 跳的边界最多有 K^h 个实体。每个实体只在最先到达它的那一跳报告一次,并经由其最强的父节点,因此结果可以画成一棵树。
如果用一次递归查询先展开全部再裁剪,就会把整个邻域物化出来;在大型命名空间上,三跳遍历可能超出 ClickHouse 的内存限制。逐跳裁剪使开销受限于结果的大小。
| 字段 | 默认值 | 作用 |
|---|---|---|
max_hops |
2(1–4) | 遍历深度。 |
top_k_per_hop |
20(最大 100) | 每一跳为每个父节点保留的子节点数。 |
min_co_occur |
1 | 每个实体对的最小观测次数。 |
max_nodes |
400(最大 5,000) | 硬性上限;达到时 truncated=true。 |
as_of |
未设置 | 保留在该时刻有效的观测。 |
labeled / relations |
false / 未设置 | 遍历带类型的三元组(全部,或仅限这些动词);节点带有 via_relation、via_direction、via_provenance。 |
hub_degree |
0(关闭) | 总度数不小于该值的节点为枢纽。 |
hub_share |
LOOM_FACTS_TRAVERSE_HUB_SHARE(0.01) |
当到达某节点的边占其度数的比例不超过该值时,该节点为枢纽。 |
rank_by |
LOOM_FACTS_TRAVERSE_RANK_BY(cosine) |
每跳裁剪依据:co_occur、specificity(via_co_occur / degree)或 cosine(via_co_occur / sqrt(degree))。 |
每个节点会报告 hop、cumulative_weight、via_co_occur、path(从种子出发的链)、valid_from / valid_to、degree,以及存在社区时的 community_id。节点先按跳数排序,再按权重排序。
枢纽。 泛化的实体("user"、"pr")会与所有内容共现。枢纽会被报告(hub: true,并列在 hubs 中),但不会被展开。种子始终会展开,因此要查看某个枢纽的邻域,可以把它作为种子。hub_share 是默认规则,因为它不依赖命名空间的度数尺度。hub_degree 则因命名空间而异;设置之前请先查看度数的长尾分布。
facts.path
在相同的边上做有界的双向广度优先搜索,在中间相遇。max_hops(1–4,默认 3)限定总长度。结果包含 found、path,以及带有每个实体对的 co_occur 及有效期的 edges。truncated=true 表示结果可能不完整。found=false 且 truncated=false 表示在 max_hops 以内没有连接。
示例
from loom import Agent
async with Agent("dev", "local", "sre-bot", base_url="http://localhost:7777") as agent:
await agent.memory.set(
"billing/depends_on",
"The billing service reads invoices from the ledger database.",
entities=["billing service", "ledger database"],
)
walk = await agent.facts.traverse("billing service", max_hops=2, top_k_per_hop=10)
for node in walk["nodes"]:
print(node["hop"], " > ".join(node["path"]), node["via_co_occur"])
route = await agent.facts.path("billing service", "ledger outage")
print(route["found"], route["path"], route["truncated"])
通过 HTTP,可以按图在过去某一时刻的状态进行遍历:
curl -s localhost:7777/v1/facts.traverse -H "Authorization: Bearer $LOOM_API_KEY" \
-H 'content-type: application/json' \
-d '{"org":"dev","namespace":"local","seed_entity":"billing service","max_hops":2,"as_of":"'"$AS_OF"'"}'
通过 MCP,调用 loom_op,并设置 op="facts.traverse"。
维护图谱
| 任务 | 方法 |
|---|---|
| 回滚某个有问题的提取器产生的三元组 | facts.expire_by_adapter(adapter_name=…, max_confidence=…)。记忆会保留。 |
| 导出图谱 | loom entity-export --org O --namespace N --format graphml(或 jsonld;--all 会包含已失效的边)。 |
| 将实体聚类为社区 | 设置 LOOM_ENTITY_COMMUNITIES_ENABLED=true(见下文)。 |
| 查看图谱 | 控制台的 Graph 视图(控制台)。 |
entity_communities worker 会按命名空间运行标签传播,并将结果写入 loom.entity_communities,供 namespace.taxonomy、图模式扩展和 community_id 读取。它覆盖启用了整合的命名空间,以及在最近 LOOM_ENTITY_COMMUNITIES_WALKED_DAYS(14)天内被遍历过的命名空间。它会先丢弃度数最高的实体(LOOM_ENTITY_COMMUNITIES_HUB_DROP_FRACTION),当某个社区包含的实体超过 LOOM_ENTITY_COMMUNITIES_GIANT_SHARE 所占比例时,会将该丢弃比例加倍,这样通用 token 就不会把整个图谱合并成一个社区。
设置
| 设置 | 章节 |
|---|---|
LOOM_FACTS_TRAVERSE_HUB_SHARE, …_RANK_BY |
命名空间健康度、知识图谱、社区 |
LOOM_ENTITY_COMMUNITIES_* |
同一章节。 |
LOOM_ENTITY_EXTRACT_* |
整合 |
LOOM_MEMORY_SEARCH_GRAPH_SEED |
记忆搜索 |
限制
- 共现不等于关系。 同一条记忆中出现的两个实体会被关联起来,无论句子本身表达的是什么。如果关系很重要,请使用类型化三元组(
labeled、relations)或memory.link。 - 图的质量取决于实体的质量。 没有实体的行不会产生任何边,直到
entity_extractorworker 处理到它们。 - 遍历有范围限制。 在断定两个实体没有连接之前,请先查看
truncated。 - 边可能滞后于被取代的行。
facts.list(include_source_status=true)会显示仍处于未关闭状态的三元组。 - 有效性指有效时间。
as_of读取的是事实成立的时间,而不是 Loom 得知该事实的时间。
相关内容
- 搜索与提问:graph 模式。
- 写入记忆:传入
entities。 - 提取:提取出的实体和三元组的来源。
- 记忆架构:投影写入器。
- Workers 参考。