推理提供商文档
聊天补全
加入 Hugging Face 社区
并获得增强的文档体验
开始使用
聊天补全
根据会话上下文中的消息列表生成响应,支持会话式语言模型 (LLM) 和会话式视觉语言模型 (VLM)。这是 文本生成
和 图像文本到文本
的一个子任务。
推荐模型
会话式大型语言模型 (LLM)
- google/gemma-2-2b-it: 一个经过训练以遵循指令的文本生成模型。
- deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B: 最强大模型之一的较小变体。
- meta-llama/Meta-Llama-3.1-8B-Instruct: 经过训练以遵循指令的非常强大的文本生成模型。
- microsoft/phi-4: Microsoft 开发的强大文本生成模型。
- simplescaling/s1.1-32B: 一个具有推理能力的非常强大的模型。
- Qwen/Qwen2.5-7B-Instruct-1M: 支持超长指令的强大对话模型。
- Qwen/Qwen2.5-Coder-32B-Instruct: 用于编写代码的文本生成模型。
- deepseek-ai/DeepSeek-R1: 强大的基于推理的开放大型语言模型。
会话式视觉语言模型 (VLM)
- Qwen/Qwen2.5-VL-7B-Instruct: 强大的图像文本到文本模型。
在此处探索所有可用模型,找到最适合您的模型 这里。
API 游乐场
对于聊天补全模型,我们提供了一个交互式 UI 游乐场,以便更轻松地进行测试
- 通过 UI 快速迭代您的提示。
- 设置和覆盖系统、助手和用户消息。
- 浏览和选择当前推理 API 中可用的模型。
- 并排比较两个模型的输出。
- 从 UI 调整请求参数。
- 在 UI 视图和代码片段之间轻松切换。

访问推理 UI 游乐场并开始探索:https://huggingface.co/playground
使用 API
API 支持
- 使用与 OpenAI SDK 兼容的聊天补全 API。
- 使用语法、约束和工具。
- 流式输出
会话式 LLM 代码片段示例
语言
客户端
提供商
import os
from huggingface_hub import InferenceClient
client = InferenceClient(
provider="cerebras",
api_key=os.environ["HF_TOKEN"],
)
completion = client.chat.completions.create(
model="openai/gpt-oss-120b",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
)
print(completion.choices[0].message)
会话式 VLM 代码片段示例
语言
客户端
提供商
import os
from huggingface_hub import InferenceClient
client = InferenceClient(
provider="cerebras",
api_key=os.environ["HF_TOKEN"],
)
completion = client.chat.completions.create(
model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this image in one sentence."
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
}
}
]
}
],
)
print(completion.choices[0].message)
API 规范
请求
标头 | ||
---|---|---|
授权 | 字符串 | 身份验证标头,形式为 'Bearer: hf_****' ,其中 hf_**** 是具有“推理提供商”权限的个人用户访问令牌。您可以从您的设置页面生成一个。 |
有效负载 | ||
---|---|---|
frequency_penalty | 数字 | 介于 -2.0 和 2.0 之间的数字。正值根据新标记在文本中已有的频率对其进行惩罚,从而降低模型逐字重复相同行的可能性。 |
logprobs | 布尔值 | 是否返回输出标记的对数概率。如果为 true,则返回消息内容中返回的每个输出标记的对数概率。 |
max_tokens | 整数 | 聊天补全中可生成的最大标记数。 |
messages* | 对象数组 | 到目前为止的对话消息列表。 |
(#1) | 未知 | 以下之一 |
(#1) | 对象 | |
content* | 未知 | 以下之一 |
(#1) | 字符串 | |
(#2) | 对象数组 | |
(#1) | 对象 | |
text* | 字符串 | |
type* | 枚举 | 可能的值:text。 |
(#2) | 对象 | |
image_url* | 对象 | |
url* | 字符串 | |
type* | 枚举 | 可能的值:image_url。 |
(#2) | 对象 | |
tool_calls* | 对象数组 | |
function* | 对象 | |
parameters | 未知 | |
description | 字符串 | |
name* | 字符串 | |
id* | 字符串 | |
type* | 字符串 | |
(#2) | 对象 | |
name | 字符串 | |
role* | 字符串 | |
presence_penalty | 数字 | 介于 -2.0 和 2.0 之间的数字。正值根据新标记是否出现在文本中对其进行惩罚,从而增加模型谈论新主题的可能性。 |
response_format | 未知 | 以下之一 |
(#1) | 对象 | |
type* | 枚举 | 可能的值:text。 |
(#2) | 对象 | |
type* | 枚举 | 可能的值:json_schema。 |
json_schema* | 对象 | |
name* | 字符串 | 响应格式的名称。 |
description | 字符串 | 响应格式的用途描述,模型使用它来确定如何以该格式响应。 |
schema | 对象 | 响应格式的模式,描述为 JSON Schema 对象。在此处了解如何构建 JSON 模式这里。 |
strict | 布尔值 | 是否在生成输出时启用严格模式遵循。如果设置为 true,模型将始终遵循 schema 字段中定义的精确模式。 |
(#3) | 对象 | |
type* | 枚举 | 可能的值:json_object。 |
种子 | 整数 | |
stop | 字符串数组 | API 将停止生成进一步标记的最多 4 个序列。 |
stream | 布尔值 | |
stream_options | 对象 | |
include_usage | 布尔值 | 如果设置,将在 data: [DONE] 消息之前流式传输一个额外的块。此块上的 usage 字段显示整个请求的标记使用统计信息,choices 字段将始终为空数组。所有其他块也将包含 usage 字段,但值为 null。 |
temperature | 数字 | 要使用的采样温度,介于 0 和 2 之间。较高的值(例如 0.8)将使输出更随机,而较低的值(例如 0.2)将使其更集中和确定性。我们通常建议更改此参数或 top_p ,但不要同时更改两者。 |
tool_choice | 未知 | 以下之一 |
(#1) | 枚举 | 可能的值:auto。 |
(#2) | 枚举 | 可能的值:none。 |
(#3) | 枚举 | 可能的值:required。 |
(#4) | 对象 | |
function* | 对象 | |
name* | 字符串 | |
tool_prompt | 字符串 | 附加在工具之前的提示 |
tools | 对象数组 | 模型可能调用的工具列表。目前,仅支持函数作为工具。使用此参数提供模型可能为其生成 JSON 输入的函数列表。 |
function* | 对象 | |
parameters | 未知 | |
description | 字符串 | |
name* | 字符串 | |
type* | 字符串 | |
top_logprobs | 整数 | 一个介于 0 和 5 之间的整数,指定在每个标记位置返回最可能的标记数量,每个标记都有一个关联的对数概率。如果使用此参数,则必须将 logprobs 设置为 true。 |
top_p | 数字 | 一种替代温度采样的采样方法,称为核采样,模型考虑具有 top_p 概率质量的标记结果。因此,0.1 表示仅考虑包含前 10% 概率质量的标记。 |
响应
输出类型取决于 stream
输入参数。如果 stream
为 false
(默认),则响应将是一个 JSON 对象,包含以下字段:
正文 | ||
---|---|---|
choices | 对象数组 | |
finish_reason | 字符串 | |
index | 整数 | |
logprobs | 对象 | |
content | 对象数组 | |
logprob | 数字 | |
token | 字符串 | |
top_logprobs | 对象数组 | |
logprob | 数字 | |
token | 字符串 | |
message | 未知 | 以下之一 |
(#1) | 对象 | |
content | 字符串 | |
role | 字符串 | |
tool_call_id | 字符串 | |
(#2) | 对象 | |
role | 字符串 | |
tool_calls | 对象数组 | |
function | 对象 | |
arguments | 字符串 | |
description | 字符串 | |
name | 字符串 | |
id | 字符串 | |
type | 字符串 | |
created | 整数 | |
id | 字符串 | |
模型 | 字符串 | |
system_fingerprint | 字符串 | |
usage | 对象 | |
completion_tokens | 整数 | |
prompt_tokens | 整数 | |
total_tokens | 整数 |
如果 stream
为 true
,生成的标记将作为流式传输返回,使用 Server-Sent Events (SSE)。有关流式传输的更多信息,请查看此指南。
正文 | ||
---|---|---|
choices | 对象数组 | |
delta | 未知 | 以下之一 |
(#1) | 对象 | |
content | 字符串 | |
role | 字符串 | |
tool_call_id | 字符串 | |
(#2) | 对象 | |
role | 字符串 | |
tool_calls | 对象数组 | |
function | 对象 | |
arguments | 字符串 | |
name | 字符串 | |
id | 字符串 | |
index | 整数 | |
type | 字符串 | |
finish_reason | 字符串 | |
index | 整数 | |
logprobs | 对象 | |
content | 对象数组 | |
logprob | 数字 | |
token | 字符串 | |
top_logprobs | 对象数组 | |
logprob | 数字 | |
token | 字符串 | |
created | 整数 | |
id | 字符串 | |
模型 | 字符串 | |
system_fingerprint | 字符串 | |
usage | 对象 | |
completion_tokens | 整数 | |
prompt_tokens | 整数 | |
total_tokens | 整数 |