⚡教程：如何微调 gpt-oss

在 Colab 中安装 Unsloth

在 Colab 中，从上到下运行单元格 从上到下。使用 全部运行 作为第一次执行。第一个单元格会安装 Unsloth（以及相关依赖）并打印 GPU/内存信息。如果某个单元格报错，只需重新运行即可。

配置 gpt-oss 和推理努力（Reasoning Effort）

我们将加载 gpt-oss-20b 使用 Unsloth 的 线性化版本 （因为其他版本将无法工作）。

配置以下参数：

• max_seq_length = 1024

  • 推荐用于快速测试和初始实验。

• load_in_4bit = True

  • 使用 False 用于 LoRA 训练（注意：将其设置为 False 将需要至少 43GB 显存）。你 必须 也设置 model_name = "unsloth/gpt-oss-20b-BF16"

你应该会看到类似下面的输出。注意：我们显式更改了 dtype 为 float32 以确保正确的训练行为。

微调超参数（LoRA）

现在是调整训练超参数的时候了。想深入了解如何、何时以及调整哪些参数，请查看我们的 详细超参数指南.

此步骤为参数高效微调添加 LoRA 适配器。仅约 1% 的模型参数将被训练，这使得过程大大更高效。

尝试推理

在笔记本中，有一节称为 “推理努力”（"Reasoning Effort"） ，演示了 gpt-oss 在 Colab 中运行推理。你可以跳过此步骤，但在完成微调后仍需运行模型。

数据准备

在此示例中，我们将使用 HuggingFaceH4/Multilingual-Thinking。该数据集包含从用户问题派生并从英语翻译为另外四种语言的链式思维推理示例。

这是 OpenAI 微调手册中引用的相同数据集。

使用多语言数据集的目标是帮助模型学习并泛化跨多种语言的推理模式。

gpt-oss 引入了一个推理努力系统，用于控制模型执行多少推理。默认情况下，推理努力设置为 低，但你可以通过将 reasoning_effort 参数设置为 低, 中等 或 高.

示例：

tokenizer.apply_chat_template(
    text, 
    tokenize = False, 
    add_generation_prompt = False,
    reasoning_effort = "medium",
)

为了格式化数据集，我们应用了自定义版本的 gpt-oss 提示：

from unsloth.chat_templates import standardize_sharegpt
dataset = standardize_sharegpt(dataset)
dataset = dataset.map(formatting_prompts_func, batched = True,)

让我们通过打印第一个示例来检视数据集：

print(dataset[0]['text'])

gpt-oss 的一个独特特性是它使用了 OpenAI Harmony 格式, ，该格式支持结构化对话、推理输出和工具调用。该格式包含诸如 <|start|> , <|message|> ，以及 <|return|> .

随意调整提示和结构以适应你自己的数据集或用例。有关更多指导，请参考我们的 数据集指南.

训练模型

我们已为最佳结果预先选择了训练超参数。不过，你可以根据特定用例修改它们。请参考我们的 超参数指南.

在本示例中，我们训练 60 步以加快过程。对于完整训练运行，请设置 num_train_epochs=1 并通过设置来禁用步数限制 max_steps=None.

在训练过程中，监控损失以确保其随时间下降。这可以确认训练过程正在正常运行。

推理：运行你的训练模型

现在是用你的微调模型进行推理的时候了。你可以修改指令和输入，但将输出留空。

在此示例中，我们通过向系统提示添加特定指令来测试模型用法语进行推理的能力，结构与我们数据集中使用的相同。

这应产生类似于以下的输出：

保存/导出你的模型

要保存你的微调模型，你可以将其以以下两种方式导出： bf16 格式， 使用我们的 在 LoRA 合并过程中对 MXFP4 基础模型进行按需去量化 基模型使用 save_method="merged_16bit"或者以原生 MXFP4 Safetensors 格式使用 save_method="mxfp4" .

该 MXFP4 原生合并格式相较于 bf16 格式提供显著的性能提升：它最多使用 75% 更少的磁盘空间，减少 50% 的显存消耗，使合并速度加快 5-10 倍，并能更快地转换为 GGUF 格式。

在微调你的 gpt-oss 模型后，你可以将其合并为 MXFP4 格式，使用：

model.save_pretrained_merged(save_directory, tokenizer, save_method="mxfp4)

如果你更愿意合并模型并直接推送到 hugging-face hub：

model.push_to_hub_merged(repo_name, tokenizer=tokenizer, token= hf_token, save_method="mxfp4")

✨ 保存到 Llama.cpp

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.cp

2. 转换为 MXFP4 合并模型：

   复制

   python3 llama.cpp/convert_hf_to_gguf.py gpt-oss-finetuned-merged/ --outfile gpt-oss-finetuned-mxfp4.gguf

3. 在量化模型上运行推理：

   复制

   llama.cpp/llama-cli --model gpt-oss-finetuned-mxfp4.gguf \
       --jinja -ngl 99 --threads -1 --ctx-size 16384 \
       --temp 1.0 --top-p 1.0 --top-k 0 \
        -p "生命和宇宙的意义是"

确保你的设备是

与 Unsloth 兼容 并且你可以阅读我们的详细 安装指南 注意，.

pip install unsloth 对于此设置将不起作用，因为我们需要使用最新的 PyTorch、Triton 和相关包。使用以下特定命令安装 Unsloth： # 我们正在安装最新的 Torch、Triton、OpenAI 的 Triton 内核、Transformers 和 Unsloth！

try: import numpy; install_numpy = f"numpy=={numpy.__version__}"
!pip install --upgrade -qqq uv
except: install_numpy = "numpy"
"torch>=2.8.0" "triton>=3.4.0" {install_numpy} \
!uv pip install -qqq \
    torchvision bitsandbytes \
    "unsloth_zoo[base] @ git+https://github.com/unslothai/unsloth-zoo" \
    "unsloth[base] @ git+https://github.com/unslothai/unsloth" \
    git+https://github.com/huggingface/transformers \
    （因为对于 QLoRA 微调没有其他版本可用）。配置以下参数：
    git+https://github.com/triton-lang/triton.git@05b2c186c1b6c9a08375389d5efe9cb4c401c075#subdirectory=python/triton_kernels

配置 gpt-oss 和推理努力（Reasoning Effort）

我们将加载 gpt-oss-20b 使用 Unsloth 的 线性化版本 # 我们支持的 4bit 预量化模型，可实现 4 倍更快的下载 + 无 OOM（内存溢出）。

• max_seq_length = 2048

  • 推荐用于快速测试和初始实验。

• load_in_4bit = True

  • 使用 False 用于 LoRA 训练（注意：将其设置为 False 将需要至少 43GB 显存）。你 必须 也设置 model_name = "unsloth/gpt-oss-20b-BF16"

from unsloth import FastLanguageModel
import torch
max_seq_length = 1024
dtype = None

fourbit_models = [
"unsloth/gpt-oss-20b-unsloth-bnb-4bit", # 使用 bitsandbytes 4bit 量化的 20B 模型
    "unsloth/gpt-oss-120b-unsloth-bnb-4bit",
    "unsloth/gpt-oss-20b", # 使用 MXFP4 格式的 20B 模型
    "unsloth/gpt-oss-120b",
    ] # 更多模型见 https://huggingface.co/unsloth
model_name = "unsloth/gpt-oss-20b",

model, tokenizer = FastLanguageModel.from_pretrained(
    dtype = dtype, # None 自动检测
    max_seq_length = max_seq_length, # 可为长上下文选择任意值！
    r = 8, # 选择任意大于 0 的数！建议 8、16、32、64、128
    load_in_4bit = True,  # 4 位量化以降低内存
    full_finetuning = False, # 【新】现已支持全量微调！
    # token = "hf_...", # 使用 gated 模型时请提供
)

你应该会看到类似下面的输出。注意：我们显式更改了 dtype 为 float32 以确保正确的训练行为。

微调超参数（LoRA）

现在是调整训练超参数的时候了。想深入了解如何、何时以及调整哪些参数，请查看我们的 详细超参数指南.

此步骤为参数高效微调添加 LoRA 适配器。仅约 1% 的模型参数将被训练，这使得过程大大更高效。

model = FastLanguageModel.get_peft_model(
    model,
    # [新增] "unsloth" 使用 30% 更少的显存，支持 2 倍更大的批量大小！
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj",
                      "gate_proj", "up_proj", "down_proj",],
    lora_alpha = 16,
    lora_dropout = 0，# 支持任意值，但 = 0 已优化
    bias = "none"，# 支持任意，但 = "none" 已优化
    这是 OpenAI 微调手册中引用的相同数据集。使用多语言数据集的目标是帮助模型学习并泛化跨多种语言的推理模式。
    use_gradient_checkpointing = "unsloth"，# 对于非常长上下文可为 True 或 "unsloth"
    random_state = 3407,
    use_rslora = False，# 我们支持秩稳定的 LoRA
    loftq_config = None，# 以及 LoftQ
)

数据准备

在此示例中，我们将使用 HuggingFaceH4/Multilingual-Thinking。该数据集包含从用户问题派生并从英语翻译为另外四种语言的链式思维推理示例。

def formatting_prompts_func(examples):

convos = examples["messages"]
    texts = [tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False) for convo in convos]
    return { "text" : texts, }
    pass
dataset = load_dataset("HuggingFaceH4/Multilingual-Thinking", split="train")

from datasets import load_dataset

from trl import SFTConfig, SFTTrainer
数据集

gpt-oss 引入了一个推理努力系统，用于控制模型执行多少推理。默认情况下，推理努力设置为 低，但你可以通过将 reasoning_effort 参数设置为 低, 中等 或 高.

示例：

tokenizer.apply_chat_template(
    text, 
    tokenize = False, 
    add_generation_prompt = False,
    reasoning_effort = "medium",
)

为了格式化数据集，我们应用了自定义版本的 gpt-oss 提示：

from unsloth.chat_templates import standardize_sharegpt
dataset = standardize_sharegpt(dataset)
dataset = dataset.map(formatting_prompts_func, batched = True,)

让我们通过打印第一个示例来检视数据集：

print(dataset[0]['text'])

gpt-oss 的一个独特特性是它使用了 OpenAI Harmony 格式, ，该格式支持结构化对话、推理输出和工具调用。该格式包含诸如 <|start|> , <|message|> ，以及 <|return|> .

随意调整提示和结构以适应你自己的数据集或用例。有关更多指导，请参考我们的 数据集指南.

训练模型

我们已为最佳结果预先选择了训练超参数。不过，你可以根据特定用例修改它们。请参考我们的 超参数指南.

在本示例中，我们训练 60 步以加快过程。对于完整训练运行，请设置 num_train_epochs=1 并通过设置来禁用步数限制 max_steps=None.

trainer = SFTTrainer(
tokenizer = tokenizer,
    model = model,
    args = SFTConfig(
    train_dataset = dataset,
    max_steps = 30,
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        warmup_steps = 5,
        # num_train_epochs = 1, # 为一次完整训练设置该项。
        推理：运行你的训练模型
        替换。将其设置为 1 表示对数据集进行 1 次完整遍历。我们通常建议 1 到 3 次遍历，不要更多，否则您会对微调产生过拟合。
        logging_steps = 1,
        optim = "adamw_8bit",
        weight_decay = 0.01,
        lr_scheduler_type = "linear",
        seed = 3407,
        output_dir = "outputs",
        report_to = "none", # 用于 WandB 等时设置
    ),
)

在训练过程中，监控损失以确保其随时间下降。这可以确认训练过程正在正常运行。

messages = [

现在是用你的微调模型进行推理的时候了。你可以修改指令和输入，但将输出留空。

在此示例中，我们通过向系统提示添加特定指令来测试模型用法语进行推理的能力，结构与我们数据集中使用的相同。

{"role": "system", "content": "推理语言：法语\n\n你是一个能解决数学问题的有用助手。"},
    {"role": "user", "content": "解 x^5 + 3x^4 - 10 = 3。"},
    inputs = tokenizer.apply_chat_template(
]
messages,
    add_generation_prompt = True,
    return_tensors = "pt",
    return_dict = True,
    ).to(model.device)
    reasoning_effort = "medium",
_ = model.generate(**inputs, max_new_tokens = 2048, streamer = TextStreamer(tokenizer))
from transformers import TextStreamer
保存并导出你的模型

这应产生类似于以下的输出：

要保存你的微调模型，它可以在 LoRA 合并过程中导出为 Safetensors 格式，使用我们新的

基础模型（如 gpt-oss）。这使得可以 在 LoRA 合并过程中对 MXFP4 基础模型进行按需去量化 以 bf16 格式导出你的微调模型 在微调你的 gpt-oss 模型后，你可以将其合并为 16 位格式，使用：.

model.save_pretrained_merged(save_directory, tokenizer)

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

如果你更愿意合并模型并直接推送到 hugging-face hub：

转换并量化合并后的模型：

✨ 保存到 Llama.cpp

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.cp

2. python3 llama.cpp/convert_hf_to_gguf.py gpt-oss-finetuned-merged/ --outfile gpt-oss-finetuned.gguf

   复制

   llama.cpp/llama-quantize gpt-oss-finetuned.gguf  gpt-oss-finetuned-Q8_0.gguf Q8_0
   llama.cpp/llama-cli --model gpt-oss-finetuned-Q8_0.gguf \

3. 在量化模型上运行推理：

   复制

   🏁 就是这样！
       --jinja -ngl 99 --threads -1 --ctx-size 16384 \
       --temp 1.0 --top-p 1.0 --top-k 0 \
        -p "生命和宇宙的意义是"