结构化输出
定义
结构化输出(structured output)指把模型生成的 token 序列约束到由模式 定义的语言 内,使输出可被程序解析、校验并直接用于下游计算;模式(schema)是对输出结构的声明式描述,JSON Schema 用字段集合、类型、必填性与取值范围描述 JSON 文档,Pydantic 用 Python 类型注解描述同一组约束;约束解码(constrained decoding)指在自回归生成的每一步,把不满足模式的状态转移概率置零后再采样,
其中 是第 步的语法状态, 是该状态下允许的 token 集合。
符号约定如下。
| 符号 | 含义 |
|---|---|
| 词表, | |
| 输出 token 序列,长度 | |
| 模式,本篇指 JSON Schema 或等价的 Pydantic 模型 | |
| 满足 的全部 JSON 文档构成的集合 | |
| 第 步的 logits | |
| 掩码向量 | |
| 描述 的自动机, 为状态集, 为字符集, 为转移函数, 为初始状态, 为接受状态集 | |
| 状态 下允许的 token 集合 | |
| 单步生成合法 token 的概率 | |
| 最大重试次数 |
其余术语在首次出现处定义:JSON Schema 是描述 JSON 文档结构的规范,当前常用草案为 2020-12;Pydantic 是 Python 的数据校验库,第二版用 Rust 实现核心校验;函数调用(function calling)指模型输出结构化的工具名与参数对象;语法约束解码(grammar-constrained decoding)指以形式文法而非 JSON Schema 为约束的约束解码;流式输出指逐 token 或逐段返回结果。
为什么重要
下游程序只接受确定的结构。自然语言回答需要额外的抽取步骤,而抽取本身又是一个模型调用,误差叠加且无法保证;结构化输出把这一步前移到生成阶段,使"解析成功"成为可验证的属性而不是概率事件。
没有结构化输出会产生四类具体成本。第一类是解析成本,自由文本中字段可能缺失、类型错误、被代码围栏包裹、被解释文字打断,解析器需要为每种情况写分支,分支的覆盖率决定系统稳定性。第二类是校验成本,即使解析成功,字段取值仍需检查范围、枚举与跨字段一致性,缺少模式时这些检查散落在业务代码中,无法复用。第三类是重试成本,解析失败后只能整段重生成,期望调用次数按几何级数增长,而结构化输出可以把失败定位到具体字段。第四类是幂等成本,重试与去重需要稳定的请求标识与结果摘要,结构化输出使这些字段可以显式声明。
结构化输出在本库中的位置是输入控制层与系统集成层的交界。Prompt工程 讨论如何用提示词表达格式要求,本篇讨论如何把要求变成可执行的约束;AI-Agent与工具调用 的调用参数是本篇模式的一个特例;RAG原理与流程 需要结构化的答案与引用字段才能做三元组评估;指令微调SFT 从训练侧教模型输出格式,本篇从解码侧保证格式,两者是互补关系。对应学习目标中的"能复现"与"会评估":能写出模式与校验循环,能测量格式合规率与语义正确率两个独立指标。
原理与推导
1 结构化输出的形式化
生成模型定义分布 ,其支持集是整个 。结构化输出的目标是使采样结果落在 内:
有两种实现路径,性质不同。
事后路径先生成再解析:从 采样完整序列,用解析器检查是否属于 ,失败则重试。设第 步生成合法 token 的概率为 ,各步近似独立,则整段合法的概率为
取 、,。即使每一步有 99% 的概率正确,200 步之后只有 13.4% 的输出整体合法。该估算偏悲观,因为模型经过指令微调后对常见 schema 的单步合法率远高于 0.99,且错误相关;但它正确指出了趋势:结构越长,事后解析的失败率越高,重试成本随长度指数上升。
过程路径在每一步限制候选集,从条件分布
中采样。逐 token 加掩码并重归一化,在 对前缀封闭(任一合法串的任一前缀都允许继续生成)的条件下,恰好实现该条件分布。合法率因此等于 1,代价是每步需要计算允许集,且输出的语义分布被改变。
2 JSON Schema 与 Pydantic
JSON Schema 是声明式约束,常用关键字及其语义如下。
| 关键字 | 语义 | Pydantic 对应 |
|---|---|---|
type | JSON 类型:object、array、string、number、integer、boolean、null | 类型注解 str、int、float、bool |
properties | 对象各字段的模式 | 模型字段声明 |
required | 必须出现的字段名列表 | 无默认值的字段 |
additionalProperties | 是否允许未声明字段 | model_config = ConfigDict(extra="forbid") |
enum | 取值必须属于给定集合 | Literal[...] 或 Enum |
pattern | 字符串必须匹配的正则(ECMA-262 语法) | Field(pattern=...) |
minimum、maximum | 数值下界与上界,含端点 | Field(ge=..., le=...) |
minLength、maxLength | 字符串长度范围,按 Unicode 码点计 | Field(min_length=..., max_length=...) |
minItems、maxItems | 数组元素个数范围 | Field(min_length=..., max_length=...) |
items | 数组元素的模式 | list[T] |
$defs`、`$ref | 可复用定义与引用,支持递归结构 | 嵌套模型、自引用模型 |
oneOf、anyOf | 满足其中之一(oneOf 要求恰好一个) | Union、判别联合 |
if、then、else | 条件约束 | 自定义校验器,无法完整映射 |
Pydantic 的工作流程是:类型注解与 Field 参数被编译为内部 core schema,model_json_schema() 从 core schema 生成符合 2020-12 草案的 JSON Schema,model_validate 或 model_validate_json 按同一 core schema 校验输入。三者共享一份定义,因此模型、模式与校验器不会漂移。
一个关键限制是表达能力不对等。JSON Schema 能表达结构约束,不能表达业务语义,例如"引用必须出现在给定文档中""两个日期字段的先后顺序""金额之和等于总额"。Pydantic 可以用 model_validator 表达跨字段约束,但这类校验器不会出现在 model_json_schema() 的输出中。后果是:用 schema 做约束解码只能保证结构合法,跨字段约束仍必须在服务端执行。把 model_validator 当作已生效的保证,是集成阶段最常见的错误。
强约束模式(部分厂商称为 strict 模式)通常要求 additionalProperties: false、所有属性列入 required、可选字段用 ["string", "null"] 表达,且只支持 JSON Schema 的子集。跨厂商移植 schema 时,应先确认目标实现支持的关键字集合,而不是假定 2020-12 全量可用。
3 函数调用与工具调用
工具调用的输入是一个三元组:工具名 、自然语言描述 、参数模式 (一个 JSON Schema 对象)。模型输出一个调用对象,包含调用标识 、工具名与参数:
{"id": "call_1", "name": "search_docs", "arguments": {"query": "GQA 显存", "top_k": 5}}
运行时依次做四件事:按 在工具注册表中查找;用 校验 arguments;执行工具;把结果以工具消息的形式回填到上下文。模型不执行任何函数,它只生成参数。这一点决定了所有安全性检查都必须在运行时完成。
函数调用与普通结构化输出的关系是特例关系:普通结构化输出的模式由任务定义,函数调用的模式由工具签名定义,且多了一个执行环节。因此本篇第 4 节的约束解码、第 6 节的失败处理同样适用,只是失败可能发生在执行阶段而不是解析阶段。
两种实现方式需要区分。部分服务在解码层把输出约束到工具模式,参数必然合法;部分服务只在训练层让模型学会输出调用格式,不提供解码保证。前者的合法性由构造保证,后者仍需校验。无论哪种,参数的业务合法性(路径是否存在、查询是否越权)都必须独立检查。并行调用时,多个调用对象共享同一轮输出,结果按 匹配,顺序不保证,运行时必须容忍乱序与部分失败。协议层面的标准化见 MCP协议,Agent 循环中的调用编排见 Agent工作流与编排。
4 约束解码的原理
自回归生成在第 步计算 logits ,采样 。约束解码在此处插入掩码:对允许集合 之外的所有 token 赋 ,再归一化。等价的实现是只对允许集合计算 softmax,数值更稳定:
语法状态由自动机维护。生成 后,状态转移到 ;允许集合是
不同结构层次对应不同的自动机。有限语言(固定的几个输出串)用前缀树或确定性有限自动机(DFA);正则表达式用 DFA;JSON 是上下文无关语言,需要下推自动机(PDA)维护括号与嵌套栈。工程实现通常把 JSON 文法编译为增量解析器,维护"当前期望的 token 类别"(键、冒号、值、逗号、闭合括号)与嵌套深度,再映射到 token 级允许集合。
token 与字符的错位是主要实现难点。BPE 的 token 可能跨多个字符,例如 ":" 是单 token,"score": 也可能是单 token。字符级自动机不能直接套用到 token 级词表,否则会屏蔽掉合法的多字符 token,或允许跨越状态边界的非法 token。正确做法是对每个状态预计算 token 级转移:枚举词表中每个 token 的字节串,从当前状态逐字符走自动机,全部可达才允许。该预计算的状态空间是 ,对复杂 schema 可能过大,实现上采用惰性计算与缓存,并配合 token 修复(token healing):当上一个 token 的前缀跨越边界时,回退并重新编码。
实现代价可以分成四项。第一是每步掩码计算,若逐 token 检查则为 ,与语言模型头的计算同阶,通常可接受;真正的开销在状态维护与转移查表。第二是批处理,同一批次中不同序列处于不同语法状态,掩码不同,朴素实现要么按状态分组、要么逐序列处理,两种方式都会降低 GPU 利用率。第三是缓存与编译,复杂 schema 的自动机构建耗时可达数百毫秒,需要按 schema 缓存。第四是数值,使用 在部分内核上会产生 NaN,工程上改用 torch.finfo(dtype).min;若某状态允许集合为空(文法死路),必须显式报错而不是继续生成。
约束解码改变语义分布,这一点常被忽略。条件化到 后,模型原本偏好的 token 若不在允许集中会被强制替换,替换可能产生语法正确但语义错误的输出。Geng 等的实验表明,语法约束解码在结构化 NLP 任务上显著提升结构正确率,同时对语义指标的影响依任务而变,在部分任务上出现下降。因此约束解码不能替代语义校验,二者测量的是不同维度。
5 提示词约束与解码约束的对比
| 维度 | 提示词约束 | 解码约束 |
|---|---|---|
| 合法性保证 | 概率性,长度增加时按 衰减 | 构造性,合法率为 1 |
| 实现成本 | 低,改提示即可 | 高,需自动机、掩码处理器、批处理改造 |
| 灵活性 | 高,任意自然语言约束 | 低,只能表达形式化模式 |
| 语义质量 | 模型按自身分布生成,通常更自然 | 可能被强制替换,出现语义偏移 |
| 可移植性 | 跨模型通用 | 依赖推理引擎接口 |
| 失败模式 | 解析失败、字段缺失、格式漂移 | 文法死路、吞吐下降、token 错位 |
| 调试难度 | 低,可读 | 高,需检查状态机与掩码 |
实践中的组合是分层的:提示词说明任务与字段含义,schema 同时出现在提示中(让模型知道目标结构),服务端做校验,对格式要求严格或重试成本高的场景再叠加约束解码。四层中任意一层缺失都会降低整体成功率,但只有校验层是不可省略的,因为它是唯一能发现语义错误的层。
6 失败处理
失败分为五类,处理方式不同。
| 类型 | 典型表现 | 处理 |
|---|---|---|
| 截断 | 序列在字符串或对象中间结束 | 提高 max_tokens,把长字段后置,必要时分段生成 |
| 语法错误 | 尾逗号、单引号、缺引号、未转义换行 | 局部修复或重试,记录原始输出 |
| 模式违反 | 字段缺失、类型错误、越界、枚举外取值 | 把具体错误回填到重试提示 |
| 语义错误 | 结构与类型全对,内容与资料不符 | 校验引用、交叉核对,重试通常无效 |
| 执行错误 | 工具参数合法但调用失败 | 把错误作为观测回填,限制重试次数 |
重试的期望成本可以量化。设单次成功概率为 ,最多重试 次(总尝试 次),则成功率与期望尝试次数为
取 、,成功率为 ,期望尝试 次。若 , 时成功率仅 ,期望尝试 次,此时应修改提示或模式,而不是继续增加重试次数。
重试提示必须携带可操作的信息。把完整错误列表回填,并指明字段路径与违反的关键字,效果优于笼统的"格式不对"。同时应避免把上一次的错误输出整段放进上下文,它会成为新的 few-shot 示例,诱导模型复制同样的错误结构。
部分修复适用于语法层错误。常见做法是提取第一个括号平衡的 JSON 对象、删除对象或数组末尾的逗号、把单引号替换为双引号、补全被截断的闭合符号。修复的风险是静默改变语义:删除逗号可能改变数组元素个数,替换引号可能破坏包含撇号的字符串。因此修复后必须重新校验,并保留原始输出用于分析。
回退策略按代价排序:先把模式简化(去掉嵌套、把联合类型改为单一类型、把枚举改为字符串加服务端校验),再把任务拆分(先输出分类,再按分类生成对应结构),最后转人工。回退不是失败,它是把不可靠的自动流程换成可靠的半自动流程。
7 流式输出与结构化
流式输出逐 token 或逐块返回,标准 JSON 解析器无法处理不完整的前缀:{"answer": "部 不是合法 JSON,json.loads 会抛出异常。三种可行做法如下。
第一,增量解析。维护解析栈,逐字符喂入,遇到完整的对象或数组元素时触发回调。实现可用现成的增量 JSON 解析器,也可以按本节的括号平衡扫描自行实现。第二,改用 JSON Lines(NDJSON),每行一个完整对象,逐行解析,天然支持流式。第三,只在完整对象到达后解析,中间状态仅用于界面展示,不进入业务逻辑。
约束解码与流式兼容,因为掩码是逐 token 应用的,不要求一次性生成全文。但字段顺序会影响流式体验:把标识、状态、短字段放在模式前面,把长文本放在最后,前端可以在长文本生成期间先渲染状态。JSON 对象的键顺序在多数实现中按模式声明顺序生成,这使顺序成为可控的设计变量,而不是偶然结果。
流式场景下的校验必须分两层:增量层只做括号与转义检查,保证不会把半截 JSON 送进业务逻辑;完整层在对象闭合后执行模式校验与语义校验。把两层合并会导致两种错误,要么在流式阶段误判合法前缀为错误,要么在完整阶段漏检跨字段约束。
关键直觉
结构化输出把"输出是否合法"从概率问题变成构造问题:约束解码在每个位置只保留合法分支并对剩余概率重归一化,因此合法性由构造保证;但语义正确性不在模式之内,仍需独立校验。
与严格定义的关系:定义中的 划定了合法集合, 实现了逐位置的集合限制, 说明了该操作对分布的影响。三者共同解释一个工程事实——schema 管结构,校验管语义,二者不可互相替代。
例子与代码
例 1:Pydantic 模型、JSON Schema 与校验重试
以下代码使用 pydantic 2.x(验证环境 2.14.1),定义带跨字段约束的答案模型,打印生成的 JSON Schema 摘要,并对三条候选输出执行校验。
import json
from typing import Literal
from pydantic import BaseModel, Field, ValidationError, model_validator
class Citation(BaseModel):
doc_id: str = Field(pattern=r"^D\d+$", description="资料编号,形如 D3")
quote: str = Field(min_length=6, max_length=120)
class Answer(BaseModel):
answer: str = Field(min_length=1, max_length=500)
citations: list[Citation] = Field(default_factory=list, max_length=5)
confidence: float = Field(ge=0.0, le=1.0)
status: Literal["answered", "insufficient_context"]
@model_validator(mode="after")
def check_consistency(self):
if self.status == "answered" and not self.citations:
raise ValueError("status=answered 时 citations 不能为空")
if self.status == "insufficient_context" and self.citations:
raise ValueError("status=insufficient_context 时不应给出 citations")
return self
schema = Answer.model_json_schema()
print("顶层字段:", sorted(schema["properties"]))
print("必填字段:", sorted(schema["required"]))
print("Citation 字段:", sorted(schema["$defs"]["Citation"]["properties"]))
print("confidence 约束:", schema["properties"]["confidence"])
print()
RAW = [
'{"answer": "GQA 降低键值头数量 [D2]。", "citations": [{"doc_id": "D2", "quote": "多个查询头共享一组键值头"}], "confidence": 0.82, "status": "answered"}',
'{"answer": "GQA 降低显存。", "citations": [], "confidence": 0.7, "status": "answered"}',
'{"answer": "GQA 降低显存。", "citations": [{"doc_id": "3", "quote": "共享键值头"}], "confidence": 1.7, "status": "answered"}',
'{"answer": "资料未覆盖该问题。", "citations": [], "confidence": 0.2, "status": "insufficient_context"}',
]
def check(raw, attempt):
try:
obj = json.loads(raw)
except json.JSONDecodeError as exc:
print(f"尝试 {attempt}: JSON 解析失败 msg={exc.msg!r} pos={exc.pos}")
return None, ["JSON 语法错误:请输出完整对象"]
try:
model = Answer.model_validate(obj)
except ValidationError as exc:
errors = [f"{'.'.join(map(str, e['loc'])) or '<root>'}: {e['msg']}"
for e in exc.errors(include_url=False)]
print(f"尝试 {attempt}: 模式校验失败 错误数={len(errors)}")
for e in errors:
print(" -", e)
return None, errors
print(f"尝试 {attempt}: 通过,confidence={model.confidence} citations={len(model.citations)}")
return model, []
def generate(raws):
history = []
for i, raw in enumerate(raws, 1):
model, errors = check(raw, i)
history.append(errors)
if model is not None:
return model, history
return None, history
model, history = generate(RAW[2:])
print("\n最终结果:", None if model is None else model.answer)
print("每轮错误数:", [len(h) for h in history])
顶层字段: ['answer', 'citations', 'confidence', 'status']
必填字段: ['answer', 'confidence', 'status']
Citation 字段: ['doc_id', 'quote']
confidence 约束: {'maximum': 1.0, 'minimum': 0.0, 'title': 'Confidence', 'type': 'number'}
尝试 1: 模式校验失败 错误数=3
- citations.0.doc_id: String should match pattern '^D\d+$'
- citations.0.quote: String should have at least 6 characters
- confidence: Input should be less than or equal to 1
尝试 2: 通过,confidence=0.2 citations=0
最终结果: 资料未覆盖该问题。
每轮错误数: [3, 0]
输出中有三处需要解释。第一,必填字段只有三项,citations 不在其中,因为它有 default_factory=list,省略时会得到空列表而不是报错;这使"字段缺失"与"字段为空"在校验层不可区分,必须用跨字段校验弥补。第二,第一次校验返回三条错误,其中两条位于 citations.0,路径精确到数组下标与字段名,这类信息可以直接回填到重试提示。第三,第二次校验通过,因为候选输出的 status 为 insufficient_context 且引用为空,满足跨字段约束;这说明校验器接受的是"资料不足"这一合法状态,而不是把所有空引用都判为错误。
若去掉 model_validator,{"status": "answered", "citations": []} 会通过校验,系统会把一条没有依据的结论当作正常答案返回。若把 citations 的默认值改为必填,则"资料不足"场景需要显式传空数组,schema 的 required 会包含该字段,提示词也必须相应说明,否则模型在拒答时会漏掉该字段。
例 2:简化的受限词表解码
下面的例子用字符级词表演示掩码机制。目标是四种合法输出:{"status": "ok", "score": 7}、{"status": "ok", "score": 87}、{"status": "failed", "score": 7}、{"status": "failed", "score": 87},用前缀集合表示自动机的状态。真实实现中词表是 BPE token 而非字符,且允许集合由 token 级转移表给出。
import numpy as np
STATUS = ('{"status": "ok", "score": ', '{"status": "failed", "score": ')
TARGETS = [s + n + "}" for s in STATUS for n in ("7", "87")]
ALPHABET = sorted(set("".join(TARGETS)))
PREFIXES = {t[:i] for t in TARGETS for i in range(len(t) + 1)}
rng = np.random.RandomState(0)
prefix = ""
records, flips = [], 0
while prefix not in TARGETS:
allowed = [c for c in ALPHABET if prefix + c in PREFIXES] # 文法状态允许的字符
z = rng.normal(size=len(ALPHABET)) * 2.0 # 模拟模型 logits
masked = np.full_like(z, -np.inf)
idx = [ALPHABET.index(c) for c in allowed]
masked[idx] = z[idx] # 只保留合法字符
greed = ALPHABET[int(z.argmax())]
choice = ALPHABET[int(masked.argmax())]
flips += int(greed != choice)
records.append((len(prefix) + 1, "".join(allowed), greed, choice))
prefix += choice
print("字符级词表大小:", len(ALPHABET), "目标串个数:", len(TARGETS))
print("步 合法字符集 未约束选择 掩码后选择")
for step, allowed, g, c in records:
if step <= 3 or len(allowed) > 1 or step >= len(records) - 1:
print(f"{step:>2} {allowed:<8} {g!r:>4} -> {c!r:>4}")
elif step == 4:
print(" ...")
print("总步数:", len(records), "掩码改变了贪心选择的步数:", flips)
print("输出:", prefix)
print("属于目标语言:", prefix in TARGETS)
字符级词表大小: 21 目标串个数: 4
步 合法字符集 未约束选择 掩码后选择
1 { '7' -> '{'
2 " '7' -> '"'
3 s '"' -> 's'
...
13 fo '}' -> 'o'
27 78 'o' -> '8'
28 7 'k' -> '7'
29 } ',' -> '}'
总步数: 29 掩码改变了贪心选择的步数: 28
输出: {"status": "ok", "score": 87}
属于目标语言: True
第 13 步与第 27 步是分支点:第 13 步的允许集为 fo,对应 ok 与 failed 的首字母;第 27 步的允许集为 78,对应一位数与两位数的首位。未约束的 argmax 在这两步分别选择了 } 与 o,都是非法字符,掩码把它们替换为合法字符。29 步中有 28 步的贪心选择被修改,说明在随机 logits 下,未经训练的输出几乎不可能碰巧合法,这正是第 1 节 衰减的直观体现。
代码中的前缀集合把整条目标串展开为所有前缀,规模为 ,只适用于有限语言。真实 schema 是递归的,状态数无界,必须用下推自动机或增量解析器,并把字符自动机提升到 token 级。去掉掩码后循环仍然会终止,但输出会包含非法字符,prefix in TARGETS 判为假;去掉 -inf 改用 0 也不可行,因为 0 只是压低概率而不排除非法 token。
例 3:从自由文本中提取并修复 JSON
下面的代码处理第 6 节的语法层失败:先从带解释文字与代码围栏的输出中截取括号平衡的对象,再修复尾逗号与单引号,最后交给 Pydantic 校验。
import json
import re
from typing import Literal
from pydantic import BaseModel, Field, ValidationError, model_validator
class Citation(BaseModel):
doc_id: str = Field(pattern=r"^D\d+$")
quote: str = Field(min_length=6, max_length=120)
class Answer(BaseModel):
answer: str = Field(min_length=1, max_length=500)
citations: list[Citation] = Field(default_factory=list, max_length=5)
confidence: float = Field(ge=0.0, le=1.0)
status: Literal["answered", "insufficient_context"]
@model_validator(mode="after")
def check_consistency(self):
if self.status == "answered" and not self.citations:
raise ValueError("status=answered 时 citations 不能为空")
if self.status == "insufficient_context" and self.citations:
raise ValueError("status=insufficient_context 时不应给出 citations")
return self
def extract_first_json(text):
"""从自由文本中截取第一个括号平衡的 JSON 对象,字符串与转义状态单独跟踪。"""
start = text.find("{")
if start < 0:
return None
depth, in_str, escaped = 0, False, False
for i in range(start, len(text)):
ch = text[i]
if in_str:
if escaped:
escaped = False
elif ch == "\\":
escaped = True
elif ch == '"':
in_str = False
continue
if ch == '"':
in_str = True
elif ch == "{":
depth += 1
elif ch == "}":
depth -= 1
if depth == 0:
return text[start:i + 1]
return None
def repair(s):
"""修复两类高频语法错误:对象或数组末尾的逗号、单引号字符串。"""
s = re.sub(r",\s*([}\]])", r"\1", s)
s = re.sub(r"'([^'\\]*)'", r'"\1"', s)
return s
FENCE = "`" * 3 # 避免源码中出现三连反引号
RAW = ("好的,结果如下:\n" + FENCE + "json\n"
'{"answer": \'GQA 降低键值头数量 [D2]。\', "citations": [{"doc_id": "D2", '
'"quote": "多个查询头共享一组键值头"}], "confidence": 0.82, "status": "answered",}\n'
+ FENCE + "\n以上是结构化结果。")
fragment = extract_first_json(RAW)
print("截取长度:", len(fragment))
print("截取片段尾部:", fragment[-20:])
fixed = repair(fragment)
obj = json.loads(fixed)
print("修复后可直接解析:", isinstance(obj, dict))
model = Answer.model_validate(obj)
print("校验通过:", model.status, model.confidence, len(model.citations))
print("answer:", model.answer)
bad = "{'answer': 'x', 'citations': [], 'confidence': 0.5, 'status': 'answered'}"
obj_bad = json.loads(repair(bad))
try:
Answer.model_validate(obj_bad)
except ValidationError as exc:
print("语义校验仍失败:", exc.errors(include_url=False)[0]["msg"])
截取长度: 132
截取片段尾部: tatus": "answered",}
修复后可直接解析: True
校验通过: answered 0.82 1
answer: GQA 降低键值头数量 [D2]。
语义校验仍失败: Value error, status=answered 时 citations 不能为空
extract_first_json 用三个状态跟踪括号、字符串与转义,避免把字符串内部的花括号计入嵌套深度;若只用 text[text.find("{"):text.rfind("}")+1],字符串中含 } 时会截错。repair 的两条正则分别处理尾逗号与单引号,修复是语法层的,不改变字段语义,但把单引号统一替换为双引号在字符串本身包含撇号时会破坏内容,因此只能作为兜底,不能作为默认路径。
最后一段故意构造了一个结构完整但语义非法的对象:修复后 JSON 合法,citations 为空且 status 为 answered,被校验器拒绝。这印证第 6 节的分类:语法错误可以修复,语义错误不能靠修复解决。
易错点
以下六条均可在运行结果或 schema 输出中直接检验。
1. 认为
required保证字段非空:required只要求键存在,""、[]、null都是合法值。非空需要minLength、minItems或跨字段校验,三者作用不同。2. 认为 Pydantic 的
model_validator会出现在 JSON Schema 中:它不会。基于 schema 的约束解码或第三方校验器无法执行该逻辑,服务端必须重复校验,否则跨字段约束形同虚设。3. 用 做掩码:部分内核会产生 NaN,整批 logits 被污染。应使用
torch.finfo(dtype).min,并在允许集为空时报错而不是继续采样。4. 把提示词中的"请输出 JSON"当作合法性保证:长结构的整体合法率按 衰减,提示只能提高单步合法率,不能提供保证。必须校验或约束解码。
5. 忽略 token 与字符的错位:把字符级文法直接应用于 BPE 词表,会屏蔽合法的多字符 token 或允许跨状态的非法 token,表现为"模型输出总是很短"或"偶尔出现非法字符"。
6. 用
json.loads解析流式片段:增量片段不是完整 JSON,必然抛异常。应使用增量解析器、NDJSON 或等对象闭合后再解析。
关联笔记
- 前置 Prompt工程:五元组中的输出格式字段与约束写法是本篇模式设计的上游,本篇第 5 节对比了两条实现路径的成本与保证。
- 后续 AI-Agent与工具调用:工具调用的参数模式是本篇第 3 节的特例,运行时校验与错误回填在该篇展开为完整协议。
- 后续 MCP协议:工具与资源的描述需要统一的模式表达,MCP 的消息格式决定了 schema 如何跨进程传递与校验。
- 后续 RAG原理与流程:结构化答案中的引用字段使三元组评估可自动化,本篇第 2 节的
citations模式是该评估流程的输入格式。 - 对照 指令微调SFT:训练侧通过样本教模型输出格式,解码侧通过掩码保证格式,两者的收益在不同任务上互补,不能互相替代。
达标检测
- [ ] 写出事后解析的合法率公式,取 、 计算整体合法率,并说明该估算为何偏悲观。
- [ ] 给定一个包含枚举、范围、数组长度与跨字段约束的需求,写出对应的 Pydantic 模型,指出哪些约束不会出现在
model_json_schema()中。 - [ ] 写出掩码后的 softmax 表达式,说明为什么逐 token 掩码等价于在 上做条件采样,并指出该等价所需的前缀封闭条件。
- [ ] 用前缀集合实现一个只接受
{"a": 1}与{"a": 12}的字符级约束解码器,统计掩码改变 argmax 的步数。 - [ ] 取 、,计算重试成功率与期望尝试次数,并说明何时应停止重试改为修改模式。
- [ ] 给出一个流式输出场景的设计:字段顺序、增量解析方式、两层校验的分工,并说明为什么不能在流式阶段执行跨字段校验。
参考来源
- OpenAI, "Function Calling" 官方文档 —— 对应第 3 节的工具三元组、调用对象结构、并行调用与结果回填。
- JSON Schema 规范(json-schema.org,draft 2020-12)—— 对应第 2 节各关键字的语义、
$defs/$ref递归结构与if/then/else条件约束。 - Pydantic 官方文档 v2 —— 对应第 2 节的模型定义、
model_json_schema()生成规则、model_validator与model_validate_json的行为。 - Geng et al., "Grammar-Constrained Decoding for Structured NLP Tasks without Finetuning", arXiv:2305.13971, 2023 —— 对应第 4 节约束解码对结构正确率与语义指标的影响。
- LangChain 官方文档(structured output 与 output parsers)—— 对应第 6 节的解析失败分类、重试与回退策略。