如何使用 Hugging Face Transformers 运行 gpt-oss

Hugging Face 的 Transformers 库提供了一种灵活的方式来在本地或服务器上加载和运行大型语言模型。本指南将引导您使用 Transformers 运行 OpenAI gpt-oss-20b 或 OpenAI gpt-oss-120b，无论是通过高级管道还是通过具有原始令牌 ID 的低级 generate 调用。

我们将涵盖使用高级管道抽象、低级 generate 调用以及使用 transformers serve 在本地提供模型（以与 Responses API 兼容的方式）来使用 OpenAI gpt-oss-20b 或 OpenAI gpt-oss-120b。

在本指南中，我们将介绍通过 Transformers 运行 gpt-oss 模型的各种优化方法。

奖励：您还可以通过 transformers 进行模型微调，在此处查看我们的微调指南。

选择您的模型

两个 gpt-oss 模型都可以在 Hugging Face 上找到：

  • openai/gpt-oss-20b
  • 使用 MXFP4 时需要约 16GB VRAM
  • 非常适合单台高端消费级 GPU
  • openai/gpt-oss-120b
  • 需要 ≥60GB VRAM 或多 GPU 设置
  • 非常适合 H100 级硬件

两者默认都经过 MXFP4 量化。请注意，MXFP4 支持 Hopper 或更高版本的架构。这包括数据中心 GPU，如 H100 或 GB200，以及最新的 RTX 50xx 系列消费级显卡。

如果您使用 bfloat16 而不是 MXFP4，内存消耗会更大（对于 20b 参数模型约为 48 GB）。

快速设置

  1. 安装依赖项 建议创建一个新的 Python 环境。安装 transformers、accelerate 以及用于 MXFP4 兼容性的 Triton 内核：
pip install -U transformers accelerate torch triton kernels

pip install git+https://github.com/triton-lang/triton.git@main#subdirectory=python/triton_kernels
  1. （可选）启用多 GPU 如果您运行大型模型，请使用 Accelerate 或 torchrun 来自动处理设备映射。

创建 OpenAI Responses / Chat Completions 端点

要启动服务器，只需使用 transformers serve CLI 命令：

transformers serve

与服务器交互的最简单方法是通过 transformers chat CLI

transformers chat localhost:8000 --model-name-or-path openai/gpt-oss-20b

或通过发送 cURL HTTP 请求，例如

curl -X POST http://localhost:8000/v1/responses -H "Content-Type: application/json" -d '{"messages": [{"role": "system", "content": "hello"}], "temperature": 0.9, "max_tokens": 1000, "stream": true, "model": "openai/gpt-oss-20b"}'

有关将 transformers serve 与 Cursor 和其他工具集成等其他用例，请参阅文档。

使用 pipeline 进行快速推理

使用 Transformers 高级 pipeline API 运行 gpt-oss 模型最简单的方法：

from transformers import pipeline

generator = pipeline(
    "text-generation",
    model="openai/gpt-oss-20b",
    torch_dtype="auto",
    device_map="auto"  # 自动放置到可用 GPU 上
)

messages = [
    {"role": "user", "content": "Explain what MXFP4 quantization is."},
]

result = generator(
    messages,
    max_new_tokens=200,
    temperature=1.0,
)

print(result[0]["generated_text"])

使用 .generate() 进行高级推理

如果您想要更多控制，可以手动加载模型和分词器并调用 .generate() 方法：

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "openai/gpt-oss-20b"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

messages = [
    {"role": "user", "content": "Explain what MXFP4 quantization is."},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
).to(model.device)

outputs = model.generate(
    **inputs,
    max_new_tokens=200,
    temperature=0.7
)

print(tokenizer.decode(outputs[0]))

Chat 模板和工具调用

OpenAI gpt-oss 模型使用 harmony 响应格式 来构建消息，包括推理和工具调用。

要构建提示，您可以使用 Transformers 内置的聊天模板。或者，您可以安装并使用 openai-harmony 库 来获得更多控制。

要使用聊天模板：

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "openai/gpt-oss-20b"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
    torch_dtype="auto",
)

messages = [
    {"role": "system", "content": "Always respond in riddles"},
    {"role": "user", "content": "What is the weather like in Madrid?"},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
).to(model.device)

generated = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(generated[0][inputs["input_ids"].shape[-1] :]))

要集成 openai-harmony 库来准备提示和解析响应，请首先像这样安装它：

pip install openai-harmony

以下是如何使用该库构建提示并将其编码为令牌的示例：

import json
from openai_harmony import (
    HarmonyEncodingName,
    load_harmony_encoding,
    Conversation,
    Message,
    Role,
    SystemContent,
    DeveloperContent
)
from transformers import AutoModelForCausalLM, AutoTokenizer

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# 构建对话
convo = Conversation.from_messages([
    Message.from_role_and_content(Role.SYSTEM, SystemContent.new()),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Always respond in riddles")
    ),
    Message.from_role_and_content(Role.USER, "What is the weather like in SF?")
])

# 渲染提示
prefill_ids = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)
stop_token_ids = encoding.stop_tokens_for_assistant_actions()

# 加载模型
model_name = "openai/gpt-oss-20b"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")

# 生成
outputs = model.generate(
    input_ids=[prefill_ids],
    max_new_tokens=128,
    eos_token_id=stop_token_ids
)

# 解析完成令牌
completion_ids = outputs[0][len(prefill_ids):]
entries = encoding.parse_messages_from_completion_tokens(completion_ids, Role.ASSISTANT)

for message in entries:
    print(json.dumps(message.to_dict(), indent=2))

请注意，Harmony 中的 Developer 角色映射到聊天模板中的 system 提示。

多 GPU 和分布式推理

大型 gpt-oss-120b 在使用 MXFP4 时可以装入单个 H100 GPU。如果您想在多个 GPU 上运行它，您可以：

  • 使用 tp_plan="auto" 进行自动放置和张量并行
  • 使用 accelerate launch 或 torchrun 启动以进行分布式设置
  • 利用专家并行
  • 使用专门的 Flash 注意力内核以实现更快的推理
from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.distributed import DistributedConfig
import torch

model_path = "openai/gpt-oss-120b"
tokenizer = AutoTokenizer.from_pretrained(model_path, padding_side="left")

device_map = {
    # 启用专家并行
    "distributed_config": DistributedConfig(enable_expert_parallel=1),
    # 启用张量并行
    "tp_plan": "auto",
}

model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype="auto",
    attn_implementation="kernels-community/vllm-flash-attn3",
    **device_map,
)

messages = [
     {"role": "user", "content": "Explain how expert parallelism works in large language models."}
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=1000)

# 解码并打印
response = tokenizer.decode(outputs[0])
print("Model response:", response.split("<|channel|>final<|message|>")[-1].strip())

然后，您可以通过以下方式在具有四个 GPU 的节点上运行此命令：

torchrun --nproc_per_node=4 generate.py