一个教育性开源项目，通过 PyTorch 高层 API 和底层手动实现双轨方式，帮助开发者在消费级硬件上深入理解 GPT-2、Qwen3 等主流大模型架构

Toy-Qwen：在 Apple Silicon 上从零手搓大语言模型\n\n## 项目背景与初衷\n\n大语言模型（LLM）已经深刻改变了自然语言处理领域，但对于许多开发者而言，这些模型仍然像"黑盒"一样神秘。虽然 Hugging Face 等库提供了开箱即用的模型调用接口，但隐藏了底层的实现细节，使得真正理解模型内部机制变得困难。\n\nToy-Qwen 项目正是为了解决这一痛点而诞生的。它的核心目标是让开发者能够在 Apple Silicon（M1/M2/M3 系列芯片）等消费级硬件上，从零开始理解并实现主流的大语言模型架构。项目采用双轨实现策略——既提供可直接运行的 PyTorch 高层 API 版本，也提供完全手写的底层实现版本，让学习者能够逐层深入理解模型的每个组件。\n\n## 支持的模型架构\n\n目前项目已实现或规划支持以下主流架构：\n\n### nano_gpt2（已完成）\n\n基于 GPT-2 架构的轻量级实现，包含以下核心组件：\n\n- 可学习位置嵌入（Learned Positional Embeddings）：让模型自动学习序列中每个位置的最佳表示\n- 多头注意力机制（MHA, Multi-Head Attention）：实现并行的自注意力计算，捕捉不同子空间的语义关系\n- 预层归一化（Pre-LayerNorm）：在注意力层和前馈层之前进行归一化，提升训练稳定性\n- GELU 激活的 MLP：使用高斯误差线性单元替代传统 ReLU，提供更平滑的非线性变换\n\n### nano_qwen3（规划中）\n\n即将实现的 Qwen3 架构，将引入更先进的技术：\n\n- 旋转位置编码（RoPE, Rotary Position Embedding）：通过旋转矩阵注入位置信息，支持更长的上下文\n- 分组查询注意力（GQA, Grouped Query Attention）：在保持性能的同时降低推理时的 KV 缓存需求\n- RMSNorm 归一化：Root Mean Square Layer Normalization，替代 LayerNorm 以提升训练效率\n- SwiGLU MLP：结合 Swish 激活和门控线性单元，增强模型的表达能力\n\n## 双轨实现：torch vs scratch\n\n项目的最大特色在于双轨实现策略：\n\n### torch 版本\n\n使用 PyTorch 的高层 API（如 nn.Linear、nn.MultiheadAttention 等），代码简洁、可直接运行。这个版本适合：\n\n- 快速验证模型架构的正确性\n- 作为基准对比手写实现的输出\n- 理解 PyTorch 框架的设计哲学\n\n### scratch 版本\n\n完全手动实现所有算子，不依赖 PyTorch 的封装。这个版本适合：\n\n- 深入理解注意力机制、归一化层、激活函数等组件的数学原理\n- 学习如何高效实现矩阵运算和梯度计算\n- 为后续自定义 CUDA 内核或移植到其他框架打下基础\n\n两套实现保持接口完全一致，你可以无缝切换，对比它们的输出和行为差异。\n\n## 项目结构解析\n\n\nToy-Qwen/\n├── configs/ # 超参数配置文件\n├── models/\n│ └── layers/\n│ ├── torch/ # PyTorch 参考实现\n│ └── scratch/ # 手动实现版本\n├── optim/\n│ ├── torch/\n│ └── scratch/\n├── data/\n│ ├── raw/ # 原始数据集\n│ ├── cache/ # tokenize 后的二进制缓存\n│ ├── prepare.py # 数据预处理脚本\n│ └── dataset.py # 数据集加载器\n├── utils/ # 工具函数\n├── train.py # 训练脚本\n└── infer.py # 推理脚本\n\n\n这种清晰的模块化设计使得每个组件都可以独立理解和测试。\n\n## 快速上手\n\n### 环境准备\n\n项目要求 Python 3.12+，推荐使用 uv 进行依赖管理：\n\nbash\n# 同步依赖\nuv sync\n\n\n### 数据准备\n\n项目使用 TinyStories 数据集——一个专为小模型设计的儿童故事语料库，大小仅约 470MB，非常适合在笔记本上训练：\n\nbash\nuv run toy-prepare\n\n\nTokenizer 采用 OpenAI 的 tiktoken cl100k_base，与 GPT 系列模型保持一致。\n\n### 训练模型\n\nbash\n# 默认使用 nano_gpt2 + torch 实现，自动检测 MPS/CUDA/CPU\nuv run toy-train\n\n# 切换到手写实现版本\nuv run toy-train --impl scratch\n\n\nApple Silicon 用户可以直接利用 MPS（Metal Performance Shaders）后端进行 GPU 加速训练。\n\n### 推理生成\n\nbash\n# 交互式生成\nuv run toy-infer\n\n# 指定提示词和生成长度\nuv run toy-infer --prompt "Once upon a time" --tokens 300\n\n\n## 教育价值与实践意义\n\nToy-Qwen 不仅仅是一个代码仓库，更是一套完整的学习资源：\n\n1. 渐进式学习路径：从 PyTorch 高层 API 入手，逐步深入到手动实现，降低学习曲线\n\n2. 消费级硬件友好：TinyStories 数据集和轻量级架构设计，让个人开发者无需昂贵 GPU 集群也能完成完整训练\n\n3. 架构对比学习：通过实现 GPT-2 和 Qwen3 两种不同架构，理解大模型技术的演进方向\n\n4. 工程实践训练：项目结构清晰，包含完整的数据处理、训练、推理流程，可作为个人项目的模板\n\n## 适用人群\n\n- 深度学习初学者：想要真正理解 Transformer 架构，而非仅仅调用 API\n- 算法工程师：需要深入模型内部进行优化或定制\n- 教育工作者：寻找适合教学的轻量级 LLM 实现案例\n- Apple Silicon 用户：希望在本地充分利用 M1/M2/M3 芯片进行深度学习实验\n\n## 总结\n\nToy-Qwen 项目以"从零开始理解大模型"为核心理念，通过双轨实现策略和精心设计的架构，为开发者提供了一个在消费级硬件上深入探索 LLM 的绝佳平台。无论你是想夯实理论基础，还是希望获得动手实践经验，这个项目都值得投入时间学习。\n\n随着 nano_qwen3 的即将发布，项目将进一步展示现代大模型架构的前沿技术。对于任何希望真正"看懂"大语言模型的人来说，Toy-Qwen 都是不可多得的学习资源。

Toy-Qwen：在 Apple Silicon 上从零手搓大语言模型\n\n项目背景与初衷\n\n大语言模型（LLM）已经深刻改变了自然语言处理领域，但对于许多开发者而言，这些模型仍然像"黑盒"一样神秘。虽然 Hugging Face 等库提供了开箱即用的模型调用接口，但隐藏了底层的实现细节，使得真正理解模型内部机制变得困难。\n\nToy-Qwen 项目正是为了解决这一痛点而诞生的。它的核心目标是让开发者能够在 Apple Silicon（M1/M2/M3 系列芯片）等消费级硬件上，从零开始理解并实现主流的大语言模型架构。项目采用双轨实现策略——既提供可直接运行的 PyTorch 高层 API 版本，也提供完全手写的底层实现版本，让学习者能够逐层深入理解模型的每个组件。\n\n支持的模型架构\n\n目前项目已实现或规划支持以下主流架构：\n\nnano_gpt2（已完成）\n\n基于 GPT-2 架构的轻量级实现，包含以下核心组件：\n\n- 可学习位置嵌入（Learned Positional Embeddings）：让模型自动学习序列中每个位置的最佳表示\n- 多头注意力机制（MHA, Multi-Head Attention）：实现并行的自注意力计算，捕捉不同子空间的语义关系\n- 预层归一化（Pre-LayerNorm）：在注意力层和前馈层之前进行归一化，提升训练稳定性\n- GELU 激活的 MLP：使用高斯误差线性单元替代传统 ReLU，提供更平滑的非线性变换\n\nnano_qwen3（规划中）\n\n即将实现的 Qwen3 架构，将引入更先进的技术：\n\n- 旋转位置编码（RoPE, Rotary Position Embedding）：通过旋转矩阵注入位置信息，支持更长的上下文\n- 分组查询注意力（GQA, Grouped Query Attention）：在保持性能的同时降低推理时的 KV 缓存需求\n- RMSNorm 归一化：Root Mean Square Layer Normalization，替代 LayerNorm 以提升训练效率\n- SwiGLU MLP：结合 Swish 激活和门控线性单元，增强模型的表达能力\n\n双轨实现：torch vs scratch\n\n项目的最大特色在于双轨实现策略：\n\ntorch 版本\n\n使用 PyTorch 的高层 API（如 nn.Linear、nn.MultiheadAttention 等），代码简洁、可直接运行。这个版本适合：\n\n- 快速验证模型架构的正确性\n- 作为基准对比手写实现的输出\n- 理解 PyTorch 框架的设计哲学\n\nscratch 版本\n\n完全手动实现所有算子，不依赖 PyTorch 的封装。这个版本适合：\n\n- 深入理解注意力机制、归一化层、激活函数等组件的数学原理\n- 学习如何高效实现矩阵运算和梯度计算\n- 为后续自定义 CUDA 内核或移植到其他框架打下基础\n\n两套实现保持接口完全一致，你可以无缝切换，对比它们的输出和行为差异。\n\n项目结构解析\n\n\nToy-Qwen/\n├── configs/ 超参数配置文件\n├── models/\n│ └── layers/\n│ ├── torch/ PyTorch 参考实现\n│ └── scratch/ 手动实现版本\n├── optim/\n│ ├── torch/\n│ └── scratch/\n├── data/\n│ ├── raw/ 原始数据集\n│ ├── cache/ tokenize 后的二进制缓存\n│ ├── prepare.py 数据预处理脚本\n│ └── dataset.py 数据集加载器\n├── utils/ 工具函数\n├── train.py 训练脚本\n└── infer.py 推理脚本\n\n\n这种清晰的模块化设计使得每个组件都可以独立理解和测试。\n\n快速上手\n\n环境准备\n\n项目要求 Python 3.12+，推荐使用 uv 进行依赖管理：\n\nbash\n同步依赖\nuv sync\n\n\n数据准备\n\n项目使用 TinyStories 数据集——一个专为小模型设计的儿童故事语料库，大小仅约 470MB，非常适合在笔记本上训练：\n\nbash\nuv run toy-prepare\n\n\nTokenizer 采用 OpenAI 的 tiktoken cl100k_base，与 GPT 系列模型保持一致。\n\n训练模型\n\nbash\n默认使用 nano_gpt2 + torch 实现，自动检测 MPS/CUDA/CPU\nuv run toy-train\n\n切换到手写实现版本\nuv run toy-train --impl scratch\n\n\nApple Silicon 用户可以直接利用 MPS（Metal Performance Shaders）后端进行 GPU 加速训练。\n\n推理生成\n\nbash\n交互式生成\nuv run toy-infer\n\n指定提示词和生成长度\nuv run toy-infer --prompt "Once upon a time" --tokens 300\n\n\n教育价值与实践意义\n\nToy-Qwen 不仅仅是一个代码仓库，更是一套完整的学习资源：\n\n1. 渐进式学习路径：从 PyTorch 高层 API 入手，逐步深入到手动实现，降低学习曲线\n\n2. 消费级硬件友好：TinyStories 数据集和轻量级架构设计，让个人开发者无需昂贵 GPU 集群也能完成完整训练\n\n3. 架构对比学习：通过实现 GPT-2 和 Qwen3 两种不同架构，理解大模型技术的演进方向\n\n4. 工程实践训练：项目结构清晰，包含完整的数据处理、训练、推理流程，可作为个人项目的模板\n\n适用人群\n\n- 深度学习初学者：想要真正理解 Transformer 架构，而非仅仅调用 API\n- 算法工程师：需要深入模型内部进行优化或定制\n- 教育工作者：寻找适合教学的轻量级 LLM 实现案例\n- Apple Silicon 用户：希望在本地充分利用 M1/M2/M3 芯片进行深度学习实验\n\n总结\n\nToy-Qwen 项目以"从零开始理解大模型"为核心理念，通过双轨实现策略和精心设计的架构，为开发者提供了一个在消费级硬件上深入探索 LLM 的绝佳平台。无论你是想夯实理论基础，还是希望获得动手实践经验，这个项目都值得投入时间学习。\n\n随着 nano_qwen3 的即将发布，项目将进一步展示现代大模型架构的前沿技术。对于任何希望真正"看懂"大语言模型的人来说，Toy-Qwen 都是不可多得的学习资源。