Hub documentation

ウィジェット

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

ウィジェット

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

多くのモデルリポジトリには、ブラウザ上で直接推論を実行できるウィジェットが用意されています。これらのウィジェットは、サーバーレス推論パートナーがサポートする数百の機械学習モデルに対して、開発者にシームレスで統合されたアクセスを提供するInference Providersによって駆動されています。

現在人気のあるモデルの例をいくつか示します。

DeepSeek V3 - 最先端のオープンウェイト対話モデル
Flux Kontext - 画像編集用のオープンウェイト・トランスフォーマーモデル
FalconsaiのNSFW検出 - 画像コンテンツのモデレーション
ResembleAIのChatterbox - 本番環境で利用可能なオープンソースのテキスト読み上げモデル。

モデルページでさらに多くのモデルとそのウィジェットを探索するか、Inference 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 にある疑似コードをご覧ください。

その他のほとんどのユースケースでは、モデルタグを使用してモデルのタスクタイプを判定します。例えば、モデルカードのメタデータに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"

さらに、モデルカードのメタデータにテキスト以外のサンプル入力も指定できます。すべてのウィジェットタイプにおけるサンプル入力の形式の完全なリストについては、こちらを参照してください。ビジョンおよびオーディオのウィジェットタイプでは、textではなくsrcでサンプル入力を提供してください。

例えば、…

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 file に、一部の言語とほとんどのウィジェットタイプ用の入力例を提供しています。例が不足している場合は、コミュニティからの追加 PR を歓迎します!

出力の例

outputプロパティに直接記述することで、各ウィジェット例に対応するモデルの出力を任意で説明できます。これは、例のインプットに対する拡張機能です。

モデルがまだInference Providersでサポートされていない場合に有用です。これにより、モデルページでモデルの動作方法や得られる結果を依然として紹介することができます。

例えば、automatic-speech-recognitionモデルの場合:

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

output プロパティは、Inference Providers からの出力形式を表す YAML 辞書である必要があります。

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

ラベルを出力するモデル（text-classificationモデルなど）の場合、出力は次のようになります。

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

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

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

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

サポートされているタスクの完全なリストについては、専用のドキュメントページをご覧ください。

すべてのプロバイダーとそのサポート対象タスクの一覧は、このドキュメントページで確認できます。

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

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

Inference Playgroundでモデルを探索する

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

カスタムプロンプトでさまざまなチャット補完モデルをテストします
異なるモデル間でレスポンスを比較する
温度や最大トークン数などの推論パラメータを調整して実験
特定のユースケースに最適なモデルを見つける

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

Update on GitHub

←Unity Sentis ウィジェット例→