Hugging Face's logo

Hub 文件

模型發佈檢查清單

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

模型發佈檢查清單

Hugging Face Hub 是分享機器學習模型的首選平台。一次執行完善的發佈可以提升您模型的曝光度與影響力。本節涵蓋了精簡、資訊豐富且對使用者友善的模型發佈之必要步驟。

正在使用程式設計代理（Coding Agent）進行發佈？請安裝 hf CLI 工具，讓您的代理為您處理上傳、模型卡片（Model Card）以及中繼資料（Metadata）。

⏳ 準備您的模型發佈

上傳模型權重

將模型上傳至 Hub 時，請遵循以下最佳實作：

  • 為不同的模型權重使用獨立的儲存庫 (Repository)：為同一架構的每個變體建立個別的儲存庫。這可以讓您將它們歸類為一個合集 (Collection)，這比單純的目錄列表更容易瀏覽。此外，由於每個模型都有專屬的 URL (hf.co/org/model-name)，這不僅能提升曝光度，還能方便搜尋，並為您的每個模型提供下載統計。一個絕佳的範例是近期發佈的 Qwen3-VL 合集，其中展示了 VL 架構的多種變體。

  • 權重序列化建議優先選擇 safetensors 而非 pickle。：safetensors 比 Python 的 pickle 或 pth 更安全且更快速。如果您有 .bin 的 pickle 檔案，請使用權重轉換工具進行轉換。

編寫詳盡的模型卡片

一份精心製作的模型卡片（儲存庫中的 README.md）對於模型的可發現性、可重現性以及有效分享至關重要。請務必包含以下內容：

  1. 中繼資料設定 (Metadata Configuration)：模型卡片頂部的中繼資料區塊 (YAML) 對於搜尋與分類至關重要。請務必包含：

    ---
pipeline_tag: text-generation    # Specify the task
library_name: transformers       # Specify the library
language:
  - en                           # List languages your model supports
license: apache-2.0              # Specify a license
datasets:
  - username/dataset             # List datasets used for training
base_model: username/base-model  # If applicable (your model is a fine-tune, quantized, merged version of another model)
tags:                            # Add extra tags which would make the repo searchable using the tag
  - tag1 
  - tag2
---

    若您在網頁介面上建立 README.md，您將看到一個表單，其中包含我們推薦的最重要中繼資料欄位 🤗。

    metadata template on the hub ui
    Hub UI 上的中繼資料表單

  2. 詳細模型描述：清晰地解釋您的模型功能、架構以及預期的應用場景。幫助使用者快速判斷它是否符合需求。

  3. 使用範例：提供清晰、可複製且可立即執行的程式碼片段，用於推論 (Inference)、微調 (Fine-tuning) 或其他常見任務。請盡量減少使用者需要進行的修改。

    加分項：在儲存庫中加入結構良好的 notebook.ipynb，展示推論或微調流程，讓使用者可以直接在 Google Colab 和 Kaggle Notebooks 中開啟。

    colab and kaggle button
    Google 與 Kaggle 使用按鈕

  4. 技術規格：包含訓練參數、硬體需求，以及其他能幫助使用者有效執行模型的詳細資訊。

  5. 效能指標：分享基準測試 (Benchmark) 與評估結果。包含定量指標與定性範例，以展示模型的優勢與侷限性。

  6. 侷限性與偏見：記錄已知的侷限性、偏見以及道德考量，以便使用者能做出明智的選擇。

為了讓流程更順暢，請點擊匯入模型卡片範本 (Import model card template)，以預填帶有預留位置的 README.md。

model card template button on the hub ui model card template on the hub
匯入模型卡片範本的按鈕 匯入後的範本區段

提升模型的可發現性與易用性

為了最大化觸及率與易用性：

  1. 函式庫整合：新增對 Hugging Face Hub 已整合的眾多函式庫（例如 transformers、diffusers、sentence-transformers、timm）的支援。此整合將顯著增加您模型的可存取性，並提供使用者使用您模型所需的程式碼片段。

    例如，若要指定您的模型可與 transformers 函式庫協作：

    ---
library_name: transformers
---
    code snippet tab
    程式碼片段分頁

    您也可以註冊您自己的模型函式庫，或將 Hub 支援加入您的函式庫與程式碼庫中，讓使用者知道如何從 Hub 下載模型權重。

    我們撰寫了一份詳細的關於上傳最佳實作指南，請見此處。

    使用已註冊的函式庫還能讓您持續追蹤模型的下載量。

  2. 正確的中繼資料:

    • Pipeline 標籤 (Pipeline Tag)：選擇正確的 pipeline 標籤，以便您的模型出現在正確的搜尋結果與元件中。

    常見 Pipeline 標籤範例：

    • text-generation - 用於生成文字的語言模型

    • text-to-image - 用於文字轉圖像生成模型

    • image-text-to-text - 用於生成文字的視覺語言模型 (VLM)

    • text-to-speech - 用於將文字轉換為語音的模型

    • 授權 (License)：授權資訊對於使用者理解如何使用該模型至關重要。

  3. 研究論文：如果您的模型有相關聯的論文，請將其引用於模型卡片中。它們將被自動交叉連結。

    ## References

* [Model Paper](https://arxiv.org/abs/xxxx.xxxxx)

  4. 合集 (Collections)：如果您要發佈多個相關模型或變體，請將它們整理成一個合集。合集能幫助使用者發現相關模型，並理解版本間的關聯。

  5. 展示專案 (Demos)：建立一個帶有互動式展示的 Hugging Face Space。這讓使用者無需編寫程式碼即可嘗試您的模型。您也可以從 Space 連結模型，使其顯示在模型頁面介面上。

    ## Demo

Try this model directly in your browser: [Space Demo](https://huggingface.co/spaces/username/model-demo)

    建立展示專案時，請從 Hub 儲存庫（而非 Google Drive 等外部來源）下載模型。這能建立人工製品的交叉連結並提升曝光度。

  6. 量化版本：考慮將量化版本（例如 GGUF）上傳至不同的儲存庫，以提升運算資源有限使用者的可存取性。使用量化模型卡片上的 base_model 中繼資料欄位來連結這些版本，並記錄效能差異。

    ---
base_model: username/original-model
base_model_relation: quantized
---
    model tree showcasing relations
    顯示量化版本的模型樹

  7. 在模型頁面上連結資料集：在您的中繼資料中連結資料集，以便它們直接顯示在您的模型頁面上。

    ---
datasets:
- username/dataset
- username/dataset-2
---

  8. 新模型版本：如果您的模型是現有模型的更新版，請在舊模型的卡片上註明。這將會在舊版頁面上顯示一個連結至更新版的橫幅。

    ---
new_version: username/updated-model
---

  9. 視覺範例：對於圖像或影片生成模型，請使用 <Gallery> 卡片元件將範例直接包含在您的模型頁面上。

    <Gallery>
![Example 1](./images/example1.png)
![Example 2](./images/example2.png)
</Gallery>

  10. 碳排放：若可能，請標明訓練過程中的碳排放量。

    ---
co2_eq_emissions:
  emissions: 123.45
  source: "CodeCarbon"
  training_type: "pre-training"
  geographical_location: "US-East"
  hardware_used: "8xA100 GPUs"
---

存取控制與可見性

  1. 可見性設定：準備好分享您的模型後，請在您的模型設定中將其切換為公開 (Public)。在執行此操作前，請務必再三檢查所有文件與程式碼範例，確保其準確且完整。

  2. 閘道存取 (Gated Access)：如果您的模型需要受控存取，請使用閘道存取功能，並明確說明使用者必須滿足的條件。這對於具有雙重用途疑慮或商業限制的模型尤為重要。

🏁 模型發佈之後

成功的模型發佈不僅止於最初的發表。為了維護品質並最大化影響力：

維護與社群互動

  1. 驗證功能：發佈後，請在乾淨的環境中測試所有程式碼片段，確認它們能如預期運作。這能確保使用者能在沒有錯誤或混亂的情況下執行您的模型。

    例如，如果您的模型是相容於 transformers 的 LLM：

    from transformers import pipeline

# This should run without errors
pipe = pipeline("text-generation", model="your-username/your-model")
result = pipe("Your test prompt")
print(result)

  2. 分享、分享、再分享：大多數使用者是透過社群媒體、聊天頻道（如 Slack 或 Discord）或電子報發現模型的。請在這些管道中分享您的模型連結，並將其加入您的個人網站或 GitHub 儲存庫中。

    您的模型獲得的訪問次數與按讚數越多，它在 Hugging Face 趨勢區塊 的排名就越高，從而帶來更高的曝光度。

  3. 社群互動：利用「社群 (Community)」分頁來回答問題、處理意見回饋並即時解決問題。釐清誤解、採納有益的建議，並關閉離題的討論串，以保持討論的聚焦。

新增評估結果

如果您在任何 Hub 上支援的基準測試資料集 上進行評估，您可以將評估結果新增至您的模型儲存庫。這將使基準分數直接顯示在模型頁面上，並出現在資料集儲存庫的基準排行榜中。請參閱 評估結果文件 以取得完整規範。

若要新增評估結果，請在模型儲存庫的 .eval_results/ 資料夾中建立 YAML 檔案。每個檔案皆參考一個 Hub 基準資料集。

# .eval_results/gpqa.yaml
- dataset:
    id: Idavidrein/gpqa
    task_id: diamond
  value: 76.1
  date: "2026-03-19"
  source:
    url: https://huggingface.co/your-org/your-model
    name: Model Card
    user: your-username

task_id 必須與基準資料集之 eval.yaml 中定義的任務相符。您可以透過查看基準資料集儲存庫（如 HLE）中的 eval.yaml 檔案，找到可用的基準與其任務 ID。

社群中的任何人也可以透過提交 Pull Request 的方式，為任何模型提供評估結果。社群提交的分數會在模型頁面上顯示「社群 (community)」徽章。為簡化此流程，您可以使用 community-evals 儲存庫，它提供了從模型卡片中提取分數並自動建立 PR 的指令碼與代理技能。

追蹤使用量與影響力

  1. 使用指標：追蹤下載量與按讚數，以了解您模型的觸及範圍與採用程度。您可以在模型設定中查看總下載指標。

  2. 檢視社群貢獻：定期查看您的模型儲存庫，了解是否有其他使用者的貢獻。社群的 Pull Request 與討論可以提供有用的意見回饋、創意與合作機會。

🏢 企業功能

Hugging Face Team & Enterprise 訂閱方案為團隊與組織提供額外的功能：

  1. 存取控制：設定資源群組 (Resource groups) 以管理特定團隊或使用者的存取權限。這能確保組織內正確的權限管理與安全協作。

  2. 儲存區域：為您的模型檔案選擇資料儲存區域（美國或歐盟），以符合區域資料法規與合規性要求。

  3. 進階分析：使用發布者分析 (Publisher Analytics)，深入了解組織內部的模型使用模式、下載量與採用趨勢。

  4. 擴充儲存空間：隨著模型組合的擴大，存取額外的私有儲存容量以託管更多模型與大型人工製品。

  5. 組織部落格文章：企業組織現在可以直接在 Hugging Face 上發布部落格文章。這讓您能夠從組織的個人檔案頁面中，與更廣大的社群分享模型發佈、研究更新與公告。

透過遵循這些準則與範例，您將能使您在 Hugging Face 上的模型發佈更清晰、實用且具影響力。這不僅有助於讓您的工作觸及更多人，也能強化 AI 社群，並提升您模型的能見度。

我們非常期待看到您下一次的分享！ 🤗

在 GitHub 上更新

←模型下載統計 本地應用程式→
© . This site is unofficial and not affiliated with Hugging Face, Inc.