验证规则 - Entity Enricher 文档

验证规则

八条校验规则保障模式质量。它们在 AI 模式生成组装出结果后由代码执行——为一条本已逐步自我纠错的流水线提供最后一道安全网。

自我纠正的工作原理

纠错发生在出错的地方,而不是等到最后。生成过程是一系列职责单一的小型调用,每次调用都自带校验器:它检查该次调用的结果,保留其中有效的部分,只针对仍然缺失的内容重新提问。因此,分片作答的模型会逐步收敛,而不必从头再来。

纠正流程

步骤答案一个具体的小问题——比如一批属性的标记,或某个专业领域的描述
校验器合并有效条目会被累积;不可用的条目会被单独丢弃,绝不会让整个批次失去已得到的正确结果
如果不完整重试只索要仍然缺失的路径——该步骤最多尝试 3 次
然后降级剩余的空缺会以确定性方式填补并在记录上注明,因此弱模型损失的是描述质量,而不是模式
组装以下 8 条规则会在模式完成后作为最后一道检查运行

只有两个步骤会直接导致生成失败:为实体命名,以及将属性分派到专业领域。其余步骤都有确定性回退方案,这正是小模型在此可用的原因。

生成与编辑规则

并非所有规则都同时适用于 schema 生成和 AI 编辑。与输入数据进行比较的规则在编辑期间会被跳过,因为您可能有意添加或删除字段:

范围已应用的规则原因
生成全部 8 条规则输入数据可用于比较
AI 编辑仅规则 2、3、4、5无输入数据;用户可能有意修改结构

8 条规则

规则 1

专业领域数量

范围:仅生成

专业领域的数量不得超过根据你的属性数量计算出的最大值。这可以防止 AI 为小型 schema 创建过多细粒度的领域。

错误示例: Too many expertise domains: 6 defined, maximum is 3

最大值按 floor(property_count / 6) 计算,最小为 1。具有 12 个属性的 schema 最多允许 2 个领域。

规则 2

至少一个属性

范围:两者

每个 schema 都必须至少定义一个属性。空的 schema 无法用于扩充。

错误示例: Schema must have at least one property

这可以捕获 AI 生成了有效 JSON 结构但忘记包含任何实际字段的情况。

规则 3

有效的 JSON Schema 类型

范围:两者

每种属性类型都必须是标准 JSON Schema 类型之一:string、number、integer、boolean、array、object 或 null。

错误示例: revenue: invalid type 'float'

AI 有时会臆造出“float”“decimal”或“date”等类型。此规则会捕捉这些情况,并要求更正为有效类型。

规则 4

$ref 目标存在

范围:两者

每个 $ref 都必须指向存在的对象:#/$defs/... 指向实体定义,#/$enums/... 指向值集。悬空引用会破坏充实流程。

错误示例: manufacturer: $ref '#/$defs/Company' references undefined definition

这两个命名空间是相互独立的:#/$defs/ 引用表示与嵌套实体的关系,而 #/$enums/ 引用则将文本属性限制为一组封闭的允许值列表。每个引用都必须在各自的块中有匹配的条目。

规则 5

专业领域键已存在

范围:两者

每个属性的专业领域值都必须与已定义的专业领域之一匹配。这可以防止拼写错误和不一致。

错误示例: revenue: expertise 'finance' not in defined domains: ['financial_analyst']

AI 可能会使用“finance”而非已定义的“financial_analyst”键。此规则会捕捉这种不匹配,以便 AI 进行更正。

规则 6

需要专业领域

范围:仅生成

非对象、非保留的属性必须分配 expertise domain。这可确保每个可 enrich 的字段都由专门的领域来处理。

错误示例: revenue: expertise is required for non-object types

对象类型无需检测,因为其子属性各自携带自身的 expertise domain。已保留的字段无需检测,因为它们会原样传递。

规则 7

类型与输入数据匹配

范围:仅生成

每个属性的 schema 类型必须与你输入数据中对应值的实际 Python 类型相匹配。

错误示例: revenue: type mismatch - input is number but schema says 'string'

如果您的输入包含 "revenue": 42.5,则 schema 必须使用类型 "number" 或 "integer",而不是 "string"。验证器很灵活:它接受用 "number" 表示整数,反之亦然。

规则 8

所有输入属性均已提供

范围:仅生成

输入数据中的每个键都必须作为一个属性出现在生成的 schema 中。这可以防止 AI 悄悄丢弃字段。

错误示例: Missing property from input: 'headquarters'

如果您的输入 JSON 包含 "headquarters" 键,则生成的 schema 必须包含它。这可确保完整覆盖您的数据。

类型推断

规则 7(类型匹配)使用自动类型推断,将您的输入值与 schema 声明的类型进行比较。该推断较为灵活,以避免误报:

输入值推断的类型同时接受
true / falseboolean(仅布尔值)
42integernumber
3.14numberinteger
"hello"string(仅限字符串)
[1, 2, 3]array(仅数组)
{"key": "val"}object(仅对象)

注意:布尔值在整数之前进行检查,因为在某些语言中布尔值是整数的子类型。此顺序可防止 true 被推断为整数。

此表描述的是校验器接受什么,而不是生成过程产出什么。样本值为 3 并不会让该属性变成整数:数值字段一律以 number 交付,除非有专门的步骤确认该数量确实是离散的,且没有任何观测值与之矛盾。样本中出现一个整数,并不能证明不可能出现小数——而错误地声明为整数,会让消费端数据库把 6.2 截断成 6

后续步骤