# ウィジェット

## ウィジェットとは何ですか？

多くのモデルリポジトリには、ブラウザ上で直接推論を実行できるウィジェットが用意されています。これらのウィジェットは、サーバーレス推論パートナーがサポートする数百の機械学習モデルに対して、開発者にシームレスで統合されたアクセスを提供する[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) - 画像編集用のオープンウェイト・トランスフォーマーモデル
- [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)でインタラクティブに試すことができます。

## ウィジェットの有効化

Widgetsは、モデルが少なくとも1つのInference Providerによってホストされている場合にのみ表示されます。これにより、モデルの推論における最適なパフォーマンスと信頼性が確保されます。各Providerは、デプロイするモデルを自律的に選択し、管理します。

表示されるウィジェットの種類（テキストから画像への変換、自動音声認識など）は、モデルの`pipeline_tag`から推測されます。これは、Hubがすべてのモデルに対して自動的に計算しようとする特別なタグです。唯一の例外は`conversational`ウィジェットで、`pipeline_tag`が`text-generation`または`image-text-to-text`のいずれかであるすべてのモデルに表示されます。簡便さのため、各モデルにつき**1つの**ウィジェットのみ公開することを選択しています。

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

複数の入力例を指定できます。ウィジェットの例のドロップダウンメニューには、`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)を参照してください。ビジョンおよびオーディオのウィジェットタイプでは、`text`ではなく`src`でサンプル入力を提供してください。

例えば、…

```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 file](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` プロパティは、Inference Providers からの出力形式を表す YAML 辞書である必要があります。

テキストを出力するモデルについては、上記の例を参照してください。

ラベルを出力するモデル（[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 UIでサンプル出力を表示することもできます。例えば、テキストから画像を生成するモデルでは、魅力的な生成画像のギャラリーを表示できます。

## ウィジェットの利用可能性とプロバイダーのサポート

すべてのモデルでウィジェットが利用可能とは限りません。ウィジェットの利用可否は、以下の要素に依存します。

1. **タスクのサポート**: モデルのタスクは、Inference Providers ネットワーク内の少なくとも 1 つのプロバイダーによってサポートされている必要があります
2. **プロバイダーの可用性**: 少なくとも1つのプロバイダーが特定のモデルを提供している必要があります
3. **モデル設定**: モデルには適切なメタデータと設定ファイルが必要です

サポートされているタスクの完全なリストについては、[専用のドキュメントページ](https://huggingface.co/docs/inference-providers/tasks/index)をご覧ください。

すべてのプロバイダーとそのサポート対象タスクの一覧は、[このドキュメントページ](https://huggingface.co/docs/inference-providers/index#partners)で確認できます。

プロバイダーのサポートがないモデルでも、モデルカードに[出力の例](#example-outputs)を含めることで、機能を紹介することができます。

モデルページ上で_プロバイダーへのサポート依頼_を直接クリックすることで、コミュニティからの関心が高ければ、プロバイダーにモデルの提供を促すことができます。

## Inference Playgroundでモデルを探索する

アプリケーションにモデルを統合する前に、[Inference Playground](https://huggingface.co/playground)で対話的にテストできます。このプレイグラウンドでは、以下を行うことができます:

- カスタムプロンプトでさまざまな[チャット補完モデル](https://huggingface.co/models?inference_provider=all&sort=trending&other=conversational)をテストします
- 異なるモデル間でレスポンスを比較する
- 温度や最大トークン数などの推論パラメータを調整して実験
- 特定のユースケースに最適なモデルを見つける

プレイグラウンドは、ウィジェットを駆動するのと同じInference Providersインフラストラクチャを使用しているため、モデルを独自のアプリケーションに統合する際にも、同様のパフォーマンスと機能性を期待できます。