tiny-llm

想象你有一台 MacBook M 系列芯片的笔记本，想亲手跑一个 AI 对话模型，却苦于没有 NVIDIA 显卡、不会配置 CUDA 环境。tiny-llm 正是为解决这个问题而生——它用 Apple Silicon 的原生 MLX 框架，让你用纯 Python 手写一个完整的 LLM 推理引擎。

这个项目不依赖任何高级神经网络 API（如 PyTorch 的 nn.Module），所有层——注意力机制、位置编码、归一化、MLP——全部从零用 MLX 底层数组运算实现。作者的目标是：让系统工程师真正理解 vLLM 等生产级推理引擎的内部原理，而不是调调 API 了事。

📖 背景与起源

项目发起人 skyzh（GitHub @skyzh）是一位独立开发者，专注于高性能系统编程。他发现市面上大多数 LLM 学习资料要么是调 API 教程，要么是理论推导，很少有人真正手把手教你怎么实现推理系统——也就是 vLLM、TensorRT-LLM、SGLang 这些生产引擎在做的事。

他选择了 Apple Silicon + MLX 作为教学平台，原因很务实：现在一台 M 系列的 MacBook 比一台带 NVIDIA GPU 的 Linux 工作站更容易获取。MLX 是 Apple 官方为 M 系列芯片设计的机器学习框架，API 简洁，学习曲线平缓，非常适合作为底层原理的教学工具。

图1：项目 Star 增长曲线 — 稳步上升，反映了社区对 LLM 推理工程化学习的强烈需求

🧩 课程体系：3 周从零到生产

课程设计遵循「渐进式复杂度」原则，分三周推进，每周围绕一个核心主题：

第 1 周：LLM 核心算子

用纯 Python + MLX 底层数组 API 从零实现 LLM 的每个组件：

• Scaled Dot-Product Attention：多头注意力的数学原理与 CUDA/WebGPU 实现思路
• RoPE（旋转位置编码）：Qwen3 使用的位置编码方案，理解它如何让模型处理长上下文
• Grouped Query Attention (GQA)：比标准 MHA 更省显存，已被 Qwen2/3/Llama3 广泛采用
• RMSNorm + MLP：轻量级归一化和前馈网络层
• Sampling 解码：Temperature、Top-P、Top-K 采样策略的实现

第 2 周：推理系统工程

这一周开始接近生产系统层面：

• KV Cache：记住已经算过的 token，避免重复计算——这是推理加速的核心
• 量化矩阵乘法：INT4/INT8 量化权重，在 Mac GPU 上高效运行 6B 参数模型
• Flash Attention 2：精确复现 PyTorch 版本的 Flash Attention，理解其在 continuous batching 中的作用
• Continuous Batching：多个请求动态打包到同一个前向传播，充分利用 GPU 并行能力
• Chunked Prefill：将长 prompt 切分，防止 KV Cache 内存峰值

第 3 周：高级主题（进行中）

• Paged Attention：vLLM 的核心创新，将 KV Cache 分页管理，解决内存碎片问题
• Speculative Decoding：用小模型预测、大模型验证的投机解码，显著提升吞吐量
• RAG Pipeline：检索增强生成的技术路径
• AI Agent / Tool Calling：模型调用外部工具的能力

🏗️ 架构设计：双实现对照学习法

这是 tiny-llm 最巧妙的设计：代码仓库中有两套实现并排存在——

你可以在 src/tiny_llm/ 中按教程填空，然后运行 pytest 验证正确性，再用 pytest-benchmark 对比自己的实现和参考实现的性能差距。这种「写代码→测试→基准对比」的学习闭环，比单纯看论文要深刻得多。

底层还有一个 src/extensions/ 目录，通过 nanobind 将 C++ 高性能扩展绑定到 Python，展示了如何用 C++ 编写融合内核（fused kernel）来进一步压榨性能。

图2：作者 skyzh 的 GitHub 头像 — 独立开发者，系统性能优化领域的活跃贡献者

🔧 技术栈全景

⚠️ 局限与挑战

学习门槛不算低：

1. 必须使用 Apple Silicon Mac：MLX 是苹果专属框架，Windows/Linux 用户无法直接使用。虽然课程讲述的原理是通用的，但代码无法在其他平台运行。
2. Python 3.10-3.12 限制：MLX 对 Python 版本有严格要求，较新的 Python 3.13 不兼容。
3. 需要 C++ 编译工具链：src/extensions/ 的高性能内核依赖 clang++，在 macOS 上还需装 Xcode Command Line Tools。
4. 课程未全部完成：第 3 周的部分章节（MoE、Tool Calling 等）仍在施工中。
5. 无 Docker 支持：无法一键部署，必须手动配置环境。

💡 为什么这很重要

2024-2025 年，LLM 推理工程化成为 AI 基础设施最热门的赛道之一。vLLM、SGLang、TensorRT-LLM 等开源推理引擎频繁登上 GitHub Trending，生产环境对「懂推理系统原理」的工程师需求旺盛。但这个领域的学习资料极度匮乏——大多数工程师只会调 API，不理解为什么 continuous batching 能省显存、为什么 Paged Attention 是革命性的。

tiny-llm 用「手写一遍」的笨功夫，把这些知识内化为直觉。对想进入 AI 基础设施领域的系统工程师来说，这是目前门槛最低、最接地气的入门路径之一。