Hugging Face 的 LOGO

Hub 文档

模型卡片

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

模型卡片

什么是模型卡片？

模型卡片是随模型附带的文件，提供有用的信息。在底层，模型卡片是简单的 Markdown 文件，附带额外的元数据。模型卡片对于可发现性、可复现性和共享至关重要！你可以在任何模型仓库的 `README.md` 文件中找到模型卡片。

模型卡片应描述

  • 模型
  • 其预期用途和潜在限制，包括 Mitchell，2018 中详述的偏见和伦理考量
  • 训练参数和实验信息（你可以嵌入或链接到实验跟踪平台以供参考）
  • 用于训练模型的哪些数据集
  • 模型的评估结果

模型卡片模板可在此处获取：此处。

如何填写模型卡片中的每个部分，请参阅注释模型卡片。

Hub 上的模型卡片有两个关键部分，信息有所重叠

模型卡片元数据

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

你添加到模型卡片的元数据有助于发现和更轻松地使用你的模型。例如

  • 允许用户在 https://huggingface.co/models 上筛选模型。
  • 显示模型的许可证。
  • 将数据集添加到元数据将向你的模型页面添加一条消息，显示“`Datasets used to train:`”，并链接相关数据集（如果它们在 Hub 上可用）。

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

向模型卡片添加元数据

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

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

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

使用元数据 UI

您可以使用元数据 UI 将元数据添加到您的模型卡片中。要访问元数据 UI，请转到模型页面，然后单击模型卡片右上角的“`Edit model card`”按钮。这将打开一个编辑器，显示模型卡片 `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，也可以是一个或多个基础模型的列表（通过其 Hub 标识符指定）。

base_model: HuggingFaceH4/zephyr-7b-beta

此元数据将用于在模型页面上显示基础模型。用户还可以使用此信息按基础模型筛选模型，或查找源自特定基础模型的模型

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

在合并情况下，您需要指定包含两个或更多基础模型的列表

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_tag`。`pipeline_tag` 指示模型预期的任务类型。此标签将显示在模型页面上，用户可以在 Hub 上按任务筛选模型。此标签还用于确定模型使用哪个小部件以及底层使用哪个 API。

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

指定许可证

您可以在模型卡片元数据部分指定许可证。许可证将显示在模型页面上，用户将能够按许可证筛选模型。使用元数据 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 规范。这使我们能够在适当的时候直接将结果索引到 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
---

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

二氧化碳排放量

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

链接论文

如果模型卡片包含指向 arXiv 论文的链接，Hugging Face Hub 将提取 arXiv ID 并以 `arxiv:` 的格式将其包含在模型标签中。单击该标签将允许您

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

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

模型卡片文本

有关如何填写不含 Hub 特定元数据的人类可读模型卡片（以便可以打印、剪切粘贴等）的详细信息，请参阅注释模型卡片。

常见问题

如何确定模型标签？

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

我可以为我的模型添加自定义标签吗？

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

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

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

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

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

您必须使用以下分隔符

  • `$$ ... $$` 用于显示模式
  • `\\(...\\)` 用于行内模式（斜杠和括号之间没有空格）。

然后你就可以写了LaTeX \LaTeX MSE=(1n)∑i=1n(yi−xi)2 \mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2} E=mc2 E=mc^2

< > 在 GitHub 上更新

←模型中心 注释模型卡片→