gpt-oss 全量技术解读-EW帮帮网

一、概述

gpt-oss 是 OpenAI 发布的开放权重（open-weight）模型系列，面向强推理、Agent 能力与多样化应用场景。

提供两种规格：

gpt-oss-120b：面向生产与高推理需求，单卡 80GB GPU（如 NVIDIA H100 或 AMD MI300X）可运行（117B 参数，活跃参数 5.1B）。
gpt-oss-20b：面向低时延、本地化或专项场景（21B 参数，活跃参数 3.6B）。

两款模型均基于 harmony 对话格式训练，必须使用该格式，否则行为不稳定。

二、亮点（Highlights）

Apache 2.0 许可：无传染条款与专利风险，便于实验、定制与商业化。
推理成本可调：按需在低/中/高之间折中推理强度与时延。
可访问的推理过程（CoT）：便于调试与可解释性（不建议直接展示给终端用户）。
可微调：支持参数级微调，适配垂直场景。
原生 Agent 能力：函数调用、网页浏览、Python 代码执行与结构化输出。
原生 MXFP4 量化：MoE 层使用 MXFP4；120b 可单卡 80GB 运行，20b 可在 16GB 级内存环境运行。

三、推理示例（Inference examples）

Transformers

可直接在 Transformers 中使用 gpt-oss-120b / gpt-oss-20b。使用 chat 模板会自动套用 harmony；如果手动 model.generate，需要显式应用（或使用 openai-harmony）。

from transformers import pipeline
import torch

model_id = "openai/gpt-oss-120b"

pipe = pipeline(
    "text-generation",
    model=model_id,
    torch_dtype="auto",
    device_map="auto",
)

messages = [
    {"role": "user", "content": "Explain quantum mechanics clearly and concisely."},
]

outputs = pipe(
    messages,
    max_new_tokens=256,
)
print(outputs[0]["generated_text"][-1])

了解如何在 Transformers 中使用 gpt-oss。

vLLM

建议用 uv 管理依赖。vLLM 可启动 OpenAI 兼容服务，命令如下：

uv pip install --pre vllm==0.10.1+gptoss \
    --extra-index-url https://wheels.vllm.ai/gpt-oss/ \
    --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \
    --index-strategy unsafe-best-match

vllm serve openai/gpt-oss-20b

了解如何在 vLLM 中使用 gpt-oss。

PyTorch / Triton / Metal

主要作为参考实现与教学用途，不建议直接用于生产（详见下文“参考实现”）。

Ollama

在消费级设备上可使用 Ollama 本地运行：

## gpt-oss-20b
ollama pull gpt-oss:20b
ollama run gpt-oss:20b

## gpt-oss-120b
ollama pull gpt-oss:120b
ollama run gpt-oss:120b

在 Ollama 上本地运行 gpt-oss 的详情。

LM Studio

在 LM Studio 中下载：

## gpt-oss-20b
lms get openai/gpt-oss-20b
## gpt-oss-120b
lms get openai/gpt-oss-120b

更多生态与推理伙伴见仓库中的 awesome-gpt-oss.md。

四、环境准备（Setup）

先决条件（Requirements）

Python 3.12
macOS：安装 Xcode CLI → xcode-select --install
Linux：参考实现依赖 CUDA
Windows：未测试；本地运行建议用 Ollama 等方案

安装（Installation）

快速试用可从 PyPI 安装：

## 仅使用工具
pip install gpt-oss
## 试用 torch 参考实现
pip install gpt-oss[torch]
## 试用 triton 参考实现
pip install gpt-oss[triton]

需要修改源码或使用 metal 实现，可本地搭建：

git clone https://github.com/openai/gpt-oss.git
GPTOSS_BUILD_METAL=1 pip install -e ".[metal]"

五、下载模型（Download the model）

通过 Hugging Face CLI 拉取权重：

## gpt-oss-120b
huggingface-cli download openai/gpt-oss-120b --include "original/*" --local-dir gpt-oss-120b/

## gpt-oss-20b
huggingface-cli download openai/gpt-oss-20b --include "original/*" --local-dir gpt-oss-20b/

六、参考 PyTorch 实现（Reference PyTorch implementation）

gpt_oss/torch/model.py 提供结构真实但效率较低的 PyTorch 参考实现，用基础算子还原模型。MoE 支持张量并行（如 4×H100 或 2×H200），权重与激活以 BF16 运行。

安装依赖：

pip install -e .[torch]

运行：

## 在 4×H100 上：
torchrun --nproc-per-node=4 -m gpt_oss.generate gpt-oss-120b/original/

七、参考 Triton 实现（单卡）（Reference Triton implementation, single GPU）

基于 Triton MoE 内核的优化实现，支持 MXFP4，并对注意力做了内存优化。使用 nightly 版 triton/torch，可在单张 80GB H100上运行 gpt-oss-120b。

安装：

## 构建 triton
git clone https://github.com/triton-lang/triton
cd triton/
pip install -r python/requirements.txt
pip install -e . --verbose --no-build-isolation

## 安装 gpt-oss 的 triton 后端
pip install -e .[triton]

运行：

## 在 1×H100 上
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
python -m gpt_oss.generate --backend triton gpt-oss-120b/original/

遇到 torch.OutOfMemoryError 时，启用可扩展分配器，避免加载 checkpoint 时崩溃。

八、参考 Metal 实现（Reference Metal implementation）

提供 Apple Silicon 的 Metal 实现，数值与 PyTorch 一致（不适合生产）。在 Apple Silicon 上安装 .[metal] 会自动编译：

pip install -e .[metal]

推理前需将 SafeTensors 转为本地格式：

python gpt_oss/metal/scripts/create-local-model.py -s <model_dir> -d <output_file>

或直接下载 metal/* 权重：

huggingface-cli download openai/gpt-oss-120b --include "metal/*" --local-dir gpt-oss-120b/metal/
huggingface-cli download openai/gpt-oss-20b --include "metal/*" --local-dir gpt-oss-20b/metal/

快速测试：

python gpt_oss/metal/examples/generate.py gpt-oss-20b/metal/model.bin -p "why did the chicken cross the road?"

九、Harmony 格式与工具（Harmony format & tools）

提供 harmony 对话格式库，用于与模型交互（见官方指南）。同时包含两类系统工具：浏览器与 Python 容器（实现见 gpt_oss/tools）。

十、客户端（Clients）

终端聊天（Terminal Chat）

终端应用演示如何在 PyTorch、Triton、vLLM 中使用 harmony，并可选择启用 Python/浏览器工具：

usage: python -m gpt_oss.chat [-h] [-r REASONING_EFFORT] [-a] [-b] [--show-browser-results] [-p] [--developer-message DEVELOPER_MESSAGE] [-c CONTEXT] [--raw] [--backend {triton,torch,vllm}] FILE

Chat example

positional arguments:
  FILE                  Path to the SafeTensors checkpoint

options:
  -h, --help            show this help message and exit
  -r REASONING_EFFORT, --reasoning-effort REASONING_EFFORT
                        Reasoning effort (default: low)
  -a, --apply-patch     Make apply_patch tool available to the model (default: False)
  -b, --browser         Use browser tool (default: False)
  --show-browser-results
                        Show browser results (default: False)
  -p, --python          Use python tool (default: False)
  --developer-message DEVELOPER_MESSAGE
                        Developer message (default: )
  -c CONTEXT, --context CONTEXT
                        Max context length (default: 8192)
  --raw                 Raw mode (does not render Harmony encoding) (default: False)
  --backend {triton,torch,vllm}
                        Inference backend (default: triton)

注：PyTorch/Triton 需要 gpt-oss-120b/original/ 与 gpt-oss-20b/original/ 下的原始 checkpoint；vLLM 使用 gpt-oss-120b/ 与 gpt-oss-20b/ 根目录下的 Hugging Face 转换版 checkpoint。

Responses API

提供简化的 Responses API 服务器示例（不覆盖全部事件，但可满足大多数基础用例），并可作为自建服务思路。可选择以下后端：

triton：使用 triton 实现
metal：Apple Silicon
ollama：调用 Ollama /api/generate
vllm：本地 vLLM
transformers：本地 Transformers 推理

usage: python -m gpt_oss.responses_api.serve [-h] [--checkpoint FILE] [--port PORT] [--inference-backend BACKEND]

Responses API server

options:
  -h, --help                    show this help message and exit
  --checkpoint FILE             Path to the SafeTensors checkpoint
  --port PORT                   Port to run the server on
  --inference-backend BACKEND   Inference backend to use

Codex

可将 codex 作为 gpt-oss 客户端。以 20b 为例，在 ~/.codex/config.toml 中配置：

disable_response_storage = true
show_reasoning_content = true

[model_providers.local]
name = "local"
base_url = "http://localhost:11434/v1"

[profiles.oss]
model = "gpt-oss:20b"
model_provider = "local"

可与任何监听 11434 端口、兼容 Chat Completions API 的服务配合（如 Ollama）：

ollama run gpt-oss:20b
codex -p oss

十一、工具（Tools）

Browser

警告：示例仅用于学习，不要直接用于生产。生产环境需替换为等价的自研浏览后端（如与 ExaBackend 同等能力）。

两种 gpt-oss 模型均受训支持 browser 工具，提供：

search：关键词检索
open：打开页面
find：页内查找

用法（在 harmony 的 system 消息里声明工具定义；完整接口可用 with_browser()，否则用 with_tools() 自定义）：

import datetime
from gpt_oss.tools.simple_browser import SimpleBrowserTool
from gpt_oss.tools.simple_browser.backend import ExaBackend
from openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

## Exa backend 需要你设置 EXA_API_KEY 环境变量
backend = ExaBackend(
    source="web",
)
browser_tool = SimpleBrowserTool(backend=backend)

## 基本 system 提示词
system_message_content = SystemContent.new().with_conversation_start_date(
    datetime.datetime.now().strftime("%Y-%m-%d")
)

## 若需要使用浏览器工具
if use_browser_tool:
    # 启用工具
    system_message_content = system_message_content.with_tools(browser_tool.tool_config)
    # 如果你的工具不是无状态的，也可以：
    system_message_content = system_message_content.with_browser()

## 构造 system 消息
system_message = Message.from_role_and_content(Role.SYSTEM, system_message_content)

## 构造整体对话
messages = [system_message, Message.from_role_and_content(Role.USER, "What's the weather in SF?")]
conversation = Conversation.from_messages(messages)

## 渲染为补全所需 token
token_ids = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)

## ……执行推理……

## 解析输出
messages = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)
last_message = messages[-1]
if last_message.recipient.startswith("browser"):
  # 执行浏览器调用
  response_messages = await browser_tool.process(last_message)

  # 追加到对话后再次推理
  messages.extend(response_messages)

实现细节：采用“窗口式滚动文本”控制上下文（先取前 50 行，再滚动 20 行等）；模型被训练为在回答中引用工具返回的片段。内置请求缓存，避免重复抓取；建议每次请求新建浏览器实例。

Python

模型受训支持在推理过程中使用 Python 工具。训练时为有状态，参考实现改为无状态（会在 system 中覆盖 openai-harmony 默认定义）。

警告：参考实现运行在权限较宽的容器中，存在提示注入等风险；生产需加强隔离与最小权限。

用法（完整接口可用 with_python()，否则 with_tools() 自定义）：

import datetime
from gpt_oss.tools.python_docker.docker_tool import PythonTool
from openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

python_tool = PythonTool()

## 基本 system 提示词
system_message_content = SystemContent.new().with_conversation_start_date(
    datetime.datetime.now().strftime("%Y-%m-%d")
)

## 若启用 Python 工具
if use_python_tool:
    # 以无状态定义启用工具
    system_message_content = system_message_content.with_tools(python_tool.tool_config)
    # 若你的工具不是无状态，也可以：
    system_message_content = system_message_content.with_python()

## 构造 system 消息
system_message = Message.from_role_and_content(Role.SYSTEM, system_message_content)

## 构造整体对话
messages = [system_message, Message.from_role_and_content(Role.USER, "What's the square root of 9001?")]
conversation = Conversation.from_messages(messages)

## 渲染为补全所需 token
token_ids = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)

## ……执行推理……

## 解析输出
messages = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)
last_message = messages[-1]
if last_message.recipient == "python":
  # 执行 Python 调用
  response_messages = await python_tool.process(last_message)

  # 追加到对话后再次推理
  messages.extend(response_messages)

Apply Patch

apply_patch 用于在本地创建、更新或删除文件。

十二、其他细节（Other details）

精度格式（Precision format）

模型以原生量化形式发布：MoE 线性投影权重使用 MXFP4。MoE 张量拆分为两部分：

tensor.blocks：FP4 数值（每两个值打包为一个 uint8）
tensor.scales：分块尺度（沿最后一维分块缩放）

其余张量采用 BF16，建议激活也使用 BF16。

采样参数建议（Recommended Sampling Parameters）

推荐基线：temperature=1.0、top_p=1.0。

gpt-oss 全量技术解读