Transformers.js v4.3发布：浏览器端结构化输出实战解析

Hugging Face 的 Transformers.js 迎来 v4.3 版本更新，距离上一个 4.2 版本已经过去一段时间。这次版本更新的核心亮点是结构化输出（Structured Output）——一项让浏览器端大模型能够严格按照预定义格式生成内容的能力。此外，团队还完全重写了文档生成系统，并合并了大量来自社区贡献者的功能与修复。

为什么需要结构化输出

在没有约束的情况下，大模型生成 JSON 存在天然的不确定性。以一个从用户输入中提取个人信息的场景为例：给定系统提示词和用户提示词后，模型确实能生成一段包含 JSON 的 Markdown 代码块，开发者可以剥离反引号后解析出对象。

问题在于，你无法保证每次都能成功。模型可能改变 JSON 的结构，可能换用 XML 或纯 Markdown，甚至可能完全不按预期输出。对于需要将模型输出直接接入应用逻辑的场景，这种不确定性是致命的。结构化输出正是为了解决这个痛点而生——它让开发者能够强制模型遵循一个精确的 schema。

约束解码：结构化输出的技术内核

结构化输出背后的技术术语叫做约束解码（Constrained Decoding）。要理解它，需要先理解大模型的生成机制：LLM 是逐 token 生成文本的，每一步都会返回一个候选 token 列表，以及每个 token 作为下一个输出的概率分数。

以「when was Danny Boyle born」为例，下一个 token 的候选可能有 born、birth、date、birthday、given 等。约束解码的核心思路是：不是让模型从全部候选中自由挑选，而是根据约束条件提前剔除掉不合法的 token。在图示中，born、birth、birthday 被标记为红色（不允许），模型只能选择 date；下一步 of 被允许，于是继续生成。通过这种方式，模型的输出被牢牢框定在预期结构内。

从实现角度看，约束解码依赖一种叫做有限状态机（FSM，Finite State Machine）或下推自动机的数学结构来表达合法输出的全集。以 JSON schema 为例，系统会将 schema 预编译为一张状态转移图：当前已生成的字符串处于某个状态，每个候选 token 尝试触发一次状态转移，如果转移后仍处于合法状态则保留，否则将其 logit 分数置为负无穷（即从候选列表中抹去）。这意味着约束校验的计算量与词表大小（通常数万到十万量级）成正比，且每生成一个 token 都要重复一次，这正是性能优化如此关键的原因。

全新的插件式包结构

这次实现结构化输出的方式很值得关注。团队在 v4 版本中对 GitHub 仓库做了重组，新增了 packages 目录。在很长一段时间里，这个目录只有 Transformers 主包，而现在多了一个 Transformers Structured Output 包。

这种重构的意义在于，团队现在可以将新功能以插件/附加组件的形式独立发布，结构化输出包就是首个这样的产物。更巧妙的是，实现这个功能几乎没有改动 Transformers.js 核心代码——因为它本身就已经支持 Logits Processor 机制。

Logits Processor 是一个能够钩入 token 生成最后一步（即解码步骤）的接口。在解码时，所有可能的下一个 token 都在这里，开发者可以介入并剔除不想要的 token。使用方式很直接：从 Structured Output 包导入 JSON processor，传入 tokenizer 和期望的 JSON schema，再把它交给 Logits Processor 即可。

运行同样的示例后，模型不再生成 Markdown，而是直接以花括号开头输出纯 JSON，并且用了 full name 而非 name——因为 schema 中明确要求了这个属性。除了 JSON schema，该包还支持**正则表达式（regex）**约束，可以强制模型生成类似 person=Bob Johnson, age=25 这样的特定格式。

Logits（对数几率）是模型在 softmax 归一化之前输出的原始分数向量，维度与词表大小相同。Logits Processor 是在这个向量上施加干预的钩子：它接收当前已生成的 token 序列和原始 logits 向量，返回修改后的 logits，再由解码器执行 softmax 采样。由于干预发生在采样之前，任何被置为负无穷的 token 在概率归一化后都会趋近于零，从而实现硬性排除。这种机制并非 Transformers.js 独创，HuggingFace 的 Python 版 Transformers 库、以及多个推理框架都提供同类接口，结构化输出只是其中一种应用场景。

真实应用：可靠的食谱生成器

作者展示了一个基于结构化输出的食谱生成器 demo。点击生成后，模型会严格按照预设的 JSON 结构输出，包含 title、description、ingredients 等字段。

拿到这段可靠的 JSON 后，应用就能直接解析并填充到界面布局中。整个流程之所以可行，正是因为开发者事先知道并可以信赖模型会输出的确切结构——这是普通生成方式无法保证的。

从 WebAssembly 到纯 JS 的性能之路

结构化输出的技术难点在于：需要一个能持续校验生成字符串是否符合约束的机制。每生成一步，都要根据约束验证所有候选 token。

社区里已有一个名为 LLGuidance 的库长期承担这个角色，vLLM、llama.cpp 以及浏览器端的 Prompt API 都基于它。团队的第一步原型是围绕 LLGuidance 的 Rust 实现做一个 WebAssembly 封装，并写一个适配器钩入 Transformers.js 的生成流程。这条路能跑通，但速度较慢，还需要下载一个 1MB 的 WebAssembly 文件，并不理想。

下一步，团队在大量编码 Agent 的辅助下，用纯 JavaScript 完整重新实现了 LLGuidance，彻底消除了那个 1MB 的 WASM 文件。团队还在性能上投入了大量精力——因为每添加一个新 token，都需要重新生成一遍允许的下一个 token 的掩码，再与模型生成的 token 做比对。

经过多轮迭代，作者用 Gemma、Granite、LFM 2.5 等不同模型、不同 tokenizer 做了测试。从 tokens per second 的对比来看，启用约束解码后几乎没有额外开销，偶尔会略慢一点，但幅度极小。最终成果是一个速度极快、且能兼容任意 tokenizer 的结构化输出包。

**WebAssembly（WASM）**是一种可在浏览器中以接近原生速度运行的二进制指令格式，常用于将 C/C++/Rust 编写的高性能库移植到 Web 环境。尽管执行速度快，WASM 模块仍有明显缺点：需要额外的网络下载（本例为 1MB）、与 JavaScript 之间的数据传递存在序列化开销（跨越"WASM 边界"的调用代价较高），以及在某些受限的浏览器环境中可能被阻止加载。这也解释了为何团队最终选择用纯 JavaScript 重写——在结构化输出场景中，约束校验的核心逻辑并非数值密集型运算，JavaScript 引擎的 JIT 编译已能提供足够的性能，同时彻底消除了 WASM 带来的工程复杂度与加载负担。

小结

Transformers.js v4.3 通过结构化输出，把过去只能在服务端稳定实现的约束解码能力带到了浏览器。JSON schema 与正则表达式两种约束方式、插件式的包架构、以及近乎零开销的纯 JS 实现，共同构成了这次更新的核心价值。仓库中已提供完整的 schema 支持文档，开发者可以直接上手尝试。