gpt-oss：运行指南

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

OpenAI 发布了“gpt-oss-120b” 和“gpt-oss-20b”，这两个最先进的开放语言模型采用 Apache 2.0 许可证发布。这两个 128k 上下文模型在推理、工具使用和智能体任务上都优于同等规模的开放模型。你现在可以使用 Unsloth 在本地运行并微调它们！

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

微调 免费微调 gpt-oss-20b，使用我们的 Colab 笔记本

使用以下方式训练： 强化学习, gpt-oss-120b 可与 o4-mini 和 gpt-oss-20b 可与 o3-mini 匹敌。两者在函数调用和 CoT 推理方面都表现出色，超越了 o1 和 GPT-4o。

为获得最佳性能，请确保你的总可用内存（统一内存 + 显存 + 系统内存）大于你正在下载的量化模型文件大小。如果没有达到，llama.cpp 仍然可以通过 SSD/HDD 卸载运行，但推理速度会更慢。

gpt-oss - Unsloth GGUF：

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

• 20B： gpt-oss-20B

• 120B： gpt-oss-120B

📜Unsloth 对 gpt-oss 的修复

我们的一些修复已向上游提交到 OpenAI 在 Hugging Face 上的官方模型。 查看

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

推理引擎通常改为使用 jinja 聊天模板，而不是 Harmony 包。我们在直接与 Harmony 比较后发现其中存在一些问题。如果你看下面，上面的是来自 Harmony 的正确渲染形式。下面的是当前 jinja 聊天模板渲染的版本。两者有相当多的差异！

我们还做了一些函数，让你在需要时无需 jinja 聊天模板，也能直接使用 OpenAI 的 Harmony 库——你只需像下面这样解析普通对话：

messages = [
    {"role" : "user", "content" : "1+1 是多少？"},
    {"role" : "assistant", "content" : "2"},
    {"role": "user",  "content": "现在旧金山的温度是多少？明天呢？今天的日期是 2024-09-30。"},
    {"role": "assistant",  "content": "用户问：‘旧金山的天气如何？’ 我们需要使用 get_current_temperature 工具。", "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(
    messages,
    reasoning_effort = "medium",
    add_generation_prompt = True,
    tool_calls = None,
    developer_instructions = None,
    model_identity = "你是 ChatGPT，一个由 OpenAI 训练的大型语言模型。",
)

harmony 格式包含多个有趣的内容：

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

2. developer_instructions 类似于你可以添加的 system prompt。

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

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

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

2. 存在一些 额外的换行 出现在 jinja 模板的一些边界位置。

3. 模型进行工具调用时的思考内容应使用 analysis 标签，而不是 final 标签.

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

我们针对 GGUF、BnB 和 BF16 上传版本以及所有版本的聊天模板都已修复！例如，对比我们的格式和 Harmony 的格式时，我们得到的字符完全没有差异：

🔢 精度问题

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

我们还制作了一个 MXFP4 推理笔记本 可在 Tesla T4 Colab 中使用！

软件模拟 可支持没有原生微缩放操作支持的硬件架构。目前在这种情况下，微缩放的 lhs/rhs 会在点积计算前先提升为 bf16 元素类型，

我们发现如果你将 float16 用作混合精度 autocast 数据类型，一段时间后会出现无穷大。为了解决这个问题，我们发现将 MoE 以 bfloat16 运行，然后保持为 bfloat16 或 float32 精度是可行的。如果旧 GPU 甚至不支持 bfloat16（如 T4），则使用 float32。

我们还会将 float16 机器上的所有运算精度（如路由器）改为 float32。

🖥️ 运行 gpt-oss

下面是该模型 20B 和 120B 变体的指南。

任何比 F16 更小的量化，包括 2-bit，精度损失都很小，因为只有部分模块（例如 attention 层）使用较低位宽，而大多数仍保持全精度。这就是为什么它们的大小与 F16 模型接近；例如，2-bit（11.5 GB）版本的表现几乎与完整 16-bit（14 GB）版本相同。一旦 llama.cpp 支持这些模型的更好量化方式，我们会尽快上传。

这些 gpt-oss 模型来自 OpenAI，并包含一个允许用户调整模型“推理强度”的功能。这使你可以控制模型性能与响应速度（延迟）之间的权衡，具体通过模型用于思考的 token 数量来体现。

这些 gpt-oss 模型提供三个可供选择的不同推理强度级别：

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

• 中：在性能和速度之间取得平衡。

• 高：为需要强推理能力的任务提供最强的推理表现，但会带来更高的延迟。

⚙️ 推荐设置

OpenAI 为这两个模型推荐以下推理设置：

temperature=1.0, top_p=1.0, top_k=0

• Temperature 设为 1.0

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

• Top_P = 1.0

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

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

聊天模板：

<|start|>system<|message|>你是 ChatGPT，一个由 OpenAI 训练的大型语言模型。\n知识截止：2024-06\n当前日期：2025-08-05\n\n推理：medium\n\n# 有效频道：analysis、commentary、final。每条消息都必须包含频道。<|end|><|start|>user<|message|>你好<|end|><|start|>assistant<|channel|>final<|message|>你好！<|end|><|start|>user<|message|>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 上运行该模型。见下文：

你可以通过我们的 Google Colab 笔记本

🦥 Unsloth Studio 指南

在本教程中，我们将使用 Unsloth Studio，这是我们用于运行和训练 LLM 的新 Web UI。通过 Unsloth Studio，你可以在本地于 Mac、Windows和 Linux 上运行模型，并且可以：

• 搜索、下载、 运行 GGUF 和 safetensor 模型

• 比较 模型 并排

• 自愈式 工具调用 + 网页搜索

• 代码执行 （Python、Bash）

• 自动推理 参数调优（temp、top-p 等）

• 训练 LLM 速度提升 2 倍，显存减少 70%

1

安装 Unsloth

MacOS、Linux、WSL：

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell：

irm https://unsloth.ai/install.ps1 | iex

2

设置 Unsloth Studio（一次性）

安装过程会自动安装 Node.js（通过 nvm）、构建前端、安装所有 Python 依赖，并构建带 CUDA 支持的 llama.cpp。

首次安装可能需要 5-10 分钟。这是正常的，因为 llama.cpp 需要编译二进制文件。请不要取消。

WSL 用户： 系统会提示你输入 sudo 密码以安装构建依赖（cmake, git, libcurl4-openssl-dev).

3

启动 Unsloth

MacOS、Linux、WSL、Windows：

unsloth studio -H 0.0.0.0 -p 8888

然后打开 http://localhost:8888 在你的浏览器中。

4

搜索并下载 gpt-oss-20b

首次启动时，你需要创建一个密码来保护你的账户，并在以后再次登录。随后你会看到一个简短的新手引导，用于选择模型、数据集和基本设置。你可以随时跳过它。

然后进入 Studio Chat 标签页，在搜索栏中搜索 gpt-oss，并下载你想要的模型和量化版本。

5

运行 gpt-oss-20b

使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。

如需更多信息，你可以查看我们的 Unsloth Studio 推理指南.

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

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

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 模型相同。

🦥 Unsloth Studio 指南

在本教程中，我们将使用 Unsloth Studio，这是我们用于运行和训练 LLM 的新 Web UI。通过 Unsloth Studio，你可以在本地于 Mac、Windows和 Linux 上运行模型，并且可以：

• 搜索、下载、 运行 GGUF 和 safetensor 模型

• 比较 模型 并排

• 自愈式 工具调用 + 网页搜索

• 代码执行 （Python、Bash）

• 自动推理 参数调优（temp、top-p 等）

• 训练 LLM 速度提升 2 倍，显存减少 70%

1

安装 Unsloth

MacOS、Linux、WSL：

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell：

irm https://unsloth.ai/install.ps1 | iex

2

设置 Unsloth Studio（一次性）

安装过程会自动安装 Node.js（通过 nvm）、构建前端、安装所有 Python 依赖，并构建带 CUDA 支持的 llama.cpp。

首次安装可能需要 5-10 分钟。这是正常的，因为 llama.cpp 需要编译二进制文件。请不要取消。

WSL 用户： 系统会提示你输入 sudo 密码以安装构建依赖（cmake, git, libcurl4-openssl-dev).

3

启动 Unsloth

MacOS、Linux、WSL：

source unsloth_studio/bin/activate
unsloth studio -H 0.0.0.0 -p 8888

Windows PowerShell：

& .\unsloth_studio\Scripts\unsloth.exe studio -H 0.0.0.0 -p 8888

然后打开 http://localhost:8888 在你的浏览器中。

4

搜索并下载 gpt-oss-120b

首次启动时，你需要创建一个密码来保护你的账户，并在以后再次登录。随后你会看到一个简短的新手引导，用于选择模型、数据集和基本设置。你可以随时跳过它。

然后进入 Studio Chat 标签页，在搜索栏中搜索 gpt-oss，并下载你想要的模型和量化版本。

5

运行 gpt-oss-120b

使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。

如需更多信息，你可以查看我们的 Unsloth Studio 推理指南.

📖 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！这实际上允许你将所有非 MoE 层放入 1 张 GPU 中，从而提高生成速度。如果你有更多 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 \

🛠️ 提升生成速度

如果你有更多显存，可以尝试卸载更多 MoE 层，或者直接卸载完整层。

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

如果你的 GPU 内存稍微更多一些，试试 -ot ".ffn_(up|down)_exps.=CPU" 这会卸载 up 和 down projection 的 MoE 层。

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

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

这些 最新的 llama.cpp 版本 还引入了高吞吐模式。使用 llama-parallel。阅读更多相关内容 这里。你还可以 将 KV cache 量化为 4bits 例如以减少显存 / 内存传输，这也能让生成过程更快。

🦥 使用 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 等。

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

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

强化学习（GRPO）

Unsloth 现在支持 gpt-oss 的 RL！我们制作了两个笔记本，更多细节请阅读我们专门针对 gpt-oss RL 的博客： gpt-oss RL

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

💾新功能：gpt-oss 训练后保存到 GGUF、vLLM

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

此前，任何经过 QLoRA 微调的 gpt-oss 模型都只能在 Unsloth 中运行。我们通过引入 按需反量化 MXFP4 基础模型（如 gpt-oss）到 LoRA 合并过程中，移除了这一限制。这使得你可以 将你微调后的模型导出为 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 进行训练。为了克服这一限制，我们通过模拟 Bitsandbytes NF4 量化，专门为 MXFP4 层实现了自定义训练函数。

我们直接使用 OpenAI 的 Triton Kernels 库来支持 MXFP4 推理。然而对于微调 / 训练，MXFP4 内核尚不支持训练，因为反向传播还没有实现。我们正在积极用 Triton 实现它！有一个名为 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 数据集。使用该数据集的目的是让模型能够在这四种不同语言中学习并发展推理能力。