结论先行:别靠"麻烦你输出 JSON"这种裸 prompt。优先级是:API 原生 schema 约束输出 > function calling > few-shot + 解析重试。无论用哪种,拿到结果后必须过一遍 schema 校验——结构化输出的可靠性永远是"约束 + 校验"两层配合的结果。
为什么裸 prompt 不稳
不用约束手段时,模型输出是自由采样,常见翻车姿势:裹一层 Markdown 代码围栏(```json);在 JSON 前后加"好的,以下是解析结果";字段名漂移(上次叫 amount 这次叫 price);该是数字的输出了字符串。你的 json.loads 每天都在赌它今天状态好不好。
根因在于:自然语言里"合法的 JSON"只是无数合理输出中的一种,采样过程没有任何机制强制它落在合法子空间里——温度稍高,一个引号、一个尾逗号都足以让解析崩掉。所以工程原则是把"格式正确"从概率问题变成机制问题。
还有一类隐性成本经常被低估:裸 prompt 的失败是偶发的,恰恰最难处理。失败率 5% 意味着每二十次调用炸一次,而每次炸的现场都不一样——这次是围栏,下次是闲话,再下次是字段名变了。团队会被迫写一堆越来越长的解析补丁,最后得到一个谁也不敢动的"正则怪物"。机制化约束消灭的正是这一整类补丁。
import json
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI()
class OrderInfo(BaseModel):
order_id: str
amount: float
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "解析订单:SF001,金额 298.5 元,输出 JSON"}],
)
# 错误写法:裸 prompt + 直接 json.loads,围栏、闲话、尾逗号都会炸
# info = json.loads(resp.choices[0].message.content)
# 正确写法:Pydantic 校验兜住解析失败,失败进入重试或告警流程
text = resp.choices[0].message.content
try:
info = OrderInfo.model_validate_json(text)
except Exception:
info = None # 进入重试或告警流程
print(info)
方法一:Schema 约束输出(首选)
主流 API 都提供结构化输出能力,底层是约束解码:推理时每一步只允许模型从"合法 JSON 语法 + 你的 schema"限定的 token 里采样,从机制上杜绝了格式错误。以 OpenAI 的 structured outputs 为例:
from openai import OpenAI
from pydantic import BaseModel
class OrderInfo(BaseModel):
order_id: str
amount: float
city: str
client = OpenAI()
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user",
"content": "解析:订单 SF20250601001,金额 298.5 元,从北京发出"}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "order_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number"},
"city": {"type": "string"},
},
"required": ["order_id", "amount", "city"],
"additionalProperties": False,
},
},
},
)
info = OrderInfo.model_validate_json(resp.choices[0].message.content)
print(info.city, info.amount)
注意 schema 能保证的只是格式合法,字段内容的正确性(city 到底是不是北京)仍然靠 prompt 和校验兜底。
两个实践细节。其一,strict 模式对 schema 有关键字限制,字段通常要求全部必填(可空用类型数组表达),设计时优先扁平——能用两个字段表达的不用三层嵌套对象。其二,解析失败率与 schema 复杂度正相关:字段越多、约束越细,被强制补齐的输出也越多,按"下游真正会用的字段"设计,不堆"以后可能有用"的字段。
方法二:Function Calling
把目标结构定义成工具的参数 schema,模型的任务变成"填参数"。它同样走约束解析的路径,适合"从文本里抽取信息"这类天然就是调工具的场景,也是 Agent 链路的基础设施。各家实现字段名不同(tools / function call / tool use),机制一致。
选 function calling 还有一个工程红利:参数 schema 是 Agent 生态的通用语言。今天这套抽取逻辑明天要接进工具调用链路(让模型自主决定何时抽取),定义好的 schema 直接复用,迁移成本远低于从裸 JSON prompt 改造。
顺带厘清它的交互形态:function calling 的一次完整流程是两段式——模型先返回"我想调用某工具、参数如下",你的代码执行后把结果作为工具消息回传,模型再生成最终回答。抽取场景通常只需要第一段,拿到参数就结束,不用回传,交互成本省一半。
方法三:Few-shot + 解析重试(兜底)
接口不支持 schema 约束时(部分开源模型自建服务、旧版 API),用 few-shot 示例稳住格式,配合容错解析与重试:
import json
FENCE = "`" * 3 # 代码围栏字符串,避免在本文件里出现裸三反引号
def parse_loose(text: str) -> dict:
"""容错解析:剥掉可能的 Markdown 围栏和前后闲话"""
text = text.strip()
if FENCE in text:
text = text.split(FENCE)[1] # 取围栏内容
text = text.split("\n", 1)[-1] # 去掉 'json' 语言标注行
start, end = text.find("{"), text.rfind("}")
return json.loads(text[start:end + 1])
def extract_with_retry(prompt: str, max_retries: int = 2) -> dict:
last_err = None
for _ in range(max_retries + 1):
resp = call_llm(prompt) # 你的 LLM 调用封装
try:
return parse_loose(resp)
except (json.JSONDecodeError, ValueError) as e:
last_err = e
prompt += f"\n\n你上次的输出无法解析({e}),请只输出合法 JSON。"
raise ValueError(f"多次解析失败: {last_err}")
重试时把解析错误回传给模型,让它自己修,比原样重问成功率高得多。
few-shot 示例也有讲究:示例的作用是"教格式",不是"教内容",放两三个覆盖不同形态(单对象、数组、空结果)就够了,堆十几个示例只是烧 token。空结果示例尤其重要——它教会模型"没有匹配信息时输出空数组,而不是硬编一条"。
三种方法怎么选
| 方法 | 格式保证 | 依赖条件 | 适用场景 |
|---|---|---|---|
| Schema 约束输出 | 机制级,杜绝非法 JSON | API 支持 structured outputs | 一切受支持的接口,首选 |
| Function calling | 机制级 | API 支持工具调用 | 抽取任务、Agent 工具链路 |
| Few-shot + 重试 | 概率级,靠示例与重试兜 | 无特殊依赖 | 老接口、自建开源模型服务 |
| 裸 prompt | 无保证 | 无 | 只适合人读的输出,禁入链路 |
判断顺序很简单:先看接口能力,再看任务形态。API 支持 schema 约束就直接用,格式问题从机制上消失;如果你的链路本身是 Agent 式的工具调用,用 function calling 顺理成章,别再叠一层 JSON prompt;只有接口不支持约束时才退回 few-shot 加重试。另外注意,schema 约束有代价:候选 token 被限制后,模型无法"跳出"格式去解释或拒答,所以 schema 模式下要在消息内容里自己留好表达"解析失败"的字段,而不是指望模型自由发挥说明原因。
跨厂商迁移时,把 schema 定义写成一份独立资产(JSON Schema 文件或 Pydantic 模型),各 API 的封装层从它派生各自的请求参数——json_schema、function calling 的 parameters、兼容接口的格式都源自同一份定义,避免三处手写三处漂移。schema 实际上是"模型与下游系统之间的接口契约",改动应走与 API 契约同级的 code review。
最后一个提醒:结构化输出不是万能出口。开放式的回答(聊天、写作)不要套 schema——约束解码会限死候选空间,输出变得干瘪。只对"下游程序要消费"的输出上约束,给人看的输出保持自由文本。
实战场景
一个简历解析服务的第一课:输入是千奇百怪的 PDF 转文本,目标是固定 schema 的工作经历数组。第一版用裸 prompt 要求 JSON,解析失败率在脏输入面前不可接受,失败样本集中三类:多段经历被拼成一个对象、日期字段五花八门(“23年3月"“2023.03”)、把"目前"写成空字符串。第二版的改造分三步:切换到 API 原生 schema 约束,日期字段收成 ISO 格式字符串、在职状态用枚举(在职/离职)而不是自由文本;Pydantic 校验层对日期做解析规整,非法值打回重试并附上具体错误;解析失败率按天监控、阈值告警。改造后格式类失败基本从告警里消失,剩下的失败全部来自输入质量(扫描版简历 OCR 出乱码),那是另一个预处理问题。这个分层很关键:格式归机制,内容归校验,输入质量归数据预处理,别把三类问题搅在一起排查。日期规整函数后来沉淀成了公共库,三个下游服务共用,同一份输入在不同服务里解析出同一结果——结构化链路的一致性,比单点成功率更重要。这套分层也成了团队内所有解析类服务的模板:先问接口支持什么约束,再设计字段,最后才写 prompt,顺序反过来就会重走一遍弯路。
检查清单
- 生产链路禁用裸 prompt 直出 JSON,从机制层解决格式
- API 支持 structured outputs 就优先用,strict 模式 + 完整 schema
- 抽取任务优先 function calling,schema 可复用进 Agent 链路
- schema 之后仍要过 Pydantic/JSON Schema 语义校验(枚举、范围、必填)
- 字段设计偏保守:枚举替代自由文本,日期用 ISO 格式,城市用编码
- 解析失败自动重试,并把具体错误回传给模型修
- schema 变更走加字段兼容,下游按需适配
- 解析失败率进监控看板,突增即排查模型版本与输入质量