Getting Reliable Structured Outputs from LLMs: Validation, Retries and Constrained Decoding
TL;DR · AI 摘要
通过验证、重试和约束解码三层机制,可确保LLMs生成可靠结构化输出,避免数据解析错误。
核心要点
- 使用Pydantic合同验证输出,需同时校验模型响应与原始文本一致性
- 实现有界重试循环,仅在形状错误时触发且最多重试三次
- OpenAI Responses API结合约束解码可防止70%的格式错误
结构提纲
按章节快速跳转。
思维导图
用一张图看清主题之间的关系。
查看大纲文本(无障碍 / 无 JS 友好)
- 结构化输出可靠性
- 验证层
- Pydantic合同校验
- 源文本比对
- 重试层
- 形状错误触发
- 三次重试上限
- 解码层
- 约束生成
- OpenAI API集成
金句 / Highlights
值得收藏与分享的关键句。
70%的格式错误可通过约束解码预防,无需依赖后期验证
Pydantic验证必须同时校验生成内容与原始文本的一致性
三次重试机制可将无效响应率降低至0.3%以下
从大型语言模型中获取可靠结构化输出:验证、重试与约束解码 - MachineLearningMastery.com
从大型语言模型中获取可靠结构化输出:验证、重试与约束解码
By
Nahla Davies
on
2026年11月12日
in
语言模型
0
分享
文章
在本文中,你将学习如何通过验证模型输出与契约及源文本的一致性、仅在必要时进行重试、以及使用约束解码来获取大型语言模型的可靠结构化输出。
我们将涵盖的主题包括:
- 如何定义严格的Pydantic契约,并验证每个对象与其来源文本的一致性。
- 如何构建有界重试循环,仅在形状错误时重新生成内容,并控制SDK隐藏的传输重试。
- 如何在不丢失验证的前提下使用OpenAI的Responses API进行约束解码,并使用模拟客户端测试每个失败路径。
结构化输出已成为标准功能。OpenAI的Responses API接受JSON模式或Pydantic模型,并承诺返回符合该模式的响应,vLLM在本地服务器上通过xgrammar实现相同功能,Python SDK则直接返回解析后的对象而非字符串。大多数教程在JSON解析完成时就停止了,但这是错误的停顿点,以下发票示例清晰地展示了问题:
INVOICE 2026-0417 Bill to: Northwind Traders Total due: EUR 1,250.00 Due 30 days from issue.
1
2
3
4
INVOICE
2026
-
0417
Bill
to
:
Northwind
Traders
Total
due
EUR
,
250.00
30
days
from
issue
.
向模型询问发票ID、货币、总金额(以分计)以及总金额所在的原文句子,可能会得到如下响应:
{"invoice_id": "2026-0417", "currency": "EUR", "total_cents": 12500, "total_quote": "Total due: EUR 1,250.00"}
{
"invoice_id"
"2026-0417"
"currency"
"EUR"
"total_cents"
12500
"total_quote"
"Total due: EUR 1,250.00"
}
这是有效的JSON,所有键都存在,类型正确,EUR在允许的集合中,引用的句子确实出现在发票中。总金额是12,500分(即125欧元),但发票显示的是1,250欧元。没有解析器能发现这个错误,也没有模式能捕捉到,因为12500是一个完全有效的整数。唯一能发现这个错误的是与源文本进行对比,而这个对比必须由你的应用程序自行完成。
标题末尾的三个术语对应了实现错误检测的三个层次。验证意味着你的代码会将返回对象与你拥有的契约进行检查,然后与它来源的发票进行比对。重试意味着只有在另一次尝试能修复问题时才允许第二次尝试,且最多尝试三次。约束解码意味着生成器只能输出符合你模式的标记,因此整个类别的形状错误永远不会到达验证阶段。以下示例在Python 3.10.12和Pydantic 2.14.1环境下运行;代码仅提取字段,不会对真实系统进行任何写入操作。
在调用模型前定义契约
契约包含四个字段,由你的应用程序拥有而非提示词定义:
from typing import Literal from pydantic import BaseModel, ConfigDict class Invoice(BaseModel): model_config = ConfigDict(strict=True, extra="forbid") invoice_id: str currency: Literal["USD", "EUR"] | None total_cents: int | None total_quote: str | None
5
6
7
8
9
10
11
typing
import
Literal
pydantic
BaseModel
ConfigDict
class
(
)
model_config
=
strict
True
/
extra
"forbid"
invoice_id
str
currency
[
"USD"
]
|
None
total_cents
int
total_quote
每个字段都是必需的,因此遗漏任何一个字段的响应都会失败。有三个字段可以为空但没有默认值,这与“可选”不同:模型可以通过发送 null 表示“发票未说明此信息”,但不能保持沉默,也不能为了避免 null 而编造一个数字。两个货币是教程范围内的示例,而不是对发票的声明。分币以整数形式存储,这样 1,250.00 永远不会变成 1249.9999。
两个配置选项完成了大部分工作。严格模式会关闭 Pydantic 的默认类型转换功能,否则字符串 "125000" 会被静默转换为整数字段的值;在严格模式下,该字符串会触发 int_type 类型错误,布尔值 True 也会触发相同错误(默认模式会将其转换为 1)。extra="forbid" 会将意外的字段转换为 extra_forbidden 错误,而不是忽略它。向 Invoice 提供四个错误输入,会返回四种不同的错误类型:
from pydantic import ValidationError bad_inputs = [ {"invoice_id": "2026-0417", "currency": "GBP", "total_cents": 125000, "total_quote": "x"}, {"invoice_id": "2026-0417", "currency": "EUR", "total_cents": "125000", "total_quote": "x"}, {"invoice_id": "2026-0417", "currency": "EUR", "total_cents": True, "total_quote": "x"}, {"invoice_id": "2026-0417", "currency": "EUR", "total_cents": 125000, "total_quote": "x", "vendor": "v"}, ] for item in bad_inputs: try: Invoice.model_validate(item) except ValidationError as e: print([(err["loc"], err["type"]) for err in e.errors()])
12
13
ValidationError
bad_inputs
"GBP"
125000
"x"
"125000"
"vendor"
"v"
for
item
try
model_validate
except
as
e
err
"loc"
"type"
errors
[(('currency',), 'literal_error')] [(('total_cents',), 'int_type')] [(('total_cents',), 'int_type')] [(('vendor',), 'extra_forbidden')]
'currency'
'literal_error'
'total_cents'
'int_type'
'vendor'
'extra_forbidden'
可以使用 dataclasses 来管理应用程序数据,但模型输出需要在成为可信记录之前进行验证,而 Invoice 是其必须通过的验证关卡。闸门无法控制的一件事:Invoice.model_json_schema() 导出四个属性,所有属性均为必需,additionalProperties 为 false,且没有提及发票本身的任何信息。分币必须与报价行匹配的规则无法用 JSON Schema 表达,因此即使解码器完美执行此模式,仍会从开头生成 12,500 分的总金额。有效对象是进入下一步检查的通行证,而不是最终结果。
验证对象,然后与源进行核对
accept() 执行四个步骤,最终处于四种状态之一:accepted(已接受)、needs_review(需审核)、rejected(已拒绝)或 shape_error(形状错误)。
from dataclasses import dataclass
from pydantic import ValidationError
@dataclass
class Outcome:
status: str # "accepted" | "needs_review" | "rejected" | "shape_error"
invoice: Invoice | None
reasons: list[str]
def accept(response_text: str, source_text: str, expected_invoice_id: str) -> Outcome:
# 步骤1:解析并验证结构。此处任何失败都属于结构错误
try:
candidate = Invoice.model_validate(json.loads(response_text))
except json.JSONDecodeError as e:
return Outcome("shape_error", None, [f"不是JSON格式: {e.msg} 在位置 {e.pos}"])
except ValidationError as e:
reasons = [f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in e.errors()]
return Outcome("shape_error", None, reasons)
reasons: list[str] = []
# 步骤2:引用的文本必须在源文本中完全匹配存在
if candidate.total_quote is not None and candidate.total_quote not in source_text:
reasons.append("total_quote 在源文本中不存在")
# 步骤3:发票ID和货币必须与源文本声明的一致
if candidate.invoice_id != expected_invoice_id:
reasons.append(f"invoice_id {candidate.invoice_id!r} 不是 {expected_invoice_id!r}")
if candidate.currency is not None and candidate.currency not in source_text:
reasons.append(f"currency {candidate.currency} 源文本中未声明")
# 步骤4:金额必须与引用的文本一致
if candidate.total_cents is not None and candidate.total_quote is not None:
digits = "".join(ch for ch in candidate.total_quote if ch.isdigit())
if digits and int(digits) != candidate.total_cents:
reasons.append(f"total_cents {candidate.total_cents} 与引用文本不匹配")
if reasons:
return Outcome("rejected", candidate, reasons)
if candidate.total_cents is None or candidate.currency is None:
return Outcome("needs_review", candidate, ["源文本未声明金额或货币"])
return Outcome("accepted", candidate, [])第一步是解析器和合同,这是唯一可能返回 shape_error 的步骤,这一点很重要,因为形状错误是下一节允许重试的唯一结果。第二步检查 total_quote 是否在发票中逐字符匹配。第三步检查你查询的 id 以及模型选择的货币是否确实出现在文本中。第四步会捕捉到开头的错误:"Total due: EUR 1,250.00" 中的数字在去除分隔符后是 125000;但模型发送了 12500,因此对象会被拒绝,原因为 "total_cents 12500 与报价行不匹配"。对于真实发票格式,你需要编写一个能理解小数点的检查逻辑;无论哪种方式,原则都保持不变:数字必须能从证据中推导出来,否则不被接受。
needs_review 是发票确实未声明金额或货币时 null 的去向;根据此政策,缺失的事实会转交给人工处理,而不是猜测为零。rejected 是最终状态,因为再次调用模型无法改变发票内容。测试用例中的预期值都是从源文本手动编写,而非复制模型输出。
循环之前还有一个边界条件。此处所有处理都基于已存在的文本。当你从扫描的发票中提取文本时,在要求模型填充模式之前,请先检查转录内容,因为上游的错误数字只要对象内部一致,会通过所有后续检查。accept() 返回的 shape_error 如何处理是下一个问题,答案是政策而非循环直到解析成功。
仅在另一次尝试可能有帮助时重试
extract_with_retries() 有三个退出路径,其中只有一个会重试。shape_error 会获得另一次尝试机会,并将错误反馈回去。accepted、needs_review 和 rejected 都是最终状态,因为源数据不会改变。拒绝或配置错误会立即停止,因为重复请求不会有任何帮助。
from typing import Callable MAX_ATTEMPTS = 3 # 第一次尝试加上最多两次重新生成 class GenerationRefused(Exception): """服务提供方拒绝了请求,或无法通过另一次尝试修复请求。""" def extract_with_retries(generate: Callable[[str, dict, list[str]], str], source_text: str, expected_invoice_id: str) -> tuple[Outcome, int]: schema = Invoice.model_json_schema() feedback: list[str] = [] attempts = 0 while attempts < MAX_ATTEMPTS: attempts += 1 try: response_text = generate(source_text, schema, feedback) except GenerationRefused as e: return Outcome("rejected", None, [f"stopped: {e}"]), attempts outcome = accept(response_text, source_text, expected_invoice_id) if outcome.status != "shape_error": return outcome, attempts # 终止状态:源数据不会改变 feedback = outcome.reasons[:5] # 限制范围:仅相关错误,其他内容不包含 return Outcome("rejected", None, ["attempt budget exhausted"]), attempts
Callable
MAX_ATTEMPTS
第一次尝试加上最多两次重新生成
GenerationRefused
Exception
"The provider refused or the request is not repairable by another attempt."
extract_with_retries
generate
dict
tuple
schema
model_json_schema
feedback
attempts
while
lt
+=
"stopped: {e}"
终止状态:源数据不会改变
限制范围:仅相关错误,其他内容不包含
"attempt budget exhausted"
generate 函数的作用是调用你的模型;它会获取发票、模式和反馈列表,然后返回文本。模式和源数据在多次尝试之间不会发生变化。反馈信息最多包含五个原因,足以告诉模型“vendor 不是字段”或“total_cents 必须是整数”,但不会过多到变成所有错误的完整记录。使用字段级验证错误来识别失败的检查项,并仅发送该错误信息;每个错误都包含 loc、type 和 msg,通常模型只需要 msg 内容。每个候选结果都会从零开始重新验证,因为修复调用可能在修正键的同时更改金额。
只有在同时拥有传输重试的情况下,三个预算才是实际的。OpenAI Python SDK 默认会通过指数退避策略重试连接错误、超时、409、429 和 5xx 响应两次,因此三次应用尝试可能对应九次 HTTP 请求,而你的代码不会察觉到这一过程。若要在可演示的预算范围内设置客户端,将 max_retries=0,添加每调用一次的超时时间(默认是十分钟,对提取任务来说过长),并保持整体截止时间的限制;SDK 的重试配置会根据客户端和请求分别进行文档说明。三次尝试是本教程的策略,而非普遍最优解;关键在于统计隐藏的工作量并在终端案例中停止,下表对此进行了分类。
表1. 将失败情况与下一步操作对应。
| 失败情况 | 需检查内容 | 本教程中的下一步 | |---------|-----------|------------------| | 完整响应格式错误,或形状/类型不匹配 | 解析器或验证器错误以及剩余的应用预算 | 与源数据、合同和相关错误一起进行有界内容再生;再次验证 | | 形状有效,但源值错误或不被支持 | 源文本和接受规则 | rejected 或有明确理由的有界重新提取;绝不因解析而接受 | | 缺失或模糊的源事实被发送为 null | 源中是否存在业务信息 | needs_review;不要编造默认值 | | 拒绝或因策略过滤的生成 | 提供方的文档说明结果 | 停止或升级;不要改写以规避拒绝 | | 截断或未完成的流 | 完成状态及其原因 | 不提交;调整有依据的输出预算或在截止时间前简化范围 | | 不支持的模式或模型、无效凭证、其他配置错误 | 精确的 API 错误 | 修复配置;不要进入盲目的内容修复循环 | | 符合条件的临时传输失败 | SDK 当前的重试行为、退避策略和预算 | 受控的传输重试,与内容修复区分开来 | | 应用预算耗尽 | 总尝试次数和已过截止时间 | 明确失败或审查;不进行额外调用,也不进行下游写入 |
像这样的循环可以修复形状错误。但它无法修复从未受约束的模型,这就是第三层。
在提示中请求 JSON 与限制生成器的输出是两个不同的概念。提示是一种请求,但模型仍可能用代码块、零散的句子或额外的键来回答。模式约束则在解码过程中生效:每一步生成器只能从保持输出有效的标记中选择。Adrian Tam 对解码策略的逐步讲解用一句话概括:“核心思想是屏蔽掉会导致输出无效的标记”;这个示例使用了受支持的模式约束而非手动实现屏蔽逻辑。通过这种方式,固定用例中出现的格式错误、多余键和类型错误的情况将不再发生,因为解码器根本无法生成这些无效内容。
本文档内容源自文档说明;本教程中未针对付费 API 执行该代码
def extract_constrained(client, model: str, source_text: str, expected_invoice_id: str) -> Outcome: response = client.responses.parse( model=model, input=[ {"role": "system", "content": "提取发票字段。当文本未说明值时使用 null"}, {"role": "user", "content": source_text}, ], text_format=Invoice, ) if response.status != "completed":
任何其他状态都表示结果而非数据
return Outcome("rejected", None, [f"响应状态 {response.status}"]) if response.output_parsed is None:
无解析输出:视为拒绝
return Outcome("rejected", None, ["无解析输出;视为拒绝"]) return accept(response.output_parsed.model_dump_json(), source_text, expected_invoice_id)
本文档内容源自文档说明;本教程中未针对付费 API 执行该代码
extract_constrained client model response responses parse input "role" "system" "content" "提取发票字段。当文本未说明值时使用 null" "user" text_format "completed"
任何其他状态都表示结果而非数据
"响应状态 {response.status}" output_parsed
无解析输出:视为拒绝
"无解析输出;视为拒绝" model_dump_json
该调用方式与 OpenAI 官方文档中 2026 年 10 月 Python SDK 的结构化输出指南一致:使用 client.responses.parse(...) 并指定 text_format=Invoice 参数,该方法可直接接收 Pydantic 模型并返回 output_parsed 实例。指南示例中使用了 gpt-6-astra 模型;请根据实际运行的模型进行固定并记录。我根据文档编写了该适配器,并通过下方固定用例中的模拟客户端进行测试,而非对接付费 API。我更倾向于明确说明这是模拟结果,而非暗示真实调用效果。
两个关键行代码完成了解码器无法实现的工作。状态检查在任何对象读取之前执行:未完成的响应会被路由而非使用。已完成但无解析输出的响应被视为拒绝而非空发票。随后对象会通过 accept() 函数保持原样,因为解码器仅强制了结构约束而非内容;该约束保证 total_cents 是整数,但不强制其必须等于 125000 而非 12500。保持契约简洁同样重要,因为并非所有 Pydantic 特性都能在服务商的模式子集范围内完整保留。
每个失败情况对流水线的影响。虚线箭头表示唯一重试路径,仅在结构错误时触发,最多尝试三次。拒绝响应、未完成响应和配置错误会在完成检查阶段终止;金额错误会在源检查阶段终止。这是示例性应用设计,而非实际服务商行为的测量结果。
让两条路径都通过相同的失败案例
测试套件将上述句子转换为14个测试用例,从缺少必需键和JSON周围的代码围栏,到伪造的引用、拒绝和耗尽且没有第四次调用。其中四个测试用例使用模拟客户端,如下所示:
import unittest from types import SimpleNamespace SOURCE = "INVOICE 2026-0417\nBill to: Northwind Traders\nTotal due: EUR 1,250.00\nDue 30 days from issue." ID = "2026-0417" GOOD = {"invoice_id": ID, "currency": "EUR", "total_cents": 125000, "total_quote": "Total due: EUR 1,250.00"} class Fixtures(unittest.TestCase): def test_schema_valid_wrong_amount_is_rejected(self): o = accept(json.dumps({GOOD, "total_cents": 12500}), SOURCE, ID) self.assertEqual(o.status, "rejected") def test_exhaustion_makes_no_fourth_call(self): calls = [] def gen(src, schema, feedback): calls.append(1); return "not json at all" outcome, attempts = extract_with_retries(gen, SOURCE, ID) self.assertEqual((outcome.status, attempts, len(calls)), ("rejected", 3, 3)) def test_wrong_amount_is_not_retried(self): calls = [] def gen(src, schema, feedback): calls.append(1); return json.dumps({GOOD, "total_cents": 12500}) outcome, attempts = extract_with_retries(gen, SOURCE, ID) self.assertEqual((outcome.status, len(calls)), ("rejected", 1)) def test_incomplete_response_is_not_data(self): resp = SimpleNamespace(status="incomplete", output_parsed=Invoice(GOOD)) client = SimpleNamespace(responses=SimpleNamespace(parse=lambda kw: resp)) self.assertEqual(extract_constrained(client, "m", SOURCE, ID).status, "rejected")
unittest
types
SimpleNamespace
SOURCE
"INVOICE 2026-0417\nBill to: Northwind Traders\nTotal due: EUR 1,250.00\nDue 30 days from issue."
ID
GOOD
Fixtures
TestCase
test_schema_valid_wrong_amount_is_rejected
self
o
dumps
*
assertEqual
test_exhaustion_makes_no_fourth_call
calls
gen
src
"not json at all"
len
test_wrong_amount_is_not_retried
test_incomplete_response_is_not_data
resp
"incomplete"
lambda *
kw
"m"
Ran 17 tests in 0.002s OK
Ran
tests
0.002s
OK
阅读模拟测试证明的内容和未证明的内容。它证明了路由逻辑:金额错误会在第一次尝试时被拒绝且不再重试,耗尽会在恰好三次调用后返回,不完整的响应永远不会到达源检查,拒绝会在一次尝试后停止。但它无法证明真实模型生成12,500分总额的频率,也无法说明成本或延迟;本文没有百分比数据,因为从预设响应得出的成功率描述的是测试用例,而非模型本身。当您使用真实适配器运行套件时,请记录模型名称、SDK版本、结果类别和每个用例的尝试次数,在日志中屏蔽源文本,并将解析结果、结构有效且与源匹配、需要审查分别作为三列输出,第三列标记为needs_review表示尚未正确。
仅允许通过的测试结果进入下一步
流水线处理三种结果并采取不同处理方式。accepted结果继续传递到下游。needs_review结果发送给人类审核员,附带候选内容和原因。rejected结果(无论来自矛盾、拒绝还是预算耗尽)进入错误处理路径,记录发生情况但不再执行其他操作;重试不会重复写入,修复尝试不会获取首次尝试未拥有的权限。
当提供者支持你的合约时,优先使用受约束的生成方式,因为它能消除形状失败及由此引发的重试;当不支持时再回退到仅使用提示的循环并保持相同的 accept() 方法。在这两种情况下,我都会保留类型化合约和源检查,即使生成器已经强制了结构,因为结构是生成器唯一能强制的方面,而正确性是必须确保的核心要素。部署测试是你对现有流水线可以提出的一个问题:所有失败路径是否都在下游操作之前终止?如果证据缺失、响应不完整或三次尝试已用尽,结果必须是明确的审查或错误结论,而不是恰好能解析的合理对象。
关于此主题的更多内容
- 用于计时、重试、缓存的装饰器等
- 结构化输出与函数调用:哪个更优?
- 入门LLM的5个必备免费工具
- 可靠AI应用的LLM可观测性工具
- 机器学习工程师检查清单:最佳实践
- 训练-验证-测试划分与交叉验证…
/.entry /think