语义 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 — 从最省成本的开始。嵌入之前的四个步骤都是纯文本比较，因此在这些步骤中确定的身份完全不产生费用：

撰写身份标识文本

用你的主要语言，将对象的关键字段拼接成一个字符串。嵌套实体的关键字段也会参与其中，作为消歧依据：与另一部影片同名的电影，可凭导演姓名区分开来。另一面是，凡是引用同一关联实体的同级对象都会带有相同的值，因此当某个关联关键字段只会让同级对象看起来雷同时，请把它从参与项中移除。数组内的项永远不会被纳入：每个数组项拥有自己的身份标识。模式编辑器中的身份参与项列表会准确显示哪些值组成该文本，并允许你重新排序或更改它们 —— 以相同顺序选取相同参与项的模式会生成完全相同的 ID。该文本会被规范化（转为小写、去除括号内容、合并空白），以缩小无关紧要的差异。如果这些关键字段全部为空，就没有任何可用来标识该对象的依据，也无法分配 ID —— 因此该对象会被移除，而不是保留为一个无法用于分组、连接或去重的匿名对象：嵌套对象在其父级中变为 null，列表中的项则会从列表中删除。被富集的实体本身永远不会被移除，它只是没有 ID 而已。

查找完全匹配项

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

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

当对象自身的某个身份关键字段是编码时 —— 即受格式约束的字段，或示例看起来像标识符的字段 —— 它会被优先组合并单独比对（关联实体的编码绝不会顶替：引用该实体的每个同级对象都共享它）。编码完全一致即可立即确定身份，无论周围的措辞如何，因此 LC-39A 能把其余文本的各种写法统一起来。同样重要的是反向作用：不同的编码会否决嵌入步骤本会接受的合并，因为标识符不同的两个事物就是两个事物，无论它们读起来多么相似。

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

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

嵌入并比较

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

询问判定模型

最接近的几个概念会交给一个小型语言模型，它只回答一个问题：其中是否有任何一个指的是同一个真实事物？它看到的每个称谓都是带标签的组成部分——绝不会看到相似度分数，那只会诱使它去信赖几何距离。如果回答“是”，该 ID 会被复用，新的措辞会被记为同一概念的另一种写法，下次出现时便无需再判。如果回答“否”或无法判断，就会新建一个全新的 ID——绝不反过来，因为两行记录日后容易合并，而一行错误融合的记录则不然。

为什么用模型而不是一个数字：仅凭相似度在两个方向上都会出错。同一家船厂的两种写法可能分数相差甚远，而某种病症与其相反情形（“急性”与“慢性”）的分数却几乎相同。没有任何阈值能区分它们，只有理解词义才能做到。判定下限（默认 0.5，可按属性调整）只决定在多大范围内寻找值得询问的候选项——它从不决定身份是否相同。

输入 ID 与生成的 ID

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

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

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

输入中无 ID → 已生成

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

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

如何启用

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

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

为架构添加语义 ID

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