教程：如何微调 gpt-oss

在 Colab 中安装 Unsloth

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

配置 gpt-oss 和推理强度

我们将加载 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% 的模型参数会被训练，这使得过程明显更高效。

尝试推理

在笔记本中，有一个名为 “推理强度” 的部分，演示了 gpt-oss 在 Colab 中的推理运行。你可以跳过此步骤，但在微调完成后仍需要稍后运行模型。

数据准备

在此示例中，我们将使用 HuggingFaceH4/Multilingual-Thinking。该数据集包含从用户问题中派生的连贯思路（chain-of-thought）推理示例，这些问题已从英语翻译成另外四种语言。

这是 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 格式， 使用我们的 对 MXFP4 基线模型的按需反量化 功能，使用save_method="merged_16bit" 或以原生 MXFP4 Safetensors 格式使用 .

save_method="mxfp4" 或以原生 原生合并格式与 bf16 格式相比提供显著的性能提升：它最多使用 75% 更少的磁盘空间，减少 50% 的显存消耗，加速合并 5-10 倍，并实现更快的转换为 GGUF 格式。

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

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 上。你也可以按照下面的构建说明。若没有 GPU 或只想使用 CPU 推理，请将 -DGGML_CUDA=ON 更改为 -DGGML_CUDA=OFF 更改为

   复制

   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-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 兼容 ，你可以阅读我们的详细 安装指南 你也可以使用我们的.

Docker 镜像 来安装 Unsloth.

注意， pip install unsloth 对于此设置不起作用，因为我们需要使用最新的 PyTorch、Triton 和相关包。请使用以下特定命令安装 Unsloth：

# 我们正在安装最新的 Torch、Triton、OpenAI 的 Triton 内核、Transformers 和 Unsloth！
!pip install --upgrade -qqq uv
try: import numpy; install_numpy = f"numpy=={numpy.__version__}"
except: install_numpy = "numpy"
!uv pip install -qqq \
    "torch>=2.8.0" "triton>=3.4.0" {install_numpy} \
    "unsloth_zoo[base] @ git+https://github.com/unslothai/unsloth-zoo" \
    "unsloth[base] @ git+https://github.com/unslothai/unsloth" \
    torchvision bitsandbytes \
    git+https://github.com/huggingface/transformers \
    git+https://github.com/triton-lang/triton.git@05b2c186c1b6c9a08375389d5efe9cb4c401c075#subdirectory=python/triton_kernels

配置 gpt-oss 和推理强度

我们将加载 gpt-oss-20b 使用 Unsloth 的 线性化版本 （因为其他版本无法用于 QLoRA 微调）。配置以下参数：

• 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

# 我们支持的 4bit 预量化模型，可实现 4 倍更快的下载并避免 OOM。
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, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/gpt-oss-20b",
    dtype = dtype, # None 表示自动检测
    max_seq_length = max_seq_length, # 为长上下文选择任意值！
    load_in_4bit = True,  # 4 位量化以减少内存
    full_finetuning = False, # [新！] 我们现在支持完全微调！
    # token = "hf_...", # 如果使用受限模型可使用
)

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

微调超参数（LoRA）

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

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

model = FastLanguageModel.get_peft_model(
    model,
    r = 8, # 选择任何大于 0 的数！建议 8、16、32、64、128
    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" 为优化设置
    # [新] “unsloth” 使用 30% 更少的显存，可容纳 2 倍更大的批次！
    use_gradient_checkpointing = "unsloth", # 对于非常长的上下文可使用 True 或 "unsloth"
    random_state = 3407,
    use_rslora = False,  # 我们支持秩稳定化的 LoRA
    loftq_config = None, # 以及 LoftQ
)

数据准备

在此示例中，我们将使用 HuggingFaceH4/Multilingual-Thinking。该数据集包含从用户问题中派生的连贯思路（chain-of-thought）推理示例，这些问题已从英语翻译成另外四种语言。

这是 OpenAI 微调手册中引用的相同数据集。使用多语言数据集的目标是帮助模型学习并在多种语言之间泛化推理模式。

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

from datasets import load_dataset

dataset = load_dataset("HuggingFaceH4/Multilingual-Thinking", split="train")
dataset

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.

from trl import SFTConfig, SFTTrainer
trainer = SFTTrainer(
    model = model,
    tokenizer = tokenizer,
    train_dataset = dataset,
    args = SFTConfig(
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        warmup_steps = 5,
        # num_train_epochs = 1, # 为一次完整训练设置此项。
        max_steps = 30,
        learning_rate = 2e-4,
        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": "reasoning language: French\n\nYou are a helpful assistant that can solve mathematical problems."},
    {"role": "user", "content": "Solve x^5 + 3x^4 - 10 = 3."},
]
inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt = True,
    return_tensors = "pt",
    return_dict = True,
    reasoning_effort = "medium",
).to(model.device)
from transformers import TextStreamer
_ = model.generate(**inputs, max_new_tokens = 2048, streamer = TextStreamer(tokenizer))

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

保存并导出你的模型

要保存微调模型，它可以在 LoRA 合并过程中以 Safetensors 格式导出，配合我们的新 使用我们的 基线模型（例如 gpt-oss）。这使得可能 将你的微调模型导出为 bf16 格式.

微调你的 gpt-oss 模型后，你可以使用以下命令将其合并为 16 位格式：

model.save_pretrained_merged(save_directory, tokenizer)

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

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

✨ 保存到 Llama.cpp

1. 从这里获取最新的 llama.cpp 在 GitHub 上。你也可以按照下面的构建说明。若没有 GPU 或只想使用 CPU 推理，请将 -DGGML_CUDA=ON 更改为 -DGGML_CUDA=OFF 更改为

   复制

   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

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

   复制

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