推理提供商文档
Responses API (beta)
并获得增强的文档体验
开始使用
Responses API (beta)
Responses API (来自 OpenAI) 为 Hugging Face 推理提供商的模型交互提供了统一的接口。使用您现有的 OpenAI SDK 来访问多提供商路由、事件流、结构化输出和远程 MCP 工具等功能。
本指南假设您拥有 Hugging Face 账户和访问令牌。您可以在 huggingface.co 创建免费账户，并从您的 设置页面 获取令牌。
为什么要构建 Responses API？
Responses API 为 Agentic 应用提供了一个统一的接口。通过它，您可以获得：
- 内置工具编排。 无需更改端点即可调用函数、服务器端 MCP 工具和模式验证的输出。
- 事件驱动流。 接收诸如
response.created、output_text.delta和response.completed等语义事件，以支持增量 UI。 - 推理控制和结构化输出。 调整推理工作的强度，并要求模型每次都返回符合模式的 JSON。
先决条件
- 一个拥有剩余推理提供商积分（提供免费套餐）的 Hugging Face 账户。
- 一个具有“Make calls to Inference Providers”权限的精细化 Hugging Face 令牌，存储在
HF_TOKEN中。
所有推理提供商的聊天补全模型都应与 Responses API 兼容。您可以在 推理模型页面 上浏览可用模型。
配置您的 Responses 客户端
在运行以下代码片段之前，请安装您选择语言的 OpenAI SDK（Python 为 pip install openai，Node.js 为 npm install openai）。如果您更喜欢发出原始 HTTP 请求，任何标准工具（如 curl）都可以。
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:groq",
instructions="You are a helpful assistant.",
input="Tell me a three-sentence bedtime story about a unicorn.",
)
print(response.output_text)如果您打算使用特定提供商，请将其附加到模型 ID，格式为
<repo>:<provider>（例如moonshotai/Kimi-K2-Instruct-0905:groq）。否则，省略后缀，让路由回退到默认提供商。
核心响应模式
纯文本输出
对于单个响应消息，请传递字符串作为输入。Responses API 会返回完整的 response 对象和一个方便的 output_text 助手。
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="moonshotai/Kimi-K2-Instruct-0905:groq",
instructions="You are a helpful assistant.",
input="Tell me a three sentence bedtime story about a unicorn.",
)
print(response.output_text)多模态输入
通过传递内容部分列表来混合文本和视觉内容。Responses API 将文本和图像统一到一个 input 数组中。
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="Qwen/Qwen2.5-VL-7B-Instruct",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "what is in this image?"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
},
],
}
],
)
print(response.output_text)多轮对话
Responses 请求接受对话历史。添加 developer、system 和 user 消息来控制助手行为，而无需自行管理聊天状态。
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="moonshotai/Kimi-K2-Instruct-0905:groq",
input=[
{"role": "developer", "content": "Talk like a pirate."},
{"role": "user", "content": "Are semicolons optional in JavaScript?"},
],
)
print(response.output_text)高级功能
高级功能使用相同的请求格式。
基于事件的流式传输
设置 stream=True 以接收增量 response.* 事件。每个事件都以 JSON 格式到达，因此您可以呈现流式传输的单词，或实时监控工具执行情况。
from openai import OpenAI
import os
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
stream = client.responses.create(
model="moonshotai/Kimi-K2-Instruct-0905:groq",
input=[{"role": "user", "content": "Say 'double bubble bath' ten times fast."}],
stream=True,
)
for event in stream:
print(event)工具调用和路由
添加一个 tools 数组，让模型调用您的函数。路由器负责处理函数调用并返回工具事件。
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="moonshotai/Kimi-K2-Instruct-0905:groq",
tools=tools,
input="What is the weather like in Boston today?",
tool_choice="auto",
)
print(response)结构化输出
通过提供 response_format 来强制模型返回匹配模式的 JSON。Python SDK 提供了 .parse 助手，可直接将响应转换为目标类型。
从 JavaScript 或原始 HTTP 调用
openai/gpt-oss-120b:groq时，请包含一个简短的指令来返回 JSON。否则，即使提供了模式，模型也可能发出 markdown。
from openai import OpenAI
from pydantic import BaseModel
import os
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.getenv("HF_TOKEN"),
)
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
response = client.responses.parse(
model="openai/gpt-oss-120b:groq",
input=[
{"role": "system", "content": "Extract the event information."},
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
],
text_format=CalendarEvent,
)
print(response.output_parsed)远程 MCP 执行
远程 MCP 允许您调用实现模型上下文协议 (Model Context Protocol) 的服务器托管工具。提供 MCP 服务器 URL 和允许的工具，Responses API 会为您处理调用。
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="moonshotai/Kimi-K2-Instruct-0905:groq",
input="how does tiktoken work?",
tools=[
{
"type": "mcp",
"server_label": "gitmcp",
"server_url": "https://gitmcp.io/openai/tiktoken",
"allowed_tools": ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
"require_approval": "never",
},
],
)
for output in response.output:
print(output)推理努力控制
一些开源推理模型提供了努力层级。传递 reasoning={"effort": "low" | "medium" | "high"} 来权衡延迟和深度。
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:groq",
instructions="You are a helpful assistant.",
input="Say hello to the world.",
reasoning={"effort": "low"},
)
for i, item in enumerate(response.output):
print(f"Output #{i}: {item.type}", item.content)API 参考
阅读官方 OpenAI Responses 参考文档。
在 GitHub 上更新