好不容易把模型文件传上去，结果仓库首页就光秃秃一个文件列表，既没说模型用途、使用限制，也没提数据来源和许可信息；要么就是模型卡能打开，但任务、支持库这类标签一个都没显示。遇到这种情况，先查 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

点击仓库导航栏里的 Files and versions。模型卡的源文件必须命名为 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

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

看别人的公开仓库时，README 页面会显示 Contribute 按钮，这个入口是用来提交协作变更的，不代表你拿到了仓库的写权限。下图里的 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

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

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

license、datasets 与 language

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

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

base_model 与模型关系

如果是微调模型、适配器、量化模型或者合并模型，都应该填写 base_model 字段。只有一个上游来源的话就填一个 Hub 模型 ID，合并模型可以填多个 ID；Hub 通常会自动推断出 finetune、adapter、quantized 或者 merge 这类关系，要是怕推断错，也可以用 base_model_relation 明确指定关系类型。

入口：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 提交变更，没尝试绕过仓库权限。