同一条「生成工单摘要」任务,我试过让模型自由写散文,也试过先锁 JSON Schema 再谈文采。结论先说:For any given task, I lock down the JSON Schema first, then focus on the finer details: this cuts the number of issues in half before deployment.. This article isComparative Structure:把「自由散文输出」和「Structured Outputs / JSON Schema 约束」摆在一张桌上。证据口径来自可核实的公开实践——OpenAI Structured Outputs 与 JSON Schema 用法说明、openai-python 仓库材料,以及 instructor 文档常见口径。禁止拿未公开的内部事故百分比当论据。最后两节给你今晚能做完的三步落地与第一周验收。

自由散文为什么「看起来能用」却难上线
散文输出的诱惑很具体:提示词里写「请用清晰中文总结」,模型当场吐出一段通顺话,产品经理点头,演示日过关。问题在于下游。工单系统要的是 priority 枚举、可检索的 ticket_id、可路由的 next_action;散文里这些字段今天叫「优先级:高」,明天变成「比较紧急」,后天埋进长段落中间——你的解析器开始写正则,正则开始写特例,特例开始变成第二套提示词。
我踩过的土坑是:同一条用户原话,温度 0 时字段齐全,温度一抬就漏 ticket_id;或者把「未知」写成抒情句子,自动化工单创建直接 400。文采没有错,错在把机器契约交给了自然语言运气。公开材料里 Structured Outputs / JSON schema 路径强调的是:在采样阶段就约束结构,而不是生成完再祈祷能 json.loadsThe
另一类假安全感是「我加了必须输出 JSON」五个字。没有 schema、没有校验、没有失败重试时,模型仍可能输出 markdown 代码围栏、尾随解释、或缺字段的半截对象。口号不是门禁。
若你的产品必须给人看长文,也请拆成两段流水线:第一段只产出 schema 对象;第二段再把允许的 string 字段渲染成对用户可见的段落。不要让「对人好读」和「对机器合法」抢同一条生成路径。
Things to Do Tonight:打开你现在的下游解析代码,数一数有多少分支是在「修模型文风」。分支多于字段定义,就先别再加「请务必输出 JSON」。
对比:自由散文 vs 先锁 JSON Schema
把两条路写成可对照的决策:
| dimension (math.) | 自由散文 / 弱约束 JSON | 先锁 JSON Schema / Structured Outputs |
|---|---|---|
| 修的是什么 | 当次可读性与文采 | 字段、类型、枚举是否满足契约 |
| 对下游系统 | 常靠正则与人工兜底 | 可直接反序列化进工单/API |
| 失败是否可定位 | 弱(「读起来不对」) | 强(缺字段/类型错/枚举外) |
| 文采放哪 | 整段输出都在比文采 | 文采只进允许的 string 字段 |
| My Default Order | 契约绿了再调 summary 语气 | 上线前先最小 schema + 校验重试 |
对比不是说散文无用。对用户可见的解释、安抚、教学文案,仍然可以是自然语言——前提是它住在 schema 允许的字段里,而不是替代 schema。OpenAI 公开的 Structured Outputs 路径与 instructor 一类工具,共同点是:把结构当成一等公民,校验失败可以回灌错误信息再生成,而不是默默写成「差不多对」。
抬杠句「schema 太死、业务常变」也成立一半:所以今晚只锁最小关键字段,把易变文案留在自由 string;变的是产品文案,不变的是工单能否创建成功。
实操上我还加一条协作约定:谁改枚举谁同步改契约编号与金标。产品口头加一个「特急」优先级,却不改 schema,结果是线上大量落到 default 或校验红灯。枚举是产品语言,不是模型即兴创作空间。
Things to Do Tonight:用上表五维给当前任务打分——哪一列已有工件。缺 schema 的那一列写成明天任务名,而不是再开「优化提示词文采」模糊票。
公开实践怎么落到「字段契约」

我读 Structured Outputs / JSON Schema 与 instructor 公开材料时,先抓共同语言,再映射到自己的仓库:
- 契约先于提示词文采。先写字段名、类型、必填、枚举、未知时的行为;再写 system 里的角色与语气。
- schema 要能被工具链消费。无论是 API 的 structured 模式,还是 instructor 的响应模型,目标都是「非法结构进不了下游」。选你能维护的那一层,别并行三套。
- 校验失败要有重试协议。解析错误、缺字段、枚举外值,应带回简短错误列表再生成一次(设上限,例如 2 次),而不是打日志后假装成功。
落到工程上,我把契约写成一页 field-contract.md 加一份 schema.json:工单摘要字段名跟产品走,但「必填 / 枚举 / 未知策略」三节不能空。每条样例输入都要能指回契约某一条;指不回去的样例要么补契约,要么删样例。
instructor 文档常见口径是用类型化模型描述输出,并在失败时重试;OpenAI 侧 Structured Outputs 材料则强调 schema 约束与可靠解析。你不必第一周绑死某一家 SDK;一个 schemas/ 目录 + 校验函数非零退出,就够挡住「自觉更通顺」的合并。
若团队已有内部 DTO 或 OpenAPI 组件,优先从那里生成 JSON Schema,而不是手抄一份「差不多」的字段表。手抄第二周就会和代码分叉。生成脚本进仓库,schema 变更看 diff。
Things to Do Tonight:新建 field-contract.md,只写四节并各填三行:必填字段、类型与枚举、未知/拒答、禁止编造项。写不满十二行,说明你还没准备好谈文采。
今晚落地:字段契约 → 最小 schema → 校验失败重试

别等下周「结构化专项」。今晚九十分钟,按这三步做完,明天你才有资格继续改 summary 文采。
- 定字段契约(25 分钟):打开空文件
field-contract.md。写清:下游系统要哪些键;哪些必填;枚举列表;遇到信息不足时是need_info还是拒答;绝对禁止的键值(伪造金额、伪造工单号)。每条用编号 F-01… 方便样例引用。 - 写最小 JSON Schema(35 分钟):只锁关键字段,禁止一上来一百个属性。示例骨架(按你的任务改名):
{
"type": "object",
"additionalProperties": false,
"required": ["ticket_id", "priority", "summary", "status"],
"properties": {
"ticket_id": {"type": "string", "minLength": 1},
"priority": {"type": "string", "enum": ["low", "mid", "high"]},
"summary": {"type": "string", "minLength": 1, "maxLength": 200},
"next_action": {"type": "string"},
"status": {"type": "string", "enum": ["ok", "need_info", "rejected"]}
}
}
- 校验失败重试(30 分钟):用官方 Structured Outputs 路径,或 instructor / 自写
jsonschema校验。失败则把错误路径列表塞回下一轮用户/工具消息,最多重试 2 次;仍失败则走need_info或人工队列,禁止静默写成散文。把命令写进 README:本地一键;CI 对金标输入跑校验,非零退出不许合提示词。
# 门禁示意:结构失败非零 python3 scripts/validate_structured.py --schema schemas/ticket.json --samples evals/struct20.jsonl || exit 1
骨架里的 additionalProperties: false 很关键:没有它,模型爱加「备注」「说明」键,下游仍会漂。样例要能指回契约;契约要能指回产品边界。
金标输入从哪来:从真实工单与客服原话各抽一批,故意包含缺字段、枚举口语、多语言混杂。每条标注期望是「通过」还是「need_info/rejected」。没有负例的结构化评测,和没有拒答样例的聊天评测一样甜。
本地跑通后,把失败样例 id 写进 PR 模板必填项。只写「已优化提示词」而不贴 id 的合并请求,直接打回。结构问题要用样例说话,不靠形容词。
Things to Do Tonight:先用一条故意缺 priority 的模型输出撞红校验,确认门禁真的会响,再接通重试;绿了再谈 summary 语气。
第一周验收:把结构红灯变成习惯
今晚三步只是开门。第一周我要求自己做完这些,才宣布「先锁 Schema 再谈文采」不是口号:
- 把
validate_structured.py(或等价)挂进 PR:凡改prompts/或schemas/必跑; - 契约与 schema 进 git,改动走评审;禁止只在聊天里改「临时字段」;
- 每发现一次解析失败或下游 400,先补契约/样例再改提示词,顺序不许颠倒;
- 若必须换模型,附前后对比:同一批结构化样例的通过率,枚举违规不得上升;
- 读一遍你选用的 Structured Outputs / instructor 文档变更,把新约束记进
schemas/READMEThe
和同事同步时,我用一句话:「summary 更漂亮但 priority 枚举外溢,那是事故预告。」把这句话贴在 schemas/README 文件头。演示日若有人想靠临时改成散文过关,就打开校验日志:红着的样例 id 不消失,发布按钮就不按。
翻车排查:假 JSON、枚举漂移、重试死循环
- 看起来像 JSON、校验却红:多半有尾随说明或代码围栏。主路径改用 Structured Outputs / 响应模型,而不是
json.loads碰运气。 - 枚举每周都在涨:产品用口语优先级,schema 却写死三个词。要么改产品文案对齐枚举,要么在契约里明确映射表;禁止解析器私自硬编码口语同义词。
- 重试死循环:错误信息太长或互相矛盾。限制 2 次;错误只回灌路径与期望类型,不回灌整份旧输出。
- schema 过度设计:第一周就 40 个字段,没人维护。砍回最小必填,其余延后。
- 文采字段失控:
summary变成小作文并夹带动作指令。加maxLength,并把动作挪到next_actionThe
收尾再钉一次顺序:上线前 → 写字段契约 → 最小 schema → 校验失败重试 → 仍不够再调 string 字段文采。OpenAI Structured Outputs 与 instructor 一类公开实践已经把「结构可失败出声」的轮子造好了;缺的是你今晚开始写的那份契约。更漂亮的句子可以以后再堆;先让缺字段在校验器上被卡住。


Comment List (0):
Load More Comments Loading...