6.1 结构化生成与约束解码

Mon, 01 Jan 0001 00:00:00 +0000

结构化生成与约束解码#

这章解决什么问题#

这一章解决的是“模型输出怎样被约束成目标格式”。如果不单独讲这一层，读者很容易把结构化生成误读成“API 层的附加能力”，而忽略它其实直接插在 generation path 里，和 sampling、logits 选择、tool parser 一起工作。

从官方文档看，SGLang 把 structured outputs 定义得很直接：你可以为请求指定 json_schema、regex 或 ebnf，并且这三种约束参数是互斥的，只能选一种。这不是外围包装，而是 generation 过程本身的一部分。

为什么它属于执行链，而不是纯 API 功能#

python/sglang/srt/sampling/sampling_params.py 里，SamplingParams 直接包含 json_schema、regex、ebnf 和 structural_tag 字段，并在 verify(...) 里明确检查 “Only one of regex, json_schema, or ebnf can be set.”。这说明约束解码不是协议层的装饰，而是采样参数对象的一部分。

这也是本章和上一章衔接的原因。执行模型章节已经解释了 sampling 参数怎样参与 token 选择；这里进一步说明，当这些参数变成 grammar constraint 时，输出就不再只是“按概率采样”，而是“在满足约束的前提下继续生成”。从系统设计上看，这比单纯在最终文本上做后处理要更稳，因为约束是在生成过程中被满足，而不是生成后再去修正。

这里最适合补图，因为“约束到底插在哪里”很难靠一两段话稳稳说清。下面这张图回答的是：Frontend / HTTP 两侧传入的 json_schema、regex、tool parser 配置，最终怎样汇入 sampling / generation path。

flowchart TB
 A["Frontend gen(...)\nregex / json_schema"] --> C["SamplingParams"]
 B["HTTP / OpenAI-compatible request\nresponse_format / extra body"] --> C
 C --> D["Grammar backend\nXGrammar / Outlines / llguidance"]
 C --> E["tool parser / function calling parser"]
 D --> F["generation path\nconstrained token selection"]
 E --> F
 F --> G["structured output / tool call payload"]

相对于纯文字，这张图多解释了“参数对象是汇合点”这一层。调用方可能从不同表面进入系统，但只要最后落到 SamplingParams 和对应 parser / grammar backend，结构化生成就不是外围技巧，而是 runtime 能力。

6.2 API 表面与协议集成

Mon, 01 Jan 0001 00:00:00 +0000

API 表面与协议集成#

这章解决什么问题#

这一章解决的是“调用方到底通过哪些表面进入 SGLang，以及这些表面怎样回到同一条 runtime path”。如果不单独讲这一层，容易把 OpenAI-compatible API、native APIs、offline engine 和 frontend language 当成互相独立的产品，而不是同一套系统暴露出的不同入口。

对工程读者来说，这个问题很实际。因为你在排查行为差异、设计接口迁移方案，或者把某条业务流从 OpenAI 托管迁到自托管时，真正关心的不是“这个接口像不像”，而是“它最后落到同一套 runtime 了吗”。

为什么要把协议表面单独拎出来#

从官方 docs 可以看到，SGLang 明确把 OpenAI-compatible APIs、native APIs 和 offline engine 分开写。docs/basic_usage/openai_api.rst 聚合的是 OpenAI-compatible usage；docs/basic_usage/native_api.ipynb 则罗列 /generate、/server_info、/flush_cache、/tokenize、/detokenize 等 native endpoints；docs/basic_usage/offline_engine_api.ipynb 则直接讨论不经过 HTTP server 的 inference engine。

这说明协议表面本身就是系统的一层设计，而不是文档编排巧合。SGLang 一方面希望让调用方能平滑迁移到 OpenAI-compatible 表面，另一方面又保留自己的 native surface 和 offline engine path，让内部能力不被单一协议形状限制住。

OpenAI-compatible API 在这套系统里的位置#

OpenAI-compatible API 的价值在于降低迁移成本。官方 openai_api_completions.ipynb 和相关 basic usage 文档都在强调这一点：你可以用接近 OpenAI 的请求格式对接本地模型服务。对于多数应用接入者来说，这是最容易上手的一层。

但从运行时角度看，重要的不是“长得像 OpenAI”，而是它最终怎样落进 http_server.py 和 TokenizerManager.generate_request(...) 这条路径。也正因为如此，OpenAI-compatible 层更适合作为“协议适配面”来理解，而不是当作独立 runtime。

6. 结构化生成与 API on Machine Learning 学习笔记

6.1 结构化生成与约束解码

结构化生成与约束解码#

这章解决什么问题#

为什么它属于执行链，而不是纯 API 功能#

6.2 API 表面与协议集成

API 表面与协议集成#

这章解决什么问题#

为什么要把协议表面单独拎出来#

OpenAI-compatible API 在这套系统里的位置#