response_format、tool constraint 与 SamplingParams 落地#

前面的结构化生成章节已经分别讲了 schema、tool parser、grammar backend、grammar manager 和 grammar queue，但如果停在这里，整条链还缺最后一座桥：一个 OpenAI-compatible request 里的 response_format、tool_choice、parallel_tool_calls、regex、ebnf 这些字段，到底怎样一步步落成 SamplingParams 上真正会被 execution 消费的字段。

这章真正补的，不是又一层协议知识，而是“协议约束怎样正式进入执行边界”的最后一跳。只要这座桥读稳了，前面的结构化生成章节和后面的 execution model 就会真正咬合起来，而不再像一组互相引用的平行专题。

先把这条桥放回完整主线#

很多读者知道 response_format 会影响输出，也知道 sampler 最后会看 grammar / vocab mask，但中间往往会少一层稳定理解：协议字段并不会直接进入 grammar backend，而是先在协议层被归一化、收束，再落成统一的 SamplingParams。

下面这张图的职责，就是把这条桥压成一条最短路径：

flowchart LR
    Req["ChatCompletionRequest / CompletionRequest"] --> Conv["to_sampling_params() / _convert_to_internal_request()"]
    Conv --> SP["SamplingParams fields"]
    SP --> GM["GrammarManager / grammar backend"]
    GM --> Exec["SamplingBatchInfo / sampler"]

图里最重要的不是“有四个框”，而是它明确拆开了两件常被混读的事情：

协议层负责把约束翻成统一采样参数
运行时层再决定怎样把这些采样参数变成 grammar 对象与 sampler 边界

最值得先读的地方其实不是 grammar，而是 `to_sampling_params(...)`#

如果你一开始就跳进 grammar backend，最容易错过的就是协议层已经做过的一次语义收敛。protocol.py 里的 to_sampling_params(...) 真正有价值的地方，不是字段多，而是它在这里已经开始做“约束归一化”：

普通采样字段，例如 temperature、top-p、top-k、min-p、penalty、seed，会先被统一压进一份采样参数字典。
response_format 会被继续折成 runtime 真正识别的形态：
- json_schema 会被转成字符串化 schema
- json_object 会退化成 {"type": "object"} 这类更统一的 schema 形态
- structural_tag 会被显式写成统一字段
如果请求里已经存在 regex / ebnf / structural_tag / json_schema 这类输出约束，协议层会先意识到“这里已经有约束了”。
如果这时 tool-call constraint 又出现，系统就必须开始处理冲突和优先级，而不是简单把所有字段一起往下塞。

这一步最值得技术书强调的，不是 API 字段映射本身，而是：协议层已经不是“被动搬运字段”，而是在主动做运行时语义的第一次编译。

`json_object` 被降成 `json_schema`，说明系统在刻意做收敛#

这是一个很好的系统设计信号。OpenAI 表面的 json_object 并没有在运行时保持成一条独立特殊分支，而是被主动降成更统一的 json_schema 形态。这样做的收益很清楚：

execution / grammar 层不用为每个协议人格单独写一套逻辑
不同来源的结构化约束可以在更低层重新汇合

从书稿角度看，这种“上游字段很多，但运行时语义刻意收敛”特别值得单独指出。因为它正好体现了一本系统书该强调的那类设计判断：外部表面可以丰富，内部执行边界最好统一。

tool-call constraint 真正改变了这条桥的语义#

serving_chat.py 的 _process_messages(...) 在这条桥上起的作用很关键。它会先尝试用 parser 生成 tool_call_constraint；如果 parser 没给出更具体约束，再退回 generic JSON schema fallback。这意味着 tool call 不是 execution 层突然冒出来的语义，而是在更早的协议解释阶段就已经开始长成约束对象。

真正重要的地方在于：一旦已有 regex / ebnf / structural_tag / json_schema，同时又来了 tool-call constraint，系统就必须做冲突判断。源码里直接给 warning，说明设计者并没有假设这些约束总能自然叠加。

这对读者特别重要，因为它直接决定维护者应怎样解释“为什么我同时开了两个约束，最后只有一个生效”。如果不把这层冲突处理单独讲清，结构化生成一旦出问题，就很容易被误判成 grammar backend 或 parser 的 bug。

chat 路径和 completions 路径看起来相近，真正复杂度却不同#

这也是这章特别适合拿来做对照阅读的地方。serving_completions.py 当然也会处理 regex、json_schema、ebnf 和 response_format，但它不像 chat 路径那样带完整 tool-call parser、reasoning 和 message 模板语义。也就是说：

completions 路径更像“直接把协议字段压成采样参数”
chat 路径则还要先穿过更复杂的消息解释与 tool-call 约束生成

这正是为什么好技术书不会只说“这两个 API 都支持结构化输出”，而会主动指出：它们在“约束是怎样长出来的”这一层已经有明显不同。

真正进入 runtime 之后，系统看到的只剩统一字段#

这条桥真正走完以后，runtime 看到的统一字段主要就是：

json_schema
regex
ebnf
structural_tag
stop_regex
以及常规的 temperature、top-p、top-k、penalty 等采样参数

也就是说，从执行层视角看，结构化约束和普通采样参数已经被收口到同一个对象里了。这一点非常关键，因为它解释了为什么前面的 execution model 章节里，SamplingBatchInfo 可以同时处理温度、penalty 和 grammar-driven vocab mask。前面如果觉得它们“怎么会在同一层”，这章正是给那个问题补桥。

这章和 execution model 真正怎样闭环#

现在你可以把整条桥连起来了：

协议字段
→ to_sampling_params() / _convert_to_internal_request()
→ SamplingParams
→ GrammarManager / grammar backend
→ SamplingBatchInfo / sampler

这就是这章最值钱的地方。它不只是把结构化生成再解释一遍，而是让前后的章节第一次能围绕同一条具体数据路径闭环。对一本系统书来说，这种“把中间桥补出来”的章节往往比再补一个边缘特性更重要。

最容易出现的三种误判#

第一，误以为 response_format 会直接决定 grammar backend 行为。
实际上中间还隔着协议归一化和 SamplingParams 收口层。

第二，误以为 tool-call constraint 和已有结构化约束总能叠加。
源码已经明确承认这里存在 warning 和优先级语义。

第三，误以为 chat / completions 只是外表不同。
它们在“约束如何长出来”这一层已经有明显复杂度差异。

真正排查“为什么这个约束没生效”时，更稳的顺序#

如果你遇到“结构化约束没按预期生效”这种问题，最稳的顺序通常是：

先确认请求里到底带了哪类约束：response_format、regex、ebnf，还是 tool 选择。
再确认 _process_messages(...) 是否生成了 tool_call_constraint。
再看 to_sampling_params(...) 最终把哪些字段写进了 SamplingParams。
最后才回到 GrammarManager 和 execution 层确认这些字段是否被正确消费。

这种顺序的价值在于，它先验证“桥有没有搭起来”，再去怀疑桥后面的运行时对象。否则很容易把协议层问题误判成 grammar backend 问题。

小结#

这章补齐的是结构化生成章节里最容易断开的那段协议桥：response_format、tool-call 语义和其他输出约束，不会直接进入执行层，而是先在协议层收敛成统一的 SamplingParams。只有把这条桥读清楚，结构化生成与 execution model 才算真正闭环。