结构化输出 - DJJ

Tager: 格式化输出

Tue, 07 Jul 2026 14:30:41 +0800

第一阶段：Prompt-only JSON#

最早的做法不是 API 级能力，而是纯 prompt 约束。开发者会在 system prompt 或 user prompt 中写：

请严格输出 JSON。
不要输出 Markdown。
不要解释。
不要添加额外文字。
必须包含 name、email、age 三个字段。

这种方式的本质是用自然语言约束自然语言模型。它在 demo 中通常有效，但在生产环境中不稳定。模型可能输出 Markdown code block：

{
 "name": "Alice"
}

也可能在 JSON 前后添加解释

下面是你要的 JSON：
{
 "name": "Alice"
}

还可能出现漏字段、字段类型错误、枚举值幻觉、数组结构不稳定、字符串转义错误等问题。

Prompt-only JSON 的问题在于，它只是软约束。模型知道你“希望”它输出 JSON，但推理过程本身没有被硬性限制。它仍然可以在任意位置输出任意 token。也就是说，JSON 在这个阶段只是一种格式建议，而不是协议。

这个阶段的典型工程补救包括：

1. 尝试 JSON.parse
2. 如果失败，要求模型重试
3. 如果仍失败，使用正则或 JSON repair
4. 再用 schema validator 检查字段
5. 如果字段错误，再 retry

这套流程可以工作，但本质上是事后补救。模型先可能犯错，然后应用程序再修复。它没有从生成机制上阻止错误发生。

参考来源：OpenAI Structured Outputs 对 JSON mode 与 Structured Outputs 的区分、JSON Schema 入门文档

第二阶段：JSON Mode#

JSON Mode 是 Prompt-only JSON 之后的一个关键进步。它不再完全依赖 prompt，而是让模型平台在输出层面保证结果是合法 JSON。

JSON Mode 解决的是：

模型输出能不能被 JSON.parse 解析？

它不能完整解决的是：

字段是否齐全？
字段类型是否正确？
枚举值是否有效？
是否添加了多余字段？
是否满足业务约束？

OpenAI 文档中明确区分了 JSON Mode 和 Structured Outputs：两者都能确保输出是 valid JSON，但只有 Structured Outputs 能确保输出遵循指定 schema。OpenAI 也建议在可用时优先使用 Structured Outputs，而不是 JSON Mode。

因此可以这样理解：

Prompt-only JSON:
 希望模型输出 JSON，但不保证。

JSON Mode:
 保证输出是合法 JSON，但不保证符合业务结构。

Structured Outputs:
 保证输出是合法 JSON，并且符合开发者提供的 JSON Schema。

JSON Mode 是一个中间阶段。它让输出从“可能不可解析”变成“通常可解析”，但还没有把模型输出升级为真正的数据契约。

参考来源：OpenAI Structured Outputs vs JSON mode

第三阶段：JSON Schema 与 Structured Outputs#

JSON Schema 的作用不是简单地告诉模型“请输出 JSON”，而是定义这个 JSON 应该长什么样。

例如：

{
 "type": "object",
 "properties": {
 "action": {
 "type": "string",
 "enum": ["search", "reply"]
 },
 "query": {
 "type": "string"
 }
 },
 "required": ["action", "query"],
 "additionalProperties": false
}

这个 schema 传达了几个信息：

输出必须是 object。
必须包含 action 和 query。
action 必须是 string。
action 只能是 search 或 reply。
query 必须是 string。
不能添加 schema 之外的字段。

JSON Schema 把 JSON Object 从“数据格式”提升为“数据契约”。这正是结构化输出真正有用的地方：应用程序不再只是拿到一个能 parse 的 JSON，而是拿到一个符合预期字段、类型和约束的数据对象。

JSON Schema 官方文档也说明，JSON Schema 是一套可以用于标注和验证 JSON 文档的词汇表。它可以描述 JSON 数据的结构、约束和类型。properties 用于定义对象字段，required 用于声明必需字段，additionalProperties: false 用于禁止额外字段。

参考来源：JSON Schema 入门、JSON Schema object / properties / required / additionalProperties

`description` 的特殊位置：它不是硬约束，而是语义说明#

在 JSON Schema 中，description 和 title 属于 annotation keywords，也就是注释型关键词。JSON Schema 官方文档明确说明，这类关键词不是用来做 validation 的，而是用来描述 schema 的含义。

也就是说：

{
 "query": {
 "type": "string",
 "description": "The search query to send to the web search engine."
 }
}

这里的 type: "string" 是硬约束。它告诉 validator 或 constrained decoder：这个字段必须是字符串。

但 description 不是硬约束。它不会阻止模型输出某个字符串。它真正的作用是告诉模型：这个字段在语义上应该填什么。

这就是为什么 description 在 LLM 时代突然变得非常重要。传统程序读取 schema 时，主要关心的是类型、必填项、枚举、额外字段等机器可验证信息。但大语言模型读取 schema 时，还会利用字段名和 description 来理解任务意图。

因此可以把 schema 分成两层：

结构层：
 type
 properties
 required
 enum
 items
 additionalProperties

语义层：
 name
 description
 field description
 examples

结构层负责“能不能填”，语义层负责“应该怎么理解”。

参考来源：JSON Schema annotations、OpenAI Function Calling function definition、Anthropic Tool Use

Structured Outputs 的实现方式：Constrained Decoding#

Structured Outputs 的关键实现思想通常是 constrained decoding，也叫 constrained sampling。它不是模型完整输出之后再接一个小模型修复 JSON，而是在模型生成每一个 token 时，根据 schema 判断哪些 token 仍然合法。

普通解码大致是：

模型根据上下文预测下一个 token 的概率分布
 ↓
从整个词表中选择一个 token
 ↓
继续生成

Constrained decoding 则是：

模型预测下一个 token 的概率分布
 ↓
Schema / grammar engine 判断当前状态下哪些 token 合法
 ↓
非法 token 被 mask，概率变成 0
 ↓
重新采样或选择下一个 token
 ↓
重复直到输出完成

OpenAI 在 Structured Outputs 技术说明中明确说，他们会把 JSON Schema 转换成 context-free grammar，推理引擎在每个 token 生成之后动态判断下一步哪些 token 合法，然后把非法 token 的概率降为 0。OpenAI 还说明，CFG 相比 FSM 或 regex 能表达更复杂的递归和嵌套结构。

这意味着 schema 不再只是事后验证器，而是变成了生成时约束器。

一句话概括：

Structured Outputs 把 JSON Schema 从“模型说完以后检查对不对”，推进为“模型每说一个 token 时就限制它不能说错格式”。

但 constrained decoding 也有边界。它主要保证结构合法，不保证语义正确。例如 schema 能保证：

{
 "city": "Paris"
}

中的 city 是字符串，但不能保证 Paris 就是用户真正想问的城市。事实正确性、业务正确性和用户意图匹配仍然依赖模型理解、上下文、工具结果以及应用侧校验。

参考来源：OpenAI Structured Outputs 技术博客、OpenAI Structured Outputs 文档

7. 主流厂商如何实现结构化输出#

7.1 OpenAI#

OpenAI 当前把结构化输出分为两类：

1. response_format / text.format:
 控制模型最终响应的结构。

2. function calling / tools:
 控制模型调用工具时的参数结构。

OpenAI 文档明确建议：如果你是在连接模型到工具、函数、数据或系统能力，应使用 function calling；如果只是希望模型最终回答符合某个结构，应使用 structured response format。

OpenAI 还区分了 JSON Mode 和 Structured Outputs。JSON Mode 只保证合法 JSON，Structured Outputs 才保证 schema adherence。对于 strict mode，OpenAI 要求 function parameters 中每个 object 设置 additionalProperties: false，并要求 properties 中所有字段都被列入 required。

参考来源：OpenAI Structured Outputs、OpenAI Function Calling strict mode

7.2 Anthropic Claude#

Anthropic 的 Claude Tool Use 文档强调：Claude 会基于用户请求和工具 description 判断是否调用工具，然后返回一个结构化调用。客户端工具由应用程序执行，服务端工具由 Anthropic 执行。

Claude 文档还明确说明，工具 token 成本来自工具名称、description、schema、tool_use blocks 和 tool_result blocks。也就是说，工具定义并不是系统外部的隐藏元数据，而是会进入模型可见的上下文，并影响模型判断。

参考来源：Anthropic Tool Use with Claude

7.3 Google Gemini#

Gemini 文档同样区分了 Structured Outputs 和 Function Calling。Gemini 的 Structured Outputs 用于让模型最终响应遵循 JSON Schema；Function Calling 用于让模型在对话过程中请求外部函数执行真实动作。

Google 文档中明确写到：Structured Outputs 适合数据抽取、结构化分类和 agentic workflows；Function Calling 则让模型连接外部工具和 API，不再只是生成文本，而是决定何时调用函数并提供执行参数。

参考来源：Gemini Structured Outputs、Gemini Function Calling

Tager: JsonOutput 到 Tools Intro

Tue, 07 Jul 2026 14:30:02 +0800

从 JSON Object 到 Tools：大语言模型工程接口的演进#

为什么需要结构化输出#

OpenAI 文档中有一句适合作为本章开场的话：

“JSON is one of the most widely used formats in the world for applications to exchange data.”

这句话的关键点是：JSON 不是为了大语言模型发明的，它本来就是现代软件系统之间交换数据的通用格式。Web API、数据库中间层、前后端通信、配置文件、日志系统、消息队列，都大量依赖 JSON。问题在于，大语言模型原本输出的是自然语言文本，而不是程序可以稳定消费的数据对象。

早期 LLM 应用的典型形态是：

应用程序发送 prompt
 ↓
模型返回一段自然语言
 ↓
应用程序尝试解析这段自然语言

这在聊天场景中没有问题，但在工程系统中会很脆弱。因为下游程序真正需要的是字段、类型、枚举、数组、对象，而不是“看起来像答案”的文本。

例如一个信息抽取任务，用户希望从简历中抽取：

{
 "name": "Alice",
 "email": "alice@example.com",
 "years_of_experience": 5,
 "skills": ["Python", "React", "SQL"]
}

如果模型返回：

姓名是 Alice，邮箱是 alice@example.com，大概有 5 年经验，技能包括 Python、React 和 SQL。

人类当然能读懂，但程序不能稳定消费。程序要继续做正则、字符串切割、异常处理、补字段、类型转换。这样一来，LLM 的输出就没有真正进入软件系统的“类型世界”。

因此，结构化输出的第一层价值是：把模型输出从“人读的文本”转成“程序读的数据”。

OpenAI 官方文档对 Structured Outputs 的定义是：让模型生成始终符合开发者提供的 JSON Schema 的响应，从而避免遗漏必需字段或生成无效枚举值。它列出的优势包括类型安全、可程序化检测拒绝、更少依赖强提示词来维持格式一致性。

参考来源：OpenAI Structured Outputs 文档

从 JSON Object 到 Tools 的完整演进图#

可以把整条演进线压缩成七个阶段：

阶段 1：Natural Language Output
 模型返回自由文本。
 适合聊天，不适合程序消费。

阶段 2：Prompt-only JSON
 用 prompt 要求模型输出 JSON。
 解决部分格式问题，但不稳定。

阶段 3：JSON Mode
 平台保证输出是 valid JSON。
 解决 parseability，但不保证业务 schema。

阶段 4：Structured Outputs / JSON Schema
 平台保证 schema adherence。
 输出成为类型安全的数据对象。

阶段 5：Tools / Function Calling
 模型不只是返回数据，而是请求外部动作。
 JSON Schema 成为函数参数契约。

阶段 6：ReAct-style Tool Use
 推理与行动交替。
 Tool result 成为 observation。

阶段 7：Agent Loop
 多轮感知、决策、工具调用、反馈和终止。
 系统从问答模型变成任务执行体。

这条路线可以用一句话概括：

JSON Object 是数据格式。
JSON Schema 是数据契约。
Structured Outputs 是生成时结构保证。
Tools 是动作契约。
Agent Loop 是围绕动作契约展开的执行系统。

参考来源：OpenAI Structured Outputs、OpenAI Function Calling、Gemini Structured Outputs vs Function Calling、ReAct 论文

三类能力的边界对比#

能力	解决的问题	输出对象	是否执行外部动作	典型场景
JSON Mode	保证输出是合法 JSON	JSON 文本	否	简单结构化返回
Structured Outputs	保证输出符合 JSON Schema	类型安全对象	否	信息抽取、分类、UI 生成、结构化报告
Tools / Function Calling	让模型请求外部能力	工具调用请求	是，由 runtime 执行	查数据库、搜索、代码执行、调用业务 API
Agent Loop	多步执行与反馈修正	多轮 tool call + tool result	是	复杂任务执行、自动化办公、代码修改、数据分析

关键区别是：

Structured Outputs:
 控制最终回答的形状。

Tools:
 控制模型请求动作的形状。

Agent Loop:
 控制动作、观察、再决策的过程。

参考来源：Gemini Structured outputs vs function calling、OpenAI Structured Outputs：function calling vs response_format、OpenAI Function Calling

HomeWork#

调用任意模型, 返回一个固定的Json Schema
制作 Read / Write / Update / List 三个工具, 并且验证使用
尝试基于以上四个工具, 实现一个最小版本的 Agent