小部件

什么是小部件？

许多模型仓库都有一个小部件，允许任何人在浏览器中直接运行推理。这些小部件由推理提供商提供支持，为开发者提供简化的、统一的访问数百个机器学习模型的途径，由我们的无服务器推理合作伙伴支持。

以下是一些当前流行模型的示例：

DeepSeek V3 - 最先进的开源权重对话模型
Flux Kontext - 用于图像编辑的开源权重 Transformer 模型
Falconsai's NSFW Detection - 图像内容审核
ResembleAI's Chatterbox - 生产级开源文本转语音模型。

你可以在模型页面上探索更多模型及其小部件，或在推理 Playground中交互式地试用它们。

启用小部件

当模型由至少一个推理提供商托管时，会显示小部件，确保模型推理的最佳性能和可靠性。提供商自主选择和控制他们部署的模型。

显示的小部件类型（文本生成、文本到图像等）是从模型的 pipeline_tag 推断出来的，这是 Hub 尝试为所有模型自动计算的特殊标签。唯一的例外是 conversational 小部件，它显示在 pipeline_tag 为 text-generation 或 image-text-to-text 的模型上，只要它们也被标记为 conversational。为了简单起见，我们选择为每个模型仅显示一个小部件。

对于某些库，如 transformers，模型类型可以根据配置文件（config.json）自动推断。架构可以确定类型：例如，AutoModelForTokenClassification 对应于 token-classification。如果你对此感兴趣，可以在此 gist中查看伪代码。

对于大多数其他用例，我们使用模型标签来确定模型任务类型。例如，如果模型卡片元数据中有 tag: text-classification，推断的 pipeline_tag 将是 text-classification。

你始终可以在模型卡片元数据中使用 pipeline_tag: xxx 手动覆盖你的管道类型。（你也可以使用元数据 GUI 编辑器来执行此操作）。

如何控制模型小部件的示例输入？

你可以在模型卡片元数据部分指定小部件输入：

widget:
  - text: "This new restaurant has amazing food and great service!"
    example_title: "Positive Review"
  - text: "I'm really disappointed with this product. Poor quality and overpriced."
    example_title: "Negative Review"
  - text: "The weather is nice today."
    example_title: "Neutral Statement"

你可以提供多个示例输入。在小部件的示例下拉菜单中，它们将显示为 Example 1、Example 2 等。可选地，你也可以提供 example_title。

widget:
  - text: "Is this review positive or negative? Review: Best cast iron skillet you will ever buy."
    example_title: "Sentiment analysis"
  - text: "Barack Obama nominated Hilary Clinton as his secretary of state on Monday. He chose her because she had ..."
    example_title: "Coreference resolution"
  - text: "On a shelf, there are five books: a gray book, a red book, a purple book, a blue book, and a black book ..."
    example_title: "Logic puzzles"
  - text: "The two men running to become New York City's next mayor will face off in their first debate Wednesday night ..."
    example_title: "Reading comprehension"

此外，你可以在模型卡片元数据中指定非文本示例输入。有关所有小部件类型的示例输入格式的完整列表，请参阅此处。对于视觉和音频小部件类型，使用 src 而不是 text 提供示例输入。

例如，允许用户为自动语音识别任务从两个示例音频文件中选择：

widget:
  - src: https://example.org/somewhere/speech_samples/sample1.flac
    example_title: Speech sample 1
  - src: https://example.org/somewhere/speech_samples/sample2.flac
    example_title: Speech sample 2

请注意，你也可以在模型仓库中包含示例文件并使用它们：

widget:
  - src: https://huggingface.co/username/model_repo/resolve/main/sample1.flac
    example_title: Custom Speech Sample 1

但更方便的是，如果文件位于相应的模型仓库中，你可以只使用仓库内的文件名或文件路径：

widget:
  - src: sample1.flac
    example_title: Custom Speech Sample 1

或者如果它嵌套在仓库内：

widget:
  - src: nested/directory/sample1.flac

我们在 default-widget-inputs.ts 文件中为某些语言和大多数小部件类型提供示例输入。如果缺少某些示例，我们欢迎社区提交 PR 来添加它们！

示例输出

作为示例输入的扩展，对于每个小部件示例，你还可以在 output 属性中可选地描述相应的模型输出。

当模型尚未被推理提供商支持时，这很有用，这样模型页面仍然可以展示模型的工作原理及其给出的结果。

例如，对于自动语音识别模型：

widget:
  - src: sample1.flac
    output:
      text: "Hello my name is Julien"

output 属性应该是一个 YAML 字典，表示来自推理提供商的输出格式。

对于输出文本的模型，请参见上面的示例。

对于输出标签的模型（例如文本分类模型），输出应如下所示：

widget:
  - text: "I liked this movie"
    output:
      - label: POSITIVE
        score: 0.8
      - label: NEGATIVE
        score: 0.2

最后，对于输出图像、音频或任何其他类型资产的模型，输出应包含一个 url 属性，链接到仓库内的文件名或路径，或远程 URL。例如，对于文本到图像模型：

widget:
  - text: "picture of a futuristic tiger, artstation"
    output:
      url: images/tiger.jpg

我们还可以在 Hugging Face UI 中展示示例输出，例如，对于文本到图像模型，显示很酷的图像生成画廊。

小部件可用性和提供商支持

并非所有模型都有可用的小部件。小部件可用性取决于：

任务支持：模型的任务必须由推理提供商网络中的至少一个提供商支持
提供商可用性：至少一个提供商必须正在服务特定模型
模型配置：模型必须具有适当的元数据和配置文件

要查看支持的任务的完整列表，请查看我们的专门文档页面。

所有提供商及其支持的任务列表可在此文档页面中找到。

对于没有提供商支持的模型，你仍然可以在模型卡片中使用示例输出来展示功能。

如果有足够的社区兴趣，你也可以直接在模型页面上点击_请求提供商支持_，以鼓励提供商服务该模型。

使用推理 Playground 探索模型

在将模型集成到应用程序之前，你可以使用推理 Playground交互式地测试它们。Playground 允许你：

使用自定义提示测试不同的聊天完成模型
比较不同模型的响应
试验推理参数，如温度、最大令牌数等
为你的特定用例找到完美的模型

Playground 使用与小部件相同的推理提供商基础设施，因此当你将模型集成到自己的应用程序中时，可以期待类似的性能和功能。

什么是小部件？​

启用小部件​

如何控制模型小部件的示例输入？​

示例输出​

小部件可用性和提供商支持​

使用推理 Playground 探索模型​