# 模型发布检查清单

[Hugging Face Hub](https://huggingface.co/models) 是分享机器学习模型的首选平台。一次执行得当的发布能够提升模型的可见度和影响力。本节介绍了**关键**步骤，以帮助你完成一次简洁、信息丰富且用户友好的模型发布。

> [!TIP]
> 使用编码代理发布？安装 [`hf` CLI Skill](./agents-cli)，让代理为您处理上传、模型卡片和元数据。

## ⏳ 为您的模型发布做准备

### 上传模型权重

将模型上传到 Hub 时，请遵循以下最佳实践：

- **为不同的模型权重使用独立的仓库**：为同一架构的每个变体创建单独的仓库。这样可以将它们归入一个[集合](https://huggingface.co/docs/hub/en/collections)，比目录列表更易于浏览。此外，由于每个模型都有自己独立的 URL（`hf.co/org/model-name`），这还能提升可见性、简化搜索，并为每个模型提供下载量统计。一个很好的例子是近期的[Qwen3-VL 集合](https://huggingface.co/collections/Qwen/qwen3-vl)，其中收录了 VL 架构的多种变体。

- **权重序列化时，优先使用 [`safetensors`](https://huggingface.co/docs/safetensors/en/index) 而非 `pickle`。**：`safetensors` 比 Python 的 `pickle` 或 `pth` 更安全、速度更快。如果您有 `.bin` pickle 文件，请使用 [权重转换工具](https://huggingface.co/docs/safetensors/en/convert-weights) 进行转换。

### 编写全面的模型卡

精心编写的模型卡片（即您仓库中的 `README.md`）对于可发现性、可复现性和有效共享至关重要。请确保涵盖以下内容：

1. **元数据配置**：模型卡片顶部的 [metadata 部分](https://huggingface.co/docs/hub/model-cards#model-card-metadata)（YAML）对于搜索和分类至关重要。请包含以下内容：
   ```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
   ---
   ```

   如果在 Web UI 中创建 `README.md`，您会看到一个包含我们推荐的最重要元数据字段的表单 🤗。

   | ![metadata template on the hub ui](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/metadata-template.png) |
   | :--: |
   | Hub 用户界面中的元数据表单 |

2. **详细模型描述**：清晰说明您的模型的功能、架构以及预期使用场景。帮助用户快速判断该模型是否满足其需求。

3. **使用示例**：提供用于推理、微调或其他常见任务的清晰、可直接复制运行的代码片段。尽量减少用户需要进行的修改。

   *加分项*：在仓库中添加一个结构良好的 `notebook.ipynb`，展示推理或微调过程，以便用户可以直接在 [Google Colab 和 Kaggle Notebooks](https://huggingface.co/docs/hub/en/notebooks) 中打开。

   | ![colab and kaggle button](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/colab-kaggle.png) |
   | :--: |
   | Google 和 Kaggle 使用按钮 |

4. **技术规格**：包括训练参数、硬件需求以及其他有助于用户有效运行模型的详细信息。

5. **性能指标**：分享基准测试和评估结果。包含定量指标和定性示例，以展示其优势和局限性。

6. **局限性与偏见**：记录已知的局限性、偏见和伦理考量，以便用户做出明智的选择。

为了使流程更加顺畅，请单击**导入模型卡片模板**，以使用占位符预填充`README.md`。

| ![model card template button on the hub ui](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/model-card-template-button.png) | ![model card template on the hub](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/model-card-template.png) |
|:--: | :--: |
| 用于导入模型卡模板的按钮 | 导入模板的一部分 |

### 提升模型的可发现性和易用性

为了最大化覆盖范围和易用性：

1. **库集成**：添加对众多[与 Hugging Face Hub 集成的库](https://huggingface.co/docs/hub/models-libraries)（例如 `transformers`、`diffusers`、`sentence-transformers`、`timm`）之一的支持。此集成可显著提高模型的可访问性，并为用户提供使用您模型的代码片段。
   
   例如，要指定您的模型与 `transformers` 库兼容：
   ```yaml
   ---
   library_name: transformers
   ---
   ```

   | ![code snippet tab](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/code-snippet.png) |
   | :--: |
   | 代码片段选项卡 |

   您还可以[注册自己的模型库](https://huggingface.co/docs/hub/en/models-adding-libraries)，或为您的库和代码库添加 Hub 支持，以便用户了解如何从 Hub 下载模型权重。

   我们撰写了一份关于上传最佳实践的详尽指南，[点击此处](https://huggingface.co/docs/hub/models-uploading)查看。

   > [!NOTE]
   > 使用已注册的库还可以让你跟踪模型随时间的下载量。

2. **正确的元数据**：
   - **流水线标签：**选择正确的[流水线标签](https://huggingface.co/docs/hub/model-cards#specifying-a-task--pipelinetag-)，以便您的模型出现在正确的搜索和组件中。

   常见的 pipeline 标签示例：
   - `text-generation` - 用于生成文本的语言模型
   - `text-to-image` - 用于文本到图像生成模型
   - `image-text-to-text` - 用于生成文本的视觉语言模型（VLMs）
   - `text-to-speech` - 用于从文本生成音频的模型
  
   - **许可证：**许可证信息对于用户了解如何使用该模型至关重要。

3. **研究论文**：如果您的模型有相关论文，请在模型卡片中引用它们。它们将被[自动交叉链接](https://huggingface.co/docs/hub/model-cards#linking-a-paper)。

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

4. **集合**：如果您正在发布多个相关的模型或变体，请将它们组织为一个[集合](https://huggingface.co/docs/hub/collections)。集合有助于用户发现相关模型并理解不同版本之间的关系。

5. **演示**：创建一个带有交互式演示的 [Hugging Face Space](https://huggingface.co/docs/hub/spaces)。这可以让用户无需编写代码即可试用你的模型。你还可以从 Space [链接到该模型](https://huggingface.co/docs/hub/spaces-config-reference)，使其显示在模型页面的 UI 中。

   ```markdown
   ## Demo
   
   Try this model directly in your browser: [Space Demo](https://huggingface.co/spaces/username/model-demo)
   ```
   
   创建演示时，请从 Hub 仓库（而非 Google Drive 等外部来源）下载模型。这会将相关工件相互关联，并提升可见性

6. **量化版本**：建议将量化版本（例如 GGUF）上传到单独的仓库，以提升计算资源有限的用户的可访问性。在量化模型卡上使用 [`base_model` 元数据字段](https://huggingface.co/docs/hub/model-cards#specifying-a-base-model) 链接这些版本，并记录性能差异。

   ```yaml
   ---
   base_model: username/original-model
   base_model_relation: quantized
   ---
   ```

   | ![model tree showcasing relations](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/release-checklist/model-tree.png) |
   | :--: |
   | 显示量化版本的模型树 |

7. **在模型页面上关联数据集**：在元数据中关联数据集，使其直接显示在您的模型页面上。

   ```yaml
   ---
   datasets:
   - username/dataset
   - username/dataset-2
   ---
   ```

8. **新模型版本**：如果你的模型是现有模型的更新版本，请在旧模型的卡片中注明。这将在旧页面上[显示一个横幅](https://huggingface.co/docs/hub/en/model-cards#specifying-a-new-version)，链接到更新版本。

   ```yaml
   ---
   new_version: username/updated-model
   ---
   ```

9. **视觉示例**：对于图像或视频生成模型，请在您的模型页面中使用 [`<Gallery>` 卡片组件](https://huggingface.co/docs/hub/en/model-cards-components#the-gallery-component) 直接包含示例。

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

10. **碳排放**：如果可能，请注明训练过程中的[碳排放](https://huggingface.co/docs/hub/model-cards-co2)。
   
   ```yaml
   ---
   co2_eq_emissions:
     emissions: 123.45
     source: "CodeCarbon"
     training_type: "pre-training"
     geographical_location: "US-East"
     hardware_used: "8xA100 GPUs"
   ---
   ```

### 访问控制和可见性

1. **可见性设置**：当准备分享您的模型时，请在您的[模型设置](https://huggingface.co/docs/hub/repositories-settings)中将其切换为公开。在此之前，请仔细检查所有文档和代码示例，确保它们准确且完整。

2. **受控访问**：如果您的模型需要受控访问，请使用 [受控访问功能](https://huggingface.co/docs/hub/models-gated)，并明确说明用户必须满足的条件。这对于具有双重用途风险或商业限制的模型尤为重要。

## 🏁 发布模型后

一次成功的模型发布并不止于最初的发布。为了保持质量并最大化影响力：

### 维护与社区互动

1. **验证功能**：发布后，在干净的环境中测试所有代码片段，以确认其按预期运行。这可以确保用户能够无错误、无困惑地运行你的模型。

   例如，如果你的模型是一个与 `transformers` 兼容的大语言模型：
   ```python
   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 热门板块](https://huggingface.co/models?sort=trending)中的排名就越高，从而获得更高的曝光度

3. **社区互动**：使用社区标签页来回答问题、处理反馈并迅速解决问题。澄清疑惑，采纳有益的建议，并关闭偏离主题的讨论，以保持讨论的聚焦。

### 添加评估结果

如果您在 [Hub 上支持的基准数据集](https://huggingface.co/datasets?benchmark=benchmark:official&sort=trending) 上进行评估，就可以将评估结果添加到您的模型仓库中。这样，基准分数将直接显示在模型页面以及数据集仓库的基准排行榜上。有关完整规范，请参阅 [评估结果文档](https://huggingface.co/docs/hub/eval-results)。

要添加评估结果，请在模型仓库的 `.eval_results/` 文件夹中创建 YAML 文件。每个文件都引用一个 Hub Benchmark 数据集：

```yaml
# .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](https://huggingface.co/datasets/cais/hle/blob/main/eval.yaml) 等基准数据集仓库中的 `eval.yaml` 文件来查找可用的基准及其任务 ID。

社区中的任何人都可以通过提交 Pull Request 来为任意模型提交评估结果。社区提交的分数会在模型页面上显示“community”徽章。为了简化此流程，您可以使用 [community-evals](https://github.com/huggingface/community-evals) 仓库，该仓库提供了用于从模型卡片中提取分数并自动创建 PR 的脚本和 agent skill。

### 跟踪使用情况与影响

1. **使用指标**：[跟踪下载量](https://huggingface.co/docs/hub/en/models-download-stats)和点赞数，以了解您的模型的传播范围和采用情况。您可以在模型的设置中查看总下载量指标。

2. **审阅社区贡献**：定期检查您的模型仓库中来自其他用户的贡献。社区的拉取请求和讨论可以提供有用的反馈、想法以及合作机会。

## 🏢 企业级功能

[Hugging Face Team & Enterprise](https://huggingface.co/enterprise) 订阅为团队和组织提供额外功能：

1. **访问控制**：设置 [资源组](https://huggingface.co/docs/hub/security-resource-groups) 以管理特定团队或用户的访问权限。这确保了组织内拥有正确的权限并实现安全协作。

2. **存储区域**：选择模型文件的数据存储区域（美国或欧盟），以满足区域数据法规和合规要求。

3. **高级分析**：使用 [Publisher Analytics](https://huggingface.co/docs/hub/publisher-analytics) 深入了解组织内模型的使用模式、下载量和采用趋势。

4. **扩展存储**：访问额外的私有存储空间，以托管更多模型和更大的工件，满足您模型组合不断扩展的需求。

5. **组织博客文章**：企业组织现在可以[直接在 Hugging Face 上发布博客文章](https://huggingface.co/blog/huggingface/blog-articles-for-orgs)。这使您能够与更广泛的社区分享模型发布、研究更新和公告，全部通过您的组织资料页面完成。

遵循这些准则和示例，可以让您在 Hugging Face 上发布的模型更加清晰、实用且富有影响力。这有助于您的工作触达更多用户，增强 AI 社区的力量，并提升您模型的可见度。

我们迫不及待想看看你接下来会分享什么！🤗