gpt-oss：如何运行指南

运行并微调 OpenAI 的新开源模型！

OpenAI 发布了 'gpt-oss-120b' 和 'gpt-oss-20b'，这两个在 Apache 2.0 许可下的最先进开源语言模型。两者的 128k 上下文模型在推理、工具使用和代理任务上都超过了同等规模的开源模型。你现在可以使用 Unsloth 在本地运行并微调它们！

运行 gpt-oss-20b运行 gpt-oss-120b微调 gpt-oss

微调 使用我们的免费 Colab 笔记本

训练于 强化学习, gpt-oss-120b 可与 o4-mini 相媲美并且 gpt-oss-20b 可与 o3-mini 相媲美。两者在函数调用和链式思维推理方面表现出色，超越了 o1 和 GPT-4o。

为了获得最佳性能，请确保你的总可用内存（统一内存 + 显存 + 系统内存）超过你要下载的量化模型文件大小。如果不足，llama.cpp 仍可以通过 SSD/HDD 进行卸载运行，但推理会更慢。

gpt-oss - Unsloth GGUF：

包含 Unsloth 的 聊天模板修复。为了获得最佳效果，请使用我们的上传并用 Unsloth 训练！

• 20B： gpt-oss-20B

• 120B： gpt-oss-120B

📜Unsloth 对 gpt-oss 的修复

我们的一些修复已被推送到 Hugging Face 上 OpenAI 的官方模型。 GLM 4.7 的工具调用

OpenAI 发布了一个独立的解析与分词库，称为 Harmony ，它允许将对话分词为 OpenAI 为 gpt-oss 推荐的格式。

推理引擎通常使用 jinja 聊天模板而不是 Harmony 包，我们在直接与 Harmony 比较后发现了一些问题。下方如果有显示，上方是来自 Harmony 的正确渲染形式。下方是当前 jinja 聊天模板渲染的结果。两者有不少差异！

我们还提供了一些函数，允许你直接使用 OpenAI 的 Harmony 库而不使用 jinja 聊天模板——如果你愿意，你可以像下面那样直接解析普通对话：

messages = [
    {"role" : "user", "content" : "What is 1+1?"},
    {"role" : "assistant", "content" : "2"},
    {"role": "user",  "content": "What's the temperature in San Francisco now? How about tomorrow? Today's date is 2024-09-30."},
    {"role": "assistant",  "content": "User asks: 'What is the weather in San Francisco?' We need to use get_current_temperature tool.", "thinking" : ""},
    {"role": "assistant", "content": "", "tool_calls": [{"name": "get_current_temperature", "arguments": '{"location": "San Francisco, California, United States", "unit": "celsius"}'}]},
    {"role": "tool", "name": "get_current_temperature", "content": '{"temperature": 19.9, "location": "San Francisco, California, United States", "unit": "celsius"}'},
]

然后使用 encode_conversations_with_harmony 来自 Unsloth 的函数：

from unsloth_zoo import encode_conversations_with_harmony

def encode_conversations_with_harmony(
    def unsloth_inference(
    reasoning_effort = "medium",
    add_generation_prompt = True,
    tool_calls = None,
    developer_instructions = None,
    model_identity = "You are ChatGPT, a large language model trained by OpenAI.",
)

Harmony 格式包含多个有趣的要素：

1. reasoning_effort = "medium" 你可以选择 low、medium 或 high，这会改变 gpt-oss 的推理预算——通常越高模型的准确性越好。

2. developer_instructions 类似于你可以添加的系统提示。

3. model_identity 最好保持不变——你可以编辑它，但我们不确定自定义的是否能正常工作。

我们发现当前的 jinja 聊天模板存在多个问题（生态系统中存在多个实现）：

1. 函数和工具调用使用 tojson进行渲染，这在作为字典时没问题，但如果它是字符串，引用符号和其他 符号会被转义为反斜杠.

2. 在某些边界处，jinja 模板中存在一些 额外的换行 。

3. 模型的工具调用思路（tool calling thoughts）应该具有 analysis 标签，而不是 final 标签.

4. 其他聊天模板似乎根本没有使用 <|channel|>final ——应该将其用于最终的助手消息。你不应将其用于思考痕迹或工具调用。

我们的 GGUF 聊天模板、我们的 BnB 和 BF16 上传以及所有版本都已修复！例如，当比较我们与 Harmony 的格式时，我们没有不同的字符：

🔢 精度问题

我们在 Tesla T4 和 float16 机器上发现了多个精度问题，主要是因为模型使用 BF16 训练，因此存在异常值和溢出。MXFP4 在 Ampere 及更老的 GPU 上实际上并不受支持，所以 Triton 为 MXFP4 矩阵乘法提供了 tl.dot_scaled 。它会在内部动态地将矩阵上采样为 BF16。

我们制作了一个 MXFP4 推理笔记本 ，也在 Tesla T4 的 Colab 中！

软件仿真 使得在没有本地微缩操作原生支持的硬件架构上也能运行。对于这种情况，微缩的 lhs/rhs 会先被上采样为 bf16 元素类型以进行点乘计算，

我们发现如果将 float16 用作混合精度自动转换的数据类型，经过一段时间会出现无穷值。为了解决这个问题，我们发现可以将 MoE 用 bfloat16 处理，然后保留为 bfloat16 或 float32 精度。如果较旧的 GPU 甚至不支持 bfloat16（例如 T4），则使用 float32。

我们还将所有操作（例如路由器）的精度对于 float16 机器改为 float32。

🖥️ 运行 gpt-oss

下面是关于该 20B 和 120B 模型的不同变体。

任何低于 F16 的量化（包括 2 位）对准确性损失极小，因为只有某些部分（例如注意力层）是较低位数，而大多数仍保持全精度。这就是大小与 F16 模型接近的原因；例如 2 位（11.5 GB）版本的性能几乎与完整 16 位（14 GB）版本相同。一旦 llama.cpp 为这些模型支持更好的量化，我们会尽快上传它们。

最新的 gpt-oss OpenAI 的模型包含一个功能，允许用户调整模型的“推理努力”设置。这让你可以在模型性能与响应速度（延迟）之间做权衡，即模型用于“思考”的 token 数量。

最新的 gpt-oss 模型提供三种不同级别的推理努力可供选择：

• 低：针对需要非常快速响应且不需要复杂多步推理的任务进行优化。

• 中：在性能与速度之间的平衡。

• 高：为需要更强推理能力的任务提供最强的推理性能，但这会导致更高的延迟。

⚙️ 推荐设置

OpenAI 建议对两款模型使用以下推理设置：

temperature=1.0, top_p=1.0, top_k=0

• 温度为 1.0

• Top_K = 0（或尝试 100 以获得可能更好的结果）

• Top_P = 1.0

• 推荐最小上下文：16,384

• 最大上下文长度窗口：131,072

聊天模板：

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.\nKnowledge cutoff: 2024-06\nCurrent date: 2025-08-05\n\nReasoning: medium\n\n# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|><|start|>user<|message|>Hello<|end|><|start|assistant<|channel|>final<|message|>Hi there!<|end|><|start|>user<|message|>What is 1+1?<|end|><|start|>assistant

句末/生成结束标记：EOS 是 <|return|>

运行 gpt-oss-20B

要使我们的动态 4-bit 量化达到每秒 6+ token 的推理速度，请至少具备 14GB 统一内存 （显存与内存合计）或 仅 14GB 系统内存 。作为经验法则，你的可用内存应与所用模型的大小相匹配或超过它。GGUF 链接： unsloth/gpt-oss-20b-GGUF

注意： 模型可以在低于其总体大小的内存上运行，但这会降低推理速度。最大内存仅在需要最快速度时才需要。

遵循 上述最佳实践。它们与 120B 模型相同。

你现在可以在 Google Colab、Docker、LM Studio 或 llama.cpp 上运行该模型。见下文：

你可以使用我们的免费运行 gpt-oss-20b 的 Google Colab 笔记本

🐋 Docker：运行 gpt-oss-20b 教程

如果你已经安装了 Docker 桌面，只需运行下面的命令即可：

docker model run hf.co/unsloth/gpt-oss-20b-GGUF:F16

✨ Llama.cpp：运行 gpt-oss-20b 教程

1. 获取最新的 llama.cpp 在 此处的 GitHub。您也可以按照下面的构建说明进行。若 -DGGML_CUDA=ON 更改为 -DGGML_CUDA=OFF 如果您没有 GPU 或仅想要在 CPU 上进行推理。 对于 Apple Mac / Metal 设备，设置 -DGGML_CUDA=OFF 然后照常继续 - Metal 支持默认启用。

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

1. 你可以直接通过 Hugging Face 拉取：

   ./llama.cpp/llama-cli \
       -hf unsloth/gpt-oss-20b-GGUF:F16 \
       --jinja -ngl 99 --ctx-size 16384 \
       --temp 1.0 --top-p 1.0 --top-k 0

2. 通过以下方式下载模型（在安装 pip install huggingface_hub hf_transfer ）。如果下载卡住，请参见 Hugging Face Hub、XET 调试

# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/gpt-oss-20b-GGUF",
    local_dir = "unsloth/gpt-oss-20b-GGUF",
    allow_patterns = ["*F16*"],
)

运行 gpt-oss-120b：

要使我们的 1-bit 量化达到每秒 6+ token 的推理速度，我们建议至少具备 66GB 统一内存 （显存与内存合计）或 66GB 系统内存 。作为经验法则，你的可用内存应与所用模型的大小相匹配或超过它。GGUF 链接： unsloth/gpt-oss-120b-GGUF

注意： 模型可以在低于其总体大小的内存上运行，但这会降低推理速度。最大内存仅在需要最快速度时才需要。

遵循 上述最佳实践。它们与 20B 模型相同。

📖 Llama.cpp：运行 gpt-oss-120b 教程

对于 gpt-oss-120b，我们将专门使用 Llama.cpp 进行优化推理。

如果你想要一个 全精度未量化版本，请使用我们的 F16 版本！

1. 获取最新的 llama.cpp 在 此处的 GitHub。您也可以按照下面的构建说明进行。若 -DGGML_CUDA=ON 更改为 -DGGML_CUDA=OFF 如果您没有 GPU 或仅想要在 CPU 上进行推理。

   apt-get update
   apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
   git clone https://github.com/ggml-org/llama.cpp
   cmake llama.cpp -B llama.cpp/build \
       -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
   cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-gguf-split
   cp llama.cpp/build/bin/llama-* llama.cpp

2. 你可以直接使用 llama.cpp 下载该模型，但我通常建议使用 huggingface_hub 要直接使用 llama.cpp，请执行：

   ./llama.cpp/llama-cli \
       -hf unsloth/gpt-oss-120b-GGUF:F16 \
       --ctx-size 16384 \
       --n-gpu-layers 99 \
       -ot ".ffn_.*_exps.=CPU" \
       --temp 1.0 \
       --min-p 0.0 \
       --top-p 1.0 \
       --top-k 0.0 \

3. 或者，在安装后通过以下方式下载模型（ pip install huggingface_hub hf_transfer ）。你可以选择 UD-Q2_K_XL 或其他量化版本。

   # !pip install huggingface_hub hf_transfer
   import os
   os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0" # 有时会有限速，因此设为 0 以禁用
   from huggingface_hub import snapshot_download
   snapshot_download(
       repo_id = "unsloth/gpt-oss-120b-GGUF",
       local_dir = "unsloth/gpt-oss-120b-GGUF",
       allow_patterns = ["*F16*"],
   )

4. 以对话模式运行模型并尝试任何提示。

5. 编辑 --threads -1 用于设置 CPU 线程数， --ctx-size 262114 用于上下文长度， --n-gpu-layers 99 用于指定将多少层卸载到 GPU。若 GPU 出现内存不足，请尝试调整它。若仅使用 CPU 推理，请移除此项。

使用 -ot ".ffn_.*_exps.=CPU" 以将所有 MoE 层卸载到 CPU！这实际上允许你在 1 张 GPU 上放置所有非 MoE 层，从而提高生成速度。如果你有更多 GPU 容量，可以自定义正则表达式以适配更多层。更多选项在 这里.

./llama.cpp/llama-cli \
    --model unsloth/gpt-oss-120b-GGUF/gpt-oss-120b-F16.gguf \
    --ctx-size 16384 \
    --n-gpu-layers 99 \
    -ot ".ffn_.*_exps.=CPU" \
    --temp 1.0 \
    --min-p 0.0 \
    --top-p 1.0 \
    --top-k 0.0 \

🛠️ "content": [{"type": "text", "text": "用 Python 创建一个 Fibonacci 函数并求 fib(20)。"}],

如果你有更多显存，可以尝试卸载更多 MoE 层，或将整个层本身卸载（offload）。

通常， -ot ".ffn_.*_exps.=CPU" 会将所有 MoE 层卸载到 CPU！这实际上允许你将所有非 MoE 层放在一块 GPU 上，从而提高生成速度。如果你有更多 GPU 容量，可以自定义正则表达式以适配更多层。

如果你有稍多的 GPU 内存，尝试 -ot ".ffn_(up|down)_exps.=CPU" 这会卸载上投影和下投影的 MoE 层。

尝试 -ot ".ffn_(up)_exps.=CPU" 如果你有更多的 GPU 内存。这只会卸载上投影的 MoE 层。

你也可以自定义正则表达式，例如 -ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU" 表示从第 6 层起卸载 gate、up 和 down 的 MoE 层。

最新的 llama.cpp 版本 还引入了高吞吐量模式。使用 llama-parallel。在此处阅读更多内容 这里。你也可以 例如将 KV 缓存量化为 4 bit 将 KV 缓存量化为 4 位

🦥 使用 Unsloth 微调 gpt-oss

8 月 28 日 更新: 你现在可以将 QLoRA 微调的 gpt-oss 模型导出/保存为 llama.cpp、vLLM、HF 等格式。

我们还引入了 Unsloth 弹性注意力（Flex Attention） ，它实现了 >8× 更长的上下文长度, >50% 更少的显存使用 和 >1.5× 更快的训练速度 相较于所有实现。 在此处阅读更多

Unsloth 的 gpt-oss 微调速度快 1.5 倍，使用 70% 更少的显存，并支持 10 倍更长的上下文长度。gpt-oss-20b 的 QLoRA 训练可在 14GB 显存上运行，gpt-oss-120b 可在 65GB 显存上运行。

• QLoRA 要求： gpt-oss-20b = 14GB 显存 • gpt-oss-120b = 65GB 显存。

• BF16 LoRA 要求： gpt-oss-20b = 44GB 显存 • gpt-oss-120b = 210GB 显存。

阅读我们逐步的 gpt-oss 微调教程：

教程：如何微调 gpt-oss

你现在可以将 QLoRA 微调的 gpt-oss 模型导出/保存为 llama.cpp、vLLM、HF 等格式。

免费的 Unsloth 笔记本用于微调 gpt-oss：

• gpt-oss-20b 推理 + 会话 笔记本

强化学习（GRPO）

Unsloth 现已支持 gpt-oss 的强化学习！我们制作了两个笔记本，更多细节请阅读我们关于 gpt-oss 强化学习的专门博客： gpt-oss RL

2048 笔记本 （OpenAI 官方示例）	核生成笔记本

💾新增：在 gpt-oss 训练后保存为 GGUF、vLLM

你现在可以对 gpt-oss 进行 QLoRA 微调后直接保存、导出或合并模型到 llama.cpp, vLLM，或 HF ——不仅限于 Unsloth。我们希望很快发布一个免费笔记本。

之前，任何 QLoRA 微调的 gpt-oss 模型都仅限于在 Unsloth 中运行。我们通过引入 在 LoRA 合并过程中按需对 MXFP4 基模型（如 gpt-oss）进行去量化 ，移除了该限制。这使得可以 以 bf16 格式导出你微调后的模型.

微调你的 gpt-oss 模型后，你现在可以用一个 单一命令:

model.save_pretrained_merged(save_directory, tokenizer)

如果你更愿意合并模型并直接推送到 Hugging Face hub，也可以使用：

model.push_to_hub_merged(repo_name, tokenizer=tokenizer, token=hf_token)

💡 使高效的 gpt-oss 微调可行

我们发现虽然 MXFP4 高度高效，但它本身并不原生支持与 gpt-oss 一起训练。为克服此限制，我们实现了专门针对 MXFP4 层的自定义训练函数，通过模仿 Bitsandbytes NF4 量化。

我们直接使用了 OpenAI 的 Triton Kernels 库以支持 MXFP4 推理。然而对于微调/训练，MXFP4 内核尚不支持训练，因为反向传播尚未实现。我们正在积极实现它！有一个名为 W_TRANSPOSE 的标志，如前所述 这里，应当被实现。导数可以通过权重矩阵的转置计算，所以我们必须实现转置操作。

如果你想使用除 Unsloth 以外的任何库来训练 gpt-oss，你需要在训练前将权重上采样为 bf16。然而这种方法会 显著增加 显存使用和训练时间，多达 300% 以上的内存使用增加! 所有其他训练方法在训练 20b 模型时都将需要至少 65GB 显存，而 Unsloth 仅需 14GB 显存（-80%）。

由于两款模型都使用 MoE 架构，20B 模型每个 token 从 32 个专家中选择 4 个，而 120B 模型每个 token 从 128 个专家中选择 4 个。在训练和发布期间，权重以 MXFP4 格式存储为 nn.Parameter 对象，而不是作为 nn.Linear 层存储，这使得量化复杂化，尤其是 MoE/MLP 专家约占 20B 参数中的 19B。

为了启用 BitsandBytes 量化和内存高效的微调，我们将这些参数转换为 nn.Linear 层。尽管这会略微降低操作速度，但它允许在显存受限的 GPU 上进行微调，这是一项值得的权衡。

数据集微调指南

尽管 gpt-oss 仅支持推理能力，你仍可以使用非推理型的 数据集对其进行微调，但这可能会影响其推理能力。如果你想保持其推理能力（可选），可以混合使用直接回答和链式思维示例。至少使用 75% 推理 和 25% 非推理 在您的数据集中，使模型保留其推理能力。

我们的 gpt-oss-20b 会话笔记本使用了 OpenAI 的示例，即 Hugging Face 的 Multilingual-Thinking 数据集。使用该数据集的目的是使模型能够在这四种不同语言中学习并发展推理能力。