gpt-oss-20B

当 OpenAI「开源」一座大模型的内部构造

2019年，OpenAI 发布了 GPT-2，彼时它被形容为「太过危险而不宜公开」。五年后，OpenAI 再次踏入开源领地，带来了 GPT-OSS 家族——GPT-OSS-20B 和 GPT-OSS-120B。区别于 GPT-2 的简单堆叠，GPT-OSS 是一个融合了当代 LLM 领域几乎所有顶尖工程技巧的庞然大物。

然而，大多数人只是在 API 后面调用它，没人知道它内部是怎么运转的。

HamzaElshafie/gpt-oss-20B 这个项目正是来解决这个问题的：作者用纯 PyTorch 从零实现了一遍 GPT-OSS-20B 的所有核心组件，所有代码完全透明，没有任何隐藏的黑箱。对于想真正理解现代大模型工程细节的人来说，这是一个不可多得的教科书级参考实现。

一、GPT-OSS 是什么：OpenAI 的「五年磨一剑」

2025年8月，OpenAI 正式发布 GPT-OSS 系列模型，这是该公司自2019年GPT-2以来首次发布开源权重模型。GPT-OSS-20B 的命名中「OSS」即 Open Source Software，表明 OpenAI 首次将旗下一个完整的大语言模型权重向公众开放。

与 GPT-2 相比，GPT-OSS 采用了大量后来才成熟的架构技术：旋转位置编码（RoPE）、SwiGLU 激活函数、RMSNorm 归一化、群组查询注意力（GQA）等。这些技术分别来自 Llama、Mistral、Gemma 等后来者的实践验证，OpenAI 将它们汇聚到了一起。

GPT-OSS 系列包含两个规模：20B（200亿参数）和 120B（1200亿参数）。两者的核心架构一致，差异主要在于层数和专家数量。20B 模型使用 32 个专家（MoE），每 token 激活其中 4 个；120B 模型则有 128 个专家。两者都采用了 MXFP4 4位量化技术，使得 20B 模型可以在约 11GB 显存中运行，120B 模型可以塞进一张 80GB 的 H100 GPU。

二、为什么需要从零实现一遍

GPT-OSS 的模型权重已经公开在 HuggingFace 上，transformers 库也已经支持直接加载运行。那么这个项目存在的意义是什么？

答案在于理解深度。

当你用 AutoModel.from_pretrained("openai/gpt-oss-20b") 加载模型时，所有底层实现细节都被封装在了高度优化的 CUDA kernel 和编译器优化背后。你知道它「能用」，但不知道它「为什么这样设计」。

gpt-oss-20B 项目则把每一行代码都摊开给你看：RoPE 旋转角度怎么算、YaRN 扩展的三段式缩放策略如何实现、SwiGLU 中 clamping 和残差连接怎么配合、GQA 里 KV cache 的内存布局……这些在官方实现中往往经过极致优化而变得难以阅读的代码，在这里以教学级的清晰度呈现。

这种「白盒」实现对于三类人特别有价值：模型研究者需要理解每个设计决策的原理，AI 工程师需要为自己的应用做定制化修改，学习者需要一份可以逐行调试的参考教材。

三、核心技术解析：从 RoPE 到 MoE

3.1 旋转位置编码（RoPE）与 YaRN 扩展

传统的位置编码（绝对位置编码或相对位置编码）在处理超长上下文时存在外推能力不足的问题。RoPE 通过将位置信息编码为旋转矩阵来解决这一问题：Query 和 Key 向量在每两个维度上组成复数对，通过旋转角度来表示位置信息。

GPT-OSS 使用了 YaRN（Yet another RoPE extensioN） 扩展，这是在标准 RoPE 基础上增加了「NTK-by-parts」缩放策略。核心思想是将旋转频率空间划分为三个区域：低频区域（时钟走得慢，跨越长距离）保持原始 RoPE 不变；高频区域（时钟走得快，处理短距离依赖）使用线性插值；中间区域做混合。这种设计让模型在将上下文窗口从 4,096 tokens 扩展到 131,072 tokens（32倍）时，仍能保持良好的性能。

代码中的 _compute_concentration_and_inv_freq 方法完整实现了这一逻辑：通过 low 和 high 两个截断点将频率空间分区，然后用 ramp 函数生成 0-1 之间的平滑过渡权重，最终将插值和外推策略加权混合。

3.2 RMSNorm：更简洁的归一化

GPT-OSS 弃用了传统的 LayerNorm，转而使用 RMSNorm（Root Mean Square Normalization）。与 LayerNorm 需要计算均值不同，RMSNorm 只计算 RMS（均方根），公式为 output = (x / RMS(x)) * scale。这省去了一个统计均值的操作，在深层网络中累积起来能节省可观的计算量。

3.3 SwiGLU：带有夹断和残差的门控激活

SwiGLU（Swish-Gated Linear Unit）是 Llama 系列推广的一种激活函数变体。它结合了门控机制（类似 LSTM 的门）和 SiLU（Swish）激活函数。GPT-OSS 的实现还增加了两个额外特性：

• Clamping（夹断）：将 SwiGLU 的门控输出限制在 ±7.0 范围内，防止极端值在深层网络中传播时导致数值不稳定。
• 残差连接：在 FFN 输出和输入之间添加残差路径，缓解深层网络的梯度消失问题。

3.4 混合专家（MoE）：稀疏激活的工程实现

混合专家（Mixture-of-Experts） 是 GPT-OSS 实现高效推理的核心技术。20B 模型有 32 个专家，每处理一个 token 时，只激活其中表现最相关的 4 个。这意味着模型拥有 32 个「专家大脑」，但每次只用 4 个，通过一个线性路由器来选择。

路由器的实现是一个简单的线性投影 + TopK 选择：输入激活向量经过路由器得到每个专家的得分，取最高的 4 个专家的加权输出（权重为 softmax 归一化后的分数）作为最终输出。这种稀疏激活策略使得 GPT-OSS-20B 在推理时只激活约 7B 参数（20B * 4/32 = 2.5B，但实际参数量因共享参数更多），同时保持了相当于 20B 级别模型的表示能力。

3.5 GQA + 滑动窗口注意力 + Attention Sinks

群组查询注意力（GQA） 将 Query 头数设为 64 个，而 Key/Value 头数仅为 8 个，即每 8 个 Query 头共享一个 KV 头。这显著降低了 KV cache 的显存占用，同时保持了 Query 侧的表达能力。

在此基础上，GPT-OSS 的注意力层交替使用两种策略：完整上下文注意力和 128-token 滑动窗口注意力（每相邻层交替）。滑动窗口让模型在局部细节上更加专注，而完整上下文注意力层负责捕捉全局依赖关系。

Attention Sinks 是一个学习到的偏置项，被加到 softmax 分母中，相当于告诉注意力机制「对某些 token 可以选择性地忽略」。这在长序列中帮助模型稳定训练和推理，避免所有注意力分散到大量 token 上导致信息稀释。

四、使用体验：透明推理流水线

项目提供了完整的推理脚本 inference.py，核心是 TokenGenerator 类。推理流程分为三个阶段：

初始化阶段：从 HuggingFace 下载 safetensors 格式的模型权重（通过 weights.py 中的 Checkpoint 类处理），加载官方 Harmony tokenizer（来自 openai-harmony 包）。初始化 24 层 KV cache（每层一个 Cache 对象）。

Prefill 阶段：将输入 prompt 转换为 token ID 序列，通过模型前向传播处理整个 prompt，填充 KV cache。

Decoding 阶段：自回归生成下一个 token，每步只需要处理单个新 token（KV cache 提供历史上下文），避免了每次都重新计算完整序列的昂贵操作。

实际运行中，在 RTX 4090 上，200 个 token 的生成约耗时 8.75 秒（Prefill 0.84 秒 + Decoding 7.91 秒）。代码支持 debug_mode 开关，可以逐 token 查看 logprob 和推理时间。

五、局限与思考

这个项目并非没有局限。首先，它是一个参考实现，不是生产级推理引擎。代码没有做 CUDA kernel 融合、KV cache 量化或连续批处理等生产优化。在实际应用中，transformers 库配合 vLLM 或 llama.cpp 的性能会好得多。

其次，权重文件需要额外下载。仓库本身只包含代码，运行前还需要通过 huggingface_hub 下载数十 GB 的模型权重。网络条件不好的用户可能需要较长时间。

第三，MXFP4 量化被有意忽略。官方模型使用 4 位 MXFP4 量化来降低显存占用，但代码中没有实现 MXFP4 解码（weights.py 中提供了 _get_mxfp4_tensor 作为参考，但被标注为「高显存占用版本」）。因此运行时会占用更多显存。

最后，代码库目前仅支持推理，不支持训练或微调。如果你想基于 GPT-OSS 做指令微调或 RLHF，这个仓库无法直接满足需求。

六、行业意义：开源大模型的新范式

GPT-OSS 的发布代表了 OpenAI 策略的一次重要转向。自 2019 年 GPT-2 之后，OpenAI 在开源上几乎一片沉默，GPT-3、GPT-4 均以 API 形式提供服务。而 GPT-OSS 的开源权重发布，意味着 OpenAI 承认：在某些场景下，开源社区的力量可以弥补闭源模型的生态局限性。

对于开源社区而言，GPT-OSS 的意义不止于「又多了一个可用模型」，更在于它的架构设计透明度。传统上，只有拥有大量 GPU 集群的研究团队才能深入研究前沿模型的内部实现；而现在，任何人都可以下载权重，在消费级 GPU 上运行，甚至修改任意组件来做实验。

gpt-oss-20B 项目则将这种透明度推到了极致——不仅模型权重开源，实现细节也完全透明。这为 AI 教育、研究复现和定制化改造提供了前所未有的基础资源。