结构化结果出问题时，先从哪条 surface 排查#

这章解决什么问题#

结构化生成这一节讲到这里，读者已经知道 grammar backend、parser、tool roundtrip 和不同 API surface 的区别。但真正难的是：一旦结果不对，该先从哪一层查？如果这件事不单独说清楚，前面几章就更像能力展示，而不是可用方法。

一种最稳的排查顺序#

1. 先确认问题属于哪一类：
   - 结构不合法
   - 结构合法但语义不对
   - tool call / reasoning 回路不闭合

2. 再确认它更像哪一层：
   - SamplingParams / grammar constraint
   - parser / function_call 路径
   - API surface / 请求映射
   - tool result 回填后的后续生成

这两步的价值，在于它让读者不会一上来就掉进最底层实现。结构化结果异常最怕的不是复杂，而是层次判断错。

当“结构不合法”时先查哪里#

这类问题通常更靠近 SamplingParams、grammar backend 和约束输入本身。也就是说，先回到 sampling_params.py、frontend gen(...) 或 structured outputs 文档确认约束是否真的进入了 generation path，通常比直接查 parser 更有效。

当“结构合法但语义不对”时先查哪里#

这类问题反而未必是 grammar backend 的责任。因为结构已经合法，说明约束至少部分生效了。此时更应该去看 schema 设计、工具结果回填和业务侧解释，而不是继续在“为什么没有约束住”上打转。

当“tool call 回路不闭合”时先查哪里#

这类问题更接近 parser 和 tool roundtrip。重点不再是 schema，而是 function call 解释、工具执行结果如何回填，以及模型是否在下一轮正确接住了结果。也就是说，它已经从“结构化输出”跨进“多轮结构化对话”了。

本章对应哪些代码路径#

这一章主要回指 python/sglang/srt/sampling/sampling_params.py、python/sglang/lang/api.py、python/sglang/srt/function_call/function_call_parser.py、python/sglang/srt/function_call/base_format_detector.py、docs/advanced_features/structured_outputs.ipynb 与 docs/advanced_features/tool_parser.ipynb。

小结#

能力讲完之后，真正让章节变厚的，往往是这种“出问题时先怎么想”。有了这章，结构化生成与 API 这一整节就更接近一本能在现场真正派上用场的技术书。