Hugging Face 的徽标

api-inference 文档

聊天完成

Hugging Face's logo
加入 Hugging Face 社区

并获取增强型文档体验

开始使用

聊天完成

在对话上下文中，根据消息列表生成响应，支持对话式语言模型 (LLM) 和对话式视觉语言模型 (VLM)。这是 text-generation 和 image-text-to-text 的子任务。

推荐模型

对话式大型语言模型 (LLM)

对话式视觉语言模型 (VLM)

API Playground

对于聊天完成模型，我们提供了一个交互式 UI Playground，以便更容易进行测试

  • 快速在 UI 中迭代您的提示。
  • 设置和覆盖系统、助手和用户消息。
  • 浏览并选择当前在推理 API 上可用的模型。
  • 并排比较两个模型的输出。
  • 从 UI 中调整请求参数。
  • 在 UI 视图和代码片段之间轻松切换。

访问推理 UI Playground 并开始探索：https://huggingface.co/playground

使用 API

API 支持

  • 使用与 OpenAI SDK 兼容的聊天完成 API。
  • 使用语法、约束和工具。
  • 流式输出

对话式 LLM 的代码片段示例

Python
JavaScript
cURL
from huggingface_hub import InferenceClient

client = InferenceClient(api_key="hf_***")

for message in client.chat_completion(
	model="google/gemma-2-2b-it",
	messages=[{"role": "user", "content": "What is the capital of France?"}],
	max_tokens=500,
	stream=True,
):
    print(message.choices[0].delta.content, end="")

要使用 Python 客户端，请参阅 huggingface_hub 的 软件包参考。

对话式 VLM 的代码片段示例

Python
JavaScript
cURL
from huggingface_hub import InferenceClient

client = InferenceClient(api_key="hf_***")

image_url = "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"

for message in client.chat_completion(
	model="meta-llama/Llama-3.2-11B-Vision-Instruct",
	messages=[
		{
			"role": "user",
			"content": [
				{"type": "image_url", "image_url": {"url": image_url}},
				{"type": "text", "text": "Describe this image in one sentence."},
			],
		}
	],
	max_tokens=500,
	stream=True,
):
	print(message.choices[0].delta.content, end="")

要使用 Python 客户端，请参阅 huggingface_hub 的 软件包参考。

API 规范

请求

有效负载
frequency_penalty 数字 -2.0 到 2.0 之间的数字。正值会根据新 token 在迄今为止文本中的出现频率对其进行惩罚，从而降低模型重复相同行逐字的可能性。
logprobs 布尔值 是否返回输出 token 的对数概率。如果为真，则在消息内容中返回每个输出 token 的对数概率。
max_tokens 整数 聊天完成中可以生成的 token 最大数量。
messages* object[] 包含迄今为止对话的所有消息的列表。
        content* 未知 以下之一
                 (#1) 字符串
                 (#2) object[]
                         (#1) 对象
                                text* 字符串
                                type* 枚举 可能的值：text。
                         (#2) 对象
                                image_url* 对象
                                        url* 字符串
                                type* 枚举 可能的值：image_url。
        name 字符串
        role* 字符串
presence_penalty 数字 -2.0 到 2.0 之间的数字。正值会根据新 token 是否出现在迄今为止的文本中对其进行惩罚，从而提高模型谈论新主题的可能性。
response_format 未知 以下之一
         (#1) 对象
                type* 枚举 可能的值：json。
                value* 未知 表示 JSON Schema 的字符串。JSON Schema 是一种声明性语言，允许使用类型和描述对 JSON 文档进行注释。
         (#2) 对象
                type* 枚举 可能的值：regex。
                value* 字符串
seed 整数
stop string[] 最多 4 个序列，API 将停止生成进一步的 token。
stream 布尔值
stream_options 对象
        include_usage* 布尔值 如果设置，将在数据之前流式传输一个额外的块：[DONE] 消息。此块上的 usage 字段显示整个请求的 token 使用统计信息，choices 字段始终为空数组。所有其他块也将包含 usage 字段，但值为 null。
temperature 数字 要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使输出更加集中和确定性。我们通常建议更改此设置或 top_p，但不要同时更改两者。
tool_choice 未知 以下之一
         (#1) 对象
         (#2) 字符串
         (#3) 对象
                function* 对象
                        name* 字符串
         (#4) 对象
tool_prompt 字符串 在工具之前附加的提示
tools object[] 模型可能调用的工具列表。目前，仅支持函数作为工具。使用此方法提供模型可能为其生成 JSON 输入的函数列表。
        function* 对象
                arguments* 未知
                description 字符串
                name* 字符串
        type* 字符串
top_logprobs 整数 介于 0 和 5 之间的整数，指定在每个 token 位置返回的可能性最大的 token 数量，每个 token 都带有相关的对数概率。如果使用此参数，则必须将 logprobs 设置为 true。
top_p 数字 对使用温度进行采样的另一种方法，称为核采样，其中模型会考虑具有 top_p 概率质量的 token 的结果。因此，0.1 表示仅考虑构成前 10% 概率质量的 token。

某些选项可以通过将标头传递到推理 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 object[]
        finish_reason 字符串
        index 整数
        logprobs 对象
                content object[]
                        logprob 数字
                        token 字符串
                        top_logprobs object[]
                                logprob 数字
                                token 字符串
        message 未知 以下之一
                 (#1) 对象
                        content 字符串
                        role 字符串
                 (#2) 对象
                        role 字符串
                        tool_calls object[]
                                function 对象
                                        参数 未知
                                        描述 字符串
                                        名称 字符串
                                ID 字符串
                                类型 字符串
创建 整数
ID 字符串
模型 字符串
系统指纹 字符串
使用情况 对象
        完成令牌 整数
        提示令牌 整数
        总令牌 整数

如果stream为true，则生成的令牌将作为流返回，使用服务器发送事件 (SSE)。有关流的更多信息，请查看本指南。

正文
choices object[]
        增量 未知 以下之一
                 (#1) 对象
                        content 字符串
                        role 字符串
                 (#2) 对象
                        role 字符串
                        tool_calls 对象
                                function 对象
                                        参数 字符串
                                        名称 字符串
                                ID 字符串
                                索引 整数
                                类型 字符串
        finish_reason 字符串
        index 整数
        logprobs 对象
                content object[]
                        logprob 数字
                        token 字符串
                        top_logprobs object[]
                                logprob 数字
                                token 字符串
创建 整数
ID 字符串
模型 字符串
系统指纹 字符串
使用情况 对象
        完成令牌 整数
        提示令牌 整数
        总令牌 整数
< > 更新 在 GitHub 上

←自动语音识别 特征提取→