mlxforge：基于Apple MLX从头构建的LLaMA推理引擎

mlxforge是一个用C++在Apple MLX框架上从头构建的LLaMA推理引擎，提供OpenAI兼容的HTTP API和连续批处理功能。它加载原始safetensors权重，在Metal GPU上运行数值正确的transformer前向传播，并通过vLLM风格的单工作线程/三队列调度器为并发用户提供服务。

• 原作者/维护者: hvasconcelos
• 来源平台: GitHub
• 原始标题: mlxforge
• 原始链接: https://github.com/hvasconcelos/mlxforge
• 发布时间: 2026年6月1日

---

在AI推理领域，大多数开发者选择使用现成的框架——vLLM、TensorRT-LLM、llama.cpp等。这些工具经过大量优化，功能丰富，但它们是黑盒。当你需要理解transformer的每个数值敏感阶段，或者需要在Apple Silicon上实现特定优化时，现成的解决方案可能无法满足需求。

mlxforge选择了一条不同的道路：从头开始，用C++在Apple的MLX框架上构建一个完整的LLaMA推理引擎。这不是为了重新发明轮子，而是为了深入理解轮子是如何转动的。

---

mlxforge是一个用C++在Apple MLX框架上从头构建的LLaMA推理引擎，提供：

• OpenAI兼容的HTTP API：/v1/chat/completions、/v1/completions、/v1/models等端点
• 连续批处理：vLLM风格的单工作线程/三队列调度器
• 数值正确性：每个数值敏感阶段都经过mlx-lm金标准验证
• KV缓存：单序列和批处理缓存，支持filter/eviction和merge/admission

目标模型：mlx-community/Llama-3.2-1B-Instruct（默认fp16，可选4-bit量化）

---

mlxforge的核心设计原则之一是数值正确性。前向传播的logits和贪婪token与mlx-lm完全匹配。金标准.npy fixtures作为每个步骤的门控，因为这里的失败模式是静默垃圾输出，而不是崩溃。

这种严格验证确保了：

• 模型行为与参考实现一致
• 调试时可以信任数值结果
• 生产环境的可预测性

mlxforge实现了两种KV缓存模式：

单序列缓存（SingleKVCache）：

• 为单个序列优化的缓存
• 支持left-padded布局
• 256-token块增长策略

批处理缓存（BatchKVCache）：

• 支持多序列批处理
• update_and_fetch：更新并获取缓存状态
• filter：驱逐不需要的token
• merge：接纳新序列
• pad_dummies：处理变长序列

mlxforge采用vLLM风格的连续批处理架构：

• 单GPU工作线程：拥有所有MLX状态，是唯一调用eval/async_eval的线程
• 每解码步骤一个async_eval：整个批次共享一次评估
• 批次大小分桶：确保图形状重复，优化编译

这种设计最大化了GPU利用率，同时保持了代码的简洁性和可维护性。

mlxforge将采样实现为MLX图操作，支持：

• 贪婪采样
• 温度采样
• Top-k采样
• Top-p采样

关键优化：无需将logits读回主机，所有采样操作都在GPU上完成。