Widgets (小工具)

什麼是 Widget？

許多模型儲存庫都配備了 Widget，讓任何人都能直接在瀏覽器中執行推論。這些 Widget 由 Inference Providers（推論供應商）提供支援，為開發者提供簡化且統一的管道來存取數百種機器學習模型，並由我們的無伺服器推論合作夥伴提供算力支援。

以下是一些目前熱門的模型範例：

• DeepSeek V3 - 最先進的開放權重對話模型
• Flux Kontext - 用於影像編輯的開放權重 Transformer 模型
• Falconsai’s NSFW Detection - 影像內容審查
• ResembleAI’s Chatterbox - 生產等級的開源文字轉語音模型。

您可以前往 模型頁面 探索更多模型及其 Widget，或在 Inference Playground（推論遊樂場） 中進行互動體驗。

啟用 Widget

當模型由至少一個推論供應商託管時，就會顯示 Widget，以確保模型推論的最佳效能與可靠性。供應商會自主選擇並控制其部署的模型。

所顯示的 Widget 類型（文字生成、文字轉圖片等）是根據模型的 pipeline_tag 推斷而來的；這是一個 Hub 會嘗試為所有模型自動計算的特殊標籤。唯一的例外是 conversational (對話) Widget，它會顯示在 pipeline_tag 為 text-generation 或 image-text-to-text 且同時被標記為 conversational 的模型上。為了簡單起見，我們選擇為每個模型僅公開**一個** Widget。

對於某些程式庫（例如 transformers），模型類型可以根據設定檔 (config.json) 自動推斷。架構可以決定類型：例如，AutoModelForTokenClassification 對應到 token-classification。如果您對此感興趣，可以在 這個 Gist 中查看虛擬碼。

對於大多數其他使用情境，我們使用模型標籤來決定模型任務類型。例如，如果 模型卡元數據 中有 tag: text-classification，則推斷出的 pipeline_tag 將會是 text-classification。

您始終可以在 模型卡元數據 中使用 pipeline_tag: xxx 手動覆寫您的 Pipeline 類型。（您也可以使用元數據 GUI 編輯器來執行此操作）。

如何控制模型的 Widget 範例輸入？

您可以在模型卡元數據部分指定 Widget 輸入。

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。

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"

此外，您可以在模型卡元數據中指定非文字類型的範例輸入。請參閱 此處 以獲取所有 Widget 類型的範例輸入格式完整列表。對於視覺與語音 Widget 類型，請使用 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 檔案 中為某些語言和大多數 Widget 類型提供了範例輸入。如果缺少某些範例，我們歡迎社群提交 PR 來補充！

範例輸出

作為範例輸入的延伸，對於每個 Widget 範例，您也可以選擇性地直接在 output 屬性中描述對應的模型輸出。

這在模型尚未被推論供應商支援時非常有用，這樣模型頁面仍然可以展示模型的工作方式及其產生的結果。

例如，對於 自動語音辨識 (automatic-speech-recognition) 模型：

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

output 屬性應為一個 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 中呈現這些範例輸出，例如，讓文字轉圖片模型顯示一個精美圖片生成的圖庫。

Widget 可用性與供應商支援

並非所有模型都有可用的 Widget。Widget 的可用性取決於：

1. 任務支援：模型的任務必須由推論供應商網路中的至少一個供應商所支援。
2. 供應商可用性：必須至少有一個供應商正在提供該特定模型。
3. 模型設定：模型必須具有正確的元數據與設定檔。

若要檢視支援任務的完整列表，請查看 我們專門的文件頁面。

所有供應商及其支援的任務列表可在 此文件頁面 中找到。

對於沒有供應商支援的模型，您仍然可以使用模型卡中的 範例輸出 來展示其功能。

如果社群有足夠的興趣，您也可以直接在模型頁面上點選「要求供應商支援」(Ask for provider support)，以鼓勵供應商來部署該模型。

使用 Inference Playground 探索模型

在將模型整合到您的應用程式之前，您可以使用 Inference Playground (推論遊樂場) 進行互動式測試。遊樂場讓您可以：

• 使用自訂提示詞 (prompts) 測試不同的 聊天補全模型
• 比較不同模型的回答
• 試驗推論參數，如 Temperature、Max Tokens 等
• 找到最適合您特定用例的模型

遊樂場使用與 Widget 相同的推論供應商架構，因此當您將模型整合到自己的應用程式中時，可以預期獲得相似的效能與功能。