Hub documentation
模型卡片
模型卡片
什么是模型卡片？
模型卡片是随模型提供的文件，包含实用信息。在底层，模型卡片是带有额外元数据的简单 Markdown 文件。模型卡片对于可发现性、可复现性和共享至关重要！您可以在任何模型仓库中找到名为 README.md 的模型卡片文件。
模型卡片应描述：
- 模型
- 其预期用途及潜在局限性，包括偏见和伦理考量，详见 Mitchell, 2018
- 训练参数和实验信息（您可以嵌入或链接到实验跟踪平台以供参考）
- 用于训练您模型的数据集
- 模型的评估结果
模型卡模板可在此处获取。
带注释的模型卡片中描述了如何填写模型卡片的各个部分。
Hub 上的模型卡片包含两个关键部分，且信息存在重叠：
模型卡元数据
模型仓库会将其 README.md 渲染为模型卡片。模型卡片是一个 Markdown 文件，顶部包含一个 YAML 部分，其中包含有关该模型的元数据。
您添加到模型卡片中的元数据有助于模型的发现和使用。例如：
- 允许用户在 https://huggingface.co/models 上筛选模型。
- 显示模型的许可证。
- 将数据集添加到元数据中，会在您的模型页面上添加一条消息，内容为
Datasets used to train:，并链接到相关数据集（如果它们在 Hub 上可用）。
数据集和语言标识符是 Datasets 和 Languages 页面上列出的那些。
为您的模型卡片添加元数据
向模型卡片添加元数据有几种不同的方法，包括：
- 使用元数据 UI
- 直接编辑
README.md文件的 YAML 部分 - 通过
huggingface_hubPython 库，有关更多详细信息，请参阅 文档。
许多具有 Hub 集成 功能的库会在你上传模型时自动向模型卡片添加元数据。
使用元数据 UI
您可以使用元数据 UI 为您的模型卡片添加元数据。要访问元数据 UI，请前往模型页面，并点击模型卡片右上角的 Edit model card 按钮。这将打开一个编辑器，显示模型卡片的 README.md 文件，以及用于编辑元数据的 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
base_model: "base model Hub identifier"
---您可以在此处找到详细的模型卡片元数据规范。
指定库
您可以在模型卡片的元数据部分中指定受支持的库。有关我们支持的库的更多信息，请参见此处。库将按照以下优先级顺序指定：
- 在模型卡中指定
library_name（如果您的模型不是transformers模型，则建议这样做）。您可以通过元数据 UI 或直接在模型卡的 YAML 部分中添加此信息：
library_name: flair- 拥有一个以受支持的库名称命名的标签
tags:
- flair如果未指定，Hub 将尝试自动检测库类型。但不建议采用这种方式，仓库创建者应尽可能使用显式的 library_name。
- 通过检查是否存在诸如
*.nemo或*.mlmodel之类的文件，Hub 可以判断该模型是来自 NeMo 还是 CoreML。 - 过去，如果未检测到任何内容且存在
config.json文件，则默认该库为transformers。对于 2024 年 8 月之后创建的模型仓库，这一情况已不再适用，因此您需要显式设置library_name: transformers。
指定基础模型
如果您的模型是基础模型的微调版本、适配器或量化版本，您可以在模型卡片的元数据部分中指定基础模型。此信息还可用于表明您的模型是多个现有模型的合并版本。因此，base_model 字段可以是单个模型 ID，也可以是一个或多个 base_models 的列表（通过它们的 Hub 标识符指定）。
base_model: HuggingFaceH4/zephyr-7b-beta此元数据将用于在模型页面上显示基础模型。用户还可以利用此信息按基础模型筛选模型，或查找由特定基础模型衍生而来的模型：
在合并的情况下，您需要指定一个包含两个或更多 base_models 的列表：
base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4Hub 会根据当前模型与基础模型之间的关系推断其类型（"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:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb指定存储桶
您可以在模型卡元数据部分中指定与您的模型关联的 存储桶。这些存储桶将作为标签显示在模型页面上，而关联的存储桶页面则会反向显示该模型。您应使用 Hub 存储桶标识符，它与存储桶的仓库名称相同：
buckets:
- my-org/my-bucket
- my-org/another-bucket指定任务（pipeline_tag）
您可以在模型卡元数据中指定 pipeline_tag。pipeline_tag 表示该模型所针对的任务类型。此标签将显示在模型页面上，用户可以在 Hub 上按任务筛选模型。该标签还用于确定模型使用哪个 widget 以及底层调用哪些 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 模型的示例：
The initial metadata spec was based on Papers with code’s model-index specification. This allowed us to directly index the results into Papers with code’s leaderboards when appropriate. You could also link the source from where the eval results has been computed.
NEW：我们推出了一种更简洁的评估结果元数据格式。请在专用文档页面中查看。
以下是一个模型索引的部分示例，其中描述了 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
---有关如何格式化此数据的更多详细信息，请参阅 Model Card 规范。
CO2 排放量
模型卡片也是展示模型 CO2 影响信息的绝佳位置。请访问我们的跟踪和报告 CO2 排放指南以了解更多信息。
关联论文
如果模型卡片中包含指向论文页面的链接（无论是 HF 上的页面还是 Arxiv 摘要/PDF），Hugging Face Hub 将提取 arXiv ID，并以 arxiv:<PAPER ID> 的格式将其包含在模型标签中。点击该标签可以：
- 访问 Paper 页面
- 筛选 Hub 上引用同一篇论文的其他模型。
阅读有关 Paper 页面的更多信息，请参见此处。
模型卡文本
有关如何填写模型卡中人类可读部分（以便可以打印、剪切和粘贴等）的详细信息，请参阅 带注释的模型卡。
常见问题
模型标签是如何确定的？
每个模型页面都会在页面头部、模型名称下方列出该模型的所有标签。这些标签主要根据模型卡元数据计算得出，但其中一些是自动添加的，具体说明请参见启用小部件。
我能否为我的模型添加自定义标签？
是的，你可以在模型卡元数据的 tags 字段中添加自定义标签。元数据界面会推荐一些常用标签，但你可以添加任意标签。例如，你可以通过添加 finance 标签来表明你的模型专注于金融领域。
如何表明我的模型不适合所有受众
您可以在模型卡元数据中添加 not-for-all-audiences 标签。当存在此标签时，模型页面将显示一条消息，提示该模型并非适合所有受众。用户可以点击该消息以查看模型卡。
如何在深色模式和浅色模式下显示不同的图片？
您可以为每个主题显示不同版本的优化图像。这对于需要在浅色和深色模式下保持可见性和美观性的徽标、图表或截图尤其有用。要使用此功能，您需要提供图像的这两个版本。
通过 Markdown 编辑器上传的图片
当直接从 Markdown 编辑器上传图片（使用拖放）时，在图片 URL 末尾添加 URI 片段 #hf-light-mode-only 或 #hf-dark-mode-only，以指定其应显示的主题：
Image only displays when viewing in light mode
Image only displays when viewing in dark mode
对于已托管的图像
如果要引用已托管的图片而无需重新上传，请使用 HTML <img> 标签，并添加以下 Tailwind CSS 类来指定其应显示的样式主题：
// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />
// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />我可以在模型卡片中使用 LaTeX 吗？
是的！Hub 使用 KaTeX 数学排版库在解析 Markdown 之前于服务器端渲染数学公式。
您必须使用以下分隔符：
$$ ... $$用于显示模式\\(...\\)用于行内模式（斜杠和括号之间没有空格）。
然后你就可以编写：
Update on GitHub