结构化输出:从合法JSON到可以进入业务事务
区分JSON语法、Schema、业务语义与授权,用严格类型和可信账户状态拒绝看似合法的错误输出。
模型返回{"account_id":"a2","amount_cents":1200,"currency":"CNY"},语法合法、字段齐全、金额为正,仍不代表可以扣款。账户a2可能属于另一个人,余额可能已变化,或者本次用户根本没有授权支付。结构化生成帮助稳定表达数据,业务系统负责决定这些数据是否可以变成操作。
四道门解决四种不同问题
第一道是JSON解析:括号、引号和转义是否有效,数据是否完整。第二道是结构契约:必须有哪些字段,类型、枚举、范围和额外字段如何处理。第三道是业务语义:账户是否存在、币种是否支持、余额是否足够、证据是否支持这个结论。第四道是授权与事务:当前身份能否操作该账户,以及提交时约束是否仍成立。
JSON Mode通常着重于有效JSON,不等于满足任意业务schema。支持严格结构化输出的模型/接口能对所支持的schema子集施加更强约束,但仍可能遇到拒绝、截断、内容缺失或不支持的schema关键字,必须检查终止状态与错误分支。字段满足schema也不能证明内容真实。
约束解码是在每一步限制可选token
生成器根据当前前缀和语法/schema状态,排除无法继续组成合法输出的候选token,再从允许集合采样。难点在于token不一定对应一个字符,转义、字符串内容、数字和嵌套结构都需要正确处理。通用上下文无关语法能力、正则约束和schema子集支持也不完全相同,应检查后端实际能力。
例如schema规定币种只能为CNY或USD,可以避免随意生成“人民币元”这样的枚举外字符串;它不知道当前用户只能动用哪个账户,也不能从一个合法引用ID推断引用内容真的支持答案。对跨字段、外部状态或授权的条件,运行时仍需查可信数据。
类型转换可能把错误藏起来
运行时校验库通常允许某些输入转换,例如字符串数字转整数。便捷转换适合某些表单场景,但模型输出契约若要求严格整数,就应明确使用严格模式或字段限制,并核对从Python对象还是JSON入口验证时的行为差异。Pydantic能统一模型、校验错误和JSON Schema,但不是自动完成业务授权的系统。
Python里bool是int的子类,所以isinstance(True,int)为真。下面金额校验使用type(amount) is int,防止把true当成1分钱。金额以整数分表达,避免二进制浮点的舍入问题;涉及汇率或小数价格时应定义Decimal精度、舍入和币种单位。
保存为validation.py,运行python -X utf8 validation.py。所有账户是内存固定数据,程序只做校验,不真实扣款。
"""严格解析、字段约束、可信业务状态校验;没有数据库写入。"""
import json
def unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError('JSON 字段重复:'+key)
result[key] = value
return result
def invalid_constant(value):
raise ValueError('非标准 JSON 常量:'+value)
def validate_transfer(raw, actor, accounts):
data = json.loads(raw, object_pairs_hook=unique_object, parse_constant=invalid_constant)
if not isinstance(data, dict) or set(data) != {'account_id','amount_cents','currency'}:
raise ValueError('字段集合不符合契约')
if not isinstance(data['account_id'], str) or not data['account_id']:
raise ValueError('account_id 必须为非空字符串')
amount = data['amount_cents']
if type(amount) is not int or not 0 < amount <= 10000:
raise ValueError('金额必须为 1–10000 的整数分')
if data['currency'] != 'CNY':
raise ValueError('不支持的币种')
account = accounts.get(data['account_id'])
if account is None or account['owner'] != actor:
raise ValueError('账户不存在或无权操作')
if amount > account['balance_cents']:
raise ValueError('余额不足')
return data
if __name__ == '__main__':
accounts={'a1':{'owner':'alice','balance_cents':5000},
'a2':{'owner':'bob','balance_cents':9000}}
for account, amount in [('a1',1200),('a2',1200),('a1',True),('a1',6000)]:
raw=json.dumps({'account_id':account,'amount_cents':amount,'currency':'CNY'})
try:
data=validate_transfer(raw,'alice',accounts)
print('允许进入事务层:',data['account_id'],data['amount_cents'])
except ValueError as exc:
print('拒绝:',exc)
print('校验没有修改余额:',accounts['a1']['balance_cents'])允许进入事务层: a1 1200
拒绝: 账户不存在或无权操作
拒绝: 金额必须为 1–10000 的整数分
拒绝: 余额不足
校验没有修改余额: 5000第二个JSON结构正确,但a2属于bob,因此alice的操作被拒绝。第三个金额是布尔值,严格类型门拒绝它。第四个请求金额超过当前余额,被业务状态门拒绝。账户归属来自可信accounts,不从模型返回的owner字段判断,否则模型只要填写alice就能绕过检查。
解析器还显式拒绝重复字段和NaN/Infinity等非标准常量,避免不同组件对同一输入产生不同解释。真实接口应在解析前限制字节长度、嵌套深度或运行资源;这段短例不替代完整的输入资源防护。
校验到提交之间还有竞争窗口
读取余额5000后检查1200可扣,但另一请求可能在你提交前先扣掉4500。只在应用层检查一次并不能保证结果;事务层需要原子条件更新、锁或适合的隔离策略,且检查影响行数。授权也应根据当前身份与资源关系判断,不能只依赖上一次会话缓存。
对已经执行成功但响应丢失的请求,重试须利用稳定幂等键及执行记录,不能再次扣款。错误修复提示只把具体字段错误反馈给模型,不应把数据库全记录或敏感授权信息直接放进prompt。重生成要有总尝试上限,不得通过反复修复绕过业务禁止条件。
流式JSON能展示,不一定能执行
流式输出前缀{"amount_cents":1可能继续变成1200;仅凭当前能解析出的局部值提交,会提前执行错误金额。工具参数应按调用ID缓冲,收到明确完成事件、检查未截断并通过整体验证后,再进入授权和事务。UI可以显示“正在生成”,但不能把未完成字段标为已确认业务事实。
拒绝与截断要独立建模。模型拒绝不应被强行修复成一个看似有效业务对象;达到输出token上限也不表示完整对象已经产生。保存原始错误类型和追踪ID,便于分辨生成问题、协议问题与业务拒绝。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
合法JSON与严格Schema都通过,为什么还不能直接扣款?
参考思路与常见误区
结构只说明表达形式,账户归属、余额、币种、授权和提交时状态还需可信业务校验。事务层要原子检查并提交,防止校验后状态变化。模型输出的owner不能作为身份依据。
常见误区:用schema校验替代鉴权和数据库事务。
JSON Mode、约束解码、Pydantic分别解决什么?
参考思路与常见误区
JSON Mode主要帮助有效JSON;约束解码在生成时限制符合支持语法/schema的token;Pydantic在运行时验证数据模型、类型和自定义条件。它们都不自动证明外部事实和业务授权,且要处理拒绝、截断和不支持schema。
常见误区:把任意一种结构工具称为全面正确性保证。
为什么金额整数校验不直接用isinstance(value,int)?
参考思路与常见误区
Python的bool是int子类,True会通过该判断。严格金额契约可用type(value) is int或合适的严格校验类型,再限制范围与币种。金额单位要明确,避免浮点和隐式字符串转换。
常见误区:认为JSON布尔值不可能被Python整数判断接受。
流中目前看到amount_cents:1,能否立刻提交?
参考思路与常见误区
不能,后续可能继续成为1200,整个对象也可能截断。要按调用ID缓冲,等待明确完成,检查结束状态并对完整对象做结构、语义、授权校验后再进入事务。
常见误区:把可展示的局部值当成业务已确认值。
余额校验通过后仍超扣,问题可能在哪里?
参考思路与常见误区
应用读取和提交之间可能有其他请求更新余额。需要事务隔离、锁或原子条件更新并检查影响行数;重复请求还需要幂等记录。单次内存校验不能证明并发提交安全。
常见误区:只增加模型提示或再次解析JSON,而不处理竞争条件。
结构化输出支持与异常分支见 OpenAI Structured Outputs,严格模式见 Pydantic文档,解析边界见 Python JSON文档。下一篇用本地HTTP观察 流式事件帧。