← 学习笔记

结构化输出是怎么做到的

LLM 的输入不过是一段提示词。凭什么它吐出来的 JSON 一定是合法的？
答案有点反直觉：根本不靠提示词。

一、你以为的地方，和真正起作用的地方

大多数人的心智模型是这样的：提示词进去 → 文字出来。既然只有提示词能控制它，那「请返回 JSON」就是你唯一的手段。

但生成过程里还有第二个你能插手的地方——采样器。模型每一步吐出来的不是一个词，而是整个词表的分数，选哪个是采样器决定的。

二、亲眼看一遍

下面这个演示，左边是模型每一步真实的倾向，右边是最终输出。把开关拨到「约束关」，你会看到它第一步就想输出 markdown 围栏——这正是「请返回 JSON」失败的真相。

三、三个层次，差别在哪

「让模型输出 JSON」有三种做法，保证力度天差地别：

那 JSON Schema 算哪一层？

Schema 不是一种做法，是一份规格说明。它同时被三个地方消费：

• 对模型：编译成文法，驱动约束解码——这是 Structured Outputs 的输入
• 对你的代码：反序列化 + 校验，出错在边界处就被拦住
• 对团队：Schema 本身就是接口定义，不用另写文档

四、Schema 是怎么变成「文法」的

约束解码需要知道「此刻哪些 token 合法」。这个判断来自把 Schema 编译成状态机。拿上面那个 Schema 举例，编译结果是一串「段」：

// {"name": string, "age": integer}  编译后
[0] LIT  '{"name":"'      ← 固定字面量，模型一个字的自由都没有
[1] VAR  字符串正文        ← 这里才有自由
[2] LIT  '","age":'       ← 又是固定
[3] VAR  数字
[4] LIT  '}'

状态 = (第几段, 段内第几个字符)。「下一个 token 允许是什么」由状态唯一决定——和模型想输出什么毫无关系，是纯粹的确定性计算。

这也解释了那两条奇怪的限制

用过 OpenAI Structured Outputs 的都被这两条卡过：

• 所有字段必须写进 required
• 必须 additionalProperties: false

原因就在这儿：字段可选 = 每个位置都要分支，字段可多 = 状态无穷。文法会爆炸，编不出高效的状态机。
想表达「这个字段可能没有」，正确做法是允许它为 null，而不是让它可缺失。

五、真实代码

OpenAI · Structured Outputs

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "order",
            "strict": True,          # ← 关键。不写就退化成 JSON Mode
            "schema": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"},
                    "amount":   {"type": "number"},
                    "status":   {"type": "string",
                                  "enum": ["paid", "refunded"]},
                    "note":     {"type": ["string", "null"]}  # 用 null 表达「可能没有」
                },
                "required": ["order_id", "amount", "status", "note"],
                "additionalProperties": False
            }
        }
    })

本地模型 · 自己写掩码

用 HuggingFace 的话，约束就是一个 LogitsProcessor——整个机制其实就是那一行 -inf：

class GrammarMask(LogitsProcessor):
    def __call__(self, input_ids, scores):
        allowed = self.fsm.allowed_tokens(input_ids[0])   # 文法说了算
        mask = torch.full_like(scores, float("-inf"))
        mask[0, allowed] = scores[0, allowed]             # 只留合法的
        return mask                                      # ← 全部秘密就在这

model.generate(**inputs, logits_processor=[GrammarMask(fsm)])

现成的轮子：Outlines、XGrammar、llama.cpp 的 GBNF、vLLM 的 guided_json。原理都是上面这套。

六、五个坑