推理提供商文档
聊天补全
加入 Hugging Face 社区
并获得增强的文档体验
开始使用
聊天补全
在对话上下文中，根据消息列表生成回复，支持对话式语言模型 (LLM) 和对话式视觉-语言模型 (VLM)。这是 text-generation 和 image-text-to-text 的子任务。
推荐模型
对话式大型语言模型 (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：微软强大的文本生成模型。
- 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 的代码片段示例
from huggingface_hub import InferenceClient
client = InferenceClient(
provider="cerebras",
api_key="hf_xxxxxxxxxxxxxxxxxxxxxxxx",
)
completion = client.chat.completions.create(
model="meta-llama/Llama-3.3-70B-Instruct",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
max_tokens=500,
)
print(completion.choices[0].message)对话式 VLM 的代码片段示例
from huggingface_hub import InferenceClient
client = InferenceClient(
provider="fireworks-ai",
api_key="hf_xxxxxxxxxxxxxxxxxxxxxxxx",
)
completion = client.chat.completions.create(
model="meta-llama/Llama-3.2-11B-Vision-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"
}
}
]
}
],
max_tokens=500,
)
print(completion.choices[0].message)API 规范
请求
| 有效负载 | ||
|---|---|---|
| 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* | 对象 | |
| arguments* | 未知 | |
| description | 字符串 | |
| name* | 字符串 | |
| id* | 字符串 | |
| type* | 字符串 | |
| (#2) | 对象 | |
| name | 字符串 | |
| role* | 字符串 | |
| presence_penalty | 数字 | 介于 -2.0 和 2.0 之间的数字。正值会根据新令牌是否到目前为止出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性 |
| response_format | 未知 | 以下之一 |
| (#1) | 对象 | |
| type* | 枚举 | 可能的值：json。 |
| value* | 未知 | 表示 JSON Schema 的字符串。JSON Schema 是一种声明性语言，允许使用类型和描述来注释 JSON 文档。 |
| (#2) | 对象 | |
| type* | 枚举 | 可能的值：regex。 |
| value* | 字符串 | |
| seed | 整数 | |
| stop | 字符串数组 | API 将停止生成更多令牌的最多 4 个序列。 |
| stream | 布尔值 | |
| stream_options | 对象 | |
| include_usage | 布尔值 | 如果设置，将在数据：[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* | 对象 | |
| arguments* | 未知 | |
| description | 字符串 | |
| name* | 字符串 | |
| type* | 字符串 | |
| top_logprobs | 整数 | 介于 0 和 5 之间的整数，指定在每个令牌位置返回的最有可能的令牌数量，每个令牌都具有关联的对数概率。如果使用此参数，则必须将 logprobs 设置为 true。 |
| top_p | 数字 | 使用温度采样的替代方法，称为核采样，其中模型考虑具有 top_p 概率质量的令牌的结果。因此，0.1 表示仅考虑包含前 10% 概率质量的令牌。 |
某些选项可以通过将标头传递给推理 API 来配置。以下是可用的标头
| 标头 | ||
|---|---|---|
| authorization | 字符串 | 形式为 'Bearer: hf_****' 的身份验证标头，其中 hf_**** 是具有推理 API 权限的个人用户访问令牌。您可以从您的设置页面生成一个。 |
| x-use-cache | 布尔值，默认为 true | 推理 API 上有一个缓存层，可以加速我们已经看到的请求。大多数模型都可以使用这些结果，因为它们是确定性的（意味着输出无论如何都是相同的）。但是，如果您使用非确定性模型，则可以将此参数设置为阻止使用缓存机制，从而产生真正的全新查询。阅读有关缓存的更多信息此处。 |
| x-wait-for-model | 布尔值，默认为 false | 如果模型未准备好，请等待它，而不是收到 503。它限制了完成推理所需的请求数量。建议仅在收到 503 错误后才将此标志设置为 true，因为它会将应用程序中的挂起限制在已知位置。阅读有关模型可用性的更多信息此处。 |
有关推理 API 标头的更多信息，请查看指南中的参数。
响应
输出类型取决于 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 | 字符串 | |
| model | 字符串 | |
| system_fingerprint | 字符串 | |
| usage | 对象 | |
| completion_tokens | 整数 | |
| prompt_tokens | 整数 | |
| total_tokens | 整数 |
如果 stream 为 true，则生成的令牌将作为流返回，使用服务器发送事件 (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 | 字符串 | |
| model | 字符串 | |
| system_fingerprint | 字符串 | |
| usage | 对象 | |
| completion_tokens | 整数 | |
| prompt_tokens | 整数 | |
| total_tokens | 整数 |