Core AI端侧约束生成coreai-models集成xgrammar实现JSON结构化输出深度解析【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-modelscoreai-models 是 Apple 推出的 Core AI 端侧 AI 开源项目提供模型导出配方、Python 原语和 Swift 运行时工具。其中最有意思的能力之一是它集成了xgrammar语法引擎让运行在 Mac / iPhone 上的本地大模型也能实现JSON 结构化输出约束生成——模型每生成一个 token都会被语法护栏实时校验输出 100% 符合你定义的 JSON Schema。为什么端侧大模型也需要结构化输出云端大模型的 API 普遍提供 JSON Mode但很多跑在本地的推理框架却只能祈祷模型吐出的 JSON 能解析。一旦输出多了个空格、少了个引号下游解析就直接崩溃。coreai-models 给出的答案是在采样阶段就禁止非法 token。这不是事后校验而是事前拦截——不合法的词在生成那一刻就根本没有机会被选中。 核心关键词速览Core AI、端侧 AI、约束生成Constrained Generation、xgrammar、JSON Schema、结构化输出项目速览一个仓库四件宝在深入之前先花 30 秒认识这个项目。仓库由四个目录组成详见 README.md目录作用与本文的关系models/30 主流模型的导出配方提供可导出的端侧模型python/PyTorch 编写原语与导出工具模型导出swift/Core AI 运行时 Swift 包✅ 约束生成就在这里skills/给编程 Agent 的插件技能辅助开发运行要求macOS / iOS 27.0Xcode 27.0。架构解析从 JSON Schema 到 Token 位掩码整个约束生成链路可以概括为三步流水线核心代码集中在 swift/Sources/CoreAILanguageModels/GuidedGeneration/ 目录JSON Schema ──编译──▶ 编译后语法 ──▶ 语法匹配器(Matcher) │ ┌─────────────────────────┘ ▼ ① 填充位掩码 bitmask哪些 token 允许出现 ② 把非法 token 的 logit 置为 -∞ ③ 采样出 token 并接受语法状态前进一格第 1 步把 JSON Schema 编译成语法在 XGrammarWrapper.swift 中GrammarCompiler负责把你的 JSON Schema 字符串编译成CompiledGrammar编译后的语法支持任意空白容忍anyWhitespace和严格模式strictMode两个开关。值得注意的细节TokenizerInfo.swift 中还内置了TokenizerInfoCache缓存 actor——同一个模型的词表信息只构建一次后续会话直接复用避免重复提取词表的开销。第 2 步每个 token 生成前算出合法词表这是 xgrammar 的精髓。语法匹配器GrammarMatcher会输出一个位掩码bitmask长度为(词表大小 31) / 32个 32 位整数每一位对应一个 token1 表示可以生成0 表示禁止生成。在 ConstrainedGenerationSession.swift 中applyMask方法会把所有被屏蔽 token 的 logit 原地置为-infinityFloat 和 Float16 两种精度都有实现。logit 变成负无穷意味着softmax 之后这些 token 的概率为 0采样器物理上不可能选中它们。第 3 步接受 token语法状态机前进采样得到 token 后调用acceptToken把它喂给语法状态机。状态机推进后下一个 token 的合法集合就变了——比如你刚生成了name:下一个只允许开头的字符串或{、[。这个会话结构体还贴心地提供了几个实用能力findJumpForwardString找出当前状态下必然会出现的确定性字符串可以直接跳过这几个 token 的推理纯性能优化 ⚡rollback语法状态回退最多 64 格配合束搜索等策略使用isTerminated双重判停——xgrammar 标记终止或位掩码全 0一个 token 都不允许 JSON 已写完xgrammar C 桥接层让 Swift 直接驱动 C 引擎xgrammar 本身是 C 库直接在 Swift 里调用会遇到复杂的 C 互操作问题。coreai-models 的方案很干净Apple 自写了一层纯 C 桥接头文件位于 swift/Sources/lib/CXGrammar/include/xgrammar_c_bridge.h。这层桥接只暴露 4 个不透明句柄和一组扁平 C 函数对象职责XGrammarTokenizerInfo词表 编码类型raw / byte-fallback / byte-levelXGrammarCompiler编译 JSON Schema 成语法XGrammarCompiledGrammar编译产物可跨会话复用XGrammarMatcher逐 token 匹配状态机位掩码通过 dlpack.h 定义的DLTensor传递——这是跨框架的张量内存标准格式也意味着位掩码未来可以直接写到 GPU 可见的 Metal Buffer 里免去 CPU 拷贝fillBitmask(into:)接口已经预留了这个能力。解码策略集成逐 token 的护栏闭环对应用开发者而言最省心的一层是 ConstrainedDecodingStrategy.swift。它实现了标准DecodingStrategy协议任何能传解码策略的地方都能用它每个 token 严格执行四步跑一次推理拿到原始 logits应用重复惩罚如有配置应用语法位掩码非法 token 清零从掩码后的 logits 采样把 token 交给语法状态机验收如果语法拒绝了这个 token理论上不该发生生成安全终止不会产出坏数据。整个过程以AsyncSequence流式输出GenerationResult文本增量 token ID 原始 logits可以边生成边渲染。另外ConstrainedSessionHandle.swift 用单一所有权句柄 借用归还模式包装了会话状态保证在流水线推理引擎中同一时刻只有一个任务持有会话——并发安全的设计藏在细节里。应用体验一个 response_format 就够用这套能力直接接入了 OpenAI 兼容的服务端 API。在 ServerAPITypes.swift 中请求体支持response_format字段{ model: qwen3-4b, messages: [{role: user, content: 提取图中的收货地址}], response_format: { type: json_schema, json_schema: { schema: { type: object, properties: { city: {type: string} } } } } }配套的 llm-server 工具会在 ChatHandler.swift 中检测到 schema 后自动切换为ConstrainedDecodingStrategy。也就是说同一套服务端接口加一个字段输出就从自由发挥变成保证合法——对做本地 Agent、结构化信息抽取、Function Calling 的开发者来说这是端侧场景下最刚需的能力之一。新手上手路径与三个设计亮点上手只需要 4 步用仓库内配方导出一个语言模型例如 models/qwen3/README.md 中的 Qwen3 系列引入swift/下的 Swift 包加载模型资源文件夹传入 JSON Schema 构造ConstrainedGenerationSession或直接使用ConstrainedDecodingStrategy正常调用生成 API收到的就是合法 JSON ✅三个值得点赞的设计决策停止词只在JSON 写完时刻放行——xgrammar 会屏蔽中途的 EOS token防止模型偷懒提前收尾产出残缺 JSON位掩码与张量解耦——通过 DLTensor 传内存CPU/Metal 两条路都走得通端侧性能友好编译产物可缓存复用——CompiledGrammar与 matcher 分离同一 schema 的多次会话只需编译一次总结coreai-models 用不到几百行 Swift 封装就把 xgrammar 的词表位掩码能力完整地搬到了 Core AI 端侧推理链路上。它证明了端侧大模型不必在能力和可靠之间做取舍——本地跑的小模型同样可以给出云端 API 级别的结构化输出体验。【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考