推理提供商文件
如何使用 OpenAI 的 GPT OSS
並獲得增強的文件體驗
開始使用
如何使用 OpenAI 的 GPT OSS
本指南將引導您使用 Hugging Face 推理提供商的 OpenAI 最新 GPT OSS 模型。GPT OSS 是一個開放權重系列，專為強大的推理、代理工作流和多功能開發人員用例而構建，它有兩種大小：一個具有 120B 引數 (gpt-oss-120b)，另一個較小，具有 20B 引數 (gpt-oss-20b)。
這兩個模型都支援推理提供商，並且可以透過與 OpenAI 相容的聊天完成 API，或更高階的響應 API 進行訪問。
快速入門
- 您將需要您的 Hugging Face 令牌。從您的設定頁面獲取一個。然後，將其設定為環境變數。
export HF_TOKEN="your_token_here"💡 專家提示：免費套餐每月提供推理積分，供您開始構建和實驗。升級到Hugging Face PRO 可獲得更大的靈活性，每月 2 美元的積分以及所有提供商的按需付費訪問許可權！
- 安裝官方 OpenAI SDK。
pip install openai
聊天完成
在推理提供商上使用 GPT OSS 模型非常簡單。與 OpenAI 相容的聊天完成 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 推理提供商的 GPT OSS 模型，它們完全相容 OpenAI API，易於整合，開箱即用！
響應 API
推理提供商實現了**與 OpenAI 相容的響應 API**，這是基於聊天的模型最先進的介面。它支援流式傳輸、結構化輸出、工具呼叫、推理工作量控制（低、中、高）以及將任務委派給外部服務的遠端 MCP 呼叫。
主要優勢
- 以代理為中心的設計：API 專為簡化代理任務的工作流而構建。它具有用於整合複雜工具使用（例如遠端 MCP 呼叫）的本機框架。
- 有狀態、事件驅動的架構：具有有狀態、事件驅動的架構。它不是在每次更新時重新發送整個文字，而是流式傳輸描述精確更改（“增量”）的語義事件。這消除了手動狀態跟蹤的需要。
- 簡化複雜邏輯的開發：事件驅動模型使構建具有多步邏輯的可靠應用程式變得更容易。您的程式碼只需偵聽特定事件，從而實現更簡潔、更強大的整合。
此實現基於開源專案 huggingface/responses.js。
流式響應
與傳統的文字流式傳輸不同，響應 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 最先進的功能是遠端 MCP 呼叫，它允許模型將任務委託給外部服務。使用響應 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)就這樣！透過推理提供商的響應 API，您可以對 GPT OSS 等強大的開放權重模型進行精細控制，包括流式傳輸、工具呼叫和遠端 MCP，使其成為構建可靠、代理驅動型應用程式的理想選擇。
< > 在 GitHub 上更新