w wyl123ly 的博客
MD

结构化输出

33 KB 2026.10.18 原文件

结构化输出

定义

结构化输出(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 对应
typeJSON 类型: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 节的解析失败分类、重试与回退策略。