---
tags: [AI, json, pydantic]
阶段: 06-Prompt与RAG
难度: ★★☆
created: 2026-10-18
related: "[[Prompt工程]], [[AI-Agent与工具调用]], [[RAG原理与流程]]"
---

# 结构化输出

## 定义

**结构化输出**（structured output）指把模型生成的 token 序列约束到由模式 $S$ 定义的语言 $L(S)\subseteq\mathcal{V}^{*}$ 内，使输出可被程序解析、校验并直接用于下游计算；**模式**（schema）是对输出结构的声明式描述，JSON Schema 用字段集合、类型、必填性与取值范围描述 JSON 文档，Pydantic 用 Python 类型注解描述同一组约束；**约束解码**（constrained decoding）指在自回归生成的每一步，把不满足模式的状态转移概率置零后再采样，

$$
y_t\sim \mathrm{softmax}\big(\mathbf{z}_t+\mathbf{m}_t\big),\qquad
m_{t,v}=\begin{cases}0,& v\in A(q_t),\\ -\infty,& v\notin A(q_t),\end{cases}
$$

其中 $q_t$ 是第 $t$ 步的语法状态，$A(q_t)$ 是该状态下允许的 token 集合。

符号约定如下。

| 符号 | 含义 |
|---|---|
| $\mathcal{V}$ | 词表，$V=\lvert\mathcal{V}\rvert$ |
| $y=(y_1,\dots,y_n)$ | 输出 token 序列，长度 $n$ |
| $S$ | 模式，本篇指 JSON Schema 或等价的 Pydantic 模型 |
| $L(S)$ | 满足 $S$ 的全部 JSON 文档构成的集合 |
| $\mathbf{z}_t\in\mathbb{R}^{V}$ | 第 $t$ 步的 logits |
| $\mathbf{m}_t\in(\mathbb{R}\cup\{-\infty\})^{V}$ | 掩码向量 |
| $G=(Q,\Sigma,\delta,q_0,F)$ | 描述 $L(S)$ 的自动机，$Q$ 为状态集，$\Sigma$ 为字符集，$\delta$ 为转移函数，$q_0$ 为初始状态，$F$ 为接受状态集 |
| $A(q)$ | 状态 $q$ 下允许的 token 集合 |
| $p$ | 单步生成合法 token 的概率 |
| $K$ | 最大重试次数 |

其余术语在首次出现处定义：**JSON Schema** 是描述 JSON 文档结构的规范，当前常用草案为 2020-12；**Pydantic** 是 Python 的数据校验库，第二版用 Rust 实现核心校验；**函数调用**（function calling）指模型输出结构化的工具名与参数对象；**语法约束解码**（grammar-constrained decoding）指以形式文法而非 JSON Schema 为约束的约束解码；**流式输出**指逐 token 或逐段返回结果。

## 为什么重要

下游程序只接受确定的结构。自然语言回答需要额外的抽取步骤，而抽取本身又是一个模型调用，误差叠加且无法保证；结构化输出把这一步前移到生成阶段，使"解析成功"成为可验证的属性而不是概率事件。

没有结构化输出会产生四类具体成本。第一类是解析成本，自由文本中字段可能缺失、类型错误、被代码围栏包裹、被解释文字打断，解析器需要为每种情况写分支，分支的覆盖率决定系统稳定性。第二类是校验成本，即使解析成功，字段取值仍需检查范围、枚举与跨字段一致性，缺少模式时这些检查散落在业务代码中，无法复用。第三类是重试成本，解析失败后只能整段重生成，期望调用次数按几何级数增长，而结构化输出可以把失败定位到具体字段。第四类是幂等成本，重试与去重需要稳定的请求标识与结果摘要，结构化输出使这些字段可以显式声明。

结构化输出在本库中的位置是输入控制层与系统集成层的交界。[[Prompt工程]] 讨论如何用提示词表达格式要求，本篇讨论如何把要求变成可执行的约束；[[AI-Agent与工具调用]] 的调用参数是本篇模式的一个特例；[[RAG原理与流程]] 需要结构化的答案与引用字段才能做三元组评估；[[指令微调SFT]] 从训练侧教模型输出格式，本篇从解码侧保证格式，两者是互补关系。对应学习目标中的"能复现"与"会评估"：能写出模式与校验循环，能测量格式合规率与语义正确率两个独立指标。

## 原理与推导

### 1 结构化输出的形式化

生成模型定义分布 $p_\theta(y\mid x)$，其支持集是整个 $\mathcal{V}^{n}$。结构化输出的目标是使采样结果落在 $L(S)$ 内：

$$
y\sim p_\theta(\cdot\mid x)\quad\text{且}\quad y\in L(S).
$$

有两种实现路径，性质不同。

事后路径先生成再解析：从 $p_\theta$ 采样完整序列，用解析器检查是否属于 $L(S)$，失败则重试。设第 $t$ 步生成合法 token 的概率为 $p_t$，各步近似独立，则整段合法的概率为

$$
P_{\text{legal}}=\prod_{t=1}^{n}p_t\approx p^{n}.
$$

取 $p=0.99$、$n=200$，$P_{\text{legal}}=0.99^{200}\approx0.134$。即使每一步有 99% 的概率正确，200 步之后只有 13.4% 的输出整体合法。该估算偏悲观，因为模型经过指令微调后对常见 schema 的单步合法率远高于 0.99，且错误相关；但它正确指出了趋势：结构越长，事后解析的失败率越高，重试成本随长度指数上升。

过程路径在每一步限制候选集，从条件分布

$$
p_{\text{con}}(y\mid x)=\frac{p_\theta(y\mid x)\,\mathbb{1}\left[y\in L(S)\right]}{\sum_{y'\in L(S)}p_\theta(y'\mid x)}
$$

中采样。逐 token 加掩码并重归一化，在 $L(S)$ 对前缀封闭（任一合法串的任一前缀都允许继续生成）的条件下，恰好实现该条件分布。合法率因此等于 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 函数调用与工具调用

工具调用的输入是一个三元组：工具名 $name$、自然语言描述 $description$、参数模式 $parameters$（一个 JSON Schema 对象）。模型输出一个调用对象，包含调用标识 $id$、工具名与参数：

```json
{"id": "call_1", "name": "search_docs", "arguments": {"query": "GQA 显存", "top_k": 5}}
```

运行时依次做四件事：按 $name$ 在工具注册表中查找；用 $parameters$ 校验 `arguments`；执行工具；把结果以工具消息的形式回填到上下文。模型不执行任何函数，它只生成参数。这一点决定了所有安全性检查都必须在运行时完成。

函数调用与普通结构化输出的关系是特例关系：普通结构化输出的模式由任务定义，函数调用的模式由工具签名定义，且多了一个执行环节。因此本篇第 4 节的约束解码、第 6 节的失败处理同样适用，只是失败可能发生在执行阶段而不是解析阶段。

两种实现方式需要区分。部分服务在解码层把输出约束到工具模式，参数必然合法；部分服务只在训练层让模型学会输出调用格式，不提供解码保证。前者的合法性由构造保证，后者仍需校验。无论哪种，参数的业务合法性（路径是否存在、查询是否越权）都必须独立检查。并行调用时，多个调用对象共享同一轮输出，结果按 $id$ 匹配，顺序不保证，运行时必须容忍乱序与部分失败。协议层面的标准化见 [[MCP协议]]，Agent 循环中的调用编排见 [[Agent工作流与编排]]。

### 4 约束解码的原理

自回归生成在第 $t$ 步计算 logits $\mathbf{z}_t\in\mathbb{R}^{V}$，采样 $y_t\sim\mathrm{softmax}(\mathbf{z}_t)$。约束解码在此处插入掩码：对允许集合 $A(q_t)$ 之外的所有 token 赋 $-\infty$，再归一化。等价的实现是只对允许集合计算 softmax，数值更稳定：

$$
p(y_t=v)=\frac{\exp(z_{t,v})}{\sum_{u\in A(q_t)}\exp(z_{t,u})},\qquad v\in A(q_t).
$$

语法状态由自动机维护。生成 $y_t$ 后，状态转移到 $q_{t+1}=\delta(q_t,y_t)$；允许集合是

$$
A(q)=\left\{v\in\mathcal{V}:\ \delta(q,v)\ \text{有定义}\right\}.
$$

不同结构层次对应不同的自动机。有限语言（固定的几个输出串）用前缀树或确定性有限自动机（DFA）；正则表达式用 DFA；JSON 是上下文无关语言，需要下推自动机（PDA）维护括号与嵌套栈。工程实现通常把 JSON 文法编译为增量解析器，维护"当前期望的 token 类别"（键、冒号、值、逗号、闭合括号）与嵌套深度，再映射到 token 级允许集合。

token 与字符的错位是主要实现难点。BPE 的 token 可能跨多个字符，例如 `":"` 是单 token，`"score":` 也可能是单 token。字符级自动机不能直接套用到 token 级词表，否则会屏蔽掉合法的多字符 token，或允许跨越状态边界的非法 token。正确做法是对每个状态预计算 token 级转移：枚举词表中每个 token 的字节串，从当前状态逐字符走自动机，全部可达才允许。该预计算的状态空间是 $\lvert Q\rvert\times V$，对复杂 schema 可能过大，实现上采用惰性计算与缓存，并配合 token 修复（token healing）：当上一个 token 的前缀跨越边界时，回退并重新编码。

实现代价可以分成四项。第一是每步掩码计算，若逐 token 检查则为 $O(V)$，与语言模型头的计算同阶，通常可接受；真正的开销在状态维护与转移查表。第二是批处理，同一批次中不同序列处于不同语法状态，掩码不同，朴素实现要么按状态分组、要么逐序列处理，两种方式都会降低 GPU 利用率。第三是缓存与编译，复杂 schema 的自动机构建耗时可达数百毫秒，需要按 schema 缓存。第四是数值，使用 $-\infty$ 在部分内核上会产生 NaN，工程上改用 `torch.finfo(dtype).min`；若某状态允许集合为空（文法死路），必须显式报错而不是继续生成。

约束解码改变语义分布，这一点常被忽略。条件化到 $L(S)$ 后，模型原本偏好的 token 若不在允许集中会被强制替换，替换可能产生语法正确但语义错误的输出。Geng 等的实验表明，语法约束解码在结构化 NLP 任务上显著提升结构正确率，同时对语义指标的影响依任务而变，在部分任务上出现下降。因此约束解码不能替代语义校验，二者测量的是不同维度。

### 5 提示词约束与解码约束的对比

| 维度 | 提示词约束 | 解码约束 |
|---|---|---|
| 合法性保证 | 概率性，长度增加时按 $p^{n}$ 衰减 | 构造性，合法率为 1 |
| 实现成本 | 低，改提示即可 | 高，需自动机、掩码处理器、批处理改造 |
| 灵活性 | 高，任意自然语言约束 | 低，只能表达形式化模式 |
| 语义质量 | 模型按自身分布生成，通常更自然 | 可能被强制替换，出现语义偏移 |
| 可移植性 | 跨模型通用 | 依赖推理引擎接口 |
| 失败模式 | 解析失败、字段缺失、格式漂移 | 文法死路、吞吐下降、token 错位 |
| 调试难度 | 低，可读 | 高，需检查状态机与掩码 |

实践中的组合是分层的：提示词说明任务与字段含义，schema 同时出现在提示中（让模型知道目标结构），服务端做校验，对格式要求严格或重试成本高的场景再叠加约束解码。四层中任意一层缺失都会降低整体成功率，但只有校验层是不可省略的，因为它是唯一能发现语义错误的层。

### 6 失败处理

失败分为五类，处理方式不同。

| 类型 | 典型表现 | 处理 |
|---|---|---|
| 截断 | 序列在字符串或对象中间结束 | 提高 `max_tokens`，把长字段后置，必要时分段生成 |
| 语法错误 | 尾逗号、单引号、缺引号、未转义换行 | 局部修复或重试，记录原始输出 |
| 模式违反 | 字段缺失、类型错误、越界、枚举外取值 | 把具体错误回填到重试提示 |
| 语义错误 | 结构与类型全对，内容与资料不符 | 校验引用、交叉核对，重试通常无效 |
| 执行错误 | 工具参数合法但调用失败 | 把错误作为观测回填，限制重试次数 |

重试的期望成本可以量化。设单次成功概率为 $p$，最多重试 $K$ 次（总尝试 $K+1$ 次），则成功率与期望尝试次数为

$$
P_{\text{succ}}=1-(1-p)^{K+1},\qquad
\mathbb{E}[\text{attempts}]=\sum_{k=0}^{K}(1-p)^{k}=\frac{1-(1-p)^{K+1}}{p}.
$$

取 $p=0.7$、$K=2$，成功率为 $1-0.3^{3}=0.973$，期望尝试 $0.973/0.7\approx1.39$ 次。若 $p=0.3$，$K=2$ 时成功率仅 $0.657$，期望尝试 $2.19$ 次，此时应修改提示或模式，而不是继续增加重试次数。

重试提示必须携带可操作的信息。把完整错误列表回填，并指明字段路径与违反的关键字，效果优于笼统的"格式不对"。同时应避免把上一次的错误输出整段放进上下文，它会成为新的 few-shot 示例，诱导模型复制同样的错误结构。

部分修复适用于语法层错误。常见做法是提取第一个括号平衡的 JSON 对象、删除对象或数组末尾的逗号、把单引号替换为双引号、补全被截断的闭合符号。修复的风险是静默改变语义：删除逗号可能改变数组元素个数，替换引号可能破坏包含撇号的字符串。因此修复后必须重新校验，并保留原始输出用于分析。

回退策略按代价排序：先把模式简化（去掉嵌套、把联合类型改为单一类型、把枚举改为字符串加服务端校验），再把任务拆分（先输出分类，再按分类生成对应结构），最后转人工。回退不是失败，它是把不可靠的自动流程换成可靠的半自动流程。

### 7 流式输出与结构化

流式输出逐 token 或逐块返回，标准 JSON 解析器无法处理不完整的前缀：`{"answer": "部` 不是合法 JSON，`json.loads` 会抛出异常。三种可行做法如下。

第一，增量解析。维护解析栈，逐字符喂入，遇到完整的对象或数组元素时触发回调。实现可用现成的增量 JSON 解析器，也可以按本节的括号平衡扫描自行实现。第二，改用 JSON Lines（NDJSON），每行一个完整对象，逐行解析，天然支持流式。第三，只在完整对象到达后解析，中间状态仅用于界面展示，不进入业务逻辑。

约束解码与流式兼容，因为掩码是逐 token 应用的，不要求一次性生成全文。但字段顺序会影响流式体验：把标识、状态、短字段放在模式前面，把长文本放在最后，前端可以在长文本生成期间先渲染状态。JSON 对象的键顺序在多数实现中按模式声明顺序生成，这使顺序成为可控的设计变量，而不是偶然结果。

流式场景下的校验必须分两层：增量层只做括号与转义检查，保证不会把半截 JSON 送进业务逻辑；完整层在对象闭合后执行模式校验与语义校验。把两层合并会导致两种错误，要么在流式阶段误判合法前缀为错误，要么在完整阶段漏检跨字段约束。

## 关键直觉

> [!tip] 结构化输出把"输出是否合法"从概率问题变成构造问题：约束解码在每个位置只保留合法分支并对剩余概率重归一化，因此合法性由构造保证；但语义正确性不在模式之内，仍需独立校验。
>
> 与严格定义的关系：定义中的 $L(S)$ 划定了合法集合，$m_{t,v}$ 实现了逐位置的集合限制，$p_{\text{con}}$ 说明了该操作对分布的影响。三者共同解释一个工程事实——schema 管结构，校验管语义，二者不可互相替代。

## 例子与代码

### 例 1：Pydantic 模型、JSON Schema 与校验重试

以下代码使用 pydantic 2.x（验证环境 2.14.1），定义带跨字段约束的答案模型，打印生成的 JSON Schema 摘要，并对三条候选输出执行校验。

```python
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])
```

```text
顶层字段: ['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 级转移表给出。

```python
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)
```

```text
字符级词表大小: 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 节 $p^{n}$ 衰减的直观体现。

代码中的前缀集合把整条目标串展开为所有前缀，规模为 $\sum_t\lvert t\rvert$，只适用于有限语言。真实 schema 是递归的，状态数无界，必须用下推自动机或增量解析器，并把字符自动机提升到 token 级。去掉掩码后循环仍然会终止，但输出会包含非法字符，`prefix in TARGETS` 判为假；去掉 `-inf` 改用 0 也不可行，因为 0 只是压低概率而不排除非法 token。

### 例 3：从自由文本中提取并修复 JSON

下面的代码处理第 6 节的语法层失败：先从带解释文字与代码围栏的输出中截取括号平衡的对象，再修复尾逗号与单引号，最后交给 Pydantic 校验。

```python
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"])
```

```text
截取长度: 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 节的分类：语法错误可以修复，语义错误不能靠修复解决。

## 易错点

> [!warning] 以下六条均可在运行结果或 schema 输出中直接检验。
> 1. 认为 `required` 保证字段非空：`required` 只要求键存在，`""`、`[]`、`null` 都是合法值。非空需要 `minLength`、`minItems` 或跨字段校验，三者作用不同。
> 2. 认为 Pydantic 的 `model_validator` 会出现在 JSON Schema 中：它不会。基于 schema 的约束解码或第三方校验器无法执行该逻辑，服务端必须重复校验，否则跨字段约束形同虚设。
> 3. 用 $-\infty$ 做掩码：部分内核会产生 NaN，整批 logits 被污染。应使用 `torch.finfo(dtype).min`，并在允许集为空时报错而不是继续采样。
> 4. 把提示词中的"请输出 JSON"当作合法性保证：长结构的整体合法率按 $p^{n}$ 衰减，提示只能提高单步合法率，不能提供保证。必须校验或约束解码。
> 5. 忽略 token 与字符的错位：把字符级文法直接应用于 BPE 词表，会屏蔽合法的多字符 token 或允许跨状态的非法 token，表现为"模型输出总是很短"或"偶尔出现非法字符"。
> 6. 用 `json.loads` 解析流式片段：增量片段不是完整 JSON，必然抛异常。应使用增量解析器、NDJSON 或等对象闭合后再解析。

## 关联笔记

- 前置 [[Prompt工程]]：五元组中的输出格式字段与约束写法是本篇模式设计的上游，本篇第 5 节对比了两条实现路径的成本与保证。
- 后续 [[AI-Agent与工具调用]]：工具调用的参数模式是本篇第 3 节的特例，运行时校验与错误回填在该篇展开为完整协议。
- 后续 [[MCP协议]]：工具与资源的描述需要统一的模式表达，MCP 的消息格式决定了 schema 如何跨进程传递与校验。
- 后续 [[RAG原理与流程]]：结构化答案中的引用字段使三元组评估可自动化，本篇第 2 节的 `citations` 模式是该评估流程的输入格式。
- 对照 [[指令微调SFT]]：训练侧通过样本教模型输出格式，解码侧通过掩码保证格式，两者的收益在不同任务上互补，不能互相替代。

## 达标检测

- [ ] 写出事后解析的合法率公式，取 $p=0.995$、$n=300$ 计算整体合法率，并说明该估算为何偏悲观。
- [ ] 给定一个包含枚举、范围、数组长度与跨字段约束的需求，写出对应的 Pydantic 模型，指出哪些约束不会出现在 `model_json_schema()` 中。
- [ ] 写出掩码后的 softmax 表达式，说明为什么逐 token 掩码等价于在 $L(S)$ 上做条件采样，并指出该等价所需的前缀封闭条件。
- [ ] 用前缀集合实现一个只接受 `{"a": 1}` 与 `{"a": 12}` 的字符级约束解码器，统计掩码改变 argmax 的步数。
- [ ] 取 $p=0.6$、$K=3$，计算重试成功率与期望尝试次数，并说明何时应停止重试改为修改模式。
- [ ] 给出一个流式输出场景的设计：字段顺序、增量解析方式、两层校验的分工，并说明为什么不能在流式阶段执行跨字段校验。

## 参考来源

- 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 节的解析失败分类、重试与回退策略。
