宽松类型校验掩盖了模型输出错误
作者以严格模式复检 4000 条 Claude 输出,发现 588 条记录存在合计 689 处被自动转换的字段,部分年份还被误读为时间戳。管道保存原始 JSON,导致 Python 校验后的类型与下游 JavaScript 实际读取的类型不一致。
AI 深度解读
99.7% 的校验通过率,也可能藏着一批类型错误。作者用 Claude 提取合同信息,Python 端一直正常,直到 Node 报表脚本把合同金额加成了 01200.50300,才发现校验通过的对象和落库的原始 JSON 根本不是一回事。
这篇文章值得读的地方,是把问题追到了三个环节:Pydantic 默认会转换类型,原始输出绕过了转换结果,下游又相信了上游的校验结论。作者重查 4,000 条输出,找出了 689 处隐式转换,并给出了一套包含严格校验、修复重试和指标监控的处理办法。
为什么通过校验,Node 还是算错了金额
作者的流水线很常见:提取合同 PDF 的文本,让 Claude 按提示返回 JSON,用 Contract.model_validate_json(raw) 校验,成功后把原始 JSON 和部分字段存进 Postgres。
合同模型包含交易对方 counterparty: str、金额 total_value: float、期限 term_months: int、自动续约标记 auto_renews: bool,以及签署时间 signed_at: datetime | None。
问题出在 Pydantic v2 默认使用宽松模式(lax mode)。字段类型不匹配时,它会尝试规定范围内的转换:
"42.5"可以进入 float 字段。"yes"、"no"、"true"、"1"等字符串可以转换成布尔值。- 没有小数部分的
12.0可以进入 int 字段。 - datetime 字段里的整数可以被解释成 Unix 时间戳。
处理表单和查询参数时,这种行为很方便,因为输入通常都是字符串。但评估 LLM 是否遵守输出约定时,它就混淆了两件事:模型是否生成了正确类型,以及校验器是否能把输入转成正确类型。
几周内,作者处理了 4,000 份文档,只有 13 次校验失败,主要原因是金额写成了 "1,200.50",宽松模式也不接受这种千位分隔符。手动重试后,99.7% 的通过率看起来相当可靠。
然而,Python 使用的是转换后的对象,数据库保存的却是转换前的字符串。Node 直接读取原始列,执行 0 + "1200.50" + 300,结果就成了字符串拼接。
校验通过的保证,只覆盖实际经过校验得到的数据。
如果下游消费的仍是原始输入,上游成功创建过一个 Python 对象,并不能保证下游拿到同样的类型。
689 处转换里,为什么有 4 处更危险
作者没有先改模型,而是对同一批数据追加严格校验。这段代码用来找出宽松模式接受、严格模式拒绝的记录,并按字段和错误类型计数:
from pydantic import ValidationError
from collections import Counter
coerced = Counter()
failed_records = 0
for row in rows: # 4,000 stored raw outputs
Contract.model_validate_json(row.raw) # lax: passes
try:
Contract.model_validate_json(row.raw, strict=True)
except ValidationError as e:
failed_records += 1
for err in e.errors():
coerced[(err["loc"][0], err["type"])] += 1
关键是第二次调用里的 strict=True:它只覆盖本次调用,不要求立即修改整个模型配置。
重查结果是,588 条记录失败,占 14.7%,累计涉及 689 个发生转换的字段。记录数和字段数不能混用,一条记录可能有多个字段依赖转换。
其中 685 处,作者认为转换在技术上正确:"1200.50" 确实可以转成 1200.5,"yes" 也可以表达 True。另有 4 处却改变了业务含义。
合同只写了「2023 年签署」,Claude 返回 "signed_at": 2023。Pydantic 把它理解为 Unix 纪元之后的 2,023 秒,生成 1970-01-01T00:33:43Z。日期类型合法,还带时区,但年份错了 53 年。
这些记录排到了「最早合同」视图前面,其中一条还被续约提醒判定为逾期半个世纪。
这比金额字符串更难发现。字符串金额可能在运算时暴露异常;转换后的日期已经是一份形状完整的数据,排序、筛选和提醒逻辑都能照常执行,只是业务结果错了。
不过,严格校验也只解决部分问题。如果模型直接返回格式正确、事实错误的日期,它依然可能通过。类型符合约定,不等于信息提取准确。
严格模式上线后,失败的输出怎么办
作者把严格校验设为模型默认行为,避免每个调用点分别传参:
from pydantic import BaseModel, ConfigDict
class Contract(BaseModel):
model_config = ConfigDict(strict=True)
counterparty: str
total_value: float
term_months: int
auto_renews: bool
signed_at: datetime | None
需要关注的是 model_config = ConfigDict(strict=True)。但不能把它理解成「JSON 中每个值都必须拥有对应的 Python 原生类型」:JSON 没有 datetime 类型,因此通过 JSON 校验时,严格模式仍接受 ISO 8601 字符串,例如 "2023-04-12T00:00:00Z",同时拒绝裸整数 2023。
如果无法一次切换整个模型,原文也提到按字段使用 StrictInt、StrictBool 或 Annotated[int, Strict()]。作者最关心的是 signed_at 和 total_value,但没有展示这两个字段的局部配置实现,不能直接把列出的整数、布尔类型套过去。
开启严格模式后,作者给失败记录增加一次修复调用:把原始输出与 Pydantic 错误列表一起发回 Claude,请它返回修正后的 JSON。错误信息包含字段路径、错误说明和实际输入,让模型知道具体改哪里。
588 条失败记录中,571 条在第一次修复后通过,剩余 17 条转人工审核,多数涉及确实存在歧义的日期。这批数据的 API 调用次数增加了 14.7%。原文没有给出 token 用量、延迟或金额成本,不能把调用次数增幅直接当成费用增幅。
随后,作者把提示词从字段含义描述改成明确的输出约束:
total_value 必须是 JSON number,不能加引号、货币符号或千位分隔符;signed_at 必须是 ISO 8601 字符串或 null,不能只返回年份。
在新抽取的 500 份文档中,严格校验失败 12 次,失败率降到 2.4%。存储环节也改成使用 contract.model_dump_json(),原始输出另外留列供审计,下游读取序列化后的结果。
最后,作者分别记录首次严格通过率和修复后严格通过率。前者用来观察模型有没有偏离输出约定,后者观察修复流程能救回多少结果。作者报告,一次模型版本切换后,首次严格通过率在一天内从 97.6% 降到 93%,而宽松通过率仍会显示 99.7%。
我的判断
我赞同作者优先修正数据出口的做法。对于 Python 提取、Node 报表或前端消费的链路,明确下游读取哪一份数据,比单独加一个校验开关更关键。保留原始输出方便追查,生产逻辑消费校验后的序列化结果,两者都有用途。
严格模式也适合作为观察模型输出稳定性的工具。宽松模式把一部分错误修好了,却同时抹掉了模型偏离约定的信号。首次严格通过率因此比单纯的宽松通过率更能反映这类变化。
但作者的数字来自单个合同提取流水线。原文没有说明 Claude 的具体型号、完整提示词、采样设置,也没有给出新旧样本难度的对照。14.7% 不是所有 LLM 的类型错误率;失败率降到 2.4%,也只能说明这套调整在作者的新样本上有效。
一次修复通过,只能证明结果满足校验约束,不能证明它忠于合同。
尤其是日期含糊时,让模型补一个能通过校验的日期,可能只是把歧义藏得更深。那 17 条进入人工审核的记录,恰好说明恢复路径需要允许「无法自动确定」。
至于常见的替代方案,例如生成端施加结构化输出约束,原文没有提供对照数据,无法据此判断哪种方案成本更低、错误更少。这篇提供的是一套有实测结果的工程经验,适合借鉴,不能替代自己链路上的验证。
能拿来做什么
- 如果你的 Python 服务校验 LLM 输出后交给 Node 或前端,先核对下游读取的是原始 JSON,还是
model_dump_json()生成的结果;把审计数据和业务数据的读取入口明确区分。 - 对已有输出先做一轮离线复查,用
model_validate_json(raw, strict=True)统计失败记录和字段类型,优先检查金额、布尔值和日期,确认隐式转换有没有改变业务含义。 - 给严格校验失败增加一次携带错误列表的修复调用,修复结果仍需重新校验;对于合同日期确有歧义的情况,保留人工处理出口。
- 在提示词或模型版本调整前后,分别记录首次严格通过率与修复后通过率,并抽查字段内容。前者帮助发现类型漂移,内容抽查帮助发现格式合法但事实错误的结果。