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

模型发布检查清单

Hugging Face Hub 是分享机器学习模型的首选平台。一次执行得当的发布可以提升模型的可见度和影响力。本节介绍了关键步骤，以完成一次简洁、信息丰富且用户友好的模型发布。

使用编码代理发布？安装 hf CLI Skill，让代理为您处理上传、模型卡片和元数据。

⏳ 为您的模型发布做准备

上传模型权重

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

为不同的模型权重使用独立的仓库：为同一架构的每个变体创建单独的仓库。这样可以将它们归入一个集合，比目录列表更易于浏览。此外，由于每个模型都有自己独立的 URL（hf.co/org/model-name），这还能提升可见性、简化搜索，并为每个模型提供下载量统计。一个很好的例子是近期的Qwen3-VL 集合，其中包含了 VL 架构的各种变体。
权重序列化时，优先使用 safetensors 而非 pickle。：safetensors 比 Python 的 pickle 或 pth 更安全、速度更快。如果您有 .bin pickle 文件，请使用权重转换工具进行转换。

编写全面的模型卡

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

元数据配置：模型卡片顶部的 metadata 部分（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，您会看到一个包含我们推荐的最重要元数据字段的表单 🤗。


Hub 用户界面中的元数据表单

模型详细描述：清晰说明您的模型的功能、架构以及预期使用场景。帮助用户快速判断该模型是否满足其需求。
使用示例：为推理、微调或其他常见任务提供清晰、可直接复制运行的代码片段。尽量减少用户需要进行的修改。

加分项：在仓库中添加一个结构良好的 notebook.ipynb，展示推理或微调过程，以便用户可以直接在 Google Colab 和 Kaggle Notebooks 中打开。

Google 和 Kaggle 使用按钮
技术规格：包括训练参数、硬件需求以及其他有助于用户有效运行模型的详细信息。
性能指标：分享基准测试和评估结果。包含定量指标和定性示例，以展示其优势和局限性。
局限性与偏见：记录已知的局限性、偏见和伦理考量，以便用户做出明智的选择。


Google 和 Kaggle 使用按钮

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


用于导入模型卡模板的按钮	导入模板的一部分

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

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

库集成：添加对众多与 Hugging Face Hub 集成的库（例如 transformers、diffusers、sentence-transformers、timm）之一的支持。此集成可显著提高模型的可访问性，并为用户提供使用您模型的代码片段。

例如，要指定您的模型与 transformers 库兼容：
```
---
library_name: transformers
---
```
代码片段选项卡

您还可以注册自己的模型库，或为您的库和代码库添加 Hub 支持，以便用户了解如何从 Hub 下载模型权重。

我们撰写了一份关于上传最佳实践的详尽指南，点击此处查看。

使用已注册的库还可以让你跟踪模型随时间的下载量。
正确的元数据：
- 流水线标签：选择正确的流水线标签，以便您的模型出现在正确的搜索和组件中。
常见的 pipeline 标签示例：
- text-generation - 用于生成文本的语言模型
- text-to-image - 用于文本到图像生成模型
- image-text-to-text - 用于生成文本的视觉语言模型（VLMs）
- text-to-speech - 用于从文本生成音频的模型
- 许可证：许可证信息对于用户了解如何使用该模型至关重要。
研究论文：如果您的模型有相关论文，请在模型卡片中引用它们。它们将被自动交叉链接。
```
## References

* [Model Paper](https://arxiv.org/abs/xxxx.xxxxx)
```
集合：如果您正在发布多个相关的模型或变体，请将它们组织为一个集合。集合有助于用户发现相关模型并理解不同版本之间的关系。
演示：创建一个 Hugging Face Space 并包含交互式演示。这样用户无需编写代码即可试用你的模型。你还可以从 Space 链接到该模型，使其显示在模型页面的 UI 中。
```
## Demo

Try this model directly in your browser: [Space Demo](https://huggingface.co/spaces/username/model-demo)
```
创建演示时，请从 Hub 仓库（而非 Google Drive 等外部来源）下载模型。这会将相关工件相互关联，并提升可见性
量化版本：建议将量化版本（例如 GGUF）上传到单独的仓库，以提升计算资源有限的用户的可访问性。在量化模型卡上使用 base_model 元数据字段链接这些版本，并记录性能差异。
```
---
base_model: username/original-model
base_model_relation: quantized
---
```
显示量化版本的模型树
在模型页面上关联数据集：在元数据中关联数据集，使其直接显示在你的模型页面上。
```
---
datasets:
- username/dataset
- username/dataset-2
---
```
新模型版本：如果你的模型是现有模型的更新版本，请在旧模型的卡片中注明。这将在旧页面上显示一个横幅，链接到更新版本。
```
---
new_version: username/updated-model
---
```
视觉示例：对于图像或视频生成模型，请在您的模型页面中使用 <Gallery> 卡片组件直接包含示例。
```
<Gallery>
![Example 1](./images/example1.png)
![Example 2](./images/example2.png)
</Gallery>
```


代码片段选项卡


显示量化版本的模型树

碳排放：如果可能，请注明训练过程中的碳排放。

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

访问控制和可见性

可见性设置：当您准备好分享模型时，请在您的模型设置中将其切换为公开。在此之前，请仔细检查所有文档和代码示例，确保它们准确且完整。
受控访问：如果您的模型需要受控访问，请使用受控访问功能，并明确说明用户必须满足的条件。这对于具有双重用途风险或商业限制的模型尤为重要。

🏁 发布模型后

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

维护与社区互动

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

例如，如果你的模型是一个与 transformers 兼容的大语言模型：
```
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)
```
分享分享分享：大多数用户通过社交媒体、聊天频道（如 Slack 或 Discord）或新闻通讯发现模型。请将这些空间中的模型链接分享出去，并将其添加到你的网站或 GitHub 仓库中。

您的模型获得的访问量和点赞越多，它在Hugging Face 热门板块中的排名就越高，从而获得更高的曝光度
社区互动：使用“社区”选项卡来回答问题、处理反馈并快速解决问题。澄清疑惑，采纳有益的建议，并关闭偏离主题的讨论，以保持讨论的聚焦。

添加评估结果

如果您在 Hub 上支持的基准数据集上进行评估，就可以将评估结果添加到您的模型仓库中。这样，基准分数将直接显示在模型页面以及数据集仓库的基准排行榜上。有关完整规范，请参阅评估结果文档。

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

# .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 的脚本和 agent skill。

跟踪使用情况与影响

使用指标：跟踪下载量和点赞数，以了解您的模型的传播范围和采用情况。您可以在模型的设置中查看总下载量指标。
审阅社区贡献：定期检查您的模型仓库中来自其他用户的贡献。社区的拉取请求和讨论可以提供有用的反馈、想法以及合作机会。

🏢 企业级功能

Hugging Face Team & Enterprise 订阅为团队和组织提供额外功能：

访问控制：设置资源组以管理特定团队或用户的访问权限。这可以确保在整个组织中拥有正确的权限并实现安全协作。
存储区域：选择模型文件的数据存储区域（美国或欧盟），以满足区域数据法规和合规要求。
高级分析：使用 Publisher Analytics 深入了解组织内模型的使用模式、下载量和采用趋势。
扩展存储：随着您的模型组合不断扩大，可访问额外的私有存储空间，以托管更多模型和更大的工件。
组织博客文章：企业组织现在可以直接在 Hugging Face 上发布博客文章。这使您能够与更广泛的社区分享模型发布、研究更新和公告，全部通过您的组织资料页完成。

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

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

Update on GitHub

←模型下载统计硬件→