vLLM 源码完全拆解（十四）：结构化输出——FSM 编译、语法 bitmask 与受限采样

编译有多慢#

GrammarCompiler.compile_json_schema 把一份 JSON Schema 编译成 xgrammar 的自适应 token 掩码数据结构。这个过程是纯 CPU 的:遍历 schema → 转成等价的 EBNF 文法 → 构建 token 树掩码。对简单的 {"type": "object", "properties": {...}} 毫秒级;但对带深层嵌套、oneOf 组合、多维数组的真实业务 schema,编译可能要秒到分钟级——xgrammar 论文里报告的最大用例(全量 MySQL schema 的 JSON)编译时间以分钟计。

问题在于这不能发生在调度热路径上。调度器每个 step 都在毫秒级预算里跑完,一条请求卡住整个引擎 30 秒不可接受;但请求也不能被丢弃——语法是用户明确要的,vLLM 既不能静默去掉约束(那是错误的输出),也不能立刻 503(那是不必要的拒绝)。

Future + 状态机:两段式等待#

解法是把”编译”变成一个可以轮询的后台任务。grammar_init(structured_output/__init__.py:63)做三件事:

1
def grammar_init(self, request: Request) -> None:
2
    ...
3
    if self.backend is None:      # ① 懒初始化全局 backend
4
        self.backend = XgrammarBackend(...)
5
    grammar = self.executor.submit(self._async_create_grammar, request)  # ②
6
    request.structured_output_request.grammar = grammar                # ③
7
    # 此刻 request.structured_output_request.grammar 是一个 Future

① 全局 backend 只建一次,持有一个带缓存的 GrammarCompiler(编译结果磁盘 LRU,容量 VLLM_XGRAMMAR_CACHE_MB,默认 512MB——同样的 schema 第二次请求直达);② 编译任务提交到线程池,线程数是CPU 核数的一半(注释:默认 cpu*5 是给 I/O 任务的,CPU 密集的语法编译不该占满核;顶多耗一半,给调度器留算力);③ Future 挂到请求上,Request.__init__ 已经把状态设为 WAITING_FOR_FSM(vllm/v1/request.py:54)。

等待端在调度器(vllm/v1/core/sched/scheduler.py:354):

1
if request.status == RequestStatus.WAITING_FOR_FSM:
2
    structured_output_req = request.structured_output_request
3
    if structured_output_req and structured_output_req.grammar:
4
        request.status = RequestStatus.WAITING      # 编译完成,进入正常调度
5
    else:
6
        self.waiting.pop_request()
7
        skipped_waiting_requests.prepend_request(request)  # 没好,放回队头
8
        continue

Grammar 属性自带完成探测(structured_output/request.py:26):

1
def _check_grammar_completion(self) -> bool:
2
    if isinstance(self._grammar, Future):
3
        try:
4
            self._grammar = self._grammar.result(timeout=0.0001)  # 100 微秒
5
            self.status = RequestStatus.WAITING
6
        except TimeoutError:
7
            return False
8
    return True

100 微秒的非阻塞轮询是这段设计的精髓:不是轮询间隔(轮询发生在每个调度步,天然节流),而是”探测成本”。Future.result(timeout=...) 底层是条件变量的带超时等待,100μs 的口径让一次探测最坏只吃掉调度步预算的百分之一;编译好了 Future 就变成了真正的 StructuredOutputGrammar,此后 grammar 属性每次访问都立即返回。请求在 WAITING_FOR_FSM 状态里不占调度预算、不占 KV block、不占 running 槽位,只是安静地排在 waiting 队列——编译慢的全部代价就是”这个请求晚几分钟开始生成”,而不是”整个引擎停摆”。

一个容易被忽略的次序细节:探测发生在每个调度 step 的 waiting 队列扫描里,而扫描是从队头来的。如果队头三条请求的 FSM 都没编译好,它们会被 prepend_request 依次放回队头,同批更靠后的纯文本请求不会被它们挡住——skipped_waiting_requests 这个专用队列的意义就在这里:跳过的请求集合与”被选中继续调度”的集合分开收集,循环结束后统一 prepend,避免跳过请求打断本轮已建立的队序。

验证层:把编译失败挡在 P0#

编译还可能失败——schema 里有 xgrammar 不支持的 JSON 关键字、正则无法转成文法、Lark 语法转 EBNF 失败。这些都发生在 P1 的编译线程里,但抛给用户的时机在 P0:process_inputs 的 _validate_structured_output(processor.py:187)在请求进入引擎之前就调用 validate_xgrammar_grammar(backend_xgrammar.py:241),做一轮”只解析、不编译”的预检:

1
if gd_params.json:
2
    ...
3
    try:
4
        xgr.Grammar.from_json_schema(schema)      # 只解析 schema,不构建掩码
5
    except Exception as err:
6
        raise ValueError("Failed to transform json schema into a grammar: ...")
7
    if has_xgrammar_unsupported_json_features(schema):
8
        raise ValueError("The provided JSON schema contains features not "
9
                         "supported by xgrammar.")

has_xgrammar_unsupported_json_features 递归扫 schema,列出已知不支持的特性:multipleOf(数字倍数)、uniqueItems/minContains/maxContains(数组约束)、format(字符串格式)、minProperties/patternProperties 等。为什么不直接编译来发现不支持?因为那要把失败信号从 P1 的线程穿透回 P0 的 HTTP 响应,而编译是在异步线程里跑的——显式列出已知不支持清单,把错误前置到立刻抛出,比事后从异常链里捞要可靠。代价是清单会过时(xgrammar 支持面在扩大),源码用 TODO 注释承认了这一点。

choice 类型还有一处改写式降级:["北京","上海","广州"] 被转换成 root ::= "北京" | "上海" | "广州" 的 EBNF 文法再统一走 grammar 通道(validate_xgrammar_grammar 中 gd_params.choice = None; gd_params.grammar = choice_grammar)。choice 在引擎内部根本不是独立类型——它的 bitmask 语法与 regex/JSON 完全共享,只是入口接口给了用户一个更顺手的形状。同类改写还有 Lark→EBNF 的自动化转换(structured_output/utils.py:41,逐行把 rule: 头转成 rule ::=、单引号字面量转双引号、补 root ::= first_rule)。

改写发生在验证层,带来一个值得单独说明的好处:改写失败(引号不配对、引用了未定义规则)在 P0 就抛 ValueError,用户拿到的是”你的 grammar 第 3 行引用了未定义的 rule”这样精确的错误;若改写发生在 P1 的异步编译里,同样的错误要经过 Future 的异常通道、可能被 _check_grammar_completion 的轮询掩盖,用户只会看到”请求一直在排队”。这也是验证层存在的深层理由——编译的失败要尽量前移到同步路径,异步段的错误越少,状态机的处理越简单。

guidance 后端与 xgrammar 的接口对照#

GuidanceBackend(backend_guidance.py)内部的 GuidanceGrammar 用 llguidance 的 LLMatcher 实现同一组动词,对照读可以看清抽象接口的边界到底裁在哪里。三处语义差异值得标记:

终止判定的来源不同。xgrammar 的 is_terminated() 直接问 matcher 内部状态;guidance 用一个自己维护的布尔 里若检测到 EOS token 就把 self.terminated = True,matcher 停止后 accept_tokens 变成无条件返回 True。两种实现对外行为一致(到终止态后不再消耗输入),但guidance 的终止要靠”EOS 出现在采样结果里”这个事件驱动,xgrammar 是状态驱动——语义等价,机制 different,混用两者的心智模型时需要注意。

错误处理的可见性不同。guidance 的 matcher 有错误态,check_error() 用一个一次性标志(printed_error=False 起步)保证同一错误只打印一次;xgrammar 的 accept_tokens 失败直接 logger.error 加”Please file an issue”——后端的错误路径设计按各自上游库的风格收敛,但都遵守”错误不中断批处理”的共识:一个请求的 FSM 出错不连带其他请求,最坏情形是该请求的约束失效或提前终止,由日志暴露。

fast-forward 的支持度不同。guidance 侧留了一段 TODO:compute_ff_bytes/compute_ff_tokens(jump-forward decoding——文法状态如果只差一个”固定后缀”就能到下一歧路口,直接把这段固定 token 跳过不采样),xgrammar 侧 find_jump_forward_string 已经在 API 里(见 backend 源码引用的文档链接)。跳过确定性后缀是受限采样独有的免费午餐:文法在”必须有右括号”的状态下,输出没有选择自由,直接填串比生成掩码更省 GPU 跳。0.9.2 的 vLLM 接口还没把 fast-forward 接进调度循环(那需要”一个 step 填多个 token”的能力与 KV 缓存的配合),但接口的动词集已经为它留了位置。

FSM 是什么,bitmask 从哪来#

xgrammar 的 GrammarMatcher 内部对编译好的文法维护着当前状态:已消费哪些 token、下一步能接哪些。fill_next_token_bitmask(bitmask, idx) 把”从当前状态出发,接受哪些 token 不会违反文法”写成一张位图——vocab_size 个比特,int32 每 32 位一个字,合法 token 的比特为 1,非法为 0。vLLM 拿到这张位图后,对 logits 做就地掩码=0 的位置减成 -inf。

先看位图缓存的数据结构与生命周期要点:

• 分配:首次需要时 backend.allocate_token_bitmask(max_batch_size * (1 + max_spec_tokens)),即每个请求一张,若开投机解码,每个投机槽位再各一张。一次分配终身复用,每个调度步开头重置。
• 重置:bitmask_tensor[...].fill_(-1)——_full_mask = torch.tensor(-1) 是 int32 的全 1,即”默认全禁”,随后每个被调度的请求把自己的合法位写出来。默认态选”全禁”而不是”全允许”是纵深防御:某个路径漏写请求的 mask 时,表现为该请求永远采不出 token(超时/卡死),而不是”约束被静默忽略、输出又飘了”。
• 传输 → numpy(structured_output/__init__.py:196;注释解释:NumPy 的序列化比 torch 快得多,这是 P1→GPU worker 的跨进程序列化路径,第九篇 Sampler 的 logprobs 也走同一条)。
• 生效 worker 收到后转回 tensor,apply_token_bitmask_inplace 的 torch.compile 实现(gpu_model_runner.py:1149)对 logits 的对应行做 logits[bit=0] = -inf。

生成端 逐请求填表#

StructuredOutputManager.grammar_bitmask(structured_output/__init__.py:114)每个调度步末尾运行,遍历本步真的被调度的结构化输出请求,逐个填位图:

1
for req_id, _ in ordered_seq:                       # 按批内下标排序
2
    ...
3
    apply_bitmask = True
4
    if self.reasoner is not None:
5
        if structured_output_request.reasoning_ended is None:
6
            structured_output_request.reasoning_ended = \
7
                self.reasoner.is_reasoning_end(request.prompt_token_ids)
8
        apply_bitmask = structured_output_request.reasoning_ended
9
    state_advancements = 0
10
    req_tokens = scheduled_spec_decode_tokens.get(req_id, []) + [None]
11
    for i, token in enumerate(req_tokens):          # 每个投机槽位 + 1 个本位
12
        if apply_bitmask and not grammar.is_terminated():
13
            grammar.fill_bitmask(bitmask_tensor, cumulative_index)
14
            if token is not None:
15
                grammar.accept_tokens(req_id, [token])   # 前瞻:假想接受
16
                state_advancements += 1
17
        cumulative_index += 1
18
    if state_advancements > 0:
19
        grammar.rollback(state_advancements)             # 回滚,恢复真状态

主循环只填一张”本位”的 mask(没有投机解码时这是唯一一张);若调度里有投机 token,对每个投机槽位额外填一张——填第 i+1 张前,把第 i 个投机 token “假想接受”进 FSM 推进状态,这样第 i 个槽位的 mask 反映的是”若前面全被接受,后面的合法选择是什么”。所有槽位填完统一 rollback。这是在用”前进再倒档”换算多步状态,而不是为每个假设状态保留独立副本——FSM 状态推进是 O(1) 的指针操作,回滚也一样便宜,远比维护多副本状态省内存,这个模式在投机解码与受限采样交叉的场景里是标准解法(第十二篇 CUDAGraphDispatcher 的 BatchDescriptor、本篇 accepted_token 前瞻,都是同型思路)。

apply_bitmask 的分支是为推理解耦/reasoning 交互:若模型是思维链型(如 DeepSeek-R1 的 <think>...</think> 结构),约束不该从第 0 个 token 就生效——推理阶段的自然语言会被 JSON 的位图活活绞死。vLLM 用 ReasoningParser 判断”思维结束了吗”,没结束的请求本步不填 mask、也不推进 FSM,等 </think> 之后才开始受限采样。should_advance(structured_output/__init__.py:198)在输出端配对:reasoner.is_reasoning_end(request.all_token_ids) 检测到思维结束的当下返回 False(本步的 token 还在思维里),下一个 pass 才开始推进 FSM——一句注释就说明白了这种 off-by-one 的处理:“Reasoning just ended, so we shouldn’t advanced til next pass”。

生效端:三把尺子对齐同一批请求#

apply_grammar_bitmask(gpu_model_runner.py:1093)是屏蔽层在 GPU 侧的最后一跳。它会遇到一个排序错位问题:调度器把 bitmask 按”结构化输出批内序”打包(紧致排列,没有约束的请求不占位),而 logits 的行序是”GPU 批内下标”(每个请求占一行,包括没有约束的)。两个序必须精确对齐,mask 才会落在请求自己的行上:

1
for req_id, batch_index in seq:                      # ① GPU 批内序
2
    logit_index = batch_index + cumulative_offset
3
    cumulative_offset += len(scheduled_spec_decode_tokens.get(req_id, []))
4
    if req_id in structured_output_request_ids:
5
        struct_out_req_batch_indices[req_id] = logit_index
6

7
for req_id, _ in seq:                                # ② 结构化批内序
8
    logit_index = struct_out_req_batch_indices[req_id]
9
    num_spec_tokens = len(scheduled_spec_decode_tokens.get(req_id, []))
10
    for i in range(1 + num_spec_tokens):
11
        sorted_bitmask[logit_index + i] = grammar_bitmask[cumulative_index + i]
12
        out_indices.append(logit_index + i)
13
        cumulative_index += 1 + num_spec_tokens

两把尺子的换算都在这段里:① 建立”请求 → 它的 logits 行号”映射,偏移量 cumulative_offset 加的是其他请求的投机 token 数——投机解码里每个请求占的 logit 行数 = 1 + 自身投机数,批内行号是逐请求累加的,不是 batch_index 直接可索引(第九篇 Sampler 的 bonus_logits_indices 处理的是同一套行号语义);② 沿结构化请求序把各自紧凑打包的 mask 行拷到 logits 行号对应的位置,投机请求的 1+num_spec_tokens 张连成一段。没有约束的请求在 sorted_bitmask 里保持全 0 初始化——np.zeros_like 保证了这一点,它们不会碰 mask(全 0 的 int32 字不是 -1,后续 kernel 对”未列出的行”跳过)。

out_indices 把”实际写了 mask 的 logits 行号”收集成一个整数列表传给 kernel,kernel 只对这些行做掩码,别的行原样不动。mask 的行数、logits 的行数、结构化请求的行数三个数互不相等,全靠显式索引对齐——这里没有 batch 维度广播的巧合,只有排序与索引的算术。

开销集中在哪#

结构化输出的运行期开销有三个来源,量级差得很远:

1. 语法编译(一次性):简单 schema 毫秒级,复杂 schema 秒到分钟级。xgrammar 论文的核心贡献就是把这个数字从分钟压到亚秒——用自适应 token 掩码(token mask tree)加缓存已见状态的掩码增量,而不是每个状态都现算全量掩码。vLLM 侧的对策是异步编译加编译结果 LRU 磁盘缓存(VLLM_XGRAMMAR_CACHE_MB),同 schema 的第二个请求零编译。
2. 每步 bitmask 填充(每跳每请求):fill_next_token_bitmask 从缓存状态增量生成,CPU 上微秒级;但它跑在 P1 的调度线程上(grammar_bitmask 在 schedule 尾部同步调用),大 batch 全是结构化输出请求时,这个逐请求串行循环本身是 O(batch × FSM 常数) 的纯 CPU 段。源码留了注释承认这里有优化空间(# NOTE: This outer loop can likely be parallelized...),当前版本没做。
3. GPU 掩码应用(每跳一次):apply_token_bitmask_inplace 是一个对 (num_reqs, vocab) 的位运算广播,微秒级开销,不构成瓶颈。值得注意 0.9.2 刻意选了 torch.compile 实现而非 Triton kernel(gpu_model_runner.py:1146-1149),注释指向 PR #19565 与 issue #19493/#18376 版在并发结构化输出场景有正确性问题,torch.compile 版虽慢一点但错不了——用微量性能换确定性的取舍,与上一章的默认全禁 mask 是同一种防御意识。

官方博客给的实测位#

vLLM 官方的结构化输出解读文章给了一组 LLaMA-3B、单卡 A6000 的对比数字(见下图):旧 V0 的 GuidedDecoding 路径(outlines/local 两种)每 token 额外开销都在数百微秒到毫秒级,换 xgrammar 的 V1 路径后,decode 每 token 的额外开销被压到 50μs 附近——几乎接近无约束基线。原理不神秘 的 logits processor 在每次采样时由 CPU 现算掩码(有的还要跨进程取),V1 把掩码生成移到调度步、把掩码应用下沉到 GPU kernel、把编译移到后台,三个阶段的成本各自落在不会阻塞关键路径的位置。

另外两个来自同一份实测的观察对容量规划有用:约束对批处理吞吐的稀释远小于对单请求延迟的影响(大 batch 下,掩码应用的固定开销被摊薄);带 any_whitespace 变体时编译产物不同(xgrammar 对”JSON 里允不允许任意空白”编译出不同 FSM),用 --structured-outputs-config '{"disable_any_whitespace": true}' 关掉可以缩小可行集、提高输出贴近 schema 的程度,但代价是输出格式更死板(没有缩进换行)。

常见坑排查手册#

1. “请求一直排队不开始生成”先查 FSM 编译。调度器日志里请求进进出出 WAITING_FOR_FSM,QPS 明明很低。三个排查方向 是不是第一次出现的复杂 schema(看 VLLM_XGRAMMAR_CACHE_MB 命中率,或看编译线程是不是在干活)、--structured-outputs-config 的 backend 是不是意外切到了 guidance(guidance 对某些文法的编译比 xgrammar 慢)、tokenier 是不是 skip_tokenizer_init——注释里明确写了 skip_tokenizer_init 的部署(纯 token id 输入)没有 StructuredOutputManager,约束会被静默忽略。
2. WAITING_FOR_FSM 的请求也占 waiting 队列的位置。前文说了它们不占算力,但队头堵一堆长编译请求时,调度循环每个 step 都要探测一遍(每条 100μs)。若一批涌入 50 条同 schema 请求,它们共享同一个编译任务吗?不——vLLM 的编译缓存(backend 的 GrammarCompiler 磁盘 LRU)在编译完成后才可能命中,提交时刻 50 条 Future 就是 50 个任务,靠 cache_enabled=True 的编译器内部去重并发。上游讨论里有 schema 加载去重的工作,0.9.2 还是靠编译器自身的缓存语义兑现。
3. 结构化输出 + prefix caching 的交集要看 FSM 状态对齐。两条请求共享前缀、但 schema 不同时,bitmask 各填各的(vLLM 按 schema 内容的 hash 是否一致来共享编译产物,而不是”同前缀就同 FSM”);同 schema 时 FSM 从 0 状态同构推进,没有 state 跨请求复用问题。自定义后端集成时要保证 StructuredOutputGrammar 的状态不逃逸出单请求。
4. reasoning 交互开启时约束生效点后移。带 <think> 的请求,JSON 约束从思维结束后才开始;若 ReasoningParser 配置的结束标记与模型实际输出不一致(或模型永远不输出 </think>),约束永远不生效,表现为”structure output 不起作用”。reasoning_ended 的初始化是惰性的(reasoning_ended is None 时才扫 prompt),已判 False 的请求不会重扫 prompt,靠每步的 all_token_ids 检查翻转——输出里搜结束标记失败的话,整个请求的自由文本一路采到底。
5. Mistral/tekken 词表要走专门路径。backend 构造里对 MistralTokenizer 单列了一支(逐 token 排序重构词表、按 tekken 与否选 RAW/BYTE_FALLBACK 词表类型,backend_xgrammar.py:39-71)。用 Mistral 模型做结构化输出看到掩码异常时,先确认这段构造走的分支是否正确。

投机解码分叉:约束语义在三处与草稿机制交叉#

投机解码(request 用草稿模型先猜 N 个 token,目标模型并行验证)与结构化输出的组合是这条链上最精细的部分,把三个交叉点单独拎出来:

交叉一:验证阶段的合法集判定。草稿给出 spec_token_ids = [t1, t2, t3],目标模型本步调度了这 3 个投机 token。grammar_bitmask 里对每个投机槽位 i:先填第 i 状态的 mask,再把 ti 假想接受进 FSM(推进),循环三次、回滚三次。这张 3 张 mask 的表随 SchedulerOutput 上 GPU,验证采样的目标模型自身也受 mask 约束(验证时目标模型对每个位置做 teacher-forced 前向,采样的是”接受/拒绝”判定所需的 token 分布)。

交叉二 只推进净接受前缀。验证结果出来,接受前缀可能是 [t1, t2](t3 被拒),此时调度器 update_from_output 调 validate_tokens([t1,t2,t3]) 返回 [t1,t2] 并 rollback;FSM 的推进量以接受前缀为准(scheduler.py:841 直接把 validate 的返回写回 request.spec_token_ids),被拒绝的 token 从未”真正”进入 FSM 的时间线。max_rollback_tokens 的构造参数(backend_xgrammar.py:122)由此而来:回滚深度只需要覆盖”本步全部投机 token 数”这个上界。

交叉三 的行号偏移在 GPU 端要二次对齐。投机解码下 logits 的形状是 (sum(1+spec_i), vocab)——每个请求占 1+自身投机数 行(第九篇的 bonus_logits_indices 处理的就是这套行号)。apply_grammar_bitmask 里 cumulative_offset 累加的就是其他请求的投机 token 行数,把紧凑打包的 mask 行精确铺到目标行的 logit_index + i 位置上。三个交叉点合起来看 状态管理(调度器侧)、mask 生成(管理器侧)、mask 落位(GPU 侧)各自独立处理投机,全靠”每个投机槽位一张 mask + 回滚到真状态”这一条主线协议统一。

从 V0 的 logits processor 到 V1 的调度步 bitmask#

结构化输出在 V0(vllm/model_executor/guided_decoding/)与 V1 的实现路径差异,是理解 0.9.2 引擎设计的一个好样本。V0 把约束作为 logits processor:采样时逐请求现算掩码,XGrammarLogitsProcessor 持有 matcher,每个 batch 采样前在 CPU 上逐请求 fill、再由框架把掩码应用到 logits。这个模型直观、与 HF transformers 的自定义 logits processor 生态兼容,但有两个执行层的问题:一是掩码生成串在采样关键路径上——batch 越大、约束越复杂,采样前的 CPU 段越长,GPU 空等;二是batch 无感知——每个请求独立填掩码、独立应用,连”同 schema 的请求可以共享编译产物”都要靠 processor 外面的缓存字典手工对齐。

V1 的改造不是换掉 xgrammar,而是把三段成本重新分配(见”性能”一章):编译进后台线程池、掩码生成进调度步(与 GPU 执行重叠)、掩码应用进 GPU kernel(与 sampler 重叠)。grammar_bitmask 的返回值是 NumPy 数组这个”看似随意”的选择,正是为跨进程传输优化的注脚——ZMQ 消息里的 payload 是纯字节数组,GPU worker 收到后一次 torch.from_numpy 进内存、一次 .to(device) 上卡,全程没有 Protobuf/JSON 的对象化开销。V0 路径在 0.9.2 里仍在但已标记 legacy,官方博客的结构化输出文章里那张对比图(见”性能”一章)对应的就是这次切换。

有一个 V1 特有的工程细节,体现这套改造的彻底性:StructuredOutputManager 整个住在 EngineCore 进程里,而编译线程也在这个进程里。编译是 CPU 密集的,与调度循环共用人核——线程池上限取一半 CPU 就是给调度主循环留的份额。设计上更激进的做法是把编译挪到 P0(前端进程)甚至独立进程,但那要求把”编译产物”跨进程序列化传输,而 CompiledGrammar 是原生对象(带 C++ 扩展的 matcher 状态),不能过 ZMQ——所以编译必须住在产物被消费的进程里,这是”数据在哪,计算就在哪”约束下的次优选择,而不是没想过。相关讨论在上游 issue 里出现过多次,拆成”编译服务 + matcher 状态同步”的方案复杂度高,0.9.2 的选择是让编译在 P1 内部并发,靠磁盘缓存兜住冷启动。

V1 的结构化输出可以压成一条四段流水线:

1. 入口验证(P0) 能否表达、支持的特性清单显式核对、choice/Lark 的入口改写,失败立刻 4xx 而不是进入引擎后再死。
2. 异步编译(P1):线程池加 Future,状态机 WAITING_FOR_FSM 隔离编译慢;编译结果磁盘 LRU,同 schema 第二次直达;编译线程只分 half CPU,把核留给调度。
3. 批量掩码(每步):按批内序紧凑填表,投机解码用”前进再倒档”换算前瞻状态,reasoning 检测决定约束从哪一跳开始生效,默认全禁 mask 提供漏填时的纵深防御。
4. 就地生效(GPU):两把尺子(批内序、logits 行号)的重排对齐,apply_token_bitmask_inplace 的 torch.compile 实现把 -inf 就地压进 logits,Sampler 全程无感知。

机制之外,这套设计最有味道的是成本搬家:编译的成本被搬到后台、掩码生成的成本被搬到调度步、掩码应用的成本被搬到 GPU 内核——每一段都问”这个开销放在哪才能不挡住关键路径”,而不是”这个开销能不能零”。这条思路与 V1 的其他改造(进程分离、连续批处理、piecewise CUDA Graph)一脉相承,也给了阅读其他推理框架(SGLang 的 constrained_json_gen、TensorRT-LLM 的 logits processor 约束)一个固定的分析框架:遇到受限解码,先问四个位置——约束在哪个进程验证、在哪编译、在哪生成掩码、在哪应用。

下一篇继续 V1 的采样侧:第九篇拆过的 Sampler 是”单跳视角”,还有一条它完全没覆盖的生产路径——stop string 的检测与截断、detokenizer 的增量解码流水线,以及它们与结构化输出的相互影响。