openai/gpt-oss

Try gpt-oss · Guides · Model card · OpenAI blog

Download gpt-oss-120b and gpt-oss-20b on Hugging Face

欢迎来到 gpt-oss 系列，这是 [OpenAI 的开放权重模型](https://openai.com/open-models/)，专为强大的推理、Agentic 任务和多样化的开发者用例而设计。 我们要发布两种版本的开放模型： - `gpt-oss-120b` — 适用于生产环境、通用目的以及适合单个 80GB GPU（如 NVIDIA H100 或 AMD MI300X）的高推理用例（117B 参数，5.1B 活跃参数） - `gpt-oss-20b` — 适用于较低延迟、本地或专业用例（21B 参数，3.6B 活跃参数） 这两个模型都使用我们的 [harmony response format][harmony] 进行训练，并且只能使用该格式；否则，它们将无法正常工作。 ## 目录 - [亮点](#highlights) - [推理示例](#inference-examples) - [关于本仓库](#about-this-repository) - [设置](#setup) - [下载模型](#download-the-model) - [参考 PyTorch 实现](#reference-pytorch-implementation) - [参考 Triton 实现（单 GPU）](#reference-triton-implementation-single-gpu) - [参考 Metal 实现](#reference-metal-implementation) - [Harmony 格式与工具](#harmony-format--tools) - [客户端](#clients) - [工具](#tools) - [其他详情](#other-details) - [贡献](#contributing) ### 亮点 - **宽松的 Apache 2.0 许可证：** 不受 copyleft 限制或专利风险地自由构建——非常适合实验、定制和商业部署。 - **可配置的推理力度：** 根据您的特定用例和延迟需求，轻松调整推理力度（低、中、高）。 - **完整的思维链：** 提供对模型推理过程的完全访问，便于调试并增加对输出的信任。此信息不旨在展示给最终用户。 - **可微调：** 通过参数微调完全定制模型以适应您的特定用例。 - **Agentic 能力：** 利用模型的原生能力进行函数调用、[网页浏览](#browser)、[Python 代码执行](#python)和结构化输出。 - **MXFP4 量化：** 模型经过 MoE 权重的 MXFP4 量化后训练，使 `gpt-oss-120b` 可以在单个 80GB GPU（如 NVIDIA H100 或 AMD MI300X）上运行，`gpt-oss-20b` 模型可在 16GB 内存内运行。所有评估均使用相同的 MXFP4 量化进行。 ### 推理示例 #### Transformers 您可以将 `gpt-oss-120b` 和 `gpt-oss-20b` 与 Transformers 库一起使用。如果您使用 Transformers 的 chat template，它将自动应用 [harmony response format][harmony]。如果您直接使用 `model.generate`，则需要使用 chat template 手动应用 harmony 格式，或使用我们的 [`openai-harmony`][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]) ``` [了解更多关于如何将 gpt-oss 与 Transformers 结合使用的信息。](https://cookbook.openai.com/articles/gpt-oss/run-transformers) #### vLLM vLLM 推荐使用 [`uv`](https://docs.astral.sh/uv/) 进行 Python 依赖管理。您可以使用 vLLM 启动一个兼容 OpenAI 的 Web 服务器。以下命令将自动下载模型并启动服务器。 ``` 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 ``` [了解更多关于如何将 gpt-oss 与 vLLM 结合使用的信息。](https://cookbook.openai.com/articles/gpt-oss/run-vllm) 离线服务代码： - 在按照描述安装适当的库之后运行此代码，同时需额外安装： - `uv pip install openai-harmony` ``` # source .oss/bin/activate import os os.environ["VLLM_USE_FLASHINFER_SAMPLER"] = "0" import json from openai_harmony import ( HarmonyEncodingName, load_harmony_encoding, Conversation, Message, Role, SystemContent, DeveloperContent, ) from vllm import LLM, SamplingParams import os # --- 1) 使用 Harmony 渲染 prefill --- 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) # Harmony stop tokens (传递给 sampler 以便它们不会包含在输出中) stop_token_ids = encoding.stop_tokens_for_assistant_actions() # --- 2) 使用 prefill 运行 vLLM --- llm = LLM( model="openai/gpt-oss-20b", trust_remote_code=True, gpu_memory_utilization = 0.95, max_num_batched_tokens=4096, max_model_len=5000, tensor_parallel_size=1 ) sampling = SamplingParams( max_tokens=128, temperature=1, stop_token_ids=stop_token_ids, ) outputs = llm.generate( prompt_token_ids=[prefill_ids], # batch of size 1 sampling_params=sampling, ) # vLLM 为您提供文本和 token ID gen = outputs[0].outputs[0] text = gen.text output_tokens = gen.token_ids # <-- these are the completion token IDs (no prefill) # --- 3) 将 completion token IDs 解析回结构化的 Harmony 消息 --- entries = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT) # 'entries' 是一个结构化对话条目序列（assistant 消息、tool calls 等）。 for message in entries: print(f"{json.dumps(message.to_dict())}") ``` #### PyTorch / Triton / Metal 这些实现主要是用于教育目的的参考实现，不期望在生产环境中运行。 [在下方了解更多。](#reference-pytorch-implementation) #### Ollama 如果您尝试在消费级硬件上运行 `gpt-oss`，可以在 [安装 Ollama](https://ollama.com/download) 后运行以下命令使用 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 ``` [了解更多关于如何将 gpt-oss 与 Ollama 结合使用的信息。](https://cookbook.openai.com/articles/gpt-oss/run-locally-ollama) #### LM Studio 如果您正在使用 [LM Studio](https://lmstudio.ai/)，可以使用以下命令进行下载。 ``` # gpt-oss-20b lms get openai/gpt-oss-20b # gpt-oss-120b lms get openai/gpt-oss-120b ``` 查看我们的 [awesome list](./awesome-gpt-oss.md) 以获取更广泛的 gpt-oss 资源和推理合作伙伴集合。 ## 关于本仓库 本仓库提供了一系列参考实现： - **推理：** - [`torch`](#reference-pytorch-implementation) — 一个非优化的 [PyTorch](https://pytorch.org/) 实现，仅用于教育目的。由于缺乏优化，至少需要 4× H100 GPU。 - [`triton`](#reference-triton-implementation-single-gpu) — 一个使用 [PyTorch](https://pytorch.org/) 和 [Triton](https://github.com/triton-lang/triton) 的更优化的实现，包括使用 CUDA graphs 和基本缓存 - [`metal`](#reference-metal-implementation) — 一个在 Apple Silicon 硬件上运行模型的 Metal 专用实现 - **工具：** - [`browser`](#browser) — 模型训练时所用的 browser 工具的参考实现 - [`python`](#python) — 模型训练时所用的 python 工具的无状态参考实现 - **客户端示例：** - [`chat`](#terminal-chat) — 一个基本的终端聊天应用程序，使用 PyTorch 或 Triton 实现进行推理，并配合 python 和 browser 工具 - [`responses_api`](#responses-api) — 一个示例 Responses API 兼容服务器，实现了 browser 工具以及其他 Responses 兼容功能 ## 设置 ### 要求 - Python 3.12 - 在 macOS 上：安装 Xcode CLI 工具 --> `xcode-select --install` - 在 Linux 上：这些参考实现需要 CUDA - 在 Windows 上：这些参考实现尚未在 Windows 上经过测试。如果您尝试在本地运行模型，请尝试使用 Ollama 等解决方案。 ### 安装 如果您想尝试任何代码，可以直接从 [PyPI](https://pypi.org/project/gpt-oss/) 安装 ``` # 如果您只需要 tools pip install gpt-oss # 如果您想尝试 torch implementation pip install gpt-oss[torch] # 如果您想尝试 triton implementation pip install gpt-oss[triton] ``` 如果您想修改代码或尝试 metal 实现，请在本地设置项目： ``` git clone https://github.com/openai/gpt-oss.git GPTOSS_BUILD_METAL=1 pip install -e ".[metal]" ``` ## 下载模型 您可以直接通过 Hugging Face CLI 从 [Hugging Face Hub](https://huggingface.co/collections/openai/gpt-oss-68911959590a1634ba11c7a4) 下载模型权重： ``` # gpt-oss-120b hf download openai/gpt-oss-120b --include "original/*" --local-dir gpt-oss-120b/ # gpt-oss-20b hf download openai/gpt-oss-20b --include "original/*" --local-dir gpt-oss-20b/ ``` ## 参考 PyTorch 实现 我们在 [gpt_oss/torch/model.py](gpt_oss/torch/model.py) 中包含了一个效率较低的参考 PyTorch 实现。此代码使用基本的 PyTorch 算子来展示确切的模型架构，并添加了少量对 MoE 中张量并行的支持，以便较大的模型可以运行此代码（例如，在 4xH100 或 2xH200 上）。在此实现中，我们将所有权重向上转换为 BF16 并以 BF16 运行模型。 要运行参考实现，请安装依赖项： ``` pip install -e ".[torch]" ``` 然后运行： ``` # 在 4xH100 上： torchrun --nproc-per-node=4 -m gpt_oss.generate gpt-oss-120b/original/ ``` ## 参考 Triton 实现（单 GPU） 我们还包含了一个优化的参考实现，它使用 [an optimized triton MoE kernel](https://github.com/triton-lang/triton/tree/main/python/triton_kernels/triton_kernels)，支持 MXFP4。它还在 attention 代码上做了一些优化以降低内存成本。要运行此实现，需要安装 nightly 版本的 triton 和 torch。此版本可以在单个 80GB GPU 上运行 `gpt-oss-120b`。 要安装参考 Triton 实现，请运行 ``` # 您需要从源代码安装 triton 才能使用 triton implementation git clone https://github.com/triton-lang/triton cd triton/ pip install -r python/requirements.txt pip install -e . --verbose --no-build-isolation pip install -e python/triton_kernels # 安装 gpt-oss triton implementation pip install -e ".[triton]" ``` 然后运行： ``` # 在 1xH100 上 export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True python -m gpt_oss.generate --backend triton gpt-oss-120b/original/ ``` 如果您遇到 `torch.OutOfMemoryError`，请确保开启 expandable allocator 以避免从 checkpoint 加载权重时发生崩溃。 ## 参考 Metal 实现 此外，我们为在 Apple Silicon 上运行提供了 Metal 的参考实现。此实现尚未准备好用于生产环境，但与 PyTorch 实现保持一致。 在 Apple Silicon 设备上运行 `.[metal]` 安装时，该实现将自动编译： ``` GPTOSS_BUILD_METAL=1 pip install -e ".[metal]" ``` 要执行推理，您首先需要使用以下命令将 Hugging Face 的 SafeTensor 权重转换为正确的格式： ``` python gpt_oss/metal/scripts/create-local-model.py -s -d ``` 或下载预转换的权重： ``` hf download openai/gpt-oss-120b --include "metal/*" --local-dir gpt-oss-120b/metal/ hf 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` 来与模型交互。查看 [此指南](https://cookbook.openai.com/articles/openai-harmony) 以了解更多关于 harmony 的信息。 我们还为模型包含两个系统工具：浏览和 python 容器。查看 [gpt_oss/tools](gpt_oss/tools) 了解工具实现。 ## 客户端 ### 终端聊天 终端聊天应用程序是一个基本示例，展示如何将 harmony 格式与 PyTorch、Triton 和 vLLM 实现一起使用。它还公开了 python 和 browser 工具作为可以使用的可选工具。 ``` 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) ``` ### Responses API 我们还包含一个示例 Responses API 服务器。该服务器并未实现 Responses API 的所有功能和事件，但应兼容大多数基本用例，并可为任何构建自己服务器的人提供灵感。我们的一些推理合作伙伴也提供他们自己的 Responses API。 您可以使用以下推理后端启动此服务器： - `triton` — 使用 triton 实现 - `metal` — 仅在 Apple Silicon 上使用 metal 实现 - `ollama` — 使用 Ollama /api/generate API 作为推理解决方案 - `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](https://github.com/openai/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。启动服务器并将 codex 指向 oss 模型： ``` ollama run gpt-oss:20b codex -p oss ``` ## 工具 ### 浏览器 两个 gpt-oss 模型都经过训练，能够使用 `browser` 工具进行浏览，该工具公开了以下三种方法： - `search` 用于搜索关键短语 - `open` 用于打开特定页面 - `find` 用于在页面上查找内容 #### 用法 要启用 browser 工具，您必须将其定义放入 harmony 格式提示的 `system` 消息中。如果您的工具实现了完整接口，可以使用 `with_browser_tool()` 方法，或使用 `with_tools()` 修改定义。例如： ``` import datetime from gpt_oss.tools.simple_browser import SimpleBrowserTool from gpt_oss.tools.simple_browser.backend import YouComBackend from openai_harmony import SystemContent, Message, Conversation, Role, load_harmony_encoding, HarmonyEncodingName encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS) # 根据您选择的 browser backend，您需要设置相应的环境变量 # 如果您使用 You.com backend，则需要设置 YDC_API_KEY 环境变量， # 而对于 Exa，您可能需要设置 EXA_API_KEY 环境变量 backend = YouComBackend( source="web", ) # backend = ExaBackend( # source="web", # ) browser_tool = SimpleBrowserTool(backend=backend) # 创建一个基本的 system prompt system_message_content = SystemContent.new().with_conversation_start_date( datetime.datetime.now().strftime("%Y-%m-%d") ) # 如果您想使用 browser tool if use_browser_tool: # enables the tool system_message_content = system_message_content.with_tools(browser_tool.tool_config) # alternatively you could use the following if your tool is not stateless system_message_content = system_message_content.with_browser_tool() # 构建 system message system_message = Message.from_role_and_content(Role.SYSTEM, system_message_content) # 创建整体 prompt messages = [system_message, Message.from_role_and_content(Role.USER, "What's the weather in SF?")] conversation = Conversation.from_messages(messages) # 转换为 tokens 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"): # perform browser call response_messages = await browser_tool.process(last_message) # extend the current messages and run inference again messages.extend(response_messages) ``` #### 详情 为了控制上下文窗口大小，此工具使用一个模型可以与之交互的可滚动文本窗口。因此，它可能会获取页面的前 50 行，然后滚动到接下来的 20 行。模型还经过训练，会在其答案中使用来自此工具的引用。 为了提高性能，该工具会缓存请求，以便模型可以重新访问页面的不同部分而无需重新加载页面。因此，您应该为每个请求创建一个新的 browser 实例。 ### Python 模型经过训练，可以使用 python 工具在其思维链中执行计算和其他操作。在训练期间，模型使用的是有状态工具，这使得在 CoT 循环之间运行工具更加容易。然而，此参考实现使用无状态模式。因此，PythonTool 定义了自己的工具描述以覆盖 [`openai-harmony`][harmony] 中的定义。 #### 用法 要启用 python 工具，您必须将其定义放入 harmony 格式提示的 `system` 消息中。如果您的工具实现了完整接口，可以使用 `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 prompt system_message_content = SystemContent.new().with_conversation_start_date( datetime.datetime.now().strftime("%Y-%m-%d") ) # 如果您想使用 python tool if use_python_tool: # enables the tool making sure that the prompt gets set with the stateless tool description system_message_content = system_message_content.with_tools(python_tool.tool_config) # alternatively you could use the following if your tool is not stateless system_message_content = system_message_content.with_python() # 构建 system message system_message = Message.from_role_and_content(Role.SYSTEM, system_message_content) # 创建整体 prompt messages = [system_message, Message.from_role_and_content(Role.USER, "What's the square root of 9001?")] conversation = Conversation.from_messages(messages) # 转换为 tokens 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": # perform python call response_messages = await python_tool.process(last_message) # extend the current messages and run inference again messages.extend(response_messages) ``` ### 应用补丁 `apply_patch` 可用于在本地创建、更新或删除文件。 ## 其他详情 ### 精度格式 我们发布了具有原生量化支持的模型。具体来说，我们在 MoE 层的线性投影权重中使用 [MXFP4](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf)。我们将 MoE 张量分为两部分存储： - `tensor.blocks` 存储实际的 fp4 值。我们将每两个值打包在一个 `uint8` 值中。 - `tensor.scales` 存储块缩放因子。对于所有 MXFP4 张量，块缩放是在最后一个维度上进行的。 所有其他张量将为 BF16。我们还建议使用 BF16 作为模型的激活精度。 ### 推荐的采样参数 我们建议使用 `temperature=1.0` 和 `top_p=1.0` 进行采样。 ## 贡献 本仓库中的参考实现旨在作为起点和灵感。除错误修复外，我们不打算接受新功能贡献。如果您基于此代码构建实现（例如新的工具实现），欢迎您将其贡献到 [`awesome-gpt-oss.md`](./awesome-gpt-oss.md) 文件中。 ## 引用 ``` @misc{openai2025gptoss120bgptoss20bmodel, title={gpt-oss-120b & gpt-oss-20b Model Card}, author={OpenAI}, year={2025}, eprint={2508.10925}, archivePrefix={arXiv}, primaryClass={cs.CL}, url={https://arxiv.org/abs/2508.10925}, } ```

标签：Agent, AI风险缓解, AMD MI300X, Apache 2.0, Apex, CUDA, GPT, gpt-oss-120b, gpt-oss-20b, GPU推理, H100, Hugging Face, LLM, Metal, NLP, OpenAI, PyTorch, Transformer, Triton, Unmanaged PE, Vectored Exception Handling, 人工智能, 低延迟, 内存规避, 凭据扫描, 基础模型, 开源大模型, 开源搜索引擎, 开源权重, 推理模型, 文本生成, 本地部署, 机器学习, 深度学习, 漏洞管理, 用户模式Hook绕过, 系统调用监控, 逆向工具