Hugging Face Hub 模型卡创建与 metadata 配置教程

正在做模型托管的小伙伴，大概都遇到过这种尴尬：好不容易把模型文件传上去，结果仓库首页就光秃秃一个文件列表，既没说模型用途、使用限制，也没提数据来源和许可信息；要么就是模型卡能打开，但任务、支持库这类标签一个都没显示。遇到这种情况，其实不用慌，先查 README.md 顶部的 metadata，再看模型卡正文就行——这两个区域分别管着「机器怎么识别模型」和「读者能不能判断模型合不合用」。

Hugging Face Hub 会自动把模型仓库根目录的 README.md 渲染成大家看到的 Model card（模型卡）。文件正文用 Markdown 编写就行，最顶部还能放一段 YAML 格式的 metadata。正文的作用是把模型本身、适用场景、限制与偏差、训练信息、所用数据集和评测结果说清楚；metadata 则管着检索、筛选、标签展示、模型关系、页面组件，还有一部分 API 的运行逻辑。

先看发布后的模型卡应该是什么样

随便打开一个公开的模型仓库，默认显示的 Model card 标签页，就是 README.md 渲染出来的效果。页面顶部的任务、支持库、文件格式、相关论文、许可协议这些标签，大多来自 metadata 或者 Hub 自动识别的结果；右侧还会根据仓库里的文件和 metadata，展示模型大小、张量类型这类信息。

1. 入口：
   目标模型仓库的 Model card 页面。

   动作：
   先记一下顶部现有的标签，再往下滑检查用途、限制、训练数据和评测说明有没有写全。

   成功标志：
   页面有通顺可读的正文，任务、许可这些标签和模型的实际情况对得上。

   失败处理：
   要是 Model card 一片空白，就切到 Files and versions 页面，检查根目录下有没有 README.md；要是标签不对，优先查 README.md 顶部的 YAML 配置。

从 Files and versions 找到 README.md

点击仓库导航栏里的

。模型卡的源文件必须命名为 README.md，而且得放在模型仓库的根目录下。要是没有这个文件，自己的仓库可以直接新建 README.md；用 Git 操作的话，也可以在本地仓库根目录创建好之后再推送到远端。

1. 入口：
   模型仓库顶部的 Files and versions 页面。

   动作：
   在根目录里找到 README.md，顺便确认旁边的提交记录是不是你预期的版本。

   成功标志：
   文件列表里能看到 README.md，点进去之后能看到 Preview 和 Code 两个选项卡。

   失败处理：
   要是 README.md 放在子目录里，就移到仓库根目录；要是没有写权限，别直接改别人的仓库，要用 Contribute 功能发起变更，或者联系仓库的所有者。

2. 入口：
   自己仓库的文件操作区，或者本地的 Git 工作目录。

   动作：
   新建一个 README.md，先写顶部的 YAML 配置，再写模型说明的正文内容。

   成功标志：
   保存或者推送之后能看到新的提交记录，Model card 标签页开始正常渲染内容。

   失败处理：
   要是网页跳出来让登录，先把账号登好再说；本地推送被拒绝的话，检查一下仓库地址、访问令牌和写权限对不对，别反复硬覆盖远端分支。

网页端选 Metadata UI 还是直接改 YAML

在自己的模型页面，点模型卡右上角的

，编辑器会同时显示 README.md 正文编辑区和 Metadata UI 配置面板。这个 UI 能自动补全常用的取值，还能校验部分字段，第一次配置的时候用起来很方便；要是碰到 UI 没覆盖到的字段，再切换到源码模式直接编辑 YAML 就行。

看别人的公开仓库时，README 页面会显示

按钮，这个入口是用来提交协作变更的，不代表你拿到了仓库的写权限。下图里的 Preview、Code、Raw、History 和 Contribute 都在同一条工具栏上，metadata 的解析结果则单独显示在正文的上方。

1. 入口：
   自己的 Model card 页面右上角的 Edit model card 按钮。

   动作：
   先在 Metadata UI 里填好语言、许可、任务、支持库和数据集这些信息，再检查一遍 README 正文。

   成功标志：
   所有字段都能正常选择或者自动补全，保存之后回到模型页，能看到对应的标签显示出来。

   失败处理：
   要是某个字段在 UI 里找不到，别硬塞到 tags 里，切换到 YAML 模式按照官方的字段名来填就行。

2. 入口：
   README.md 文件页的 Code 选项卡或者 Contribute 按钮。

   动作：
   查看源码，有需要的话修改之后再提交。

   成功标志：
   自己的仓库会生成一条新的提交记录；别人的仓库会生成一个可审阅的 Pull Request。

   失败处理：
   要是跳出来登录页，说明当前会话没登录；要是提示权限拒绝，说明不能直接写入，记得先保存好改动内容，换成协作流程来提交。

把 YAML 放在文件最顶部

metadata 必须从 README.md 的第一行开始写，用三条短横线（---）作为开头和结尾的标记。等结束的分隔线写完之后，再写模型卡的正文内容。列表项要用统一的缩进，字段名后面留一个空格，仓库 ID 要写成「所属账号/组织名 + 仓库名」的格式。

---
language:
- zh
- en
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
datasets:
- my-org/my-dataset
base_model: my-org/base-model
tags:
- instruction-tuned
---

# 模型名称

这里开始写用途、限制、训练信息和评测结果。

在真实仓库的 Code 视图里，能直接看到这组边界标记：第一行是三横线，license、pipeline_tag、library_name 和 tags 这些字段都在结束分隔线的前面。Preview 只会展示解析好的 metadata，要排查缩进、拼写、分隔线这类问题，得用 Code 视图才方便。

1. 入口：
   README.md 的 Code 视图，或者本地的文本编辑器。

   动作：
   把 YAML 内容移到文件第一行，并且用成对的三横线包裹起来。

   成功标志：
   Preview 页面的顶部会出现独立的 metadata 区块，正文里不会再把字段当成普通文字显示。

   失败处理：
   要是 metadata 原样出现在正文里，先检查第一行前面有没有空格、空行或者不可见字符，再看看结束的分隔线是不是漏写了。

2. 入口：
   页面的保存按钮，或者本地的 Git 提交流程。

   动作：
   提交修改后的 README.md，然后等模型页面重新渲染。

   成功标志：
   Model card 能正常打开，顶部的标签和 YAML 里的配置一一对应。

   失败处理：
   要是渲染失败，先回滚到上一条能用的提交，再逐个把字段加回去；一次只改一组字段，方便定位到底是哪里出了错。

核心字段怎样填才不误导

library_name 与 pipeline_tag

要填实际能加载这个模型的库名。官方文档建议大家主动显式填写；2024 年 8 月之后创建的仓库，光有 config.json 已经不代表 Hub 一定会默认把它识别成 transformers 库的模型了。 填模型的主要任务，比如文本生成。这个字段会影响任务标签、模型筛选、页面组件还有一部分底层 API 的行为，所以别同时塞好几个互相冲突的主任务进去。

Metadata UI 里的库和任务字段，或者 README 里的 YAML 配置。选择真实支持的库，并且只填一个主任务。模型页顶部出现对应的库和任务标签，页面的组件也和任务类型匹配。要是任务值无效，优先在 Metadata UI 里重新选；要是自动推断的结果不符合模型用途，就用 YAML 里的 pipeline_tag 明确覆盖掉自动识别的结果。

license、datasets 与 language

要用有效的许可标识，还要保证仓库里的 LICENSE 文件和页面上的说明一致。如果是自定义许可，就填 other，同时补上许可名称和许可说明的位置。 填 Hub 上真实存在的数据集仓库 ID， 用标准的语言标识列表。这些字段填对之后，模型页会展示许可信息，还会把训练数据链接到对应的数据集页面。

Metadata UI，或者 YAML 里的 license、datasets、language 字段。一项一项填好可以核验的标识。许可标签显示正确，数据集名称能被 Hub 识别，用语言筛选也能搜到这个模型。要是数据集没被识别，就核对一下账号/组织名、仓库名还有大小写对不对；要是许可不在常用列表里，就用官方支持的自定义许可结构，别自己瞎编 license 的值。

base_model 与模型关系

如果是微调模型、适配器、量化模型或者合并模型，都应该填写

字段。只有一个上游来源的话就填一个 Hub 模型 ID，合并模型可以填多个 ID；Hub 通常会自动推断出 finetune、adapter、quantized 或者 merge 这类关系，要是怕推断错，也可以用 明确指定关系类型。

README 的 YAML 配置里的 base_model 字段。填写真实的上游模型 ID，要是觉得关系可能被误判，就补上 base_model_relation 字段。模型页会出现 Model tree（模型树），在上游模型的衍生列表里也能找到当前这个模型。要是模型树没出来，就检查上游 ID 是不是完整、有没有把多个 ID 错写在同一行，还有 relation 的值和模型的实际类型是不是对得上。

正文不能只剩一串标签

metadata 是解决机器识别的问题，正文还是得回答读者关心的判断问题。至少要写清楚模型能干啥、适合和不适合用在什么场景、有哪些已知的限制和偏差、训练参数或者实验条件是什么、用了什么数据集、评测方法和结果怎么样。涉及数值的话，一定要带上对应的任务、数据集、指标和测试条件，别只写一句「效果很好」就完事了。

README.md 里，YAML 结束分隔线之后的正文区域。按照读者做决策的顺序，补上用途、限制、训练细节、数据集和评测这些内容。完全不了解这个项目的人，光看模型卡就能判断这个模型适不适合下载、部署或者继续做评估。要是资料不全，就明确标注哪些实验条件还没提供，别靠推测瞎填；涉及安全、偏差或者使用边界的内容，一定要把限制放在显眼的位置。

保存后按这条路线排错

1. 入口：
   Model card 页面的顶部标签。

   动作：
   对照着检查 language、license、library_name、pipeline_tag、datasets 和 base_model 这几个字段。

   成功标志：
   所有标签和模型关系，都和 YAML 里的配置一致。

   失败处理：
   缺哪个标签，就回到 Code 视图只查对应的字段就行，别一上来就把整份 README 全重写了。

2. 入口：
   README Preview 页面的 metadata 区块。

   动作：
   确认所有字段都被正确解析了，没混到正文里。

   成功标志：
   metadata 单独显示在一块区域，正文从模型标题和说明部分开始。

   失败处理：
   要是字段跑到正文里了，就检查首行格式、成对的分隔线、缩进、冒号还有列表的短横线对不对。

3. 入口：
   Files and versions 页面的 History 选项，或者本地的 Git 日志。

   动作：
   对比出错前后的几次 README 提交记录。

   成功标志：
   能定位到是哪次最小的改动引入了问题。

   失败处理：
   实在查不出来的话，先恢复到上一条能用的提交，再一小步一小步地加字段，每次加完都看一下模型页的渲染情况。

模型卡完成核对

1. README.md 放在模型仓库的根目录下，Model card 能正常渲染。
2. YAML 配置从文件第一行开始，并且由成对的三横线包裹。
3. library_name、pipeline_tag、license、datasets、language 这些字段，都和模型的实际情况一致。
4. 微调、适配器、量化或者合并类的模型，已经填写了 base_model，关系也没有标错。
5. 正文里包含了用途、限制、训练信息、数据集、评测方法和结果这些内容。
6. 保存之后，已经检查过顶部标签、Preview 的 metadata、Model tree 和提交记录。
7. 没有写权限的时候，用 Contribute 或者 Pull Request 提交变更，没尝试绕过仓库权限。