语义 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 生成 — 它在丰富化之后的处理过程中计算得出，因此模型无法凭空捏造它。它是一个直通字段（输入值原封不动地流经）：始终是字符串，绝不作为键，绝不保留，绝不多语言，每个对象中至多一个。
•允许用于任何对象——整个实体（根）、一对一嵌套对象（例如manufacturer），或数组中的每一项（例如每个side_effect）。

工作原理

模型返回结果后，Entity Enricher 通过六个步骤解析每个语义 ID — 从最省成本的开始。嵌入之前的四个步骤都是纯文本比较，因此在这些步骤中确定的身份完全不产生费用：

撰写身份标识文本

用你的主要语言，将标识对象自身的键字段拼接成一个字符串。本身即为独立实体的嵌套对象会被排除在外：它的键标识的是它自己，而不是引用它的对象，并且引用同一实体的每个同级字段都会带有相同的值 —— 共用同一发射场的两个任务读起来几乎一样，有被合并为一条的风险。仅用于分组字段的嵌套对象仍会参与；若你自行添加了关联实体的键，它同样会参与。数组中的元素永远不会被纳入：每个数组元素都有自己的标识。Schema 编辑器的标识参与项列表准确展示了哪些值组成该文本，并可让你重新排序或更改它们 —— 以相同顺序选取相同参与项的 Schema 会生成完全相同的 ID。该文本会被规范化（转为小写、去除括号内容、合并空白），以缩小无关紧要的差异。如果这些键字段全部返回为空，就无从标识该对象，也无法分配 ID —— 因此该对象会被移除，而不是保留为一个无法用于分组、联接或去重的匿名对象：嵌套对象在其父对象中变为 null，列表中的元素则会从列表中删除。被增强的实体本身永远不会被移除，只是没有 ID。

查找完全匹配项

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

如果有代码，则按代码匹配

当某个标识键是代码时——即受模式约束的字段，或示例看起来像标识符的字段——它会被优先组合并单独比较。代码完全一致即可立刻确定标识，无论周围文字如何表述，因此 LC-39A 能统一其余文本的各种写法。同样重要的是反方向也成立：代码不同会否决嵌入步骤本来会接受的合并，因为标识符不同的两个事物就是两个事物，无论它们读起来多么相似。

按相同词语匹配，不论顺序

在花费一次嵌入之前，先把词本身作为集合来比较：如果一段文本的词被另一段包含，它们就是同一身份的不同长度写法 — “Boeing” 与 “The Boeing Company”。这恰好捕捉到被嵌入判定为相距甚远的繁简差异，而且完全免费：与精确文本步骤一样，此处命中就意味着不调用嵌入、不产生费用。

嵌入并比较

否则，文本会被嵌入，并借助向量相似度按含义与相同概念类型（默认为实体类型名称——可在编辑器中覆盖，从而让名称不同的 schema 共享同一概念空间）下的现有概念进行比较——因此“Acme Inc.”和“Acme Incorporated”会彼此相邻。

复用或新建

如果最接近的匹配得分高于相似度阈值（默认 0.92，可按属性调整），则复用该概念的 ID。否则会生成一个全新的 ID 并保存以供下次使用。有一种例外会推翻高分：当两段文本用词相同但计数不同时——“第二级”和“第三级”——它们会被视为不同的事物，因为计数正是区分二者的关键。同一个数字的两种写法（2 和II）仍会匹配。

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

输入 ID 与生成的 ID

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

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

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

输入中无 ID → 已生成

如果对象没有语义 ID，平台会按上述步骤生成一个。此后该 ID 就成为该对象在你所在组织数据库中的稳定标识符。

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

如何启用

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

所有者在设置 → 组织 → 默认值中选择一个支持嵌入的模型作为组织的默认嵌入模型（该设置受套餐限制；哪些模型支持嵌入请参见模型与定价）。已存储的向量在不同模型之间不可比较，因此一旦已存在概念，该设置本身就只能清除 — 切换需在语义 ID 页面以迁移方式运行，它会重新嵌入每个概念并保留其 ID。若未设置模型，语义 ID 会被直接跳过。

为架构添加语义 ID

两种方式，都在工作流编辑器中：