结构化响应设计：从 schema 到可消费结果#

这章解决什么问题#

即使读者已经知道 json_schema、regex、tool parser 和 API 表面怎样工作，仍然可能缺少一个更实用的问题答案：怎样设计一个真正适合被模型稳定生成、又适合下游系统消费的响应结构？如果没有这一层，结构化生成章节仍然更像能力介绍，而不像工程书。

这一章的目标，就是把“schema 能不能写出来”推进到“schema 应不应该这样写”。这是很多好技术书都会额外补上的层次：不仅讲功能，还讲怎样把功能设计成更稳的工程接口。

为什么 schema 设计本身就是工程决策#

从 structured_outputs.ipynb 和 sampling_params.md 看，系统允许调用方传入 schema、regex 或其他约束。但这并不等于任何 schema 设计都同样稳定。过深的嵌套、含糊的字段语义、过多自由文本空间，都会让结构虽然“合法”，却仍然难以稳定消费。

这说明结构化响应设计不是“用哪种语法”这么简单，而是一个工程问题：你究竟想让模型输出什么形状，后续系统怎样消费它，以及错误时是更容易在生成侧、解析侧还是业务侧暴露问题。

一个更稳的 schema 设计思路#

对第一版读者来说，最稳的设计顺序通常是：

先定义最小可消费结构，而不是一次性追求完整业务对象
把高自由度文本字段尽量往外缘推，不要让所有字段都可自由发挥
优先设计“容易被 parser 和下游程序消费”的字段，而不是“人类看着舒服”的字段
对 tool call 或 reasoning 结果，尽量让结构能和后续结果回填流程对上

这种写法看起来更保守，但它更适合真实工程环境。因为结构化输出一旦进入程序链路，稳定性比表面优雅更重要。

一个更像实践建议的最小对照#

更稳：
{
  "city": "Qingdao",
  "unit": "celsius"
}

更脆弱：
{
  "request": "Please tell me the full weather situation in a rich natural language paragraph"
}

这个对照不是说自由文本没价值，而是提醒你：如果目标是“可消费”，结构应该尽量先把机器需要的部分固定下来，再把解释性文本放在外围。

为什么这章对整本书很重要#

没有这一章，结构化生成这一部分更像“系统支持哪些约束”。有了这一章，读者才会开始思考“怎样把这些约束设计成稳定接口”。这让整本书从“认识能力”进一步升级成“知道怎样把能力做成可靠系统”。

本章对应哪些代码路径#

这一章主要回指 docs/advanced_features/structured_outputs.ipynb、docs/basic_usage/sampling_params.md、python/sglang/srt/sampling/sampling_params.py 与 OpenAI-compatible structured output 用法相关文档。它的重点不在增加新的底层实现，而在于帮助读者更稳地使用前面已经建立好的能力。

小结#

优秀技术书会在“机制之后”继续补一层“设计判断”。这一章承担的正是这个角色：把结构化生成从“能用”推进到“用得稳”。