结构化输出与受限解码：从 JSON Schema 到 Token 掩码

提示词约束的常见翻车方式：
□ 前置寒暄：「好的，我来为你生成……{...}」
□ 代码块包裹：```json ... ```（多了围栏）
□ 尾随逗号：{"a": 1,}（JSON 不允许）
□ 字段缺失 / 类型漂移：数字写成字符串
□ 幻觉字段：多出 schema 里没有的 key
□ 截断：max_tokens 用尽，JSON 半截

以 JSON {"name": "x"} 为例：

状态 S0：期望 '{'     → 只允许 token '{'（或含 '{' 的开头）
状态 S1：期望 '"'     → 只允许 '"'
状态 S2：key 字符串   → 允许字母（不能是 '"'）
状态 S3：期望 ':'     → 只允许 ':'
...
状态 Sn：期望 '}'     → 只允许 '}' 或空白
状态 S_end：结束       → 只允许 EOS（或合法的后续）

每一步：把「所有 token」映射到「该状态下合法的 token 集合」，
      非法 token 的 logits 置为 -inf，再做采样。

# 概念示意（真实实现用编译好的 FSM/索引加速）
def constrained_sample(logits, state, tokenizer):
    allowed_ids = fsm.allowed_tokens(state)      # 当前状态合法 token 集合
    mask = torch.full_like(logits, float("-inf"))
    mask[allowed_ids] = 0.0                       # 合法位置保留
    masked_logits = logits + mask                 # 非法位置 -inf
    token = sample(masked_logits)                 # 采样（temperature 等照常）
    return token, fsm.step(state, token)          # 状态推进

掩码的两个技术难点：
① 词表遍历开销：每步要对 10 万+ 词表算合法性
   → 用预编译的「状态 → 合法 token 集合」索引
② token 跨字符边界：一个 token 可能含多个字符（如 "ab{"）
   → 需要「token → 字符序列」展开后再匹配 FSM

编译流水线：
JSON Schema
  → 归一化（展开 $ref、补全类型、处理 default）
  → 语法描述（正则 / 上下文无关文法 CFG / GBNF）
  → 有限状态机 / 下推自动机
  → 词表级状态转移表（每个 token 触发的状态迁移）
  → 运行时查表掩码

重要边界：受限解码只保证「结构合法」，不保证「语义正确」。
□ 结构：字段名、类型、嵌套、枚举值 → 保证
□ 语义：「age 是合理年龄」「金额单位正确」→ 不保证，仍需校验

from pydantic import BaseModel, Field
from typing import Literal

class WeatherQuery(BaseModel):
    city: str = Field(description="城市名")
    unit: Literal["celsius", "fahrenheit"] = "celsius"
    days: int = Field(ge=1, le=14)

# 该 schema 会被编译成 FSM，约束模型输出
# 输出必然是 {"city": ..., "unit": "celsius"|"fahrenheit", "days": 1..14}

from vllm import LLM, SamplingParams
from vllm.sampling_params import GuidedDecodingParams

llm = LLM(model="Qwen/Qwen2.5-7B-Instruct")

# 方式一：JSON Schema 约束
params = SamplingParams(
    temperature=0.7,
    max_tokens=256,
    guided_decoding=GuidedDecodingParams(json=schema_dict),
)
out = llm.generate(["提取城市和天数"], params)

# 方式二：正则约束（如固定格式编号）
params = SamplingParams(
    guided_decoding=GuidedDecodingParams(regex=r"\d{4}-\d{2}-\d{2}"),
)

# grammar.gbnf —— 手写文法约束输出为「键值对列表」
root   ::= "{" pair ("," pair)* "}"
pair   ::= string ":" value
string ::= "\"" [a-zA-Z_]+ "\""
value  ::= string | number
number ::= [0-9]+

./llama-cli -m model.gguf --grammar-file grammar.gbnf \
    -p "输出一个包含 name 和 age 的 JSON"

选型建议：
□ 已在 vLLM/SGLang 上 → 直接用原生 guided_decoding（默认 XGrammar）
□ 端侧 / llama.cpp → GBNF 或 json_schema 参数
□ 自研引擎 → 集成 Outlines/XGrammar 库
□ 闭源 API → 用其原生 structured output 参数，别自己解析

① 每步掩码计算
   朴素实现：遍历词表判合法性 → O(V) per step（V 常 5万~15万）
   → 延迟显著上升，尤其短输出场景

② 状态转移与缓存
   复杂 schema 的 FSM 状态多，转移表大 → 缓存未命中代价高

③ 编译开销
   Schema → FSM 的编译有一定固定成本
   → 应在服务启动时预编译，别每次请求编译

一个关键认知：受限解码对「长输出」的相对开销小，
对「短输出」的相对开销大（固定开销摊薄不了）。
→ 短输出 + 高 QPS 场景，务必用高效后端 + 预编译缓存。

陷阱 1：只约束结构，不校验语义
  → schema 保证 {"age": 999} 合法，但不保证合理
  → 解：结构约束 + 业务校验双层

陷阱 2：max_tokens 太小导致截断
  → 受限解码会让模型「必须写完整」，截断时 JSON 不闭合
  → 解：max_tokens 留足余量，或容忍未完成时返回错误

陷阱 3：schema 过复杂拖慢编译与推理
  → 深层嵌套 + 大枚举 = 巨量状态
  → 解：拆分为多次小请求，或简化枚举

陷阱 4：忽略掩码与采样参数的交互
  → 极端低 temperature 下，受限解码可能「卡死」在某状态
  → 解：保持合理温度，避免全 greedy + 强约束

陷阱 5：跨请求复用状态机出错
  → 并发请求共享 FSM 实例导致状态串扰
  → 解：每请求独立状态实例，FSM 定义只读共享

最佳实践清单：
□ 用引擎原生 guided decoding，别自研
□ 服务启动预编译 schema，缓存 FSM
□ 结构约束 + 语义校验双层防护
□ max_tokens 留足，避免截断
□ 监控「约束失败率」（理想为 0）与「掩码耗时」
□ 与函数调用/工具调用规范对齐（见跨专题文章）