【Zig 日报】zigllm：一个用 Zig 编写的 Transformer 架构教学实现

[jiacai2050]

通过用 Zig 语言从零构建大语言模型（LLM），学习其工作原理 —— 从张量（Tensor）到文本生成。

zigllm 是一个用 Zig 编写的 Transformer 架构教学实现。它涵盖了 6 个循序渐进的层级，每一层都建立在上一层的基础上，实现了 18 个模型系列（包括 LLaMA、Mistral、GPT-2、Falcon、Mamba、BERT 等）。每个组件都附带文档，不仅解释“如何实现”，更解释“为什么要这么做”。

同时，它也证明了 Zig 是一种适用于机器学习/人工智能（ML/AI）工作负载的语言 —— 它提供手动内存控制、编译时泛型（comptime）以及一流的 SIMD 支持，且无需运行时或垃圾回收。

为什么选择 zigllm？

• 通过构建来学习 Transformer：循序渐进的架构带你从原始张量操作过渡到完整的文本生成。没有任何“黑盒” —— 每一层都是清晰明确的。
• Zig 助力 ML/AI：编译时计算、SIMD 内联函数以及确定性的内存管理，使 Zig 独特地适用于高性能推理。本项目证明了这一点。
• 阅读真实代码，而非幻灯片：285 多个测试用例充当了可执行的文档。每个测试都演示了一个概念并验证了数学逻辑。

快速开始

git clone https://github.com/Skelf-Research/zigllm.git
cd zigllm
zig build test

前提条件

• Zig 0.14+
• 现代 CPU（推荐支持 AVX/AVX2，但非必须）

架构
zigllm 通过 6 个渐进层级建立理解：
6. 推理 (Inference)：文本生成、采样、KV 缓存、流式输出
5. 模型 (Models)：LLaMA、GPT-2、Mistral、Falcon、GGUF 加载、分词
4. Transformer：多头注意力、前馈网络、完整区块
3. 神经原语 (Neural Primitives)：激活函数 (SwiGLU, GELU)、归一化 (RMSNorm)、RoPE
2. 线性代数 (Linear Algebra)：SIMD 矩阵操作、K-量化、IQ-量化（18 种以上格式）

1. 基础 (Foundation)：张量、内存管理、内存映射

每一层仅依赖于其下方的层级。请从底层开始向上探索。

模型架构
实现了 18 种架构系列，覆盖了约 80% 的实际 LLM 应用：

类别	架构
核心 LLM	LLaMA/LLaMA2, Mistral, GPT-2, Falcon, Qwen, Phi, GPT-J, GPT-NeoX, BLOOM
专用模型	Mamba (状态空间), BERT (双向), Gemma, StarCoder (代码)
高级架构	混合专家模型 (MoE), 多模态 (视觉-语言), BLAS 集成

特性

• 优化：KV 缓存（加速 20 倍）、SIMD 加速（3-5 倍）、18 种以上量化格式（最高减少 95% 内存占用）、内存映射模型加载、批处理。
• 采样：贪婪搜索、Top-k、Top-p、温度调节、Mirostat、典型采样、无尾采样 (Tail-free) 以及对比解码。支持语法约束生成（JSON、正则、CFG）。
• 格式支持：支持加载与 llama.cpp 生态兼容的 GGUF 模型。支持从 10 亿到 700 亿以上参数规模的模型。

文档

路径	你将学到什么
快速概览	整体蓝图
第 1 层：基础	张量与内存
第 2 层：线性代数	SIMD 与量化
第 3 层：神经原语	激活函数与归一化
第 4 层：Transformer	注意力机制与 FFN
第 5 层：模型	LLaMA 架构与 GGUF
第 6 层：推理	生成与优化

测试

zig build test                    # 运行所有 285+ 测试
zig build test-foundation         # 仅测试基础层
zig build test-linear-algebra     # 仅测试线性代数层

示例

示例	描述
examples/simple_demo.zig	端到端概览
examples/educational_demo.zig	逐层深入讲解
examples/benchmark_demo.zig	性能分析
examples/gguf_demo.zig	加载预训练模型
examples/model_architectures_demo.zig	比较 18 种架构

贡献
特别欢迎旨在提高教育价值的贡献：

• 更清晰的解释和文档
• 额外的测试用例和边缘情况处理
• 新模型架构的实现
• 注意力模式和张量操作的可视化工具

请保持代码的可读性 —— 教学上的清晰度优先于微小的性能优化。

许可证
MIT

致谢

• Meta AI —— LLaMA 架构
• Georgi Gerganov / llama.cpp —— 生产级参考
• Zig —— 编程语言本身

加入我们

Zig 中文社区是一个开放的组织，我们致力于推广 Zig 在中文群体中的使用，有多种方式可以参与进来：

1. 供稿，分享自己使用 Zig 的心得
2. 改进 ZigCC 组织下的开源项目
3. 加入微信群、Telegram 群组