# 小部件

## 什么是小部件？

许多模型仓库都提供了一个小部件，允许任何人在浏览器中直接运行推理。这些小部件由 [Inference Providers](https://huggingface.co/docs/inference-providers) 提供支持，它们为开发者提供了对数百个机器学习模型的简化、统一访问，背后由我们的无服务器推理合作伙伴支撑。

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

- [DeepSeek V3](https://huggingface.co/deepseek-ai/DeepSeek-V3-0324) - 最先进的开源权重对话模型
- [Flux Kontext](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev) - 用于图像编辑的开放权重 Transformer 模型
- [Falconsai 的 NSFW 检测](https://huggingface.co/Falconsai/nsfw_image_detection) - 图像内容审核
- [ResembleAI 的 Chatterbox](https://huggingface.co/ResembleAI/chatterbox) - 生产级开源文本转语音模型。

您可以在[模型页面](https://huggingface.co/models?inference_provider=all&sort=trending)上探索更多模型及其小部件，或在[Inference Playground](https://huggingface.co/playground)中交互式地试用它们。

## 启用小部件

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

显示的组件类型（如文本生成图像、自动语音识别等）是根据模型的 `pipeline_tag` 推断得出的，这是 Hub 尝试为所有模型自动计算的一个特殊标签。唯一的例外是 `conversational` 组件，它会显示在所有 `pipeline_tag` 为 `text-generation` 或 `image-text-to-text` 的模型上。为了简洁起见，我们选择每个模型只暴露 **一个** 组件。

对于某些库（例如 `transformers`），模型类型可以根据配置文件（`config.json`）自动推断。架构可以决定类型：例如，`AutoModelForTokenClassification` 对应 `token-classification`。如果你对此感兴趣，可以在 [此 gist](https://gist.github.com/julien-c/857ba86a6c6a895ecd90e7f7cab48046) 中查看伪代码。

对于大多数其他用例，我们使用模型标签来确定模型任务类型。例如，如果[模型卡片元数据](./model-cards)中包含`tag: text-classification`，则推断出的`pipeline_tag`将为`text-classification`。

**您始终可以在 [模型卡片元数据](./model-cards#model-card-metadata) 中使用 `pipeline_tag: xxx` 手动覆盖流水线类型。**（您也可以使用元数据 GUI 编辑器来完成此操作）。

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

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

```yaml
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"
```

您可以提供多个示例输入。在 widget 的示例下拉菜单中，它们将显示为 `Example 1`、`Example 2` 等。可选地，您还可以提供 `example_title`。

```yaml
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"
```

此外，您可以在模型卡元数据中指定非文本示例输入。有关所有小部件类型的示例输入格式的完整列表，请参阅[此处](./models-widgets-examples)。对于视觉和音频小部件类型，请使用`src`而非`text`提供示例输入。

例如，通过以下方式允许用户从两个示例音频文件中自动选择用于语音识别任务的文件：

```yaml
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
```

请注意，您还可以在模型仓库中包含示例文件，并将其用作：

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

但更方便的是，如果该文件位于对应的模型仓库中，您可以直接使用仓库内的文件名或文件路径：

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

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

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

我们在 [default-widget-inputs.ts 文件](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/default-widget-inputs.ts) 中为部分语言和大多数小部件类型提供了示例输入。如果缺少某些示例，我们欢迎社区提交 PR 来补充！

## 示例输出

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

当模型尚未被 Inference Providers 支持时，此功能非常有用，它可以让模型页面继续展示模型的工作方式及其产生的结果。

例如，对于一个 [automatic-speech-recognition](./models-widgets-examples#automatic-speech-recognition) 模型：

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

`output` 属性应为一个 YAML 字典，用于表示来自 Inference Providers 的输出格式。

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

对于输出标签的模型（例如 [text-classification](./models-widgets-examples#text-classification) 模型），输出应如下所示：

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

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

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

我们也可以在 Hugging Face 界面中展示示例输出，例如，对于文本生成图像模型，可以展示一个包含精美生成图像的图库。

## 小部件可用性与提供商支持

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

1. **任务支持**：该模型的任务必须至少被 Inference Providers 网络中的一个提供商所支持
2. **提供商可用性**：至少一个提供商必须正在提供该特定模型
3. **模型配置**：模型必须具有正确的元数据和配置文件

要查看支持的任务完整列表，请访问[我们的专用文档页面](https://huggingface.co/docs/inference-providers/tasks/index)。

所有提供商及其支持的任务列表可在[此文档页面](https://huggingface.co/docs/inference-providers/index#partners)中查看。

对于没有提供商支持的模型，您仍可以在模型卡片中使用[示例输出](#example-outputs)来展示其功能。

您也可以在模型页面上直接点击 _请求提供商支持_，以鼓励提供商部署该模型，前提是社区有足够多的兴趣。

## 在推理游乐场中探索模型

在将模型集成到您的应用程序之前，您可以通过[Inference Playground](https://huggingface.co/playground)进行交互式测试。该游乐场允许您：

- 使用自定义提示词测试不同的[聊天补全模型](https://huggingface.co/models?inference_provider=all&sort=trending&other=conversational)
- 比较不同模型的响应
- 尝试使用 temperature、max tokens 等推理参数
- 找到适合您特定用例的完美模型

Playground 使用了与 widgets 相同的 Inference Providers 基础设施，因此将模型集成到您自己的应用程序时，您可以预期获得相似的性能和功能。