在工程化落地大语言模型（LLM）的实践中，开发者面临的最大痛点之一就是模型的输出不确定性。
在早期的 AI 应用开发中，让大模型稳定返回特定格式的 JSON 简直是一场“噩梦”。为了让后端能够安全地解析数据，开发者不得不编写冗长的 Prompt（例如：“请严格返回 JSON，不要包含任何 Markdown 标记，否则我的系统会崩溃！”），甚至还要在后端编写复杂的正则表达式来清洗 ````json` 等废话标签。
Structured Outputs（结构化输出） 的出现彻底终结了这一乱象。它不再是单纯依靠提示词来“恳求”模型，而是从模型底层进行物理约束，做到 100% 严格遵循开发者定义的 JSON Schema。本文将从底层原理、演进历史、代码实践以及工程最佳实践四个维度，为你全面拆解这项核心技术。
一、 底层原理：它是如何做到“强行约束”的？
要理解结构化输出的强力之处，我们需要理解它所采用的核心技术——约束解码（Constrained Decoding） 。
大模型在生成文本时，本质上是在预测下一个词元（Token）的概率分布。例如，当模型吐出 "name": 后，常规状态下它会根据概率自由选择接下来的 Token，这往往会导致格式失控。
而在开启 Structured Outputs 后，API 引擎会在后台把你提供的 JSON Schema 编译成一个有限状态机（FSM，Finite State Machine） 或正则约束图。
[模型预测中] ──> 生成到 `"age": ` ──> [状态机介入] ──> 过滤所有非数字Token
│
└──> 只释放 [0-9] 的概率 ──> 强制输出整数
- 动态 Logits 遮罩（Logits Masking）： 状态机会实时跟踪模型当前已经生成的字符。如果 Schema 规定
age字段必须是整数（Integer），当模型生成到"age":时，系统会在概率分布层面直接将所有字母和特殊符号的 Token 概率强制设为 0。 - 零容错闭环： 模型此时只能在数字 Token（0-9）中进行选择。它不再是“在输出后进行校验和重试”，而是在物理生成层面上就掐断了输出错误格式的可能性。
二、 技术演进：从 “全凭运气” 到 “100% 确定”
为了更直观地理解结构化输出的优势，我们可以将它与早期的方案进行横向对比：
| 发展阶段 | 实现机制 | 优势 | 致命缺陷（工程痛点） |
|---|---|---|---|
| 1. 纯 Prompt 提示 | 在提示词里写：“请严格返回 JSON，包含 name 和 age”。 | 极其简单，无需代码层面的特殊配置。 | 极不稳定。 模型经常夹带诸如 Here is your result: 的废话，或者由于幻觉丢失字段。 |
| 2. JSON Mode | API 层面开启 JSON 模式，强制保证返回的外壳是合法 JSON。 | 彻底杜绝了非法 JSON 字符串，不会有多余的废话。 | 无法保证 Schema 的正确性。 模型可能随意捏造字段名，或者把预期的数字类型错写成字符串。 |
| 3. Structured Outputs | API 层面传入标准的 JSON Schema，底层进行 Token 概率遮罩。 | 100% 类型与结构安全。字段名、嵌套结构、数据类型完全符合预期，后端可直接反序列化。 | 对于极度复杂的 Schema，可能会略微增加首次请求（冷启动）的编译延迟。 |
三、 代码实战：基于 Pydantic 的工业级实现
目前业界最优雅、最主流的实现范式是结合 Python 的 Pydantic 库。你只需要用 Python 类定义好数据结构，API 会自动将其转换为 JSON Schema 并对大模型施加约束。
以下是一个模拟从一段杂乱的非结构化文本中，精确提取用户画像的完整工程示例：
1. 定义数据结构 (Schema)
我们通过 Pydantic 显式定义所需字段、数据类型，并利用 Field 增加字段描述，这能极大帮助模型理解业务含义。
Python
from pydantic import BaseModel, Field
from typing import List, Optional
class UserProfile(BaseModel):
name: str = Field(description="用户的姓名")
age: int = Field(description="用户的年龄，如果文本未提及请设为 0")
skills: List[str] = Field(description="用户掌握的技术或技能列表")
is_active: bool = Field(description="用户当前是否在职或活跃")
email: Optional[str] = Field(None, description="用户的电子邮箱，若无则返回空")
2. 调用 API 并注入约束
在发起 API 请求时，将定义好的 UserProfile 结构体传入对应的 Schema 配置项中（以主流大模型 API 的常见标准语法为例）：
Python
import os
import google.generativeai as genai # 以 Gemini API 为例
# 初始化模型
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel('gemini-1.5-pro')
# 输入一段混杂、非结构化的文本
raw_text = """
面试官你好，我是张三。我今年有28岁了。我在前端和后端都有涉猎，
熟练掌握了 Python、Docker 以及 React 开发。我目前在一家电商公司全职在职。
顺便说一下，我的联系邮箱是 zhangsan@example.com。
"""
# 发起请求并强制约束输出
response = model.generate_content(
f"请从以下文本中提取用户信息：\n{raw_text}",
generation_config=genai.GenerationConfig(
response_mime_type="application/json",
response_schema=UserProfile, # <--- 核心：强行约束在此发生
),
)
# 打印大模型返回的结果
print(response.text)
3. 完美输出的 JSON 结果
无论你调用多少次，大模型返回的永远是以下干净、无瑕疵的纯 JSON 字符串。没有任何 Markdown 外壳，你可以直接用后端代码进行反序列化：
JSON
{
"name": "张三",
"age": 28,
"skills": ["Python", "Docker", "React"],
"is_active": true,
"email": "zhangsan@example.com"
}
四、 生产环境下的避坑指南与最佳实践
尽管 Structured Outputs 提供了 100% 的格式保障，但在实际工程落地中，为了保证系统的高效与稳定，仍需注意以下几点：
1. 结构化约束 🌟= 逻辑正确
结构化输出只保证“骨架（格式）”的绝对正确，不保证“血肉（逻辑）”的完美。例如，如果你定义的 Schema 要求
age是整数，模型绝不会返回字符串"28"，但如果文本中没有提及年龄，它可能会产生幻觉编造一个数字。
- 对策： 依然需要在 Prompt 中清晰地指导模型如何处理缺失值（例如：“若文本未提及年龄，请务必输出 0”）。
2. 善用描述字段（Description）
在 Pydantic 中使用
Field(description="...")不仅仅是写给协同看注释，这些描述会被转换为 JSON Schema 的说明并直接输入给大模型。这是引导模型进行精准字段提取的最有效手段。3. 避免过度深层的嵌套结构
虽然技术上支持五层、十层的深层 JSON 嵌套，但层级越深，状态机的约束链路就越长：
- 这会导致模型在生成时的 Token 推理难度增大，进而增加响应延迟（Latency） 。
- 建议在设计数据结构时尽量保持扁平化，将复杂的深层结构拆分为并列的扁平字段。
4. 处理“拒绝回答”的边界情况
某些模型（如 OpenAI 的特定版本）在遇到违反安全政策的提示词时，由于无法满足 Schema 约束，可能会直接触发拒绝。在生产环境下，代码层面的
try-except异常捕获机制依然必不可少，用以应对 API 层面可能抛出的特例错误。
五、 总结
Structured Outputs（结构化输出）的普及，标志着 LLM 应用开发从“玄学 Prompt 调优”走向了“确定性工程开发”。它打通了非结构化自然语言与结构化代码世界之间的最后一道屏障。通过将逻辑校验前置到大模型的 Token 生成层，开发者得以构建出更加强壮、抗风险能力更高的企业级 AI 应用。
