推理提供商文档
如何使用 OpenAI gpt-oss
并获得增强的文档体验
开始使用
如何使用 OpenAI gpt-oss
本指南将引导您使用 Hugging Face Inference Providers 来使用 OpenAI 最新的 gpt-oss 模型，它与为官方 OpenAI Playground (gpt-oss.com) 提供支持的基础设施相同。OpenAI gpt-oss 是一个开放权重模型系列，专为强大的推理能力、智能工作流程和多样的开发者用例而构建，它提供两种尺寸：一个拥有 1200 亿参数的版本 gpt-oss-120b，以及一个拥有 200 亿参数的较小版本 (gpt-oss-20b)。
Inference Providers 支持这两种模型，可以通过与 OpenAI 兼容的 Chat Completions API 或更高级的 Responses API 来访问。
快速入门
- 您需要您的 Hugging Face 令牌。请从您的 设置页面获取。然后，将其设置为环境变量。
export HF_TOKEN="your_token_here"💡 专业提示：免费套餐为您提供每月推理额度，以便您开始构建和实验。升级到 Hugging Face PRO 以获得更大的灵活性，每月 2 美元额度，外加所有提供商的按使用付费访问！
- 安装官方 OpenAI SDK。
pip install openai
聊天补全
在 Inference Providers 上开始使用 gpt-oss 模型非常简单直接。与 OpenAI 兼容的 Chat Completions API 支持诸如工具调用、结构化输出、流式传输和推理成本控制等功能。
这是通过快速的 Cerebras 提供商使用 gpt-oss-120b 的基本示例
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
response = client.chat.completions.create(
model="openai/gpt-oss-120b:cerebras",
messages=[{"role": "user", "content": "Tell me a fun fact about the Eiffel Tower."}],
)
print(response.choices[0].message.content)您还可以让模型访问工具。下面，我们定义了一个 get_current_weather 函数，并让模型决定是否调用它
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
tools = [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
},
}
]
response = client.chat.completions.create(
model="openai/gpt-oss-120b:cerebras",
messages=[{"role": "user", "content": "What is the weather in Paris in Celsius?"}],
tools=tools,
tool_choice="auto",
)
# The response will contain the tool_calls object if the model decides to use the tool
print(response.choices[0].message)对于数据提取等结构化任务，您可以使用 response_format 参数强制模型返回有效的 JSON 对象。我们使用 Fireworks AI 提供商。
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
# Force the model to output a JSON object
response = client.chat.completions.create(
model="openai/gpt-oss-120b:fireworks-ai",
messages=[
{
"role": "system",
"content": "You are a helpful assistant designed to output JSON.",
},
{
"role": "user",
"content": "Extract the name, city, and profession from the following sentence: 'Amélie is a chef who lives in Paris.'",
},
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "person",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"city": {"type": "string"},
"profession": {"type": "string"},
},
"required": ["name", "city", "profession"],
},
},
},
)
# The output is a valid JSON string that can be easily parsed
output_json_string = response.choices[0].message.content
parsed_output = json.loads(output_json_string)
print(parsed_output)只需几行代码，您就可以开始在 Hugging Face Inference Providers 上使用 gpt-oss 模型，它们完全兼容 OpenAI API，易于集成，并且开箱即用！
Responses API
Inference Providers 实现与 OpenAI 兼容的 Responses API，这是聊天模型最先进的接口。它支持流式传输、结构化输出、工具调用、推理成本控制（低、中、高）以及 Remote MCP 调用，以将任务委派给外部服务。
主要优势
- Agent-Oriented Design：该 API 专为简化智能任务的工作流程而设计。它拥有一个本地框架，用于集成复杂的工具使用，如 Remote MCP 调用。
- Stateful, Event-Driven Architecture：具有有状态、事件驱动的架构。它不是在每次更新时都重新发送整个文本，而是流式传输描述仅精确更改（“delta”）的语义事件。这消除了手动状态跟踪的需要。
- 简化复杂逻辑的开发：事件驱动的模型使得构建可靠的多步逻辑应用程序更加容易。您的代码只需监听特定事件，从而实现更清晰、更强大的集成。
该实现基于开源的 huggingface/responses.js 项目。
流式响应
与传统的文本流式传输不同，Responses API 使用语义事件系统进行流式传输。这意味着流不仅仅是原始文本，而是一系列结构化事件对象。每个事件都有一个类型，因此您可以监听您关心的特定事件，例如正在添加的内容（output_text.delta）或消息已完成（completed）。下面的示例显示了如何遍历这些事件并在内容到达时打印它。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
# Set stream=True to receive a stream of semantic events
stream = client.responses.create(
model="openai/gpt-oss-120b:fireworks-ai",
input="Tell me a short story about a robot who discovers music.",
stream=True,
)
# Iterate over the events in the stream
for event in stream:
print(event)工具调用
您可以扩展模型的功能，使其能够访问外部数据。下面的示例定义了一个 get_current_weather 函数，模型可以选择调用它。
from openai import OpenAI
import os
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
tools = [
{
"type": "function",
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location", "unit"],
},
}
]
response = client.responses.create(
model="openai/gpt-oss-120b:fireworks-ai",
tools=tools,
input="What is the weather like in Boston today?",
tool_choice="auto",
)
print(response)远程 MCP 调用
该 API 最先进的功能是 Remote MCP 调用，它允许模型将任务委派给外部服务。使用 Responses API 调用远程 MCP 服务器非常简单。例如，您可以通过 DeepWiki MCP 服务器询问几乎任何公共 GitHub 存储库的问题。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
response = client.responses.create(
model="openai/gpt-oss-120b:fireworks-ai",
input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
tools=[
{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp",
"require_approval": "never",
},
],
)
print(response)推理成本
您还可以通过 reasoning 参数来控制模型的“思考”时间。下面的示例将模型推向花费中等量的精力来回答。
from openai import OpenAI
import os
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
response = client.responses.create(
model="openai/gpt-oss-120b:fireworks-ai",
instructions="You are a helpful assistant.",
input="Say hello to the world.",
reasoning={
"effort": "low",
},
)
for index, item in enumerate(response.output):
print(f"Output #{index}: {item.type}", item.content)就是这样！通过 Inference Providers 上的 Responses API，您可以精细控制 gpt-oss 等强大的开放权重模型，包括流式传输、工具调用和远程 MCP，使其成为构建可靠、智能驱动应用程序的理想选择。
在 GitHub 上更新