# 带注释的模型卡模板

> [!TIP]
> 准备发布了吗？请参阅[模型发布清单](./model-release-checklist)，了解简洁、信息丰富且用户友好的模型发布所需的关键步骤。

## 模板

[modelcard_template.md 文件](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)

## 方向

完整填写模型卡需要多个不同角色的参与。（一个人可能同时承担多个角色。）我们将这些角色称为**开发者**，负责编写代码并运行训练；**社会技术专家**，擅长从长期角度分析技术与社会的互动（包括律师、伦理学家、社会学家或权利倡导者）；以及**项目组织者**，了解模型的整体范围和影响，能够大致填写卡片的各个部分，并作为模型卡更新的联系人。

* **开发者**对于填写[训练流程](#training-procedure-optional)和[技术规格](#technical-specifications-optional)是必需的。他们在[偏见、风险与局限性](#bias-risks-and-limitations)的“局限性”部分也尤为有用。他们负责为评估提供[结果](#results)，并理想情况下与其他角色协作，以定义评估的其余部分：[测试数据、因素与指标](#testing-data-factors--metrics)。

* **社会技术**对于填写[偏见、风险与局限性](#bias-risks-and-limitations)中的“偏见”和“风险”部分是必要的，并且对于[用途](#uses)中的“范围外使用”特别有用。

* **项目组织者**是填写[模型详情](#model-details)和[用途](#uses)所必需的。他们可能还会填写
[训练数据](#training-data)。项目组织者还可以负责[引用](#citation-optional)、[术语表](#glossary-optional)、[模型卡片联系人](#model-card-contact)、[模型卡片作者](#model-card-authors-optional)以及[更多信息](#more-information-optional)。

_以下以斜体提供了说明。_

模板变量名称显示为`monospace`。

--- 

# 模型名称

**章节概述：** 提供模型名称以及对该模型的 1-2 句话总结。

`model_id`

`model_summary`

# 目录

**章节概览：** 提供指向每个章节的链接，以便人们可以轻松跳转、在其他位置使用该文件并保留目录、打印内容等。

# 模型详情

**章节概述：**本节提供有关模型的基本信息，包括其当前状态和来源。对于任何想要引用该模型的人来说，这些信息都很有用。

## 模型描述

`model_description`

_提供有关模型的基本信息。这包括架构、版本、是否在论文中提出、是否提供原始实现以及创建者。任何版权都应在此处注明。有关训练流程、参数和重要免责声明的一般信息也可以在此部分中提及。_

* **开发者：** `developers`

_List （理想情况下还应链接到）构建该模型的人员。

* **资助方：** `funded_by`
  
_List （理想情况下应链接到）在资金、算力或其他方面支持或促成该模型的资金来源。

* **共享者 [可选]：** `shared_by`

_List （理想情况下还应链接到）在线提供该模型的人员/组织。

* **模型类型：** `model_type`

_您可以将“type”命名为：_

_1. 监督/学习方法_

_2. 机器学习类型_

_3. 模态_

* **语言** [NLP]: `language`

_当系统使用或处理自然（人类）语言时，请使用此字段。_

* **许可证：** `license`

_所使用的许可证的名称及链接。_

* **微调自模型 [可选]：** `base_model`

_如果该模型以另一个模型为基础，请在此处链接到该模型。_

## 模型来源 [可选]

* **仓库：** `repo`
* **论文 [可选]：** `paper`
* **演示 [可选]：** `demo`

_提供来源，以便用户直接查看模型及其详细信息。其他类型的资源——训练日志、经验教训等——应放在 [更多信息](#more-information-optional) 部分。如果在此部分包含一项内容，请链接到代码仓库。_

# 用途

**本节概述：**本节旨在解答模型在不同应用场景中的预期用途相关问题，讨论模型的可预见用户（包括受模型影响的群体），并描述被视为超出适用范围或属于模型误用的使用方式。请注意，本节不打算包含许可证使用详情。如需了解相关信息，请直接链接至许可证。

## 直接使用

`direct_use`

_说明如何在不进行微调、后处理或集成到流水线（pipeline）的情况下使用该模型。建议提供示例代码片段。_

## 下游用途 [可选]

`downstream_use`

_说明该模型在针对特定任务进行微调后，或集成到更大的生态系统或应用中时如何使用。建议提供示例代码片段。_

## 范围外使用

`out_of_scope_use`

_列出模型可能被误用的方式（即模型无法按预期工作的使用方式），并说明用户不应如何使用该模型。_

# 偏差、风险与局限性

**本节概述：**本节旨在识别可预见的危害、误解以及技术和社技层面的局限性。同时，本节还提供了有关警告和潜在缓解措施的信息。偏见、风险和局限性有时难以区分，或指向相同的问题。通常，偏见和风险属于社技层面，而局限性属于技术层面：
- **偏差**是指针对某些子群体的刻板印象或不成比例的表现（偏斜）。
- **风险**是指模型可能会引发的具有社会相关性的问题。
- **局限性**是一种可能的失效模式，可以按照列出的建议进行处理。

`bias_risks_limitations`

_该模型存在哪些已知或可预见的问题？_

## 建议

`bias_recommendations`

_针对可预见的问题，有哪些建议？这可以包括从“对图像进行下采样”到过滤露骨内容等所有方面。_

# 训练详情

**章节概述：**本节提供用于描述和复现训练的信息，包括训练数据、训练元素的速度和规模，以及训练的环境影响。本节与[技术规格](#technical-specifications-optional)密切相关，当内容与训练流程相关时，应在此处链接到该章节。对于希望深入了解模型输入和训练足迹的人员，本节非常有用。对于任何希望了解模型学习基础内容的人员，本节也与之相关。

## 训练数据

`training_data`

_用 1-2 句话描述训练数据的内容。理想情况下，此处应链接到数据集卡片以获取更多信息。与数据预处理或额外过滤相关的文档链接也可以放在这里，也可以放在[更多信息](#more-information-optional)中。_
 

## 训练流程 [可选]

### 预处理

`preprocessing`

_详细说明标记化、调整大小/重写（取决于模态）等。_

### 速度、大小、时间

`speeds_sizes_times`

_详细记录吞吐量、开始/结束时间、检查点大小等。_

# 评估

**章节概述：** 本节介绍了评估协议、评估中测量的内容，并提供了评估结果。理想的评估至少包含两个部分：一部分关注对通用性能的定量测量（[测试数据、因素与指标](#testing-data-factors--metrics)），例如通过基准测试完成；另一部分关注与特定社会安全问题相关的性能（[社会影响评估](#societal-impact-assessment-optional)），例如通过红队测试完成。您还可以在模型卡元数据中以结构化方式指定模型的评估结果。结果将由 Hub 解析，并以小部件的形式显示在模型页面上。参见 https://huggingface.co/docs/hub/model-cards#evaluation-results。

## 测试数据、因素和指标

_理想情况下，评估应针对任务、领域和人群子群体等不同因素进行**分解**，并使用对可预见的使用场景最具意义的指标进行计算。如果模型在不同子群体上的评估表现相同，则称其在这些子群体之间是“公平”的；目标公平性指标应根据模型使用场景下哪些错误更可能引发问题来决定。不过，本节通常用于报告在不同任务基准上的总体评估表现。_

### 测试数据

`testing_data`

_描述测试数据或链接到其数据集卡片。_

### 因素

`testing_factors`

_哪些可预见的特征会影响模型的行为？理想情况下，评估应针对这些因素进行拆分，以揭示性能上的差异。_

### 指标

`testing_metrics`

_将使用哪些指标进行评估？_

## 结果

`results`

_结果应基于上述定义的因素和指标。_

### 摘要

`results_summary`

_结果说明了什么？这可以作为面向普通读者的一种简要总结。_

## 社会影响评估 [可选]

_使用此自由文本部分说明该模型如何就社会危害风险进行评估，例如儿童安全、NCII、隐私和暴力。这可能表现为对以下问题的回答：_

- _该模型是否适合儿童使用？原因是什么？_
- _该模型是否经过测试，以评估与未经同意的亲密图像（包括 CSEM）相关的风险？_
- _该模型是否经过测试以评估与暴力活动或暴力描绘相关的风险？结果如何？_

_还可以提供每个问题的量化数据。_

# 模型检查 [可选]

**章节概述：**这是一个实验性章节，一些开发者开始在其中添加关于可解释性/可解释性的工作。

`model_examination`

# 环境影响

**章节概述：** 概述了计算环境影响（如电力消耗和碳排放）所需的信息。

* **硬件类型：** `hardware_type`
* **已使用小时数：** `hours_used`
* **云服务商：** `cloud_provider`
* **计算区域：** `cloud_region`
* **碳排放量：** `co2_emitted`

_可以使用 [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700) 中介绍的 [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) 来估算碳排放。_

# 技术规格 [可选]

**章节概述：**本章节包含有关模型目标和架构以及计算基础设施的详细信息。对于对模型开发感兴趣的人员来说，本章节非常有用。撰写本章节通常需要模型开发人员直接参与。

## 模型架构与目标

`model_specs`

## 计算基础设施

`compute_infrastructure`

### 硬件

`hardware_requirements`

_最低硬件要求是什么，例如处理、存储和内存要求？_

### 软件

`software`

# 引用 [可选]

**章节概述：** 开发者推荐用于引用此模型的文献。这通常是一篇论文。

### BibTeX 

`citation_bibtex`

### APA 

`citation_apa`

# 术语表 [可选]

**章节概述：**本节定义了常用术语以及指标的计算方式。

`glossary`

_明确定义术语，以便不同受众都能理解。_

# 更多信息 [可选]

**本节概述：**本节提供了有关数据集创建、技术规范、经验教训和初步结果的链接。

`more_information`

# 模型卡作者 [可选]

**章节概述：** 本节列出了创建模型卡的人员，以表彰并明确其在构建过程中所投入的细致工作的责任归属。

`model_card_authors`

# 模型卡联系

**章节概述：** 为那些对模型卡片有更新、建议或问题的人提供了一种联系模型卡片作者的方式

`model_card_contact`

# 如何开始使用模型

**章节概述：** 提供代码片段，展示如何使用该模型。

`get_started_code`

---

**请引用为：** Ozoani, Ezi and Gerchick, Marissa and Mitchell, Margaret. Model Card Guidebook. Hugging Face, 2022. https://huggingface.co/docs/hub/en/model-card-guidebook