Laya-MLX 实战指南：在 Apple Silicon 上以毫秒级延迟原生运行 Laya 类型化决策模型

Laya-MLX 实战指南在 Apple Silicon 上以毫秒级延迟原生运行 Laya 类型化决策模型【免费下载链接】laya-mlxNative MLX runtime for Laya typed decision models — 7–14 ms short decisions on M3 Max. No text generation, PyTorch, or cloud API.项目地址: https://gitcode.com/gh_mirrors/la/laya-mlxLaya-MLX 是 Laya 类型化决策模型typed decision models在 Apple Silicon 上的原生 MLX 推理运行时它把“给出一段文本状态回答一组结构化问题”的推理压缩到单次双向前向传播零输出 token、无 PyTorch/Transformers 推理依赖、不调用任何云端 API。本文基于仓库 README.zh-CN.md 与源码完整讲解它的安装、Python/CLI 用法、三种问题类型choice/score/noul、支持的检查点、M3 Max 实测性能、权重转换、多语言路由以及可复现的测试与 benchmark 流程读完即可在本机跑通一条端到端的本地决策推理链路。类型化决策为什么不需要“生成”答案常规大模型回答任何问题都需要逐 token 解码而软件系统真正需要的往往只是一个分类结论这个工单该转给哪个部门这个请求有多紧急用户是不是要求退款Laya 用“类型化决策”直接回答这类约束问题推理过程是一句可概括的流水线state typed question → 双向编码器 → 决策头 → 概率三种问题类型由 laya_mlx/common.py 中的QTYPES定义各对应一种确定性的结果格式choice对若干命名选项输出分类概率如billing / technical / sales三选一score对有序评分等级输出概率并给出期望得分如not urgent / soon / criticalnoul对某个命题输出P(true)如“客户是否要求退款”。每个问题作为独立的一行输入双向编码器编码器表示同时依赖 state 与问题本身——因此该运行时不宣称把 state 编码一次后跨任意问题复用 hidden states。结果保留上游的四位小数概率格式与action.act_probability字段usage中的output_tokens恒为 0这正是“0 输出 token”的由来见 agent.py。编码器、决策 Transformer、评分头与动作头全部在 MLX 中运行tokenization 使用 Hugging Face 的 Rust tokenizertokenizers库原始预训练权重、问题格式、温度校准与输出 schema 均保留。需要说明的是这是独立的 MLX 移植并非 Convai Innovations 的官方发布RLCD 训练与微调仍在上游项目进行本仓库只负责推理与权重转换。快速开始三条命令跑通第一个决策安装并加载 multilingual 检查点对一个中文工单做一次部门分类pip install laya-mlximport laya_mlx as laya agent laya.load(aac6fef/laya-multilingual-mlx) result agent.predict( 发票被重复扣款请退款。, { department: { type: choice, instructions: Who should handle this?, criteria: [billing, technical, sales], } }, ) print(result[answers][department])首次load会从 Hugging Face 下载检查点之后完全本地推理。predict是system_one的别名state 可以是纯文本、JSON 字典或对话列表。返回结果形如{ answers: { department: { type: choice, confidence: 0.9987, action: {act_probability: 0.9982}, choice: billing, probabilities: {billing: 0.9987, technical: 0.0009, sales: 0.0004} } }, usage: {input_tokens: 46, output_tokens: 0} }choice的criteria可以是唯一标签列表也可以扩展为{标签: 描述}的字典描述会进入上下文帮助模型区分相近选项score的criteria必须是等级列表score返回从 0 开始的期望等级noul返回P(true)。仓库自带的 examples/questions.json 就是一个同时包含三种类型的最小示例。一次提问多个问题决策模型的价值在于一次前向传播并行回答多个问题。把questions扩展为一个以问题 ID 为键的字典即可result agent.predict( 发票被重复扣款请今天退款。, { department: { type: choice, instructions: Which department should handle this request?, criteria: [billing, technical, sales], }, refund: { type: noul, instructions: Does the customer ask for money back?, }, }, ) print(result[answers])batch_size16默认控制每次前向计算的问题数更多问题会自动分块处理见 agent.py内存充足时可以调大。batch_size必须是正整数否则构造Agent时直接抛ValueError。关键加载参数laya.load对应 agent.py 中的Agent构造参数参数默认值说明dtypefloat16计算精度float32/float16/bfloat16。默认 FP16需要更接近原版 FP32 的数值时用float32。bfloat16可请求但不在已发布的验证矩阵内batch_size16单次前向的最大问题数超出分块处理deviceNonegpu/metal/cpuNone时用 MLX 默认设备revisionNone固定 Hub revision 哈希保证可复现subfolderNone从捆绑仓库中选择某个子目录检查点如multilingualcompileFalse启用mx.compile编译适合重复负载首次使用有编译开销与形状特化pad_to_multipleNone把序列长度补齐到该值的整数倍如 16配合编译使用某些负载可能变慢cache_promptsFalse前缀缓存上限 128 个问题共享 CPU 侧 state tokenization但每个问题仍单独计算编码器加载时会对每个参数名与形状做严格校验strictTrue不支持的编码器与非默认 RoPE 缩放会直接失败ModernBERT 的全局/局部注意力模式、滑动窗口边界、双 RoPE base 与首层归一化行为都被保留。以上三个优化选项默认全部关闭实测数据见 docs/SNAKE_OPTIMIZATION.md。支持的检查点检查点编码器参数量最大上下文用途convaiinnovations/layaModernBERT-large421M512英文convaiinnovations/laya-multilingualmmBERT-base322M1,024多语言输入100 语言convaiinnovations/laya-typed-decisionsModernBERT-large421M1,024上游 typed-decisions 工作流上下文预算包含问题、选项与输入状态。中文等非英语输入应使用 multilingual 检查点——英文检查点在非英语输入上会剧烈退化并伴随高置信度这是路由器必须存在的原因详见下文。三个已转换的 FP16 MLX 权重仓库可直接传给laya.load(...)aac6fef/laya-mlx英文aac6fef/laya-multilingual-mlx多语言aac6fef/laya-typed-decisions-mlxtyped-decisions 工作流每个模型仓库都附带模型卡、验证结果、来源、许可证与文件校验清单三个仓库共 36 个文件均通过严格远端校验固定版本与权重哈希记录在 benchmarks/results/hub-publication.json。也可以加载上游捆绑仓库中的子目录# 在上游捆绑仓库中选择 multilingual 子目录 multi laya.load(convaiinnovations/laya, subfoldermultilingual) # 固定 revision 以保证可复现 agent laya.load( convaiinnovations/laya, revisionc5d78730f3493e4fe16d61507ef4b78eef7318cf, )M3 Max 实测13.4 ms 与 7.4 ms 的含义FP16端到端Laya 421MMultilingual 322M单个短问题 P5013.42 ms7.39 ms单个短问题 P9513.92 ms7.79 ms50 问题吞吐量146.8 q/s395.0 q/s单个短问题 MLX 峰值分配943.6 MiB687.6 MiB硬件为 M3 Max40 核 GPU、128 GiB 内存。计时包含提示准备、tokenization、张量构建、GPU 同步推理、校准与结果格式化排除模型加载50 问题吞吐量使用batch_size64公开 API 默认 16。不同长度、问题数量与运行条件都会改变延迟完整方法与每个计时样本见 BENCHMARKS.md。移植一致性三个检查点在 FP32 与 FP16 下均通过 63/63 验证问题的上游 argmax 对齐合计 378/378 次比较每个配置各执行 100 次重复调用结果有限、确定实测活跃内存增长为零。这验证的是移植保真度不代表所有实际问题都能答对——模型能力与限制来自上游。需要特别区分两个数字13.4 / 7.4 ms 来自单问题 API 基准而贪吃蛇 demo 的每帧会批量回答三个问题帧耗时另有独立的 docs/SNAKE_BENCHMARKS.md 报告。README 顶部那张 GIF 就是真实本地运行的原速回放每一步都调用 Laya界面同时显示循环路径安全层及其接管次数。安装与运行环境要求Apple Silicon Mac本机实测环境M3 Max40 核 GPU128 GB 内存macOS 14Python 3.11实测 Python 3.12.13MLX 0.32.2pyproject.toml中约束为mlx0.32.2,0.33仅 darwin/arm64实测 MLX 0.32.2 提供 macOS 14 / 15 / 26 的 wheel本机选择了 26 构建旧系统未在这台机器上实测。方式一PyPI 安装推荐pip install laya-mlx方式二源码开发安装gh repo clone mizorewww/laya-mlx cd laya-mlx uv sync uv run python examples/quickstart.pyuv sync会按 pyproject.toml 解析依赖模型权重单独下载不进入 Git 仓库。若需运行贪吃蛇 demo则要安装demoextrapip install laya-mlx[demo] hf download aac6fef/laya-multilingual-mlx laya-snakehf download提前下载一次权重游戏运行期间完全本地推理。终端至少需要104 列 × 35 行空格暂停、↑/↓ 调速、R 重开、Q 退出。--max-speed持续满速运行每一步都等待新的模型结果。laya-snake --optimize --max-speed启用经过验证的编译与前缀复用路径在同轮成对测试中2,400 步达到75.40 步/秒零死亡、安全接管 2 次比 eager 基线快约6.5%。完整游戏表现、优化测量与一致性证据见 docs/SNAKE_OPTIMIZATION.md。命令行预测命令行支持文本或 JSON 状态输入问题定义从 JSON 文件读取格式见 examples/questions.jsonuv run laya-mlx predict \ --model aac6fef/laya-multilingual-mlx \ --state 发票被重复扣款请退款。 \ --questions examples/questions.json也可用--state-file examples/state.json传入 JSON 状态examples/state.json 展示了from / subject / body的邮件结构与email_questions预置配合。CLI 入口定义在 laya_mlx/cli.py--state与--state-file互斥且必选其一--questions必填另有--dtype默认float16、--devicegpu/cpu、--batch-size默认 16、--subfolder、--revision。若权重已下载在本地把--model改成相应本地目录如models/下的路径即可避免再次下载。转换权重从上游检查点导出 MLX 格式uv run laya-mlx convert \ --model convaiinnovations/laya \ --dtype float16 \ --output models/laya-mlx-fp16转换后可直接用laya.load(./models/laya-mlx-fp16)加载。输出目录包含model.safetensors、编码器与 agent 配置、tokenizer 文件以及mlx_config.json。注意两点已有目录不会被覆盖模型权重不会提交到 GitHub原始检查点本身存储的就是 FP16 权重这里的转换只是调整参数命名与计算精度不是量化也不涉及重新训练。选择 FP32 提高的是算术精度而不是源权重的存储精度。转换命令的具体参数解析与convert调用链见 laya_mlx/cli.py。多语言路由与预置问题上游路由的核心教训是英文检查点在非英语输入上不是温和退化而是近乎崩溃——例如在 20 选项的 MASSIVE intent 上对印地语得分 0.100、韩语 0.103随机猜测为 0.050且报出高置信度ECE 0.855。因此脚本检测是第一路由信号。from laya_mlx import Router, triage_questions router Router(dtypefloat16, max_loaded2) result router.predict({message: 发票被重复扣款请退款。}, triage_questions()) print(result[routing]) # multilingualRouterlaya_mlx/router.py默认管理三个检查点english、multilingual、typed-decisions三者合计约 1.16B 参数。路由优先级为显式model 显式task 检测到的工作流需auto_task_detectionTrue显式开启 显式lang 脚本/语言检测 默认值。max_loaded限制常驻模型数量超出时按 LRU 驱逐。冷加载耗时数秒而语言检测只需微秒级因此交替使用多语言的服务建议Router(preloadTrue)一次性驻留全部三个模型或router.preload([english, multilingual])只驻留所需两个attach(name, agent)把进程里已构建的Agent登记给路由器避免重复加载同一份 421M 参数unload()/loaded释放一个或全部模型、查看当前常驻列表tasktyped_decisions显式选择 typed-decisions 检查点。该检查点针对四个合成工作流微调永远不会被自动选中除非你显式开启auto_task_detectionTrue或传入tasktyped_decisions或问题 ID 集合与某个工作流签名完全匹配精确集合匹配见_TYPED_DECISION_WORKFLOWS——这是刻意的设计避免它成为静默默认值。Router.predict的返回在system_one结果基础上追加routing字段包含model、repo、reason与detection信息。预置问题函数laya_mlx/presets.py覆盖常见生产场景均可直接传入predict函数场景含问题triage_questions()客服工单分诊intent(choice)、is_urgent(noul)、frustration(score)、refund_requested(noul)、churn_risk(noul)email_questions()入站邮件分诊与威胁过滤category(choice)、is_spam、is_phishing、urgency(score)、needs_replyguard_questions()LLM 输入护栏jailbreak、prompt_injection、sensitive_data、harm_severity(score)、topic(choice)moderation_questions()内容安全与审核toxic、harassment、threat、spam、severity(score)router_questions()智能模型路由difficulty(score)、domain(choice)、needs_tools(noul)、is_sensitive(noul)此外 laya_mlx/email.py 提供clean_email_body、email_statelaya_mlx/lang.py 提供detect_language、detect_script、is_english全部在 laya_mlx/init.py 中统一导出__version__为 0.1.0。测试与 benchmark完整复现链路单元测试使用小型随机模型并包含与 Transformers 及固定版本上游决策头的直接对比fixture 见 tests/conftest.py真实检查点验证则覆盖 tokenization、logits、校准概率、重复输出与活跃内存增长。完整复现流程uv sync --extra dev --extra reference --extra benchmark --extra demo source .venv/bin/activate gh repo clone NandhaKishorM/laya .upstream git -C .upstream checkout 6a5819129eb220570792e417e49723d697efd76f pytest -q python -m benchmarks.download python -m benchmarks.validate --repeats 100 python -m benchmarks.run --iterations 50 --warmup 5 python -m benchmarks.accuracy --per-class 64 python -m benchmarks.reportGPU 测试应串行运行。benchmark 在每个新进程中运行各后端/检查点并把全部计时样本写入 benchmarks/results原始数据都在这里含 FP16/FP32 的 P50/P95、吞吐量、内存、数值一致性、重复运行与固定抽样分类测试。pytest中的 integration 标记需要已下载的真实检查点对应 pyproject.toml 中的integrationmarker。GitHub Actions 只在 macOS arm64 runner 上跑小模型 CPU 测试完整检查点的 GPU benchmark 是本地测量不属于托管 CI。关于“再快 10 倍”的性能研究结论仓库还附有两份面向“能否再快一个数量级”的深入报告均基于本地实测而非推测docs/PERFORMANCE_RESEARCH.md初步性能研究分析实现瓶颈、MLX kernel 派发与受控实验计划docs/MATH_10X_RESEARCH.md数学分析——计算预算、带宽条件下界、真实权重谱、精确复用以及蒸馏学生模型的设计空间docs/ENGINEERING_10X_RESEARCH.md工程实测——编译、量化、最后一层输出裁剪、自定义 Metal 核与代表性矩阵乘法实验。experiments/ 目录保存研究脚本与原始数据各实验变体的耗时与数值一致性单独记录。目前证据不支持在相同检查点下普遍再快 10 倍部分场景的逐轮配对中位加速约为 1.03–1.08 倍误差区间、量化保真结果与自定义 Metal 核的实测详见工程报告——这本身就是一份克制且严谨的结论。小结Laya-MLX 用“单次前向传播 三类结构化问题”把本地决策推理的延迟压到毫秒级M3 Max 上单问题端到端中位耗时 13.42 ms英文 421M与 7.39 ms多语言 322M吞吐量分别达 146.8 q/s 与 395.0 q/s且 378/378 次 argmax 对齐验证了移植保真度。它适合工单分诊、邮件分类、LLM 输入护栏、内容审核等需要低延迟、低依赖、完全本地的结构化决策场景。项目采用 Apache-2.0 协议原作者与移植说明见 NOTICE。需要留意的是英文检查点不能替代 multilingual 检查点模型输出概率也不等于答案必然正确——这些限制与上游保持一致。【免费下载链接】laya-mlxNative MLX runtime for Laya typed decision models — 7–14 ms short decisions on M3 Max. No text generation, PyTorch, or cloud API.项目地址: https://gitcode.com/gh_mirrors/la/laya-mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考