Hugging Face's logo
加入 Hugging Face 社区

并访问增强的文档体验

开始使用

模型卡片

什么是模型卡片?

模型卡片是随模型一起提供的文件,并提供方便的信息。在底层,模型卡片是简单的 Markdown 文件,带有额外的元数据。模型卡片对于可发现性、可重复性和共享至关重要!您可以在任何模型仓库中找到作为 README.md 文件的模型卡片。

模型卡片应描述

  • 模型
  • 其预期用途和潜在限制,包括偏差和道德考量,如 Mitchell, 2018 中详述
  • 训练参数和实验信息(您可以嵌入或链接到实验跟踪平台以供参考)
  • 用于训练模型的哪些数据集
  • 模型的评估结果

模型卡片模板在此处 可用

如何在 带注释的模型卡片 中描述填写模型卡片每个部分的方法。

Hub 上的模型卡片有两个主要部分,信息重叠

模型卡片元数据

模型仓库将渲染其 README.md 作为模型卡片。模型卡片是一个 Markdown 文件,顶部有一个 YAML 部分,其中包含有关模型的元数据。

您添加到模型卡片的元数据支持发现和更轻松地使用您的模型。例如

  • 允许用户在 https://huggingface.co/models 处过滤模型。
  • 显示模型的许可证。
  • 将数据集添加到元数据将在您的模型页面上添加一条消息,内容为 用于训练的数据集:,并链接到相关的数据集(如果它们在 Hub 上可用)。

数据集、指标和语言标识符是 数据集指标语言 页面上列出的那些。

向模型卡片添加元数据

有几种不同的方法可以向模型卡片添加元数据,包括

  • 使用元数据 UI
  • 直接编辑 README.md 文件的 YAML 部分
  • 通过 huggingface_hub Python 库,有关更多详细信息,请参阅 文档

许多带有 Hub 集成 的库会在您上传模型时自动向模型卡片添加元数据。

使用元数据 UI

您可以使用元数据 UI 向模型卡片添加元数据。要访问元数据 UI,请转到模型页面,然后单击模型卡片右上角的 编辑模型卡片 按钮。这将打开一个编辑器,显示模型卡片 README.md 文件,以及一个用于编辑元数据的 UI。

此 UI 将允许您向模型卡片添加关键元数据,并且许多字段将根据您提供的信息自动完成。使用 UI 是向模型卡片添加元数据的最简单方法,但它不支持所有元数据字段。如果您想添加 UI 不支持的元数据,您可以直接编辑 README.md 文件的 YAML 部分。

编辑 README.md 文件的 YAML 部分

您还可以直接编辑 README.md 文件的 YAML 部分。如果模型卡片尚不包含 YAML 部分,您可以通过在文件顶部添加三个 --- 来添加一个,然后包含所有相关的元数据,并使用另一组 --- 关闭该部分,如下例所示

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
metrics:
- metric1
- metric2
base_model: "base model Hub identifier"
---

您可以在 此处 找到详细的模型卡片元数据规范。

指定库

您可以在模型卡片元数据部分指定支持的库。在此处 了解 有关我们支持的库的更多信息。库将按以下优先级顺序指定

  1. 在模型卡片中指定 library_name(如果您的模型不是 transformers 模型,则推荐使用此方法)。此信息可以通过元数据 UI 添加,也可以直接在模型卡片 YAML 部分添加
library_name: flair
  1. 拥有一个带有支持库名称的标签
tags:
- flair

如果未指定,Hub 将尝试自动检测库类型。但是,不鼓励使用这种方法,仓库创建者应尽可能使用显式的 library_name

  1. 通过查看是否存在 *.nemo*.mlmodel 等文件,Hub 可以确定模型是否来自 NeMo 或 CoreML。
  2. 过去,如果未检测到任何内容且存在 config.json 文件,则假定库为 transformers。对于 2024 年 8 月之后创建的模型仓库,情况不再如此 – 因此您需要显式 library_name: transformers

指定基础模型

如果您的模型是基础模型的微调版本、适配器或量化版本,您可以在模型卡片元数据部分指定基础模型。此信息也可用于指示您的模型是否是多个现有模型的合并版本。因此,base_model 字段可以是单个模型 ID,也可以是一个或多个 base_model 的列表(由其 Hub 标识符指定)。

base_model: HuggingFaceH4/zephyr-7b-beta

此元数据将用于在模型页面上显示基础模型。用户还可以使用此信息按基础模型过滤模型,或查找从特定基础模型派生的模型

对于微调模型
对于适配器(LoRA、PEFT 等)
对于另一个模型的量化版本
对于两个或多个模型的合并

在合并的情况下,您需要指定两个或多个 base_model 的列表

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

Hub 将从当前模型推断到基础模型的关系类型("adapter"、"merge"、"quantized"、"finetune"),但如果需要,您也可以显式设置它:例如 base_model_relation: quantized

指定新版本

如果 Hub 中有模型的新版本可用,您可以在 new_version 字段中指定它。

例如,在 l3utterfly/mistral-7b-v0.1-layla-v3

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

此元数据将用于在模型页面上显示指向模型最新版本的链接。如果 new_version 中链接的模型也具有 new_version 字段,则始终会显示最新版本。

指定数据集

您可以在模型卡片元数据部分指定用于训练模型的数据集。数据集将显示在模型页面上,用户将能够按数据集过滤模型。您应该使用 Hub 数据集标识符,该标识符与数据集的仓库名称相同作为标识符

datasets:
- imdb
- HuggingFaceH4/no_robots

指定任务 ( pipeline_tag )

您可以在模型卡元数据中指定 pipeline_tagpipeline_tag 指示模型旨在执行的任务类型。此标签将显示在模型页面上,用户可以通过任务在 Hub 上筛选模型。此标签还用于确定要用于模型的小部件以及在后台使用的 API。

对于 transformers 模型,pipeline 标签会自动从模型的 config.json 文件中推断出来,但如果需要,您可以在模型卡元数据中覆盖它。在元数据 UI 中编辑此字段将确保 pipeline 标签有效。一些具有 Hub 集成的其他库也会自动将 pipeline 标签添加到模型卡元数据中。

指定许可证

您可以在模型卡元数据部分指定许可证。许可证将显示在模型页面上,用户将能够按许可证筛选模型。使用元数据 UI,您将看到最常用许可证的下拉列表。

如果需要,您还可以通过添加 other 作为许可证值,并在元数据中指定许可证名称和链接来指定自定义许可证。

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

如果许可证无法通过 URL 获得,您可以链接到模型仓库中存储的 LICENSE 文件。

评估结果

您可以在模型卡元数据中以结构化的方式指定模型的评估结果。结果由 Hub 解析并在模型页面上的小部件中显示。以下是 bigcode/starcoder 模型的示例外观

元数据规范基于 Papers with code 的 model-index specification。这使我们能够在适当时直接将结果索引到 Papers with code 的排行榜中。您还可以链接计算评估结果的来源。

这是一个部分示例,用于描述 01-ai/Yi-34B 在 ARC 基准测试上的得分。结果来自 Open LLM Leaderboard,它被定义为 source

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

有关如何格式化此数据的更多详细信息,请查看模型卡规范

CO2 排放

模型卡也是展示模型 CO2 影响信息的绝佳位置。访问我们的 跟踪和报告 CO2 排放指南以了解更多信息。

链接论文

如果模型卡包含指向 arXiv 上论文的链接,Hugging Face Hub 将提取 arXiv ID 并以 arxiv:<PAPER ID> 格式将其包含在模型标签中。点击标签将使您能够

  • 访问论文页面
  • 筛选 Hub 上引用同一篇论文的其他模型。

在此处阅读有关论文页面的更多信息 here

模型卡文本

有关如何在没有 Hub 特定元数据的情况下填写人类可读的模型卡的详细信息(以便可以打印、剪切+粘贴等),请参阅带注释的模型卡

常见问题解答

模型标签是如何确定的?

每个模型页面在页面标题中、模型名称下方列出了模型的所有标签。这些标签主要从模型卡元数据计算得出,尽管有些标签是自动添加的,如启用小部件中所述。

我可以向我的模型添加自定义标签吗?

是的,您可以通过将自定义标签添加到模型卡元数据中的 tags 字段来将其添加到您的模型。元数据 UI 将建议一些流行的标签,但您可以添加任何您想要的标签。例如,您可以通过添加 finance 标签来表明您的模型专注于金融领域。

如何表明我的模型不适合所有受众

您可以向模型卡元数据添加 not-for-all-audience 标签。当存在此标签时,模型页面上将显示一条消息,指示该模型不适合所有受众。用户可以点击此消息以查看模型卡。

我可以在模型卡中编写 LaTeX 吗?

是的!Hub 使用 KaTeX 数学排版库在服务器端渲染数学公式,然后再解析 Markdown。

您必须使用以下分隔符

  • $$ ... $$ 用于展示模式
  • \\(...\\) 用于内联模式(斜杠和括号之间没有空格)。

然后您就可以编写LaTeX \LaTeX MSE=(1n)i=1n(yixi)2 \mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2} E=mc2 E=mc^2

< > 在 GitHub 上更新