在 Apple 芯片上用 MLX 从零手写 Qwen3 推理与 vLLM 级服务系统

方案简介

tiny-llm 是一套面向系统工程师的 LLM 推理实战课程，目标是端到端理解推理服务：从加载 Qwen3 模型、把 token 变成 logits，到生成文本的完整路径。它被定位为 CMU Needle 项目的「LLM serving 对应版本」。课程基于 MLX 数组和 MLX 扩展运行时，不使用高层神经网络层；在教某个算子时，学员需用 Python、C++ 或 Metal 自己实现，而不是调用 MLX 的优化算子，MLX 则作为正确性参考和性能基线。课程按四周路径推进：第一周从矩阵乘法到文本生成，第二周加入 KV cache 并做基准驱动的优化，第三周构建迷你 vLLM（连续批处理、分页 KV），第四周构建编程 Agent。适合想在 Apple silicon 单机上理解内存流量、内核占用、KV-cache 增长、批处理与请求调度之间联系的工程师。

亮点与能力

• 从 mlx.core 数组操作直接搭建 Qwen3 模型：attention、RoPE、GQA、RMSNorm、MLP、采样与自回归循环
• 加入 KV cache，并建立同步 MLX 基线，让基准测试决定每一步优化
• 从量化 decode matvec 到融合模型内核、分块 prefill、split-K 等优化
• 引入 continuous batching 与 chunked admission，paged KV 作为规范服务布局
• Decode attention 与 FlashAttention 直接读取页，调度器无需每步重建稠密历史
• 第四周构建一个有界、经过验证的 Agent 循环并连接小型工作区
• Agent 支持检查点恢复、效果回执、上下文压缩、可检查暂停与确定性结果评估
• 覆盖 Qwen3 的 GQA、QK normalization、BF16 激活与 4-bit 权重等现代服务特征

组成与分工

• MLX：提供数组操作与扩展运行时，是整个课程的基座；不使用其高层网络层，仅作为正确性 oracle 与性能基线
• Metal：学员实现算子的目标内核后端之一，配合 C++ 编写自定义内核
• Qwen3 / Qwen3-4B：课程使用的目标模型，规模足以暴露真实的权重带宽、注意力与缓存成本，又可在本地迭代
• pdm：Python 项目管理与环境安装、测试执行入口
• tiny_llm / tiny_llm_ref：学员实现练习的包，以及供测试与基准附录使用的参考实现
• Discord：课程社区交流渠道

前置要求

本方案要求 Apple silicon 硬件：

• Apple 芯片（统一内存空间、可直接访问 Metal 内核），无需昂贵的 CUDA GPU 配置
• Python 环境与包管理器 pdm
• Qwen3-4B 模型（含 GQA、QK 归一化、BF16 激活、4-bit 权重）

环境验证命令（材料原文）：

bash
pdm install -v
pdm run check-installation
pdm run test-refsol -- -- -k week_1

使用与配置要点

• 课程教材发布于 skyzh.github.io/tiny-llm，章节顺序见 book/src/SUMMARY.md
• 学员在 tiny_llm 包中实现练习，tiny_llm_ref 供测试与基准对照
• 每章完成后用 pdm run test-refsol 跑测试，用基准决定优化取舍
• Roadmap 表格用 Code/Test/Doc/Audit 四列追踪实现、测试、文档渲染与作者审阅状态
• 第四周运行 Agent 循环前应使用一次性工作区（不含密钥），并先阅读 Week 4 概览

注意事项与常见问题

• 未覆盖的主题包括：量化/压缩 KV cache、跨请求前缀缓存、微调、长上下文技术
• Week 2 起的章节 Audit 列多为 🚧，即作者对已发布内容的编辑审校仍在进行
• Week 4 采用逐个发布经审阅 checkpoint 的方式，Day 1–9 目前对学员可用
• Day 3 可读取文件内容、经批准后修改文件并运行一条精确配置的命令，需注意工作区安全

优缺点

• ✓ 单机统一内存即可完成
• ✓ 贴近真实模型服务工作负载
• ✕ 依赖 Apple 硬件环境
• ✕ 不覆盖 CUDA GPU 路径

出处

本方案挖掘自开源项目 skyzh/tiny-llm，方案内容与实施命令均来自其 README 原文。