openai.cookbook 如何使用 vLLM 运行 GPT-OSS

作者：Dominik Kundel (OpenAI)

cookbook.openai.com/

概述

vLLM 是一个开源的高吞吐量推理引擎，通过优化内存使用和处理速度，能够高效地服务于大语言模型（LLM）。本指南将介绍如何使用 vLLM 在服务器上部署 gpt-oss-20b 或 gpt-oss-120b，将其作为 API 提供给应用程序使用，并连接到 Agents SDK。

注意：本指南适用于配备专用 GPU（如 NVIDIA H100）的服务器应用。如果需要在消费级 GPU 上进行本地推理，请参考我们的 Ollama 或 LM Studio 指南。

---

选择模型

vLLM 支持两种规模的 GPT-OSS 模型：

• openai/gpt-oss-20b

  • 较小的模型
  • 仅需约 16GB 显存（VRAM）

• openai/gpt-oss-120b

  • 完整的较大模型
  • 建议 ≥60GB 显存
  • 可单张 H100 或多 GPU 配置运行

两个模型默认都使用 MXFP4 量化（一种高效的模型压缩技术，可在保持性能的同时减少内存占用）。

---

快速设置

1. 安装 vLLM

vLLM 推荐使用 uv 管理 Python 环境，它能根据你的环境自动选择正确的实现。具体可参考 vLLM 快速入门。

运行以下命令创建虚拟环境并安装 vLLM：

# 创建 Python 3.12 虚拟环境
uv venv --python 3.12 --seed

# 激活虚拟环境（Linux/macOS）
source .venv/bin/activate

# 安装 vLLM 及依赖（包括 PyTorch Nightly 版本和 CUDA 12.8 支持）
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

2. 启动服务器并下载模型

vLLM 提供了 serve 命令，可自动从 HuggingFace 下载模型，并在 localhost:8000 启动一个兼容 OpenAI 的服务器。

根据你选择的模型，在服务器终端中运行以下命令：

# 运行 20B 模型
vllm serve openai/gpt-oss-20b
 
# 运行 120B 模型
vllm serve openai/gpt-oss-120b

服务器启动后，即可通过 API 访问模型。

译者注： 使用国内镜象,不然慢成狗了

export HF_ENDPOINT=https://hf-mirror.com

---

使用 API

vLLM 提供了兼容 OpenAI Chat Completions 和 Responses 的 API，你可以使用 OpenAI SDK 几乎无需修改代码即可调用。

以下是 Python 调用示例：

from openai import OpenAI
 
# 初始化客户端，指向本地 vLLM 服务器
client = OpenAI(
    base_url="http://localhost:8000/v1",  # vLLM 默认端口
    api_key="EMPTY"  # 无需认证密钥
)
 
# 使用 Chat Completions API
result = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain what MXFP4 quantization is."}
    ]
)
print(result.choices[0].message.content)
 
# 使用 Responses API（更简洁的接口）
response = client.responses.create(
    model="openai/gpt-oss-120b",
    instructions="You are a helpful assistant.",
    input="Explain what MXFP4 quantization is."
)
print(response.output_text)

如果你之前使用过 OpenAI SDK，只需更改 base_url，现有代码即可正常工作。

---

使用工具（函数调用）

vLLM 支持函数调用（Function Calling），使模型能够使用外部工具（如获取天气、浏览网页等）。

函数调用可通过 Responses 和 Chat Completions API 实现。

以下是通过 Chat Completions 调用函数的示例：

# 定义可调用的函数工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather in a given city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"]
            },
        },
    }
]
 
# 调用模型，并传入工具定义
response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "What's the weather in Berlin right now?"}],
    tools=tools
)
 
print(response.choices[0].message)

由于模型通过思维链（Chain-of-Thought, CoT）  进行工具调用，你需要将 API 返回的推理结果再次传入后续调用，直到模型获得最终答案。

---

集成 Agents SDK

想要将 GPT-OSS 与 OpenAI 的 Agents SDK 结合使用？

Agents SDK 允许你覆盖 OpenAI 基础客户端，将其指向 vLLM 服务的自托管模型。对于 Python SDK，你还可以使用 LiteLLM 集成来代理 vLLM。

以下是使用 Python Agents SDK 的示例：

# 安装 Agents SDK
uv pip install openai-agents

使用

import asyncio
from openai import AsyncOpenAI
from agents import Agent, Runner, function_tool, OpenAIResponsesModel, set_tracing_disabled
 
# 禁用跟踪（可选）
set_tracing_disabled(True)
 
# 定义一个工具函数
@function_tool
def get_weather(city: str):
    print(f"[debug] getting weather for {city}")
    return f"The weather in {city} is sunny."
 
 
async def main():
    # 创建 Agent，使用 vLLM 服务的模型
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",  # 指示 Agent 只用俳句回答
        model=OpenAIResponsesModel(
            model="openai/gpt-oss-120b",
            openai_client=AsyncOpenAI(
                base_url="http://localhost:8000/v1",  # 指向 vLLM
                api_key="EMPTY",
            ),
        ),
        tools=[get_weather],
    )
 
    # 运行 Agent
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)
 
if __name__ == "__main__":
    asyncio.run(main())

---

使用 vLLM 进行直接采样

除了使用 vllm serve 作为 API 服务器，你还可以直接使用 vLLM Python 库来控制推理过程。

如果直接使用 vLLM 进行采样，必须确保输入提示（prompt）遵循 Harmony 响应格式，否则模型无法正常工作。你可以使用 openai-harmony SDK 来处理格式。

# 安装 Harmony SDK
uv pip install openai-harmony

安装后，你可以使用 harmony 来编码和解析 vLLM generate 函数生成的 token。

import json
from openai_harmony import (
    HarmonyEncodingName,
    load_harmony_encoding,
    Conversation,
    Message,
    Role,
    SystemContent,
    DeveloperContent,
)
 
from vllm import LLM, SamplingParams
 
# --- 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?"),
    ]
)
 
# 渲染为模型可接受的 token ID 序列
prefill_ids = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)
 
# 获取停止 token（用于告诉采样器在何处停止生成）
stop_token_ids = encoding.stop_tokens_for_assistant_actions()
 
# --- 2) 使用 vLLM 进行推理 ---
llm = LLM(
    model="openai/gpt-oss-120b",
    trust_remote_code=True,  # 信任远程代码（通常用于自定义模型）
)
 
# 设置采样参数
sampling = SamplingParams(
    max_tokens=128,     # 最大生成 token 数
    temperature=1,      # 温度值（控制随机性）
    stop_token_ids=stop_token_ids,  # 停止 token
)
 
# 生成文本
outputs = llm.generate(
    prompt_token_ids=[prefill_ids],   # 将预填充 token 作为输入（批量大小为 1）
    sampling_params=sampling,
)
 
# 提取生成结果
gen = outputs[0].outputs[0]
text = gen.text  # 生成的文本
output_tokens = gen.token_ids  # 生成的 token ID（不包含预填充部分）
 
# --- 3) 将生成的 token 解析回结构化的 Harmony 消息 ---
entries = encoding.parse_messages_from_completion_tokens(output_tokens, Role.ASSISTANT)
 
# 'entries' 是结构化的对话条目序列（助手消息、工具调用等）
for message in entries:
    print(f"{json.dumps(message.to_dict())}")

---

总结

通过 vLLM，你可以高效地在服务器上部署和运行 GPT-OSS 模型，并通过兼容 OpenAI 的 API 进行调用。无论是通过简单的 API 访问、复杂的函数调用，还是与 Agents SDK 集成，vLLM 都提供了灵活而强大的解决方案。

如果你遇到问题，可参考 vLLM 官方文档 或 OpenAI Harmony 文档 获取更多信息。