Machine Learning Mastery

Getting Reliable Structured Outputs from LLMs: Validation, Retries and Constrained Decoding

8.5内容质量

TL;DR · AI 摘要

通过验证、重试和约束解码三层机制,可确保LLMs生成可靠结构化输出,避免数据解析错误。

核心要点

  • 使用Pydantic合同验证输出,需同时校验模型响应与原始文本一致性
  • 实现有界重试循环,仅在形状错误时触发且最多重试三次
  • OpenAI Responses API结合约束解码可防止70%的格式错误

结构提纲

按章节快速跳转。

  1. 揭示当前LLMs结构化输出验证的常见误区及潜在风险。

  2. 展示如何通过Pydantic模型建立可验证的数据契约。

  3. 构建仅在形状错误时触发的三次重试安全循环。

  4. 演示如何通过OpenAI API限制生成内容的格式边界。

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • 结构化输出可靠性
    • 验证层
      • Pydantic合同校验
      • 源文本比对
    • 重试层
      • 形状错误触发
      • 三次重试上限
    • 解码层
      • 约束生成
      • OpenAI API集成

金句 / Highlights

值得收藏与分享的关键句。

#LLMs#结构化输出#Pydantic#OpenAI
打开原文

从大型语言模型中获取可靠结构化输出:验证、重试与约束解码 - 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

print

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(形状错误)。

python
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