语义 ID - Entity Enricher 文档

语义 ID

一次次丰富同一类实体，你会不断重新发现相同的现实事物——同一家公司、同一种药物副作用、同一个人——每次却用略有不同的措辞来描述。语义 ID 是 Entity Enricher 根据对象的关键字段为其分配的稳定、组织范围内的标识符，因此这些近似重复项会归并为单一身份，供你进行分组、去重和联接。

问题所在：同一事物，不同说法

对象的标识由其关键字段构建——可以是一个或多个。两个示例：

一个密钥

以 `name` 为键的副作用

在不同运行和语言中，它显示为 Headache、Céphalée 和 Cephalalgia。一个关键字段，三种拼写，同一个真实概念。

两个密钥

以`名称` + `国家/地区`为键的公司

Acme Inc. · United States 和 Acme Incorporated · United States 是同一家公司 — 而 Acme Inc. · Germany 则是另一家。第二个键用于消除歧义；这就是一个对象可以携带多个键的原因。

纯字符串匹配对这些情况全部失效；而人能判断哪些是同一个。语义 ID 会自动编码这一判断。

什么是 semantic ID

•对象上的单个 string 属性（默认命名为 id），保存一个不透明且稳定的标识符。
•稳定且按 organization 隔离——同一个现实世界的事物，仅在您的 organization 范围内，跨 enrichment、batch 和时间都会解析为相同的 ID。
•自动分配，绝不由 LLM 分配 — 它在丰富后的处理阶段计算得出，因此模型无法凭空捏造。它是一个直通（preserve）字段：始终为字符串，绝不是键，绝不是多语言，每个对象最多一个。
•允许用于任何对象——整个实体（根）、一对一嵌套对象（例如manufacturer），或数组中的每一项（例如每个side_effect）。

工作原理

模型返回结果后，Entity Enricher 会分四步解析每个语义 ID——从成本最低的开始：

撰写身份标识文本

将 该对象的所有关键字段——以及它所包含的任何 一对一嵌套对象 的键——合并为单个字符串，使用你的主要语言。数组内的项不会被纳入：每个数组项拥有自己的标识。文本会被规范化（转为小写、去除括号内容、折叠空白）以缩小无关紧要的差异。

查找完全匹配项

如果该完全相同的规范化文本此前在你的 organization 中出现过，则会立即复用其现有 ID——无需 model 调用，无成本。

嵌入并比较

否则，文本会被嵌入，并通过向量相似度按含义与同类型的现有概念进行比较——因此 “Acme Inc.” 和“Acme Incorporated”会彼此相邻。

复用或新建

如果最接近的匹配得分高于相似度阈值（默认 0.92，可按属性调整），则复用该概念的 ID。否则会生成一个全新的 ID 并存储以备下次使用。

阈值权衡：阈值越高越严格（意外合并更少）；越低越宽松（去重更激进）。当默认值 0.92 合并过多或过少时，可按 property 单独调整。

输入 ID 与生成的 ID

是否生成 ID 取决于该对象的输入中是否已存在 ID。这正是实现往返的关键：先富集一次以获取 ID，随后在后续运行中传回已知 ID，从而将新事实附加到同一身份上——更省成本且无歧义。

输入中已存在 ID → 保留（查找）

如果你发送的对象已带有语义 ID，则会被视为一次查找：ID 原样保留，record 关联到该现有概念，并且不进行嵌入——无成本，也无匹配或生成。你是在告诉平台“该对象已在我们的数据库中被标识”。

输入中无 ID → 已生成

如果对象没有语义 ID，平台会通过上述四个步骤生成一个。此后该 ID 将成为该对象在你 organization 数据库中的稳定标识符。

存在但无法识别的值（并非真正的概念 ID）将被忽略，转而生成一个 ID。

如何启用

选择一个嵌入模型（每个组织仅需一次）

所有者在模型管理中选择一个支持嵌入的模型作为组织的默认嵌入模型。它几乎不可更改：一旦存在概念，就只能清除而无法切换（存储的向量在不同模型间无法比较）。若未设置，则语义 ID 将直接被跳过。

为架构添加语义 ID

两种方式，均在架构编辑器中：

生成时自动创建 — 勾选“为类型生成语义 ID”；每个带有键的对象（自身的键，或某个一对一嵌套对象上的键）都会获得一个，包括根实体。
手动——在任意对象或实体页脚上使用“+ 添加语义 ID”控件。

每次充实时，解析会消耗少量嵌入用量（与任何模型调用一样按量计费）。精确匹配缓存让重复调用免费，输入提供的 ID 则不产生任何费用。

这些 ID 出现在何处及如何使用

解析出的 ID 会出现在充实输出的 JSON 中（每个对象上的 id 字段）以及记录详情的语义概念中。可用它们来：

•跨批次并随时间对行进行去重。
•为您的数据仓库或 CRM 构建稳定的连接键。
•协调在不同日期或不同语言中出现的同一实体。

对多模型融合形成补充

融合会在单次运行内协调各模型之间的分歧；语义 ID 则跨多次运行和时间协调同一实体。两者协同工作。