推理提供商文档
Chat Completion
加入 Hugging Face 社区
并获得增强的文档体验
开始使用
聊天补全
根据对话上下文中的消息列表生成响应,支持对话语言模型(LLMs)和对话视觉语言模型(VLMs)。这是 text-generation 和 image-text-to-text 的子任务。
推荐模型
对话式大型语言模型(LLMs)
- google/gemma-2-2b-it:一个旨在遵循指令的文本生成模型。
- Qwen/Qwen3-Coder-480B-A35B-Instruct:强大的代码生成文本模型。
- openai/gpt-oss-120b:出色的文本生成模型,具有顶级的工具调用能力。
- zai-org/GLM-4.5:强大的文本生成模型。
- Qwen/Qwen3-4B-Thinking-2507:一个具有推理能力的小型强大模型。
- Qwen/Qwen2.5-7B-Instruct-1M:强大的对话模型,支持超长指令。
- Qwen/Qwen2.5-Coder-32B-Instruct:用于编写代码的文本生成模型。
- deepseek-ai/DeepSeek-R1:强大的基于推理的大型语言模型。
对话式视觉语言模型(VLMs)
- zai-org/GLM-4.5V:尖端的推理视觉语言模型。
探索所有可用模型,找到最适合您的模型 这里。
API Playground
对于聊天补全模型,我们提供了一个交互式UI Playground,方便测试。
- 通过UI快速迭代您的提示。
- 设置和覆盖系统、助手和用户消息。
- 浏览并选择当前在Inference API上可用的模型。
- 并排比较两个模型的输出。
- 从UI调整请求参数。
- 在UI视图和代码片段之间轻松切换。
访问Inference UI Playground并开始探索:https://huggingface.co/playground
使用 API
API支持
- 使用与OpenAI SDK兼容的聊天补全API。
- 使用语法、约束和工具。
- 流式输出
对话式LLM代码片段示例
语言
客户端
提供商
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
completion = client.chat.completions.create(
model="zai-org/GLM-4.7:cerebras",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
)
print(completion.choices[0].message)对话式VLM代码片段示例
语言
客户端
提供商
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
completion = client.chat.completions.create(
model="CohereLabs/aya-vision-32b:cohere",
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 | boolean | 是否返回输出标记的对数概率。如果为 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 Schema 。 |
| strict | boolean | 是否启用严格的模式遵循。如果设置为 true,模型将始终遵循 schema 字段中定义的精确模式。 |
| (#3) | 对象 | |
| type* | 枚举 | 可能的值:json_object。 |
| 种子 | 整数 | |
| stop | 字符串数组 | 最多 4 个序列,API 将停止生成更多标记。 |
| stream | boolean | |
| stream_options | 对象 | |
| include_usage | boolean | 如果设置,将在 [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,则生成的标记将以服务器发送事件 (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 | 整数 |