一个专为 Apple Silicon 打造的纯 Rust + Metal 大语言模型推理引擎，零 Python 依赖，支持 GGUF 格式，实现与 llama.cpp 100% 的 token 匹配。

RunIT：从零构建的 Rust + Metal LLM 推理引擎\n\n在 Apple Silicon 上进行大语言模型（LLM）本地推理，通常面临一个两难选择：要么使用 Python 生态（如 PyTorch）带来的繁重依赖，要么使用 llama.cpp 这类 C++ 实现但难以深度定制。RunIT 项目提供了一个全新的解决方案——一个从零开始用纯 Rust 和 Metal 编写的 LLM 推理引擎，专为 macOS 和 Apple Silicon 优化。\n\n## 项目核心理念\n\nRunIT 的最大亮点在于其极简的依赖栈：没有 Python，没有 PyTorch，没有 llama.cpp 依赖。整个引擎完全基于 Rust 语言和 Apple 的 Metal GPU 框架构建。这种设计选择带来了多重优势：更小的二进制体积、更快的启动速度、更直接的硬件控制，以及更易于理解和修改的代码库。\n\n项目开发者通过精心设计的 Metal 着色器和 Rust 调度层，在保持与 llama.cpp 100% token 匹配的同时，实现了具有竞争力的推理速度。\n\n## 性能表现与优化历程\n\nRunIT 的性能演进展示了系统级优化的力量。以 Qwen2.5-0.5B Q8_0 模型在 Apple M4 Pro 上的测试为例：\n\n| 版本 | 优化技术 | 速度 (tok/sec) | 加速比 |\n|------|---------|---------------|--------|\n| v0.0.1 | Kahan GEMV + f32 权重 | 73 | 1.0× |\n| v0.2.0 | simd_sum + half4 + f16 反量化 | 161 | 2.2× |\n| v0.3.0 | 融合 Q8_0 GEMV | 224 | 3.1× |\n| v0.7.0 | 融合 Q4_0 GEMV + 内核融合 | 233 | 3.2× |\n\n最终版本达到了 233 tok/sec 的解码速度，与 llama.cpp 的 230 tok/sec 基本持平，同时保持完全相同的输出质量。\n\n## 关键技术优化\n\nRunIT 实现了一系列先进的 GPU 优化技术：\n\n### 融合量化 GEMV\n\n引擎实现了 fused Q8_0 GEMV 和 fused Q4_0 GEMV 内核，在矩阵向量乘法过程中实时反量化权重，无需中间缓冲区。这使得内存带宽占用降低至 1.06 bytes/element（Q8_0）和 0.56 bytes/element（Q4_0），相比传统的 f16 权重有显著节省。\n\n### 内核融合策略\n\n通过将多个操作融合为单个 GPU 调度，RunIT 大幅减少了 CPU-GPU 通信开销：\n\n- 融合 QKV + 偏置：将 6 次调度合并为每次层 1 次\n- 融合 FFN：将 gate、up 和 SiLU 激活合并为单次调度\n- 融合 RoPE：QK 位置编码合并处理\n\n这些优化将每次前向传播的调度次数从 387 次减少到 242 次。\n\n### SIMD 与向量化\n\n利用 Metal 的 simd_sum() 硬件指令替代传统的 Kahan 求和，将归约操作从 124 步缩减到 1 个周期。同时通过 half4/float4 向量化加载，实现 4 倍更少的内存访问和完美的 256 字节合并访问模式。\n\n## 架构设计与模型支持\n\nRunIT 采用分层架构设计，主要 crate 包括：\n\n- bare-metal-gguf：GGUF 文件解析器，支持内存映射和零拷贝视图\n- bare-metal-tokenizer：HuggingFace tokenizer 封装\n- bare-metal-kernels：Metal 着色器集合和 Rust 调度层\n- bare-metal-engine：模型配置、前向传播、KV 缓存和 HTTP 服务器\n\n目前支持的模型架构包括 Qwen2、Qwen3、LLaMA、Mistral 和 OLMoE（Mixture of Experts）。量化格式方面，原生支持 Q8_0、Q4_0、Q4_K_M、Q5_K、Q6_K、F16 和 BF16，其中 Q8_0 和 Q4_0 实现了 GPU 融合反量化，其他格式通过 CPU 反量化到 f16 处理。\n\n## 精度保障与验证\n\nRunIT 对精度的追求达到了极致。项目文档详细记录了一次关键 bug 的修复过程：RoPE（旋转位置编码）曾错误地使用了交错配对（0,1）、（2,3）...，而非正确的非交错配对（i, i+d/2）。这个 bug 在单 token 测试中难以发现，因为在位置 0 时 RoPE 是恒等变换。只有在位置 ≥ 1 时，错误的配对才会扰乱位置编码，导致多 token 注意力计算错误。\n\n修复后，RunIT 在贪婪解码（temperature=0）下与 llama.cpp 实现了 100% 的 token 匹配。项目提供了详细的逐位置 logits 对比测试，涵盖数学问题、常识问答、翻译和创意写作等多种场景。\n\n## 使用方式与部署\n\nRunIT 提供了两种主要使用方式：\n\n命令行生成工具：\n```bash\n./target/release/generate ~/models/model.gguf \

--tokenizer ~/models/tokenizer.json
--prompt '<|im_start|>user\nHello<|im_end|>'
--tokens 100\n\n\n**OpenAI 兼容 HTTP 服务器**：\nbash\n./target/release/serve ~/models/model.gguf
~/models/tokenizer.json --port 8080\n```\n\n服务器支持标准的 chat completions API，可直接接入现有生态。\n\n## 技术亮点总结\n\nRunIT 代表了 Rust 在 AI 推理领域的一次成功实践。它证明了通过精心设计的底层优化，纯 Rust 实现可以达到与成熟 C++ 方案相当的性能，同时提供更好的内存安全保证和开发体验。项目完全使用 safe Rust 编写，没有任何 unsafe 代码块，这在系统级 AI 软件中尤为难得。\n\n对于希望深入理解 LLM 推理原理、或在 Apple Silicon 上构建定制化 AI 应用的开发者来说，RunIT 不仅是一个可用的工具，更是一个极佳的学习资源。

RunIT：从零构建的 Rust + Metal LLM 推理引擎\n\n在 Apple Silicon 上进行大语言模型（LLM）本地推理，通常面临一个两难选择：要么使用 Python 生态（如 PyTorch）带来的繁重依赖，要么使用 llama.cpp 这类 C++ 实现但难以深度定制。RunIT 项目提供了一个全新的解决方案——一个从零开始用纯 Rust 和 Metal 编写的 LLM 推理引擎，专为 macOS 和 Apple Silicon 优化。\n\n项目核心理念\n\nRunIT 的最大亮点在于其极简的依赖栈：没有 Python，没有 PyTorch，没有 llama.cpp 依赖。整个引擎完全基于 Rust 语言和 Apple 的 Metal GPU 框架构建。这种设计选择带来了多重优势：更小的二进制体积、更快的启动速度、更直接的硬件控制，以及更易于理解和修改的代码库。\n\n项目开发者通过精心设计的 Metal 着色器和 Rust 调度层，在保持与 llama.cpp 100% token 匹配的同时，实现了具有竞争力的推理速度。\n\n性能表现与优化历程\n\nRunIT 的性能演进展示了系统级优化的力量。以 Qwen2.5-0.5B Q8_0 模型在 Apple M4 Pro 上的测试为例：\n\n| 版本 | 优化技术 | 速度 (tok/sec) | 加速比 |\n|------|---------|---------------|--------|\n| v0.0.1 | Kahan GEMV + f32 权重 | 73 | 1.0× |\n| v0.2.0 | simd_sum + half4 + f16 反量化 | 161 | 2.2× |\n| v0.3.0 | 融合 Q8_0 GEMV | 224 | 3.1× |\n| v0.7.0 | 融合 Q4_0 GEMV + 内核融合 | 233 | 3.2× |\n\n最终版本达到了 233 tok/sec 的解码速度，与 llama.cpp 的 230 tok/sec 基本持平，同时保持完全相同的输出质量。\n\n关键技术优化\n\nRunIT 实现了一系列先进的 GPU 优化技术：\n\n融合量化 GEMV\n\n引擎实现了 fused Q8_0 GEMV 和 fused Q4_0 GEMV 内核，在矩阵向量乘法过程中实时反量化权重，无需中间缓冲区。这使得内存带宽占用降低至 1.06 bytes/element（Q8_0）和 0.56 bytes/element（Q4_0），相比传统的 f16 权重有显著节省。\n\n内核融合策略\n\n通过将多个操作融合为单个 GPU 调度，RunIT 大幅减少了 CPU-GPU 通信开销：\n\n- 融合 QKV + 偏置：将 6 次调度合并为每次层 1 次\n- 融合 FFN：将 gate、up 和 SiLU 激活合并为单次调度\n- 融合 RoPE：QK 位置编码合并处理\n\n这些优化将每次前向传播的调度次数从 387 次减少到 242 次。\n\nSIMD 与向量化\n\n利用 Metal 的 simd_sum() 硬件指令替代传统的 Kahan 求和，将归约操作从 124 步缩减到 1 个周期。同时通过 half4/float4 向量化加载，实现 4 倍更少的内存访问和完美的 256 字节合并访问模式。\n\n架构设计与模型支持\n\nRunIT 采用分层架构设计，主要 crate 包括：\n\n- bare-metal-gguf：GGUF 文件解析器，支持内存映射和零拷贝视图\n- bare-metal-tokenizer：HuggingFace tokenizer 封装\n- bare-metal-kernels：Metal 着色器集合和 Rust 调度层\n- bare-metal-engine：模型配置、前向传播、KV 缓存和 HTTP 服务器\n\n目前支持的模型架构包括 Qwen2、Qwen3、LLaMA、Mistral 和 OLMoE（Mixture of Experts）。量化格式方面，原生支持 Q8_0、Q4_0、Q4_K_M、Q5_K、Q6_K、F16 和 BF16，其中 Q8_0 和 Q4_0 实现了 GPU 融合反量化，其他格式通过 CPU 反量化到 f16 处理。\n\n精度保障与验证\n\nRunIT 对精度的追求达到了极致。项目文档详细记录了一次关键 bug 的修复过程：RoPE（旋转位置编码）曾错误地使用了交错配对（0,1）、（2,3）...，而非正确的非交错配对（i, i+d/2）。这个 bug 在单 token 测试中难以发现，因为在位置 0 时 RoPE 是恒等变换。只有在位置 ≥ 1 时，错误的配对才会扰乱位置编码，导致多 token 注意力计算错误。\n\n修复后，RunIT 在贪婪解码（temperature=0）下与 llama.cpp 实现了 100% 的 token 匹配。项目提供了详细的逐位置 logits 对比测试，涵盖数学问题、常识问答、翻译和创意写作等多种场景。\n\n使用方式与部署\n\nRunIT 提供了两种主要使用方式：\n\n命令行生成工具：\n```bash\n./target/release/generate ~/models/model.gguf \

--tokenizer ~/models/tokenizer.json
--prompt '<|im_start|>user\nHello<|im_end|>'
--tokens 100\n\n\n**OpenAI 兼容 HTTP 服务器**：\nbash\n./target/release/serve ~/models/model.gguf
~/models/tokenizer.json --port 8080\n```\n\n服务器支持标准的 chat completions API，可直接接入现有生态。\n\n技术亮点总结\n\nRunIT 代表了 Rust 在 AI 推理领域的一次成功实践。它证明了通过精心设计的底层优化，纯 Rust 实现可以达到与成熟 C++ 方案相当的性能，同时提供更好的内存安全保证和开发体验。项目完全使用 safe Rust 编写，没有任何 unsafe 代码块，这在系统级 AI 软件中尤为难得。\n\n对于希望深入理解 LLM 推理原理、或在 Apple Silicon 上构建定制化 AI 应用的开发者来说，RunIT 不仅是一个可用的工具，更是一个极佳的学习资源。